xrd_fit.py のMarkdownドキュメントを以下に示します。
# ``xrd_fit.py``
## 概要
このスクリプトは、実験的に測定されたX線回折（XRD）パターンと、結晶構造情報ファイル（CIF）から計算された理論的なXRDパターンを比較・分析するためのツールです。主な機能として、パターンプロット、相関分析、オーバーラップチェック、およびLASSO回帰による混合相の定量フィッティングを提供します。
## 詳細説明
本スクリプトは、様々なモードでXRDデータ解析を実行します。
- ``plot_all``: 実験XRDパターンと各CIF由来の理論XRDパターンを個別のグラフに表示します。
- ``plot_one``: 実験XRDパターンと各CIF由来の回折ピーク位置を一つのグラフに表示します。
- ``plot_one2``: 実験XRDパターンと各CIF由来の理論XRDパターンを一つのグラフに表示します。
- ``overwrap``: 異なるCIFパターン間のオーバーラップ（重なり）を評価します。
- ``CIFcorrelation``: CIFパターン間の相関係数を評価します。
- ``correlation``: 実験パターンとCIFパターン間の相関係数を評価します。
- ``fit``: LASSO回帰を用いて実験パターンを背景とCIFパターンでフィッティングし、各相の寄与を定量化します。
スマアリング（ブロードニング）効果や背景処理もサポートしています。
## 関連リンク
xrd_fit_usage
## 非標準ライブラリ
本プログラムは以下の非標準ライブラリに依存しています。
- ``tklib``:
- ``tklib.tkapplication``
- ``tklib.tkfile``
- ``tklib.tkutils``
- ``tklib.tkvariousdata``
- ``tklib.tksci.tksci``
- ``tklib.tksci.tkmatrix``
- ``tklib.tkcrystal.tkxrd``
- ``tklib.tkgraphic.tkplotevent``
## コマンドライン引数
``xrd_fit.py`` は以下のコマンドライン引数を取ります。引数の順序は固定されています。
| 引数番号 | 変数名 | 型 | 説明 | デフォルト値 |
| :------- | :------------ | :------ | :------------------------------------------------------ | :-------------------- |
| 1 | ``mode`` | str | 実行モード (``plot``, ``overwrap``, ``fit`` など) | ``plot`` |
| 2 | ``plugin_dir`` | str | プラグインディレクトリのパス | ``filter`` |
| 3 | ``infile`` | str | 入力実験XRDデータファイルのパス | ``*.txt`` |
| 4 | ``cif_files`` | str | CIFファイル群へのパスまたはワイルドカード | ``data/*.*`` |
| 5 | ``wavelength`` | str | X線波長の種類 (例: ``CuKa``) | ``CuKa`` |
| 6 | ``xmin`` | float | 2$\theta$の最小値 | ``20.0`` |
| 7 | ``xmax`` | float | 2$\theta$の最大値 | ``120.0`` |
| 8 | ``xstep`` | float | 2$\theta$のステップ幅 | ``0.02`` |
| 9 | ``fwhm`` | float | 回折ピークの半値幅 (FWHM) | ``0.2`` |
| 10 | ``Gfraction`` | float | ガウス成分の割合 (0.0:ローレンツ, 1.0:ガウス) | ``0.5`` |
| 11 | ``fwhm_smear`` | float | スマアリングに用いるFWHM | ``0.0`` |
| 12 | ``Gfraction_smear`` | float | スマアリングに用いるガウス成分の割合 | ``0.0`` |
| 13 | ``yscale`` | str | Y軸のスケール (``linear`` または ``log``) | ``linear`` |
| 14 | ``BGorder`` | int | 背景多項式の次数 | ``3`` |
| 15 | ``alpha`` | float | LASSO回帰の正則化パラメータ | ``0.1`` |
## グローバルパラメータ
スクリプト内で定義されているグローバルパラメータは以下の通りです。
- ``module_names``: ロードされたモジュール名のリスト (初期値: 空リスト ``[]``)。
- ``modules``: ロードされたモジュールオブジェクトのリスト (初期値: 空リスト ``[]``)。
- ``markers``: プロットに使用するマーカーシンボルのリスト。
- ``['o', 's', '+', 'x', 'D', 'v', '^', '<', '>', '8', 'h', 'H']``
- ``colors``: プロットに使用する色のリスト。
- ``['black', 'red', 'blue', 'darkgreen', 'darkorange', 'hotpink', 'lightgreen', 'cyan', 'yellow', 'magenta', 'chocolate', 'navy', 'slategray', 'olive']``
- ``figsize``: 標準のフィギュアサイズ。
- ``(12, 8)``
- ``figsize_one``: 単一プロット用のフィギュアサイズ。
- ``(10, 6)``
- ``figsize_coeff``: 係数プロット用のフィギュアサイズ。
- ``(8, 6)``
- ``fontsize``: プロットのフォントサイズ。
- ``12``
- ``legend_fontsize``: 凡例のフォントサイズ。
- ``8``
- ``legend_fontsize_one``: 単一プロットの凡例のフォントサイズ。
- ``12``
## 関数説明
### ``usage()``
コマンドライン引数の使い方を表示する。
**詳細説明:**
アプリケーションとパラメータオブジェクトから利用方法文字列を取得し、整形して標準出力に出力する。
**引数:**
- ``app``: ``tkApplication`` のインスタンス。
- ``cparams``: 設定パラメータを保持するオブジェクト。
**戻り値:**
なし
### ``initialize()``
アプリケーションのパラメータを初期値で設定する。
**詳細説明:**
デバッグフラグ、プラグインディレクトリ、モード、入力ファイルパス、CIFファイルパス、X線波長、2$\theta$範囲、FWHM、ガウス比率、Yスケール、背景次数、LASSOのalphaなどの初期値を設定する。
**引数:**
- ``app``: ``tkApplication`` のインスタンス。
- ``cparams``: 設定パラメータを保持するオブジェクト。
**戻り値:**
なし
### ``update_vars()``
コマンドライン引数に基づいて設定パラメータを更新する。
**詳細説明:**
``sys.argv`` から引数を取得し、``cparams`` オブジェクトの対応する属性に設定する。数値型引数は適切な型に変換される。
**引数:**
- ``app``: ``tkApplication`` のインスタンス。
- ``cparams``: 設定パラメータを保持するオブジェクト。
**戻り値:**
なし
### ``read_file()``
指定されたパスのファイルを読み込み、その内容を処理する。
**詳細説明:**
登録されているモジュールを順に試行し、ファイルのタイプを判別する。ファイルタイプが一致したモジュールを使用してデータを読み込み、必要に応じて変換する。
**引数:**
- ``path``: str. 読み込むファイルのパス。
- ``app``: ``tkApplication`` のインスタンス。
- ``cparams``: 設定パラメータを保持するオブジェクト。
**戻り値:**
tuple. (``module``, ``inf``). ``module`` はファイルを読み込んだモジュールオブジェクト、``inf`` は読み込まれたデータを含む辞書。ファイルが読み込めない場合は (``None``, ``None``).
### ``read_all_files()``
入力XRDファイルとすべてのCIFファイルを読み込む。
**詳細説明:**
``cparams.infile`` で指定された入力XRDファイルを読み込み、その2$\theta$範囲に基づいて解析範囲を調整する。``cparams.cif_files`` で指定されたマスクに一致するCIFファイルをすべて読み込み、変換処理を行う。``input_only`` が ``True`` の場合、入力ファイルのみを読み込む。
**引数:**
- ``app``: ``tkApplication`` のインスタンス。
- ``cparams``: 設定パラメータを保持するオブジェクト。
- ``input_only``: bool. ``True`` の場合、入力ファイルのみを読み込む。
**戻り値:**
dict. 読み込まれたモジュールとデータを含む辞書。キーは ``"module_input"``, ``"module_cif"``, ``"inf_input"``, ``"inf_cif_list"``。
### ``max_none()``
``None`` 値を含むリストまたはイテラブルの最大値を返す。
**詳細説明:**
入力されたリスト ``x`` の要素から ``None`` を除外し、残りの数値の最大値を計算する。数値要素が一つもない場合は、非常に小さい負の値を返す。
**引数:**
- ``x``: list or iterable. 数値と ``None`` を含むリストまたはイテラブル。
**戻り値:**
float. 最大値。
### ``min_none()``
``None`` 値を含むリストまたはイテラブルの最小値を返す。
**詳細説明:**
入力されたリスト ``x`` の要素から ``None`` を除外し、残りの数値の最小値を計算する。数値要素が一つもない場合は、非常に大きい正の値を返す。
**引数:**
- ``x``: list or iterable. 数値と ``None`` を含むリストまたはイテラブル。
**戻り値:**
float. 最小値。
### ``normalize_none()``
``None`` 値を含むリストの要素を指定された範囲に正規化する。
**詳細説明:**
リスト ``l`` の数値要素を ``[vmin, vmax]`` の範囲から ``[Amin, Amax]`` の範囲に線形変換して正規化する。``vmin`` または ``vmax`` が指定されない場合は、リスト内の ``None`` 以外の要素から自動的に計算される。``None`` 値は変更されない。
**引数:**
- ``l``: list. 数値と ``None`` を含むリスト。
- ``Amin``: float. 正規化後の最小値。デフォルトは ``0.0``。
- ``Amax``: float. 正規化後の最大値。デフォルトは ``1.0``。
- ``vmin``: float, optional. 元データの最小値。指定しない場合は自動計算。
- ``vmax``: float, optional. 元データの最大値。指定しない場合は自動計算。
**戻り値:**
list. 正規化されたリスト。
### ``normalize()``
数値リストの要素を指定された範囲に正規化する。
**詳細説明:**
リスト ``l`` の要素を ``[vmin, vmax]`` の範囲から ``[Amin, Amax]`` の範囲に線形変換して正規化する。``vmin`` または ``vmax`` が指定されない場合は、リスト内の要素から自動的に計算される。入力リストが ``None`` の場合は ``None`` を返す。
**引数:**
- ``l``: list. 数値のリスト。
- ``Amin``: float. 正規化後の最小値。デフォルトは ``0.0``。
- ``Amax``: float. 正規化後の最大値。デフォルトは ``1.0``。
- ``vmin``: float, optional. 元データの最小値。指定しない場合は自動計算。
- ``vmax``: float, optional. 元データの最大値。指定しない場合は自動計算。
**戻り値:**
list or None. 正規化されたリスト、または入力が ``None`` の場合は ``None``。
### ``plot_all()``
実験XRDパターンとCIFからの理論パターンを個別のサブプロットに表示する。
**詳細説明:**
入力された実験XRDパターンを最上段のサブプロットに表示し、その後、読み込まれた各CIFファイルから計算されたXRDパターンをそれぞれ異なるサブプロットに表示する。各理論パターンには回折ピーク位置もプロットされる。すべてのプロットは共通の2$\theta$軸を共有する。
**引数:**
- ``inf``: dict. 読み込まれたデータを含む辞書。
- ``app``: ``tkApplication`` のインスタンス。
- ``cparams``: 設定パラメータを保持するオブジェクト。
**戻り値:**
なし
### ``plot_input()``
入力された実験XRDパターンのみをプロットする。
**詳細説明:**
``inf`` から実験XRDデータを取得し、一つのグラフにプロットする。Y軸のスケールは ``cparams.yscale`` に従う。
**引数:**
- ``inf``: dict. 読み込まれたデータを含む辞書。
- ``app``: ``tkApplication`` のインスタンス。
- ``cparams``: 設定パラメータを保持するオブジェクト。
**戻り値:**
なし
### ``plot_one()``
実験XRDパターンとCIFからの回折ピーク位置を同じグラフに表示する。
**詳細説明:**
入力された実験XRDパターンと、読み込まれた各CIFファイルから計算された回折ピーク位置（強度は正規化）を同一のグラフにプロットする。これにより、実験パターンと各結晶相のピーク位置の関係を一度に確認できる。
**引数:**
- ``inf``: dict. 読み込まれたデータを含む辞書。
- ``app``: ``tkApplication`` のインスタンス。
- ``cparams``: 設定パラメータを保持するオブジェクト。
**戻り値:**
なし
### ``plot_one2()``
実験XRDパターンとCIFからの理論XRDパターンを同じグラフに表示する。
**詳細説明:**
入力された実験XRDパターンと、読み込まれた各CIFファイルから計算された理論XRDパターン（ブロードニング適用済み）を同一のグラフにプロットする。これにより、実験パターンと各結晶相の回折プロファイルの形状を一度に比較できる。
**引数:**
- ``inf``: dict. 読み込まれたデータを含む辞書。
- ``app``: ``tkApplication`` のインスタンス。
- ``cparams``: 設定パラメータを保持するオブジェクト。
**戻り値:**
なし
### ``convolution()``
データ ``y`` を指定された ``filter`` で畳み込む。
**詳細説明:**
離散的な畳み込み演算を実行し、``y`` の各点において ``filter`` を適用して平滑化された（またはブロードニングされた）データ ``yc`` を生成する。``nskip`` パラメータで畳み込みの計算間隔を制御し、結果のデータ点数を減らすことができる。
**引数:**
- ``x``: list or array. x座標のリスト。
- ``y``: list or array. 畳み込み対象のy座標のリスト。
- ``filter``: list or array. 畳み込みに使用するフィルタの配列。
- ``nskip``: int. 畳み込み計算をスキップする間隔。1の場合、すべての点で計算する。
**戻り値:**
tuple. (``_x``, ``_y``). 畳み込み後のx座標とy座標のリスト。``y`` が ``None`` の場合は ``None`` を返す。
### ``collect_data()``
フィッティングや相関分析のために、実験および理論XRDデータを収集・前処理する。
**詳細説明:**
入力された実験XRDデータと各CIFファイルから計算された理論XRDデータを統一された2$\theta$範囲に補間し、スマアリング（畳み込み）と正規化を適用する。さらに、背景多項式のための基底関数も準備する。
**引数:**
- ``inf``: dict. 読み込まれたデータを含む辞書。
- ``app``: ``tkApplication`` のインスタンス。
- ``cparams``: 設定パラメータを保持するオブジェクト。
- ``is_print``: bool. 処理の詳細をコンソールに出力するかどうか。
**戻り値:**
tuple. (``Q2_list``, ``yobs_infile``, ``ysim_infile``, ``bg_names``, ``bg_list``, ``sample_names``, ``ycif_list``, ``labels_train``, ``x_train``)。
- ``Q2_list``: list. 共通の2$\theta$座標のリスト。
- ``yobs_infile``: list. 前処理された実験XRD強度データ。
- ``ysim_infile``: list or None. 前処理されたシミュレーションXRD強度データ（存在する場合）。
- ``bg_names``: list. 背景多項式のラベルのリスト。
- ``bg_list``: list. 背景多項式の基底関数（レジェンドル多項式）のリスト。
- ``sample_names``: list. CIFファイルから取得した試料名またはファイルボディ名のリスト。
- ``ycif_list``: list. 各CIFファイルから計算され前処理された理論XRD強度データのリスト。
- ``labels_train``: list. 学習データ（``x_train``）の各列に対応するラベルのリスト。
- ``x_train``: list. 学習データとなる背景多項式と理論XRD強度のリスト。
### ``check_overwrap()``
異なるCIFファイル由来のXRDパターン間のオーバーラップ（重なり）をチェックし、可視化する。
**詳細説明:**
各CIFファイルの回折ピークが、他のCIFファイルから生成された回折パターンとどの程度重なっているかを計算し、その結果をプロットする。これにより、複数の結晶相が混在する場合に、各相のピークが互いに干渉する度合いを評価できる。
**引数:**
- ``inf``: dict. 読み込まれたデータを含む辞書。
- ``app``: ``tkApplication`` のインスタンス。
- ``cparams``: 設定パラメータを保持するオブジェクト。
**戻り値:**
なし
### ``CIF_correlation()``
CIFファイルから生成されたXRDパターン間の相関係数を計算し、可視化する。
**詳細説明:**
すべてのCIFファイルから生成された理論XRDパターン間の相関係数を計算し、結果をテキストで出力する。また、各CIFパターンと入力実験パターンとの相関係数を、スマアリングFWHMを変化させながらプロットし、最も相関の高いスマアリング条件や、異なる相間の類似性を評価する。
**引数:**
- ``inf``: dict. 読み込まれたデータを含む辞書。
- ``app``: ``tkApplication`` のインスタンス。
- ``cparams``: 設定パラメータを保持するオブジェクト。
**戻り値:**
なし
### ``correlation()``
入力された実験XRDパターンとCIFファイルから生成された理論パターンとの相関係数を計算し、可視化する。
**詳細説明:**
実験XRDパターンと、読み込まれた各CIFファイルから計算された理論XRDパターン間の相関係数を計算し、結果をテキストで出力する。さらに、これらの相関係数をスマアリングFWHMを変化させながらプロットし、最も相関の高い相や適切なスマアリング条件を評価する。
**引数:**
- ``inf``: dict. 読み込まれたデータを含む辞書。
- ``app``: ``tkApplication`` のインスタンス。
- ``cparams``: 設定パラメータを保持するオブジェクト。
**戻り値:**
なし
### ``fit()``
LASSO回帰を用いて実験XRDパターンを背景とCIF由来の理論パターンでフィッティングする。
**詳細説明:**
実験XRDパターンを目的変数、背景多項式と各CIFファイルから計算された理論XRDパターンを説明変数として、LASSO回帰を実行する。異なる ``alpha`` 値での係数変化とRMSEの変化をプロットし、最終的に指定された ``alpha`` 値でのフィッティング結果（係数、RMSE、MAV）とフィッティングされたパターンをプロットで表示する。
**引数:**
- ``inf``: dict. 読み込まれたデータを含む辞書。
- ``app``: ``tkApplication`` のインスタンス。
- ``cparams``: 設定パラメータを保持するオブジェクト。
**戻り値:**
なし
### ``main()``
メイン関数。XRD解析スクリプトのエントリポイント。
**詳細説明:**
アプリケーションの初期化、パラメータの読み込みと更新、プラグインモジュールのロード、および指定されたモードに応じたXRD解析処理（プロット、相関分析、フィッティングなど）を実行する。処理のログはファイルにも出力される。
**戻り値:**
なし
## 入出力仕様
### 入力ファイル
- **実験XRDデータファイル**:
- コマンドライン引数 ``infile`` で指定されるファイル（例: ``*.txt``）。
- ファイル形式は ``plugin_dir`` で指定されたディレクトリ内のプラグインモジュールによって自動的に判別され、読み込まれます。
- 通常、2$\theta$値と強度値を含むテキストファイルが想定されます。
- **CIFファイル**:
- コマンドライン引数 ``cif_files`` で指定されるファイル群（例: ``data/*.*``）。
- 結晶構造情報ファイル（CIF形式）であり、回折ピークの計算に利用されます。
- ファイル形式はプラグインモジュールによって判別されます。
### 出力ファイル
- **ログファイル**:
- 入力ファイル名に基づいて自動生成されます（例: ``{filebody}-out.txt``）。
- スクリプトの実行ログ、パラメータ、計算結果の概要などがテキスト形式で記録されます。
- **グラフィカル出力**:
- ``matplotlib`` を用いて生成されるプロットが画面上に表示されます。これには、XRDパターン、回折ピーク位置、オーバーラップ、相関係数、フィッティング結果などが含まれます。
- 画像ファイルとしての出力機能は、コードからは確認できません。表示されたプロットを手動で保存することは可能です。
## 使用例
```bash
python xrd_fit.py plot_all {infile} {wavelength} {xmin} {xmax} {xstep} {fwhm} {yscale} {BGorder} {alpha}
python xrd_fit.py plot_one {infile} {wavelength} {xmin} {xmax} {xstep} {fwhm} {yscale} {BGorder} {alpha}
python xrd_fit.py plot_one2 {infile} {wavelength} {xmin} {xmax} {xstep} {fwhm} {yscale} {BGorder} {alpha}
python xrd_fit.py fit {infile} {wavelength} {xmin} {xmax} {xstep} {fwhm} {yscale} {BGorder} {alpha}