トラブルシューティングガイド

ラマン分光分析アプリケーションの一般的な問題と解決方法

📋 目次

インストール問題
起動とクラッシュ
データロード問題
前処理エラー
分析エラー
機械学習問題
パフォーマンス問題
UI/表示問題
エクスポート問題
プラットフォーム固有の問題

インストール問題

問題1: "Python not found"エラー

症状:

'python' is not recognized as an internal or external command

原因: Pythonがインストールされていないか、PATHに追加されていません

解決策:

Windows:

# 1. Python 3.10以上をダウンロード
https://www.python.org/downloads/

# 2. インストール時に「Add Python to PATH」にチェック

# 3. 確認
python --version

macOS:

# Homebrewを使用
brew install python@3.10

# 確認
python3 --version

Linux:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install python3.10 python3-pip

# 確認
python3 --version

問題2: "Permission denied"インストールエラー

症状:

ERROR: Could not install packages due to an EnvironmentError: [Errno 13] Permission denied

原因: システムディレクトリへの書き込み権限がありません

解決策:

オプション1: 仮想環境を使用（推奨）

# 仮想環境を作成
python -m venv venv

# 有効化
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

# インストール（リポジトリ内で実行）
pip install -e .

問題3: UVのインストールが失敗する

症状:

Failed to install UV package manager

解決策:

Windows:

# PowerShellを管理者として実行
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

# 再度実行
irm https://astral.sh/uv/install.ps1 | iex

# または手動ダウンロード
https://github.com/astral-sh/uv/releases

macOS/Linux:

# curlが利用できない場合
brew install curl

# または wgetを使用
wget -qO- https://astral.sh/uv/install.sh | sh

# PATH に追加
export PATH="$HOME/.cargo/bin:$PATH"
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc

問題4: 依存関係の競合

症状:

ERROR: Could not install the project because these package versions have conflicting dependencies

解決策:

# 1. 新しい仮想環境を作成
python -m venv clean_env
source clean_env/bin/activate  # または clean_env\Scripts\activate

# 2. pipを更新
pip install --upgrade pip setuptools wheel

# 3. 依存関係を1つずつインストール
pip install numpy scipy pandas
pip install PyQt6 matplotlib
pip install scikit-learn

# 4. アプリケーションをインストール（リポジトリから）
pip install -e .

# または（編集可能インストールが不要なら）
pip install .

特定のバージョンを指定:

# 互換性のあるバージョンを使用
pip install numpy==1.24.0 scipy==1.11.0 scikit-learn==1.3.0

起動とクラッシュ

問題5: アプリケーションが起動しない

症状: ダブルクリックしても何も起こらない

診断ステップ:

# ステップ1: ターミナルから実行してエラーを確認
python main.py

# ステップ2: 依存関係を確認
pip list | grep -E "PyQt6|numpy|scipy|sklearn|matplotlib|pandas"

# ステップ3: Pythonバージョンを確認
python --version  # 3.10以上が必要

一般的な解決策:

解決策A: PyQt6の問題

# PyQt6を再インストール
pip uninstall PyQt6 PyQt6-Qt6 PyQt6-sip
pip install PyQt6

解決策B: 環境変数

# Linux/macOS
export QT_DEBUG_PLUGINS=1
python main.py

# Windows (PowerShell)
$env:QT_DEBUG_PLUGINS=1
python main.py

解決策C: ディスプレイ設定

# Linux リモート接続の場合
export DISPLAY=:0
xhost +

# または Xvfb を使用
xvfb-run python main.py

問題6: 起動後すぐにクラッシュ

症状: スプラッシュスクリーン表示後にクラッシュ

ログを確認:

# ログファイルの場所
# Windows
type %APPDATA%\RamanApp\logs\app.log

# macOS
cat ~/Library/Logs/RamanApp/app.log

# Linux
cat ~/.local/share/RamanApp/logs/app.log

一般的なエラーと解決策:

エラー1: "Qt platform plugin"エラー

This application failed to start because no Qt platform plugin could be initialized

解決策:

