optimize_peakfit_mf.py 技術ドキュメント

プログラムの動作

optimize_peakfit_mf.py は、汎用的な数値最適化フレームワーク tklib.tksci.tkoptimize_flex を利用して、データフィッティング（特にピークフィッティングや曲線フィッティング）を実行するためのPythonスクリプトです。このプログラムの主な目的は、実験データやシミュレーションデータに対して、特定のモデル関数を最適にフィッティングするパラメータを探索することです。

主な機能は以下の通りです。

• 設定管理: 外部のINI形式設定ファイルから、最適化手法、許容誤差、最大反復回数、ファイルパスなどの様々な設定を読み込みます。

• フィッティングパラメータの初期化: 別のファイルからフィッティング対象となるパラメータの初期値、制約（最小値、最大値）、スケールなどを読み込み、最適化プロセスに組み込みます。

• モデル評価: peakfit (エイリアス omodel) モジュールに定義されたモデル関数を利用し、与えられたパラメータセットと入力データに基づいてモデルの出力を計算します。

• 最適化実行: scipy.optimize.minimize が提供する様々なアルゴリズム（例：Nelder-Mead, L-BFGS-B）を使用して、モデルの出力と実測データの間の残差二乗和を最小化するパラメータを探索します。

• 結果の保存: 最適化されたフィッティングパラメータ、フィッティング履歴、およびフィッティング結果のグラフをファイルに保存します。

• 外部コマンド連携: 必要に応じて、フィッティングプロセス中に外部のPythonスクリプトを実行する機能も備えていますが、本コードではその部分はコメントアウトされています。

このプログラムは、特に複雑なデータセットに対して自動的かつ効率的にモデルを適合させたい場合に有用です。

原理

optimize_peakfit_mf.py は、主に最小二乗法に基づいた非線形最適化の原理を利用して、与えられたモデル関数をデータにフィッティングします。

1. 目的関数 (Objective Function) フィッティングの目的は、モデル関数 \(f(\mathbf{x}, \mathbf{p})\) の出力が実測データ \(y_{data}\) に最も近づくように、パラメータ \(\mathbf{p}\) を決定することです。ここで、\(\mathbf{x}\) は独立変数（入力データ）、\(\mathbf{p} = (p_1, p_2, \ldots, p_n)\) はフィッティング対象のパラメータです。 この目的は、通常、モデルの出力と実測データとの残差二乗和 (Sum of Squared Residuals, SSR) を最小化することで達成されます。目的関数 \(F(\mathbf{p})\) は次のように定義されます。

\[F(\mathbf{p}) = \sum_{i=1}^{N} w_i \left( y_{data,i} - f(\mathbf{x}_i, \mathbf{p}) \right)^2\]

ここで、\(N\) はデータ点の総数、\(w_i\) は各データ点に割り当てられる重み（誤差の逆数など）、\(y_{data,i}\) は実測データ、\(f(\mathbf{x}_i, \mathbf{p})\) はモデル関数による予測値です。

2. 最適化アルゴリズム このプログラムは、scipy.optimize.minimize が提供する多様な最適化アルゴリズムを利用します。利用可能なアルゴリズムは、設定ファイル（cfg.method）で指定できます。一般的な手法には以下のようなものがあります。

• Nelder-Mead法: 勾配情報を使用しないシンプレックス法の一種で、初期値の選択に頑健ですが、収束が遅い場合があります。

• L-BFGS-B法: 準ニュートン法の一種で、勾配情報（近似されたヘッセ行列）を利用します。制約付き最小化問題に適しており、高速な収束が期待できます。

• その他、scipy.optimize がサポートする多くの手法（例: TNC, SLSQP, COBYLA）。

プログラム内では、init_fit 関数で tkFit_mxy オブジェクトが初期化され、fit._minimize_func が実測データとモデル出力の残差を計算し、最適化ライブラリに渡されます。

3. モデル関数 実際のモデル関数（例: ガウス関数、ローレンツ関数、複数のピークの重ね合わせなど）は、外部の peakfit モジュール（コード内では omodel としてインポート）に実装されています。具体的には、omodel.cal_ylist(app, xk_all, x_list, ...) が、与えられたパラメータ xk_all と入力データ x_list に基づいて、モデルの予測値リスト ylist を計算します。

4. ペナルティ関数 フィッティングパラメータに特定の制約（例: パラメータの範囲、特定の関係性）を課すために、ペナルティ関数が導入されることがあります。プログラム内では fit._cal_penalty 関数で計算され、目的関数に追加されることで、制約違反の場合に目的関数値が大きくなるように調整されます。

