tkfitdiag.py ライブラリ技術ドキュメント
ライブラリの機能や目的
tkfitdiag.py は、フィット結果の診断を支援するPythonライブラリです。特に、線形または非線形モデルのフィッティング後に得られたパラメータ共分散行列を基に、モデルの同定性やパラメータの不確かさを評価するためのユーティリティを提供します。
主な機能は以下の通りです。
共分散行列から標準偏差および相関係数行列を計算します。
共分散行列の固有値と固有ベクトルを解析し、パラメータの不確かな方向を特定します。
ヤコビアン行列から計算される \(J^T J\) 行列の固有値と条件数を評価し、同定しにくいパラメータ結合を診断します。
相対誤差、他のパラメータとの強相関、および共分散の固有方向への寄与に基づいて、フィッティング時に固定を検討すべきパラメータの候補を提案します。
このライブラリは、モデルの過剰パラメータ化や、データから十分に決定できないパラメータが存在する場合に、その原因を特定し、モデル改善のヒントを得ることを目的としています。
importする方法
tkfitdiag.py を他のPythonプログラムからインポートするには、このファイルをPythonのパスが通っているディレクトリに配置するか、直接スクリプトと同じディレクトリに置きます。
一般的なインポートの方法は以下の通りです。
import tkfitdiag
# ライブラリの関数やクラスを使用する例
# result = tkfitdiag.diagnose_covariance(...)
特定の関数やクラスだけをインポートする場合は、以下のように記述します。
from tkfitdiag import FitDiagnostics, diagnose_covariance, propose_fix_candidates
必要な非標準ライブラリとインストール方法
tkfitdiag.py は、以下の非標準ライブラリに依存しています。
NumPy: 数値計算、特に多次元配列操作のために使用されます。
これらのライブラリは pip コマンドでインストールできます。
pip install numpy
dataclasses および typing, math はPythonの標準ライブラリであるため、別途インストールする必要はありません。
importできる変数と関数
tkfitdiag.py ライブラリからimportできる主要なクラス（データ構造）と関数は以下の通りです。
クラス
EigenSummary
固有ベクトルの主要成分をまとめたデータクラスです。
rank(int): 固有値がソートされた順位（1から始まる）。eigenvalue(float): 対応する固有値。components(List[Tuple[str, float]]): その固有ベクトルに強く寄与するパラメータとその寄与度（ベクトルの成分値）のリスト。
FixCandidate
固定または外部拘束の候補となるパラメータに関する情報を持つデータクラスです。
param(str): パラメータ名。score(float): そのパラメータを固定する候補としてのスコア。値が大きいほど固定候補としての優先度が高い。value(float): パラメータの推定値。stderr(float): パラメータの標準誤差。relerr(Optional[float]): パラメータの相対標準誤差 (\( \text{stderr} / |\text{value}| \))。値が計算できない場合はNone。reasons(List[str]): そのパラメータが固定候補として挙げられた理由のリスト。
FitDiagnostics
パラメータ共分散行列に基づく診断結果全体を保持するデータクラスです。
names(List[str]): パラメータ名のリスト。values(np.ndarray): パラメータ値の配列。stderr(np.ndarray): パラメータの標準誤差の配列。relerr(np.ndarray): パラメータの相対標準誤差の配列。cov(np.ndarray): パラメータ共分散行列。corr(np.ndarray): パラメータ相関係数行列。eig_cov_values_desc(np.ndarray): 共分散行列の固有値（降順）。eig_cov_vectors_desc(np.ndarray): 共分散行列の固有ベクトル（eig_cov_values_descに対応し、列ベクトルとして格納）。eig_cov_summary(List[EigenSummary]): 共分散行列の固有ベクトルの主要成分サマリ。jtj(Optional[np.ndarray]): 残差のヤコビアン \(J\) が与えられた場合の \(J^T J\) 行列。ヤコビアンが与えられない場合はNone。eig_jtj_values_asc(Optional[np.ndarray]): \(J^T J\) 行列の固有値（昇順）。ヤコビアンが与えられない場合はNone。eig_jtj_vectors_asc(Optional[np.ndarray]): \(J^T J\) 行列の固有ベクトル（eig_jtj_values_ascに対応し、列ベクトルとして格納）。ヤコビアンが与えられない場合はNone。cond_jtj(Optional[float]): \(J^T J\) 行列の条件数。ヤコビアンが与えられない場合はNone。warning(str): 診断プロセス中に発生した警告メッセージ。
関数
covariance_to_correlation(cov: np.ndarray) -> Tuple[np.ndarray, np.ndarray]
共分散行列から相関係数行列と標準偏差を計算します。
引数:
cov(np.ndarray): 正方行列である共分散行列。
戻り値:
corr(np.ndarray): 相関係数行列。stderr(np.ndarray): 各パラメータの標準偏差の1次元配列。
計算: 標準偏差 \( \sigma_i \) は共分散行列の対角成分の平方根です。 $\( \sigma_i = \sqrt{\text{Cov}(i,i)} \)\( 相関係数 \) \rho_{ij} \( は共分散 \) \text{Cov}(i,j) \( を標準偏差の積で割ったものです。 \)\( \rho_{ij} = \frac{\text{Cov}(i,j)}{\sigma_i \sigma_j} \)$
eigen_sorted_symmetric(A: np.ndarray, descending: bool = True) -> Tuple[np.ndarray, np.ndarray]
対称行列の固有値と固有ベクトルをソートして返します。
引数:
A(np.ndarray): 対称行列。descending(bool):Trueの場合、固有値は降順にソートされます。Falseの場合、昇順にソートされます。デフォルトはTrue。
戻り値:
vals(np.ndarray): ソートされた固有値の1次元配列。vecs(np.ndarray): ソートされた固有値に対応する固有ベクトルが列ベクトルとして格納された行列。
summarize_eigenvectors(eigenvalues: Sequence[float], eigenvectors: np.ndarray, names: Sequence[str], *, topk: int = 3, compk: int = 3) -> List[EigenSummary]
固有ベクトルの主要な成分を読みやすい形式でまとめます。
引数:
eigenvalues(Sequence[float]): 固有値のシーケンス。eigenvectors(np.ndarray): 固有ベクトルが列として格納された行列。names(Sequence[str]): 各パラメータ名のシーケンス。topk(int): 要約する固有値/固有ベクトルの上位 \(k\) 個。デフォルトは3。compk(int): 各固有ベクトルについて、最も寄与の大きい成分を上位 \(k\) 個表示する。デフォルトは3。
戻り値:
List[EigenSummary]:EigenSummaryオブジェクトのリスト。
diagnose_covariance(names: Sequence[str], values: Sequence[float], cov: np.ndarray, *, jacobian: Optional[np.ndarray] = None, topk_eigen: int = 3, compk_eigen: int = 4) -> FitDiagnostics
パラメータの共分散行列からフィット診断結果を作成します。
引数:
names(Sequence[str]): パラメータ名のシーケンス。values(Sequence[float]): パラメータ値のシーケンス。cov(np.ndarray): パラメータ共分散行列。jacobian(Optional[np.ndarray]): 残差のヤコビアン行列。これを渡すと \(J^T J\) の条件数と最小固有方向も評価されます。デフォルトはNone。topk_eigen(int): 共分散行列の固有値サマリで表示する上位 \(k\) 個の固有方向。デフォルトは3。compk_eigen(int): 各固有方向について、最も寄与の大きいパラメータを上位 \(k\) 個表示する。デフォルトは4。
戻り値:
FitDiagnostics: 診断結果を含むFitDiagnosticsオブジェクト。
警告:
jacobianの形状がパラメータ数と一致しない場合、または \(J^T J\) がゼロまたは負の固有値を持つ場合、FitDiagnostics.warningに警告メッセージが格納されます。
\(J^T J\) の条件数: \(J^T J\) の条件数 \( \kappa \) は、その最大固有値 \( \lambda_{max} \) と最小固有値 \( \lambda_{min} \) の比として定義されます。 $\( \kappa = \frac{\lambda_{max}}{\lambda_{min}} \)$ この値が大きいほど、モデルの同定が困難であるか、パラメータ間に強い線形従属関係がある可能性を示唆します。
propose_fix_candidates(names: Sequence[str], values: Sequence[float], stderr: Sequence[float], corr: np.ndarray, *, eig_cov_values: Optional[Sequence[float]] = None, eig_cov_vectors: Optional[np.ndarray] = None, corr_thr: float = 0.95, relerr_thr: float = 0.5, topn: int = 3) -> List[FixCandidate]
固定または外部拘束を検討すべきパラメータの候補をヒューリスティックに基づいて提案します。
引数:
names(Sequence[str]): パラメータ名のシーケンス。values(Sequence[float]): パラメータ値のシーケンス。stderr(Sequence[float]): パラメータの標準誤差のシーケンス。corr(np.ndarray): パラメータ相関係数行列。eig_cov_values(Optional[Sequence[float]]): 共分散行列の固有値（降順）。diagnose_covarianceのeig_cov_values_descを渡すことを想定。eig_cov_vectors(Optional[np.ndarray]): 共分散行列の固有ベクトル。diagnose_covarianceのeig_cov_vectors_descを渡すことを想定。corr_thr(float): 強相関と見なす相関係数の絶対値のしきい値。デフォルトは0.95。relerr_thr(float): 相対標準誤差が高いと見なすしきい値。デフォルトは0.5。topn(int): 提案する候補の最大数。デフォルトは3。
戻り値:
List[FixCandidate]:FixCandidateオブジェクトのリスト。
判断材料:
パラメータの相対標準誤差が
relerr_thr以上。他のパラメータとの相関係数の絶対値が
corr_thr以上。共分散行列の最大固有値（最も不確かな方向）の固有ベクトルへの寄与度。
注意: この関数は数値的な「決まりにくさ」を診断するものであり、最終的な判断は物理的妥当性、独立測定、文献値の有無などを考慮して行う必要があります。
propose_fix_candidates_from_diagnostics(diag: FitDiagnostics, *, corr_thr: float = 0.95, relerr_thr: float = 0.5, topn: int = 3) -> List[FixCandidate]
FitDiagnostics オブジェクトから固定候補を提案するためのショートカット関数です。内部的には propose_fix_candidates を呼び出します。
引数:
diag(FitDiagnostics):diagnose_covarianceから返されたFitDiagnosticsオブジェクト。corr_thr(float):propose_fix_candidatesと同じ。デフォルトは0.95。relerr_thr(float):propose_fix_candidatesと同じ。デフォルトは0.5。topn(int):propose_fix_candidatesと同じ。デフォルトは3。
戻り値:
List[FixCandidate]:FixCandidateオブジェクトのリスト。
format_fix_candidates(candidates: Sequence[FixCandidate]) -> str
固定候補のリストを、コンソール表示に適した整形済み文字列に変換します。
引数:
candidates(Sequence[FixCandidate]):propose_fix_candidatesが返すFixCandidateオブジェクトのリスト。
戻り値:
str: 整形された文字列。
diagnostics_to_dict(diag: FitDiagnostics) -> dict
FitDiagnostics オブジェクトの内容を、JSON形式で保存しやすい辞書に変換します。NumPy配列はPythonのリストに変換されます。
引数:
diag(FitDiagnostics):diagnose_covarianceから返されたFitDiagnosticsオブジェクト。
戻り値:
dict:FitDiagnosticsの内容を表現する辞書。
main scriptとして実行したときの動作
tkfitdiag.py ライブラリは、単体で実行されたときに特定の動作を行うための if __name__ == "__main__": ブロックを持っていません。
したがって、このファイルを直接実行しても何も出力されず、機能は実行されません。
このライブラリの機能を使用するには、上記「importする方法」に従って、別のPythonスクリプトから関数やクラスをインポートして呼び出す必要があります。