# Linux
sudo apt-get install libxcb-xinerama0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-render-util0

# PyQt6を再インストール
pip install --force-reinstall PyQt6

エラー2: "OpenGL"エラー

Could not initialize OpenGL

解決策:

# ソフトウェアレンダリングを使用
export QT_QUICK_BACKEND=software
python main.py

# またはアプリ設定
設定 → グラフィックス → 
「ソフトウェアレンダリングを使用」

エラー3: “Segmentation fault”

Segmentation fault (core dumped)

解決策:

# 1. すべての依存関係を更新
pip install --upgrade numpy scipy matplotlib PyQt6

# 2. 競合するパッケージを削除
pip uninstall PyQt5  # PyQt5とPyQt6の競合

# 3. システムライブラリを更新（Linux）
sudo apt-get update
sudo apt-get upgrade

問題7: ランダムなクラッシュ

症状: 使用中に不定期にクラッシュ

診断:

# デバッグモードで実行
python main.py --debug

# または
python -m pdb main.py

一般的な原因:

メモリ不足

# メモリ使用量を確認
# Linux
free -h

# macOS
vm_stat

# Windows (PowerShell)
Get-Process python | Select-Object WS

解決策: データサイズを減らす、RAMを増やす

スレッディング問題

# 設定で並列処理を無効化
設定 → パフォーマンス → 
「並列処理を使用」のチェックを外す

破損した設定ファイル

# 設定をリセット
# Windows
rd /s "%APPDATA%\RamanApp"

# macOS/Linux
rm -rf ~/.config/RamanApp/

データロード問題

問題8: CSVファイルが読み込めない

症状: "Failed to load file"エラー

診断:

# Pythonで手動確認
import pandas as pd
df = pd.read_csv('your_file.csv')
print(df.head())
print(df.shape)
print(df.dtypes)

一般的な問題と解決策:

問題A: エンコーディングエラー

UnicodeDecodeError: 'utf-8' codec can't decode byte

解決策:

# 異なるエンコーディングを試す
# CSVをUTF-8で再保存

# Excel で:
名前を付けて保存 → CSV UTF-8 (カンマ区切り)

# Python で変換:
import pandas as pd
df = pd.read_csv('file.csv', encoding='latin1')
df.to_csv('file_utf8.csv', encoding='utf-8', index=False)

問題B: 区切り文字の問題

データが1列にまとめられている

解決策:

# セミコロン区切りの場合
df = pd.read_csv('file.csv', sep=';')

# タブ区切りの場合
df = pd.read_csv('file.txt', sep='\t')

# 自動検出
df = pd.read_csv('file.csv', sep=None, engine='python')

問題C: 小数点の問題

数値がNaNになる

解決策:

# カンマが小数点の場合（ヨーロッパ形式）
df = pd.read_csv('file.csv', decimal=',')

# アプリ内設定
設定 → データ → 小数点記号: カンマ

問題D: ヘッダーの問題

列名が正しく認識されない

解決策:

# 正しいフォーマット:
Wavenumber,Sample1,Sample2
400,0.123,0.145
401,0.134,0.156

# 間違ったフォーマット（複数のヘッダー行）:
# Experiment 1
# Date: 2026-01-24
Wavenumber,Sample1,Sample2
400,0.123,0.145

最初のヘッダー行のみを残し、コメント行を削除

問題9: “Memory Error” データロード時

症状: 大きなファイルのロード時にメモリエラー

解決策:

方法1: チャンク読み込み

# 大きなファイルをチャンクで読み込む
import pandas as pd

chunks = []
for chunk in pd.read_csv('large_file.csv', chunksize=1000):
    # 必要な処理
    processed = chunk[chunk['Wavenumber'].between(500, 2000)]
    chunks.append(processed)

df = pd.concat(chunks)

方法2: 波数範囲を制限

データをロード → 
フィルタ → 波数範囲 → 
範囲を指定（例: 500-2000 cm⁻¹）

方法3: ダウンサンプリング

データをロード → 
リサンプル → 
ステップ: 2（2ポイントごと）または 3