5. 勾配 (Jacobian) L-BFGS-Bなどの勾配ベースの最適化アルゴリズムを使用する場合、目的関数の勾配（各パラメータに関する偏微分）が必要となります。プログラムでは、cfg.jac の設定に応じて、数値微分（'2-point', '3-point', 'cs'）を使用するか、またはユーザーが定義した解析的な勾配関数 diff1(xk, fit)（現在はコメントアウトされており、使用されない場合は cfg.jac = '2-point' などが設定される）を使用できます。

これらの原理に基づいて、optimize_peakfit_mf.py は、ユーザーが指定したデータとモデルに対して、最適なパラメータを効率的に探索します。

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

optimize_peakfit_mf.py は、いくつかの非標準ライブラリに依存しています。これらのライブラリは、Pythonのパッケージマネージャ pip を使ってインストールできます。

以下のライブラリはPyPIで公開されており、pip でインストール可能です。

• numpy: 数値計算のための基本的なパッケージ。

  pip install numpy
  

• scipy: 科学技術計算のためのパッケージ。最適化、補間、信号処理などが含まれます。

  pip install scipy
  

• pandas: データ構造とデータ分析ツールを提供します。主にデータの読み込みや処理に使用されます。

  pip install pandas
  

• matplotlib: グラフ描画ライブラリ。フィッティング結果の可視化に使用されます。

  pip install matplotlib
  

さらに、以下のカスタムライブラリが必要です。これらはPyPIには公開されておらず、別途提供されるか、特定のGitリポジトリからクローンしてPythonの環境パスに配置する必要があります。

• tklib: このプログラムの内部で利用される汎用ユーティリティ（tkParams）、最適化フレームワーク（tksci.tkoptimize_flex, tksci.tkFit_mxy_flex）、およびデータ処理ユーティリティ（tksci.tkFit_lib, tksci.tkFit_object）が含まれています。

• peakfit: モデル関数 (omodel.read_input_data, omodel.cal_ylist) が定義されているモジュールです。このプログラムがフィッティングする対象の具体的な数学モデルが含まれています。

これらのカスタムライブラリのインストール方法については、それらの提供元に確認してください。通常は、プログラムがそれらをインポートできるよう、PYTHONPATH 環境変数を設定するか、カレントディレクトリに配置するか、あるいは仮想環境にインストールすることで利用可能になります。

必要な入力ファイル

optimize_peakfit_mf.py の実行には、以下の種類の入力ファイルが期待されます。これらのファイルは、プログラムの動作やフィッティングプロセスを定義するために使用されます。

1. 設定ファイル (Configuration File)

   • ファイル形式: INI形式 (例: config.ini)

   • 内容: 最適化の全体的な設定を定義します。

     • [Preferences] セクション: プロットのサイズ (figsize) など。

     • [Files] セクション: 入力データファイル (datafile)、結果出力ファイル (outfile)、履歴ファイル (historyfile) などのパス。テンプレートパス (templatepath) も含まれる場合があります。

     • [Flags] セクション: 履歴保存の有無 (fhistory)、フィッティングファイル保存の有無 (ffitfiles)、後方データ切断の有無 (fdisconnect_backward_data) など、ブール値フラグ。

     • [Condition] セクション: 最適化手法 (method 例: nelder-mead, L-BFGS-B)、ヤコビアン計算方法 (jac 例: 2-point, 3-point), 最大反復回数 (nmaxiter), 最大関数評価回数 (nmaxcall), 許容誤差 (tol, xatol), Y軸スケール (y_scale) など、最適化条件。

     • [Data] セクション: データの範囲指定 (Tmin, Tmax, Nmin, Nmax) など、データ処理に関する設定。

     • [Scan] セクション: スキャン機能が有効な場合に使用される設定 (target_var, x0, x1, nx)。

   • パス: コマンドライン引数 --config で指定されることが多いです。

2. フィッティングパラメータ設定ファイル (Fitting Parameter Configuration File)

   • ファイル形式: CSV形式またはINI形式 (例: parameters.csv または fit_config.ini)

   • 内容: フィッティング対象となる個々のパラメータに関する詳細な設定を定義します。

     • [Parameters] セクション: 各フィッティング変数の初期値、単位 (unit), スケール (pk_scale), 最適化ID (optid), 線形ID (linid), ステップサイズ (dx), 最小値 (kmin), 最大値 (kmax), ペナルティ係数 (kpenalty) など。

   • パス: コマンドライン引数 --fit-config で指定されることが多いですが、cfg.infile から派生することもあります。fit.fitfile_path で内部的に管理されます。

