XRD_GUI.py 技術ドキュメント

プログラムの動作

XRD_GUI.py は、X線回折 (XRD) データを視覚的に解析するためのグラフィカルユーザーインターフェース (GUI) ツールです。複数のXRDデータファイルとリファレンス（標準ピークデータ）を同時に読み込み、重ね合わせて表示することで、データの比較や解析を効率化します。

主な機能:

  • XRDデータ読み込みと表示: 複数のXRDデータファイル（2θ/θ角 vs 強度）を読み込み、折れ線グラフとして上部パネルに表示します。

  • リファレンスデータ読み込みと表示: 複数の標準ピークデータファイル（H, K, L, 2θ/θ角, 相対強度）を読み込み、ステムプロットとして下部パネルに表示します。

  • グラフのカスタマイズ:

    • Y軸スケール: データおよびリファレンスそれぞれで、線形、平方根、対数スケールを選択できます。

    • オフセット: 複数のデータセットやリファレンスを比較しやすいように、手動または自動で垂直方向のオフセットを調整できます。

    • 色と線幅: 各データセットやリファレンスの色、線の太さを個別に設定できます。カラースケールの一括適用も可能です。

    • 軸ラベルと凡例: X軸/Y軸のラベルテキスト、凡例の表示/非表示を切り替えられます。

    • フォント設定: グラフ全体のフォントの種類とサイズを変更できます。

  • 表示モード切り替え:

    • 2画面モード: XRDデータとリファレンスデータを上下に分けて表示し、X軸を共有します。上下プロットの高さ比率を調整可能です。

    • 1画面モード: リファレンスを非表示にし、XRDデータのみを単一のグラフで表示します。

  • ピークフィルタリング: リファレンスデータに対し、Miller指数 (h, k, l) やi値を用いた条件式（例: l==0）でピークをフィルタリングし、表示するピークを限定できます。

  • ズームとパン: グラフのX軸、Y軸範囲をマウス操作や数値入力で調整できます。X軸は特定の範囲にロックすることも可能です。

  • マーカー機能: ピーク付けモードを有効にすることで、リファレンスのピークにスナップしたり、手動で指定した位置にマーカーを設置し、そのシンボル、色、高さをカスタマイズできます。

  • セッションの保存と読み込み: 現在のアプリケーションの状態（読み込まれたデータ、リファレンス、UI設定）をJSONファイルとして保存・復元できます。

  • グラフのエクスポート: 表示されているグラフをPNG, JPEG, SVG, PDFなどの画像・ベクタ形式で保存できます。

  • ドラッグ＆ドロップ: データファイルやリファレンスファイルをGUIウィンドウにドラッグ＆ドロップして読み込めます。

解決する課題:

研究者が複数のXRDパターンを相互に比較したり、理論的なピーク位置（リファレンス）と実験データを照合したりする際に、柔軟な可視化とインタラクティブな操作を提供することで、データの解釈と分析を支援します。特に、Y軸のスケール調整やオフセット、ピークのフィルタリング機能は、複雑なXRDパターンから特定の情報を取り出す際に有効です。

原理

1. XRDデータとリファレンスデータの表示

  • XRDデータ: 角度 (2θ/θ) をX軸、強度をY軸とする通常の2次元線グラフで描画されます。NumPy配列としてデータを内部で保持し、Matplotlibの plot 関数を使用して表示されます。

  • リファレンスデータ: 角度をX軸、相対強度をY軸とするステムプロットで描画されます。各リファレンスは独立したベースラインから始まり、相対強度がプロット高さに変換されます。Matplotlibの stem 関数が用いられます。

2. Y軸スケールとオフセット

プログラムは、データとリファレンスに対して独立してY軸のスケールとオフセットを適用します。

  • Y軸スケール:

    • 線形 (Linear): 測定された強度値をそのままプロットします。

    • 平方根 (Square Root): 強度値 \(I\) を \(\sqrt{I}\) としてプロットします。これにより、ノイズの大きい低強度領域が相対的に拡大され、ノイズのばらつきが均一に見える効果があります。

    • 対数 (Logarithmic): 強度値 \(I\) を \(\log_{10}(I)\) としてプロットします。広範囲の強度変化を一度に視覚化するのに適しています。0以下の強度は対数を取れないため、設定に応じて1に置換されるオプションがあります。

  • データセットの自動オフセット調整 (_recompute_dataset_offsets_for_scale): 複数のデータセットを読み込んだ際、それぞれのデータが重なりすぎずに視覚的に分離されるよう、自動的にY軸オフセットが計算されます。

    1. まず、各データセットのY軸方向の「厚み」（例えば、強度範囲の1%点から99%点）を推定します。この際、対数スケールであれば対数変換後の値で、線形スケールであれば線形値で計算します。

    2. これらの厚みのメディアン値から、データセット間の推奨オフセットステップを決定します（デフォルトはステップ値の1.2倍）。

    3. 各データセットは、リストの表示順に基づいて、このステップ量だけY軸方向にシフトされます。

      • 線形/平方根スケール: 強度値に直接オフセット値が加算されます。

      • 対数スケール: 強度値に \(10^{\text{offset}}\) が乗算されます。これにより、対数空間での垂直シフト（見かけ上の加算）を実現します。 $\(I_{\text{plot}} = I_{\text{original}} \times 10^{\text{offset}_{\text{log}}}\)$