方法4: データ型の最適化

# float64 → float32に変換
df = df.astype('float32')

# アプリ設定
設定 → データ → 
「float32を使用（メモリ節約）」

問題10: スペクトルが正しく表示されない

症状: ロード後のスペクトルがおかしい

確認項目:

波数の順序

# 昇順であるべき
wavenumbers = [400, 401, 402, ..., 2000]

# 降順の場合は反転
データ → 変換 → 波数を反転

単位

波数単位: cm⁻¹
強度単位: 任意（自動スケーリング）

外れ値

# 異常な値を確認
データ → 統計 → 
最小値、最大値、中央値を確認

# 外れ値を除去またはクリップ
データ → フィルタ → 
「外れ値を除去」

前処理エラー

問題11: ベースライン補正が機能しない

症状: 適用後もベースラインが残る

診断:

前処理 → プレビュー → 
青線（元）と緑線（処理後）を比較

解決策:

問題A: lambdaが大きすぎる

現在: lambda = 10000000
→ ベースラインが過度に平坦化、ピークも除去

推奨: lambda = 100000

問題B: pが大きすぎる

現在: p = 0.5
→ 非対称性が弱い、ピークがベースラインとして扱われる

推奨: p = 0.01

問題C: 反復回数が不足

設定 → AsLS → 
max_iter: 10（デフォルト）→ 20に増やす

問題D: データが適さない

# 負の値がある場合
データ → 変換 → 
「負の値をゼロに設定」

# または異なる手法を試す
AsLS → AirPLS または Whittaker

問題12: スムージング後にピークが消える

症状: Savitzky-Golay適用後にピークが消失

原因: ウィンドウサイズが大きすぎる

解決策:

# 現在の設定
window = 51  # 大きすぎる！
polyorder = 3

# 推奨設定
window = 11  # ピーク幅の約1/3
polyorder = 2 または 3

# 経験則
ピーク幅が約30ポイント → window = 9-11
ピーク幅が約10ポイント → window = 5-7

段階的調整:

window = 5 で開始（ノイズ多め）
window = 7
window = 11
window = 15（滑らかだがピーク保持）
window = 21（過度に滑らか）

最適なバランスを見つける

問題13: 正規化が期待通りに機能しない

症状: 正規化後もスペクトルのスケールが大きく異なる

診断:

# 正規化前後の統計を確認
データ → 統計 → 
各スペクトルの min, max, mean を確認

問題と解決策:

問題A: 外れ値の影響

1つの外れ値がスケーリングを歪める

解決策:
1. 外れ値を除去
   データ → フィルタ → 外れ値除去
2. ロバストな正規化を使用
   ベクトルノルム → 分位点正規化

問題B: 間違った正規化手法

目的に応じた選択:

探索的分析 → ベクトルノルム
定量分析 → SNV または MSC
比較分析 → 最大値正規化

問題C: 負の値

SNV は負の値があると失敗する可能性

解決策:
1. ベースライン補正を先に実行
2. または Min-Max正規化を使用

問題14: "Singular matrix"エラー

症状:

numpy.linalg.LinAlgError: Singular matrix

原因: 行列が特異（逆行列が存在しない）

一般的な状況:

重複データ

解決策:
データ → 重複を削除

定数列（分散ゼロ）

# すべてのスペクトルで同じ値を持つ波数

解決策:
前処理 → 特徴量選択 → 
「低分散特徴量を除去」
閾値: 0.001

線形従属

いくつかの列が他の列の線形結合

解決策:
分析前にPCAで次元削減:
前処理 → PCA → 
n_components: 50（またはデータサイズに応じて）

サンプル数 < 特徴量数

5サンプル vs 1000波数 → 問題

解決策:
- より多くのサンプルを収集
- PCAで次元削減
- 波数範囲を制限

分析エラー

問題15: PCAで"explained variance"が低い

症状: 最初の2成分で説明分散が50%未満

原因と解決策:

原因A: データのノイズが多い

解決策:
1. 前処理を改善
   - より強いスムージング
   - より良いベースライン補正