3. 入力データファイル (Input Data File)

   • ファイル形式: CSV形式またはテキスト形式。具体的な形式は peakfit モジュール (omodel.read_input_data) の実装に依存します。

   • データ構造: 通常、複数の列から成り、少なくとも1つの独立変数（\(x\)）と1つ以上の従属変数（\(y\)）を含みます。重み（\(w\)）データも含まれることがあります。 例:

     x_label,y1_label,y2_label,weight_label
     1.0,10.2,5.1,1.0
     2.0,12.5,6.3,1.0
     ...
     

   • パス: 設定ファイル (datafile または infile キー) またはコマンドライン引数で指定されます。

これらのファイルは、プログラムが最適化を実行するために不可欠な情報を提供します。

生成される出力ファイル

optimize_peakfit_mf.py は、フィッティングプロセスの結果として複数のファイルを生成します。

1. 最適化されたフィッティングパラメータファイル

   • ファイル名: 通常、入力フィッティングパラメータファイルの名前に基づき、{filebody}_parameters.csv のような形式で生成されます（例: data_parameters.csv）。

   • 内容: 最適化プロセスによって決定された最終的なフィッティングパラメータの値が保存されます。各パラメータの名前、最適値、単位、制約などが含まれます。このファイルは、以降の分析や再実行のための初期値として利用できます。

2. フィッティング履歴ファイル

   • ファイル名: 設定ファイルで historyfile として指定されます（例: fit_history.log, fit_history.csv）。

   • 内容: 最適化の各イテレーションにおける中間結果（パラメータ値、目的関数値、残差など）が時系列で記録されます。これにより、最適化の収束挙動を追跡し、問題の原因を特定するのに役立ちます。

3. フィッティング結果のプロット画像

   • ファイル名: last_fit.png など、設定またはコード内で定義されます。

   • 内容: 入力データ、フィッティングされたモデル曲線、および残差などがグラフとして描画され、PNG形式などの画像ファイルとして保存されます。これにより、フィッティングの品質を視覚的に評価できます。

4. 出力データファイル

   • ファイル名: 設定ファイルで outfile として指定されます。

   • 内容: オリジナルの入力データに加えて、フィッティングされたモデルの予測値や残差などが追加された形式で保存されることがあります。具体的な内容は tkFit_lib.save_data 関数に依存します。

5. ログファイル

   • ファイル名: logfile として指定される場合があります。

   • 内容: プログラムの実行中に発生したイベント、警告、エラー、およびデバッグ情報などが記録されます。

これらの出力ファイルは、フィッティングの結果を文書化し、その後の分析や検証、あるいは将来のフィッティング作業の基盤として利用されます。

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

optimize_peakfit_mf.py は、コマンドラインから実行され、引数を通じて各種設定ファイルを指定できます。

基本的な使用法は以下の通りです。

python optimize_peakfit_mf.py [options]

主要なオプション

このプログラムは tklib.tksci.tkoptimize_flex モジュールを利用しているため、そのモジュールが提供する共通のコマンドライン引数を受け入れます。一般的な引数には以下のようなものがあります（正確な引数名と機能は tkoptimize_flex の実装に依存します）。

• --config <path_to_config.ini>

  • 設定ファイルへのパスを指定します。ここに最適化手法、ファイルパス、フラグなどの全体的な設定が記述されます。

• --fit-config <path_to_fit_params.csv>

  • フィッティングパラメータの初期値や制約が記述されたファイルへのパスを指定します。

• --infile <path_to_input_data.csv>

  • フィッティング対象となるデータファイルへのパスを指定します。

• --outfile <path_to_output_results.csv>

  • フィッティング結果を保存する出力ファイルへのパスを指定します。

• --historyfile <path_to_history.log>

  • 最適化の履歴を記録するファイルへのパスを指定します。

• --mode <mode_name>

  • プログラムの実行モードを指定します (例: fit, scan など)。

• --fplot <0|1>

  • プロットの表示/保存を制御するフラグ (0: 無効, 1: 有効)。

• -p <param_name> <value>

  • 特定のフィッティングパラメータの初期値をコマンドラインから直接上書きします。例えば -p peak1_amplitude 100.0。

