D:/git/sphinx/tkProg/source/regression/mlsq_error_argparse.py マニュアル

プログラムの動作

本プログラム D:/git/sphinx/tkProg/source/regression/mlsq_error_argparse.py は、指定された次数の多項式を用いた最小二乗法による回帰分析を実行し、その予測の不確実性を可視化するツールです。 入力されたデータセットに対して多項式フィッティングを行い、得られた係数やその分散共分散行列から、モデルの予測における各種不確実性（パラメータの不確実性、残差分散を含めた予測不確実性、測定ノイズを含めた総合的な不確実性）を算出します。 計算結果はExcelファイルとして出力され、同時に matplotlib を用いたグラフとして画面上に可視化されます。これにより、フィッティング曲線の妥当性や、予測値が持つ誤差範囲を視覚的かつ定量的に評価するという課題を解決します。 なお、コード内の関数定義直後には、3重引用符で囲まれたdocstringが記述されており、各関数の入出力仕様が定義されています。

原理

本プログラムでは、多項式回帰のパラメータ推定に通常の最小二乗法（OLS）を用いています。

まず、入力データ \(x\) に対して、指定された多項式の次数 \(p\) （プログラム中の order）までのべき乗を要素に持つ計画行列（デザイン行列） \(X\) を構築します。サイズが \(N \times (p + 1)\) となる行列 \(X\) の各要素は以下のようになります。

\[ X_{ij} = x_i^j \quad (j = 0, 1, \dots, p) \]

この計画行列と観測値ベクトル \(y\) から、最小二乗推定量としての係数ベクトル \(\beta\) を以下の式で求めます。

\[ \beta = (X^T X)^{-1} X^T y \]

推定量を用いた予測値（フィッティング値）は \(\hat{y} = X\beta\) となり、残差ベクトルは \(y - \hat{y}\) となります。 この残差から残差平方和（RSS: Residual Sum of Squares）を求め、自由度 \(N - (p + 1)\) で割ることで残差分散 \(\sigma^2_{\text{resid}}\) を推定します。

\[ \sigma^2_{\text{resid}} = \frac{(y - X\beta)^T (y - X\beta)}{N - (p + 1)} \]

得られた残差分散を用いて、推定されたパラメータ \(\beta\) の共分散行列 \(\text{cov}(\beta)\) を計算します。

\[ \text{cov}(\beta) = \sigma^2_{\text{resid}} (X^T X)^{-1} \]

計算グリッド \(x_{\text{cal}}\) 上での予測値の不確実性は、上記の共分散行列を用いて評価されます。任意の入力 \(X_{\text{cal}}\) における予測値の分散 \(\text{Var}(\hat{y})\) は、以下の式で計算されます。

\[ \text{Var}(\hat{y}) = \text{diag}(X_{\text{cal}} \cdot \text{cov}(\beta) \cdot X_{\text{cal}}^T) \]

可視化される不確実性のバンド（標準偏差）は以下の3種類です。

  1. パラメータの不確実性: \(\sigma_{\text{param}} = \sqrt{\text{Var}(\hat{y})}\)

  2. パラメータと残差分散を含んだ予測区間: \(\sigma_{\text{pred}} = \sqrt{\text{Var}(\hat{y}) + \sigma^2_{\text{resid}}}\)

  3. 測定誤差を含んだ総合的な不確実性: \(\sigma_{\text{combined}} = \sqrt{\text{Var}(\hat{y}) + \sigma_{\text{meas}}^2}\)

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

本プログラムを実行するには、一般的なデータ解析用ライブラリに加え、専用の独自ライブラリ（tklib）が必要です。

必要な非標準ライブラリ（PyPIからインストール可能なもの）:

  • numpy

  • matplotlib

  • argparse （Python標準ですが明記します）

インストールコマンドの例:

pip install numpy matplotlib

注意: 本プログラムは tklib という独自のパッケージ（tkutils, tkapplication, tkVariousData, tkPlotEvent, tkFit などを包含）に依存しています。実行環境の PYTHONPATH に tklib が含まれるディレクトリを追加するか、同じワークスペース内に配置してインポート可能な状態にする必要があります。