2. 外れ値を除去
3. より多くの成分を使用（5-10）

原因B: データが複雑

多くの独立した変動源がある

これは正常な場合もある:
- 生物学的サンプルの自然な変動
- 複雑な混合物
- 多数の化合物

対応:
- より多くの成分を使用
- 非線形手法を試す（UMAP）

原因C: 前処理が不十分

解決策:
ベースライン補正を確認
正規化を確認
スケーリングを追加

問題16: クラスタリングで意味のない結果

症状: すべてのサンプルが1つのクラスターに、または各サンプルが別々のクラスター

診断:

1. スコアプロット（PCA/UMAP）を確認
   → 視覚的な分離があるか？

2. デンドログラム（階層的）を確認
   → 自然なグループがあるか？

3. シルエットスコアを確認
   → スコア > 0.5 が良好

解決策:

問題A: パラメータが不適切

K-means:
- k が大きすぎる → 減らす
- k が小さすぎる → 増やす
→ エルボー法で最適なkを決定

DBSCAN:
- eps が大きすぎる → すべて1クラスター
- eps が小さすぎる → すべて外れ値
→ k-距離プロットで調整

問題B: 前処理が不適切

クラスタリングはスケールに敏感

解決策:
1. 適切な正規化（StandardScaler）
2. PCAで前処理（オプション）

問題C: データが実際にクラスターを持たない

すべてのサンプルが連続的な分布

対応:
- 階層的クラスタリングを使用
- デンドログラムで構造を確認
- 連続的な変動として扱う

問題17: 統計検定で"すべてのp値が有意"

症状: 数千の波数すべてでp < 0.05

原因: 多重比較問題

解決策:

分析 → 統計検定 → 
多重比較補正を有効化:

オプション1: Bonferroni（保守的）
  α_adjusted = 0.05 / n_tests
  例: 1000検定 → α = 0.00005

オプション2: FDR（False Discovery Rate）
  より緩やか、より多くの発見
  q値 < 0.05 を使用

オプション3: FWERコントロール
  Holm-Bonferroni法

結果の解釈:

補正後:
- 有意な波数が少数 → 真の差
- 依然として多数が有意 → 強い差がある
- 有意な波数なし → 差があるがわずか

機械学習問題

問題18: モデルの精度が非常に低い（<60%）

症状: トレーニング精度もテスト精度も低い → 過小適合

診断:

# 学習曲線を確認
機械学習 → 評価 → 学習曲線

両方のスコアが低く平坦 → 過小適合

解決策:

ステップ1: 前処理を改善

現在の前処理を確認:
- ベースライン補正は適用済みか？
- 正規化は適用済みか？
- ノイズは除去したか？

推奨パイプライン:
1. AsLS (lambda=100000)
2. Savitzky-Golay (window=11)
3. SNV
4. （オプション）一次微分

ステップ2: より複雑なモデルを使用

現在: ロジスティック回帰（線形）
→ Random Forest または XGBoost（非線形）

または
SVM でカーネルを変更:
linear → rbf または poly

ステップ3: 特徴量を増やす

現在: PCAで10成分のみ
→ 50-100成分に増やす

または PCA を使用しない

ステップ4: ハイパーパラメータを調整

機械学習 → 設定 → 
グリッドサーチを有効化

Random Forest:
- n_estimators: 100 → 500
- max_depth: None（無制限）
- min_samples_split: 2 → 5

問題19: トレーニング精度99%、テスト精度60% → 過学習

症状: トレーニングとテストの大きな差

診断:

過学習の兆候:
✓ 訓練精度 >> テスト精度
✓ 学習曲線: 訓練誤差減少、検証誤差増加
✓ CV スコアの分散が大きい

解決策:

ステップ1: データを増やす

最も効果的だが、常に可能とは限らない

可能なら:
- より多くのサンプルを収集
- データ拡張（ノイズ追加など）

ステップ2: 正則化を増やす

Random Forest:
- max_depth を制限: None → 10
- min_samples_leaf を増やす: 1 → 5
- max_features を減らす: 'auto' → 'sqrt'