3. リファレンスのピークフィルタリング

ユーザーが入力した条件式に基づき、表示されるリファレンスピークをフィルタリングする機能です。

  • 利用可能な変数: h, k, l (Miller指数), i (リファレンスファイルから抽出された追加の指数、例えば六方晶系の\(-(h+k)\)など) を条件式内で使用できます。

  • 安全な式評価 (_safe_evaluate_filter): ユーザーが任意のPythonコードを入力することを防ぐため、標準の eval() 関数は使用せず、ast (抽象構文木) モジュールを用いた安全な評価メカニズムが導入されています。

    1. 入力された条件式はまず ast.parse() で構文解析され、抽象構文木が生成されます。

    2. _eval_node ヘルパー関数がこの構文木を再帰的に走査し、各ノードを評価します。

    3. 評価は、事前に定義されたホワイトリスト（許可された演算子、関数、変数）に厳密に従います。例えば、__import__, os.system などの危険な関数は許可されません。

    4. 計算負荷の高い操作（例: pow() 関数の指数が極端に大きい場合）に対するDoS（Denial of Service）攻撃を防ぐための制限も組み込まれています。

    5. これにより、ユーザーは k==0 and l==0 や abs(h)+abs(k)+abs(l) > 3 といったフィルタ式を安全に適用できます。

4. マーカー機能

  • ピーク付けモード: このモードが有効な場合、マウスが下部リファレンスグラフ上のピークにホバーすると、最も近いピークのH,K,L指数と2θ値がツールチップとして表示されます。

  • ピークスナップと追加: ピーク付けモード中にリファレンスグラフをクリックすると、ホバー中のピーク情報が自動的に取得され、その位置にマーカーが選択中のXRDデータセットに追加されます。手動でX軸位置を指定してマーカーを追加することも可能です。

  • マーカーの高さ調整: マーカーのY軸位置は、対象のデータセットのローカルなピーク最大値から、marker_offset_percent で指定された割合だけ上にオフセットされます。

    • 線形スケール: 強度範囲のパーセンテージとしてオフセットを加算。 $\(Y_{\text{marker}} = Y_{\text{peak}} + (\max(Y_{\text{data}}) - \min(Y_{\text{data}})) \times \frac{\text{offset}_{\%}}{100}\)$

    • 対数スケール: 強度値に対して割合を乗算。 $\(Y_{\text{marker}} = Y_{\text{peak}} \times (1 + \frac{\text{offset}_{\%}}{100} \times 5)\)$ （対数スケールではオフセットが小さく見えがちなので、線形スケールよりも大きめの係数（x5）でオフセットを強調しています。） これにより、Y軸のスケールやデータセット全体のオフセットに関わらず、マーカーがピークの上部に適切な相対位置で描画されます。

必要な非標準ライブラリとインストール方法

XRD_GUI.py を実行するためには、以下のPythonライブラリが必要です。

  • numpy: 高性能な数値計算

  • matplotlib: グラフ描画

  • PyQt6: GUIフレームワーク

  • pandas: データ処理（特にファイル解析補助や内部処理で利用されることがあります）

これらのライブラリは pip を使ってインストールできます。

pip install numpy matplotlib pyqt6 pandas

補足: XRD_GUI_lib.py という外部ライブラリが存在する場合は、XRDデータのパース処理をそちらに委譲するようになっています。このドキュメントでは、XRD_GUI_lib.py が存在しない場合の挙動を主に記述しています。

必要な入力ファイル

1. XRDデータファイル

  • 形式: テキストファイル (.txt が推奨されますが、Matplotlibが読み込める形式であれば可)。

  • 内容: ヘッダー行の後に、主に2列の数値データが続く形式を想定しています。

    • 1列目: 2θ/θ角 (度)

    • 2列目: 強度 (任意単位)

  • プログラムによるパースの挙動:

    • ファイル名がデフォルトのサンプル名として使用されます。

    • ヘッダー内の "Sample" で始まる行からサンプル名を抽出する試みが行われます。

    • "Step" または "ScanSpeed" というキーワードを含む行の次から、数値データ（2θと強度）の読み込みを開始します。

  • 例:

    Sample  MySample_1
Comment  XRD pattern of ZnO thin film
Measurement Date  2023-01-15
Step    0.01
2theta  Intensity  Counts
10.000  100.5
10.010  102.3
10.020  105.1
...