• -v <var_name> <value>

  • 設定ファイル内の任意の変数を上書きします。例えば -v method L-BFGS-B。

これらの引数を組み合わせて使用することで、多様なフィッティングシナリオに対応できます。

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

ここでは、架空のファイル名と設定を例として、optimize_peakfit_mf.py の具体的な使用方法と、その実行結果について説明します。

まず、以下の3つの入力ファイルがカレントディレクトリにあると仮定します。

1. config.ini (設定ファイル)

   [Files]
   infile = measurement_data.csv
   outfile = fitted_results.csv
   historyfile = fit_log.txt
   
   [Condition]
   method = L-BFGS-B
   tol = 1e-6
   nmaxiter = 1000
   
   [Flags]
   fplot = 1
   ffitfiles = 1
   

2. parameters.csv (フィッティングパラメータファイル)

   varname,initial_value,unit,pk_scale,optid,kmin,kmax
   peak1_amplitude,100.0,,1.0,1,10.0,200.0
   peak1_center,5.0,,1.0,1,0.0,10.0
   peak1_width,1.0,,1.0,1,0.1,5.0
   baseline_offset,0.0,,1.0,1,-10.0,10.0
   

3. measurement_data.csv (入力データファイル)

   x_value,y_value,weight
   0.0,1.2,1.0
   1.0,5.8,1.0
   2.0,25.1,1.0
   3.0,50.3,1.0
   4.0,85.2,1.0
   5.0,99.8,1.0
   6.0,84.5,1.0
   7.0,51.0,1.0
   8.0,26.5,1.0
   9.0,6.0,1.0
   10.0,1.5,1.0
   

   （これは単一のピークを持つガウス関数のようなデータと仮定します。）

実行コマンド

上記のファイルを使用し、config.ini を主設定ファイルとして、parameters.csv をフィッティングパラメータファイルとして指定し、プロットを有効にして実行する場合のコマンドは次のようになります。

python optimize_peakfit_mf.py --config config.ini --fit-config parameters.csv

または、config.ini の infile 設定が優先されるため、--infile は省略できます。

python optimize_peakfit_mf.py --config config.ini

さらに、特定のパラメータ（例: peak1_amplitude）の初期値をコマンドラインから一時的に変更したい場合は、以下のようにします。

python optimize_peakfit_mf.py --config config.ini -p peak1_amplitude 110.0

実行結果の説明

上記のコマンドを実行すると、プログラムは以下のような処理を行い、いくつかのファイルを生成します。

1. コンソール出力:

   • プログラムはまず、config.ini および parameters.csv から設定を読み込んだことを示すメッセージを出力します。

   • 最適化プロセスの詳細（各イテレーションでのパラメータ値、目的関数値など）がリアルタイムでコンソールに表示されます。

   • 最適化が収束した際、最終的なパラメータ値と目的関数値、収束メッセージが出力されます。

2. 生成されるファイル:

   • fitted_results.csv: config.ini で outfile として指定されたファイルが生成されます。このファイルには、元の measurement_data.csv の内容に加え、フィッティングされたモデルの予測値や、実測値とモデル予測値の残差などの列が追加されて保存されます。

     x_value,y_value,weight,fitted_y_value,residual
     0.0,1.2,1.0,1.05,-0.15
     1.0,5.8,1.0,5.92,0.12
     ...
     

   • parameters_parameters.csv: parameters.csv の名前から派生した、最適化されたパラメータを保存するファイルが生成されます。

     varname,value,unit,pk_scale,optid,kmin,kmax
     peak1_amplitude,98.567,,1.0,1,10.0,200.0
     peak1_center,4.981,,1.0,1,0.0,10.0
     peak1_width,0.952,,1.0,1,0.1,5.0
     baseline_offset,0.015,,1.0,1,-10.0,10.0
     

   • fit_log.txt: config.ini で historyfile として指定されたログファイルが生成されます。このファイルには、最適化の各ステップの詳細な情報が記録されており、最適化プロセスを後から検証するのに役立ちます。

   • last_fit.png: fplot = 1 が設定されているため、フィッティング結果を示すグラフが画像ファイルとして生成されます。このグラフには、元のデータ点、フィッティングされた曲線、そして通常は残差プロットが含まれ、フィッティングの視覚的な確認が可能です。

これにより、ユーザーは指定したデータに対してモデルのパラメータを自動的に最適化し、その結果を数値および視覚的に確認することができます。