SVM:
- C を減らす: 1.0 → 0.1
- gamma を減らす: 'auto' → 0.001

XGBoost:
- reg_lambda を増やす: 0 → 1.0
- reg_alpha を増やす: 0 → 0.5
- max_depth を制限: 6 → 3

ステップ3: 特徴量を減らす

PCA で次元削減:
1000波数 → 50主成分

または特徴量選択:
- 分散閾値法
- 相互情報量
- RFE（再帰的特徴削減）

ステップ4: クロスバリデーションを使用

機械学習 → 設定 → 
クロスバリデーション: 5-fold

結果が安定していることを確認

ステップ5: 早期停止（XGBoost/NNの場合）

XGBoost設定:
early_stopping_rounds = 10
eval_metric = 'mlogloss'
eval_set = [(X_val, y_val)]

問題20: “ValueError: Found input variables with inconsistent numbers of samples”

症状:

ValueError: Found input variables with inconsistent numbers of samples: [100, 80]

原因: Xとyのサンプル数が一致しない

診断:

print(f"X shape: {X.shape}")  # (100, 1000)
print(f"y shape: {y.shape}")  # (80,)
→ サンプル数が一致しない！

一般的な原因と解決策:

原因A: ラベルの欠落

一部のサンプルにラベルがない

解決策:
1. データ → グループ → 
   すべてのサンプルがグループに属していることを確認

2. または欠落サンプルを除去

原因B: フィルタリングの不一致

データをフィルタしたが、ラベルは更新しなかった

解決策:
フィルタ操作後にデータとラベルを同期

原因C: データ分割エラー

# 間違い
X_train, X_test = train_test_split(X, test_size=0.3)
y_train, y_test = train_test_split(y, test_size=0.3)
→ 異なるランダムシードで分割される

# 正しい
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.3, random_state=42
)

問題21: XGBoostが非常に遅い

症状: トレーニングに数時間かかる

原因と解決策:

原因A: tree_methodが最適でない

# 遅い（デフォルト）
tree_method = 'auto'

# 高速（GPUがある場合）
tree_method = 'gpu_hist'

# 高速（CPUの場合）
tree_method = 'hist'

# アプリ内設定
機械学習 → XGBoost → 設定 → 
tree_method: 'hist'

原因B: ハイパーパラメータ探索が広すぎる

# グリッドサーチの範囲を制限
機械学習 → 設定 → グリッドサーチ → 
パラメータ数を減らす

# 例
n_estimators: [50, 100]  # [50, 100, 200, 500] の代わりに
max_depth: [3, 5]        # [3, 5, 7, 10] の代わりに

原因C: データサイズが大きい

解決策:
PCAで特徴量を削減: 1000 → 100
サンプリング: 全データの80%でトレーニング
早期停止を使用

原因D: n_estimatorsが大きすぎる

# 現在
n_estimators = 1000  # 遅い

# 推奨（早期停止と組み合わせ）
n_estimators = 100-300
early_stopping_rounds = 10

パフォーマンス問題

問題22: UI がフリーズする

症状: 処理中にUIが応答しない

原因: メインスレッドでの重い計算

回避策:

設定 → パフォーマンス → 
「バックグラウンド処理を使用」にチェック

一時的な解決策:

- 処理の進行を待つ（進行状況バーが表示される）
- 強制終了しない（データが失われる可能性）

恒久的な解決策:

より小さなデータセットでテスト
プレビューを無効化
より高速なアルゴリズムを使用

問題23: メモリ使用量が増え続ける

症状: アプリが時間とともに遅くなる

原因: メモリリーク

診断:

# メモリ使用量を監視
# Linux
watch -n 1 'ps aux | grep python'

# Windows (PowerShell)
while($true) {
    Get-Process python | Select-Object WS; 
    Start-Sleep 1
}

解決策:

短期的:

定期的にアプリを再起動
ファイル → 再起動

長期的:

1. 不要なデータをクリア
   データ → クリア → 
   「前処理済みデータをクリア」

2. 結果をエクスポートしてからクリア