2. リファレンスファイル

  • 形式: テキストファイル (.txt が推奨)。

  • 内容: XRDピークのリファレンス情報を含むピークリスト。

    • 最低限、Miller指数 (h, k, l) と 2θ/θ角、相対強度が必要です。

  • プログラムによるパースの挙動:

    • ファイル名がデフォルトのリファレンス名として使用されます。

    • ヘッダー行に "h", "k", "l" が含まれている場合、それをヘッダーとして認識します。

    • データ列として、2θ/θ角と強度を自動的に判別して読み込もうとします（"2θ", "2theta", "Intensity", "I" などのキーワードを検索）。

  • 例:

    h   k   l   2theta  Intensity
1   1   1   28.452  100.00
2   0   0   33.001  80.50
2   2   0   47.300  50.25
2   2   2   56.123  30.10
...

3. セッションファイル

  • 形式: JSONファイル (.json)。

  • 内容: 過去の作業状態を保存したファイル。読み込むと、以前ロードしたXRDデータ、リファレンス、およびUI設定（Y軸スケール、オフセット、フォント、ズーム範囲など）が復元されます。特別な形式は不要で、GUIの「セッション読み込み」機能から選択します。

生成される出力ファイル

1. グラフ画像ファイル

  • 形式:

    • PNG (.png)

    • JPEG (.jpg, .jpeg)

    • SVG (.svg)

    • PDF (.pdf)

  • 内容: 現在GUIに表示されているグラフの画像またはベクターデータ。PNG形式の場合、背景が透過で保存されます。解像度は300dpiで保存されます。

2. セッションファイル

  • 形式: JSONファイル (.json)。

  • 内容: 現在のアプリケーションの状態を完全に保存します。これには、読み込まれたXRDデータ（元の強度とX軸データ）、リファレンスデータ（ピーク位置、強度、H, K, L指数）、各データの色や線幅、Y軸オフセット、および全てのUI設定（Y軸スケール、凡例表示、フォント、フィルタ条件、グラフの縦横比など）が含まれます。このファイルを読み込むことで、以前の作業状態を正確に復元できます。

コマンドラインでの使用例 (Usage)

XRD_GUI.py はGUIアプリケーションであるため、特別な引数を必要とせず、直接Pythonインタープリタで実行します。

python XRD_GUI.py

コマンドラインでの具体的な使用例

XRD_GUI.py はGUIアプリケーションであり、コマンドライン引数を受け取って動作を制御する設計にはなっていません。すべての操作はGUIを通じて行われます。

例1: プログラムの起動

  • コマンド:

    python XRD_GUI.py

  • 実行結果の説明: コマンドを実行すると、まず必要なPythonライブラリ (numpy, matplotlib, PyQt6, pandas) がインストールされているかどうかのチェックが行われます。不足しているライブラリがある場合は、pip install コマンドを含むエラーメッセージが表示され、プログラムは終了します。 すべてのライブラリが揃っている場合、「XRD分析グラフツール」というタイトルを持つGUIウィンドウが起動し、XRDデータやリファレンスを読み込む準備が整います。

例2: XRDデータの読み込み (GUI操作)

  1. GUIの操作: プログラム起動後、左側のコントロールパネルにある「ファイル操作」グループ内の「XRDデータ読み込み」ボタンをクリックします。

  2. ファイル選択ダイアログ: 開いたファイル選択ダイアログで、XRDデータファイル（例: my_sample.txt）を選択し、「開く」をクリックします。

  3. 実行結果の説明: 選択されたXRDデータが解析され、グラフの上部パネルにプロットされます。同時に、左側の「データリスト」にそのデータセットの名前（例: my_sample）が追加されます。グラフは自動的にX軸とY軸の範囲を調整し、読み込んだデータ全体を表示するように更新されます。

例3: リファレンスデータの読み込みとフィルタリング (GUI操作)

  1. GUIの操作: プログラム起動後、「ファイル操作」グループ内の「リファレンス読み込み」ボタンをクリックします。

  2. ファイル選択ダイアログ: リファレンスファイル（例: ref_pattern.txt）を選択し、「開く」をクリックします。

  3. フィルタ条件の入力: 左側の「リファレンスリストと操作」グループ内にある「ピークフィルタ」の入力欄に、特定の条件式（例: l==0）を入力し、その隣にある「適用」ボタンをクリックします。

  4. 実行結果の説明: リファレンスデータが解析され、グラフの下部パネルにステムプロットとして表示されます。その後、入力したフィルタ条件 l==0 が適用され、Miller指数 l が0であるピークのみがグラフに表示されるように更新されます。例えば、bcc構造の(110), (200), (211)ピークのうち、(200)ピーク（\(l=0\)）のみが強調されるといった形で視覚的に確認できます。