必要な入力ファイル

プログラムは、Excel形式（.xlsx や .xls、またはCSV等の tkVariousData で読み込み可能な形式）の入力ファイルを必要とします。

  • ファイル形式: Excelファイル（デフォルト名: random-poly.xlsx）

  • データ構造: 列ベースのデータ構造が期待されます。X軸のデータとY軸のデータがそれぞれ特定の列に配置されており、プログラム実行時に --xlabel および --ylabel を用いて、対象データの「列名（ヘッダー文字列）」または「列インデックス（数値）」を指定して抽出します。

生成される出力ファイル

プログラムを実行すると、入力ファイル名（例: data.xlsx）をベースにして、同じディレクトリ内に以下のファイルが生成・保存されます。

  1. パラメータ出力ファイル ({filebody}-parameters.xlsx)

    • 内容: フィッティングによって得られた多項式の各係数（coeff）と、その標準誤差（std）が保存されます。

  2. フィッティング結果出力ファイル ({filebody}-fit.xlsm)

    • 内容: 元の \(x, y\) データ、フィッティング結果 \(y(\text{fit})\)、および計算グリッド \(x(\text{cal})\) 上での予測平均値 \(y(\text{mean})\) や、各種不確実性の標準偏差（std(param)、std(param&resid)、std(param&noise)）が出力されます。指定したExcelテンプレート（デフォルト: StandardGraph.xlsm）に基づいて作成されます。

  3. ログファイル ({filebody}.log など、app.replace_path に依存）

    • 内容: コマンドラインに出力されるフィッティング係数や計算範囲などの実行時の標準出力が、ログファイルとしてテキスト形式で保存されます。

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

本プログラムはコマンドラインから引数を与えて実行します。

基本的な実行構文:

python D:/git/sphinx/tkProg/source/regression/mlsq_error_argparse.py [オプション]

主要なコマンドライン引数:

  • --infile: 入力データファイルのパス（デフォルト: random-poly.xlsx）

  • --xlabel: Xデータのラベル名またはインデックス（デフォルト: 0）

  • --ylabel: Yデータのラベル名またはインデックス（デフォルト: 1）

  • --norder: 多項式の次数（デフォルト: 3）

  • --xmin, --xmax: フィッティングに使用するXデータの最小値と最大値

  • --xcalmin, --xcalmax: 計算グリッド（曲線描画用）の最小・最大X値

  • --ncal: 計算グリッドのポイント数（デフォルト: 201）

  • --plot_ci: 信頼区間プロットを別枠で表示するかどうか（1で表示、0で非表示）

  • --pause / --no-pause: 処理終了時にコンソールを一時停止するかどうかのフラグ

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

入力データ experiment_data.xlsx を用い、Xデータとして time 列、Yデータとして voltage 列を指定して、2次多項式でフィッティングを行う場合の実行例です。

python D:/git/sphinx/tkProg/source/regression/mlsq_error_argparse.py --infile experiment_data.xlsx --xlabel time --ylabel voltage --norder 2 --no-pause

実行結果の説明:

  1. experiment_data.xlsx から time と voltage のデータを読み込みます。

  2. データに対して2次多項式（\(y = c_0 + c_1 x + c_2 x^2\)）の最小二乗フィッティングを行います。

  3. コンソール（およびログファイル）に、算出された係数 \(c_0, c_1, c_2\) の値とそれぞれの不確実性、および残差分散が出力されます。

  4. experiment_data-parameters.xlsx と experiment_data-fit.xlsm が生成され、フィッティングされた係数と計算グリッド上の曲線データ・不確実性の値が保存されます。

  5. 画面にグラフウィンドウが表示され、左側のプロットには生の散布図と赤線のフィッティング曲線、青や紫で塗りつぶされた不確実性のバンド（信頼区間・予測区間）が描画されます。右側のプロットには、求まった各係数の値とエラーバー（\(\pm 1\sigma\)）が可視化されます。

  6. --no-pause を指定しているため、グラフウィンドウを閉じると入力待機をせずにプログラムが即座に終了します。