3. キャッシュをクリア
   設定 → キャッシュ → クリア

4. ガベージコレクションを強制
   設定 → パフォーマンス → 
   「定期的なガベージコレクション」

問題24: 大きなファイルのエクスポートが遅い

症状: Excelエクスポートに10分以上かかる

解決策:

方法1: より高速なフォーマットを使用

Excel → CSV に変更
（10倍高速）

方法2: エクスポートを分割

1. データを複数のファイルに分割
   - data_part1.xlsx (1-1000行)
   - data_part2.xlsx (1001-2000行)

2. または必要なシートのみエクスポート

方法3: 圧縮を無効化

エクスポート → オプション → 
「圧縮を無効化」にチェック

方法4: 形式を見直す（大規模データ）

大規模データの場合は、まず CSV ではなく PKL（pickle）などの形式を検討してください。
※ HDF5 形式のエクスポートは現時点では未対応です。

UI/表示問題

問題25: 図が表示されない

症状: 空白の図エリア

診断:

# Matplotlibバックエンドを確認
python -c "import matplotlib; print(matplotlib.get_backend())"

# 期待される出力: Qt5Agg または Qt6Agg

解決策:

方法1: バックエンドを変更

# matplotlibrcファイルを編集
# Linux/macOS: ~/.matplotlib/matplotlibrc
# Windows: %USERPROFILE%\.matplotlib\matplotlibrc

backend: Qt6Agg

# またはコード内
import matplotlib
matplotlib.use('Qt6Agg')

方法2: ソフトウェアレンダリング

設定 → グラフィックス → 
「ソフトウェアレンダリングを使用」

方法3: Matplotlibを再インストール

pip uninstall matplotlib
pip install matplotlib

問題26: フォントが正しく表示されない

症状: 文字化けまたは□が表示される

原因: 必要なフォントがない

解決策:

Windows:

# 日本語フォントをインストール
設定 → 時刻と言語 → 言語 → 
日本語 → オプション → フォントを追加

macOS:

# システムフォントを使用
設定 → フォント → 
「システムフォントを使用」

Linux:

# 日本語フォントをインストール
sudo apt-get install fonts-noto-cjk

# フォントキャッシュを更新
fc-cache -fv

# Matplotlibキャッシュをクリア
rm -rf ~/.cache/matplotlib

アプリ内設定:

設定 → 外観 → フォント → 
日本語対応フォントを選択:
- Noto Sans CJK JP
- MS Gothic (Windows)
- Hiragino Sans (macOS)

問題27: ハイDPI画面で表示が小さい

症状: 4Kモニターでテキストやボタンが小さすぎる

解決策:

Windows:

# アプリケーション設定
設定 → 外観 → スケーリング → 
150% または 200%

# またはシステム設定
設定 → システム → ディスプレイ → 
拡大/縮小レイアウト: 150%

macOS:

# Retinaディスプレイで自動的に調整されるはず

# 問題がある場合:
システム環境設定 → ディスプレイ → 
解像度: スケーリング

Linux:

# 環境変数を設定
export QT_SCALE_FACTOR=1.5

# または ~/.bashrc に追加
echo 'export QT_SCALE_FACTOR=1.5' >> ~/.bashrc

# アプリ内
設定 → 外観 → スケーリング → 150%

エクスポート問題

問題28: Excelエクスポートが失敗する

症状: “Failed to export to Excel”

診断:

# openpyxl がインストールされているか確認
pip list | grep openpyxl

# インストールされていない場合
pip install openpyxl

一般的な問題:

問題A: Excelファイルが開いている

エラー: Permission denied

解決策:
1. Excelを閉じる
2. 別の名前で保存

問題B: パスに特殊文字

ファイル名: results (2).xlsx
→ 括弧が問題を引き起こす可能性

解決策:
英数字とアンダースコアのみ使用:
results_2.xlsx

問題C: ディスク容量不足

確認:
# Linux/macOS
df -h

# Windows
wmic logicaldisk get size,freespace,caption

解決策:
不要なファイルを削除、または別のドライブに保存

問題29: 図のエクスポート品質が悪い

症状: 保存したPNG画像がぼやけている

解決策:

方法1: DPIを上げる

図を右クリック → 画像として保存 → 
DPI: 300（印刷用）または 600（高品質）

デフォルト: 100（画面用）

方法2: ベクトル形式を使用

フォーマット: PNG → SVG
（拡大縮小しても品質維持）

方法3: サイズを大きくする

図の設定 → サイズ → 
幅: 3000 pixels
高さ: 2000 pixels

方法4: アンチエイリアスを有効化

設定 → グラフィックス → 
「高品質レンダリング」にチェック

プラットフォーム固有の問題

Windows固有

問題30: “VCRUNTIME140.dll が見つかりません”

解決策:

Visual C++ Redistributable をダウンロード
   https://aka.ms/vs/17/release/vc_redist.x64.exe

インストーラーを実行

アプリを再起動

問題31: Windows Defenderがブロック

症状: “WindowsによってPCが保護されました”

解決策:

「詳細情報」をクリック
「実行」をクリック

または

Windows Defender → 除外 → 
アプリケーションフォルダを追加

macOS固有

問題32: “開発元を確認できないため開けません”

解決策:

# ターミナルで
sudo xattr -cr /Applications/RamanApp.app

# または
sudo xattr -rd com.apple.quarantine /Applications/RamanApp.app

その後:

システム環境設定 → セキュリティとプライバシー → 
「このまま開く」をクリック

問題33: macOS Big Sur以降でクラッシュ

原因: Rosetta 2の問題（M1/M2 Macの場合）

解決策:

# Rosetta 2をインストール
softwareupdate --install-rosetta

# またはネイティブARMバージョンを使用
（注）pip での配布は現時点では未対応です。

Linux固有

問題34: "libGL error"エラー

症状:

libGL error: No matching fbConfigs or visuals found
libGL error: failed to load driver: swrast

解決策:

# Ubunt/Debian
sudo apt-get install libgl1-mesa-glx libgl1-mesa-dri

# Fedora
sudo dnf install mesa-libGL mesa-dri-drivers

# Arch
sudo pacman -S mesa

問題35: Wayland vs X11の問題

症状: アプリが起動しない（Wayland使用時）

解決策:

# X11を強制使用
export QT_QPA_PLATFORM=xcb
python main.py

# または ~/.bashrc に追加
echo 'export QT_QPA_PLATFORM=xcb' >> ~/.bashrc

🆘 それでも解決しない場合

ログの収集

# 1. ログファイルを見つける
# Windows
type %APPDATA%\RamanApp\logs\app.log

# macOS
cat ~/Library/Logs/RamanApp/app.log

# Linux
cat ~/.local/share/RamanApp/logs/app.log

# 2. 詳細ログを有効化
python main.py --debug --log-level DEBUG > debug.log 2>&1

バグレポートの作成

GitHub Issueを作成する際に含めるべき情報:

**環境**
- OS: [Windows 11 / macOS 13 / Ubuntu 22.04]
- Pythonバージョン: [3.10.8]
- アプリバージョン: [1.0.0]
- インストール方法: [pip / 実行可能ファイル / ソース]

**問題の説明**
何が起こったかを明確に説明

**再現手順**
1. データをロード
2. AsLS を適用
3. PCA を実行
4. → エラー発生

**期待される動作**
何が起こるべきだったか

**実際の動作**
何が実際に起こったか

**エラーメッセージ**

完全なエラーメッセージを貼り付け

**ログ**

関連するログエントリを貼り付け

**スクリーンショット**
可能であれば添付

サポートを受ける

GitHub Issues: https://github.com/zerozedsc/Raman-Spectroscopy-Analysis-Application/issues
GitHub Discussions: https://github.com/zerozedsc/Raman-Spectroscopy-Analysis-Application/discussions

📚 関連リソース

FAQ - よくある質問
ユーザーガイド - 完全な使用ガイド
インストールガイド - 詳細なインストール手順
開発ガイド - 開発者向け情報

最終更新: 2026年1月24日