tkfitdiag プログラム仕様

tkfitdiag.py

フィット結果の診断ユーティリティ。

線形/非線形を問わず、パラメータ共分散行列が得られた後に使う。 主な用途: - 共分散行列 -> 標準偏差・相関係数行列 - 共分散行列の固有値/固有ベクトルから、不確かな方向を調べる - J^T J の固有値/条件数から、同定しにくいパラメータ結合を調べる - 相対誤差・強相関・不確かな固有方向への寄与から固定候補を提案する

tkfitdiag.py ライブラリ技術ドキュメント

class regression.tklsq.tkfitdiag.EigenSummary(rank: int, eigenvalue: float, components: List[Tuple[str, float]])

ベースクラス: object

固有ベクトルの主要成分サマリ。

概要:

固有ベクトルの主要成分をまとめたデータ構造。

詳細説明:

固有値、その固有ベクトルに対応するランク、および主要なパラメータ成分を格納します。

パラメータ:

• rank -- 固有値の順位 (1-indexed)。

• eigenvalue -- 固有値。

• components -- 主要なパラメータ成分とその寄与度（正規化されていない値）。

components: List[Tuple[str, float]]

eigenvalue: float

rank: int

class regression.tklsq.tkfitdiag.FitDiagnostics(names: List[str], values: ndarray, stderr: ndarray, relerr: ndarray, cov: ndarray, corr: ndarray, eig_cov_values_desc: ndarray, eig_cov_vectors_desc: ndarray, eig_cov_summary: List[EigenSummary], jtj: ndarray | None = None, eig_jtj_values_asc: ndarray | None = None, eig_jtj_vectors_asc: ndarray | None = None, cond_jtj: float | None = None, warning: str = '')

ベースクラス: object

パラメータ共分散に基づく診断結果。

概要:

フィット診断の結果を格納するデータ構造。

詳細説明:

パラメータ名、値、誤差、共分散行列、相関係数行列、固有値解析の結果など、 フィットの不安定性や問題点を特定するための情報を含みます。

パラメータ:

• names -- パラメータ名のリスト。

• values -- パラメータ値のNumpy配列。

• stderr -- パラメータの標準誤差のNumpy配列。

• relerr -- パラメータの相対標準誤差のNumpy配列。

• cov -- パラメータ共分散行列のNumpy配列。

• corr -- パラメータ相関係数行列のNumpy配列。

• eig_cov_values_desc -- 共分散行列の固有値（降順）のNumpy配列。

• eig_cov_vectors_desc -- 共分散行列の固有ベクトル（対応する固有値が降順）のNumpy配列。

• eig_cov_summary -- 共分散行列の主要な固有方向のサマリーリスト。

• jtj -- Jacobianの転置とJacobianの積 (J^T J) のNumpy配列。指定されない場合はNone。

• eig_jtj_values_asc -- J^T J の固有値（昇順）のNumpy配列。指定されない場合はNone。

• eig_jtj_vectors_asc -- J^T J の固有ベクトル（対応する固有値が昇順）のNumpy配列。指定されない場合はNone。

• cond_jtj -- J^T J の条件数。指定されない場合はNone。

• warning -- 診断中に発生した警告メッセージ。

cond_jtj: float | None = None

corr: ndarray

cov: ndarray

eig_cov_summary: List[EigenSummary]

eig_cov_values_desc: ndarray

eig_cov_vectors_desc: ndarray

eig_jtj_values_asc: ndarray | None = None

eig_jtj_vectors_asc: ndarray | None = None

jtj: ndarray | None = None

names: List[str]

relerr: ndarray

stderr: ndarray

values: ndarray

warning: str = ''

class regression.tklsq.tkfitdiag.FixCandidate(param: str, score: float, value: float, stderr: float, relerr: float | None, reasons: List[str] = <factory>)

ベースクラス: object

固定または外部拘束の候補。

概要:

パラメータの固定または外部拘束の候補を表すデータ構造。

詳細説明:

パラメータ名、スコア、値、標準誤差、相対誤差、および候補として提案された理由を保持します。

パラメータ:

• param -- パラメータ名。

• score -- 固定候補としての総合スコア。

• value -- パラメータの値。

• stderr -- パラメータの標準誤差。

• relerr -- パラメータの相対標準誤差 (stderr / |value|)。値が0に近い場合はNoneになることがあります。

• reasons -- 候補として提案された理由のリスト。

param: str

reasons: List[str]

relerr: float | None

score: float

stderr: float

value: float

regression.tklsq.tkfitdiag.covariance_to_correlation(cov: ndarray) → Tuple[ndarray, ndarray]

共分散行列から相関係数行列と標準偏差を計算する。

概要:

共分散行列から相関係数行列と標準偏差を計算します。

詳細説明:

共分散行列の対角要素の平方根から標準偏差を求め、それらを用いて相関係数行列を計算します。 標準偏差がゼロのパラメータが存在する場合、その相関係数はNaNとなります。

パラメータ:

cov -- 共分散行列。正方行列である必要があります。

戻り値:

相関係数行列 (np.ndarray) と標準偏差 (np.ndarray) のタプル。

regression.tklsq.tkfitdiag.diagnose_covariance(names: Sequence[str], values: Sequence[float], cov: ndarray, *, jacobian: ndarray | None = None, topk_eigen: int = 3, compk_eigen: int = 4) → FitDiagnostics

共分散行列からフィット診断を作る。

概要:

パラメータ共分散行列に基づいてフィットの診断結果を生成します。

詳細説明:

共分散行列から標準誤差、相対誤差、相関係数行列を計算し、さらに共分散行列の固有値解析を行います。 Jacobian行列が提供された場合は、J^T J行列の条件数と最小固有方向も評価し、 これらの診断情報を`FitDiagnostics`オブジェクトにまとめて返します。

パラメータ:

• names -- パラメータ名のシーケンス。

• values -- パラメータ値のシーケンス。

• cov -- パラメータ共分散行列。

• jacobian -- 残差のJacobian行列。渡すと J^T J の条件数と最小固有方向も評価します。デフォルトはNone。

• topk_eigen -- 共分散行列の固有ベクトルサマリーで表示する上位の固有方向の数。デフォルトは3。

• compk_eigen -- 共分散行列の固有ベクトルサマリーで、各固有方向で表示する主要なパラメータ成分の数。デフォルトは4。

戻り値:

フィット診断結果を格納した`FitDiagnostics`オブジェクト。

regression.tklsq.tkfitdiag.diagnostics_to_dict(diag: FitDiagnostics) → dict

JSON保存しやすい辞書に変換する。

概要:

`FitDiagnostics`オブジェクトを、JSON形式で保存するのに適した辞書形式に変換します。

詳細説明:

Numpy配列はPythonのリストに変換され、`EigenSummary`オブジェクトも入れ子になった辞書に変換されます。 これにより、標準的なJSONシリアライザで`FitDiagnostics`オブジェクトの内容を簡単に保存・復元できます。 `jtj`や`eig_jtj`関連のフィールドがNoneの場合は、出力辞書でもNoneとして表現されます。

パラメータ:

diag -- 変換する`FitDiagnostics`オブジェクト。

戻り値:

変換された辞書形式のデータ。

regression.tklsq.tkfitdiag.eigen_sorted_symmetric(A: ndarray, descending: bool = True) → Tuple[ndarray, ndarray]

対称行列の固有値・固有ベクトルをソートして返す。

概要:

対称行列の固有値と固有ベクトルを計算し、指定された順序でソートして返します。

詳細説明:

`numpy.linalg.eigh`を使用して固有値と固有ベクトルを計算した後、 `descending`引数に基づいて固有値をソートし、それに対応する固有ベクトルもソートします。

パラメータ:

• A -- 対称行列。

• descending -- 固有値を降順にソートするかどうか。Trueの場合降順、Falseの場合昇順。デフォルトはTrue。

戻り値:

ソートされた固有値の配列 (np.ndarray) と、それに対応するソートされた固有ベクトルを行列として格納したタプル (np.ndarray)。

regression.tklsq.tkfitdiag.format_fix_candidates(candidates: Sequence[FixCandidate]) → str

固定候補をコンソール表示しやすい文字列にする。

概要:

固定または外部拘束の候補リストを、コンソールで読みやすい複数行の文字列形式に整形します。

詳細説明:

各`FixCandidate`オブジェクトのパラメータ名、値、標準誤差、相対誤差、スコア、 および提案理由を抽出し、見出し付きで詳細なリストとして表示します。

パラメータ:

candidates -- `FixCandidate`オブジェクトのシーケンス。

戻り値:

フォーマットされた文字列。

regression.tklsq.tkfitdiag.propose_fix_candidates(names: Sequence[str], values: Sequence[float], stderr: Sequence[float], corr: ndarray, *, eig_cov_values: Sequence[float] | None = None, eig_cov_vectors: ndarray | None = None, corr_thr: float = 0.95, relerr_thr: float = 0.5, topn: int = 3) → List[FixCandidate]

固定/外部拘束候補をヒューリスティックに提案する。

概要:

フィットパラメータの固定または外部拘束の候補をヒューリスティックな基準で提案します。

詳細説明:

パラメータの相対標準誤差、他のパラメータとの強相関、共分散行列の最大固有値方向への寄与度に基づいて、 各パラメータの「固定しやすさ」スコアを計算します。 スコアが高く、相対誤差や強相関の閾値を超えるパラメータを候補としてリストアップし、 スコアの降順でソートして返します。

判断材料: - 相対標準誤差 stderr / |value| - 他パラメータとの強相関 - 共分散最大固有値方向への寄与

注意: これは数値的な「決まりにくさ」の診断であり、最終判断は物理的妥当性、 独立測定、文献値の有無と合わせて行う必要があります。

パラメータ:

• names -- パラメータ名のシーケンス。

• values -- パラメータ値のシーケンス。

• stderr -- パラメータの標準誤差のシーケンス。

• corr -- 相関係数行列。

• eig_cov_values -- 共分散行列の固有値（降順）。Noneの場合、固有方向からの寄与は評価されません。デフォルトはNone。

• eig_cov_vectors -- 共分散行列の固有ベクトル（対応する固有値が降順）。Noneの場合、固有方向からの寄与は評価されません。デフォルトはNone。

• corr_thr -- 強相関と見なす相関係数の絶対値の閾値。デフォルトは0.95。

• relerr_thr -- 相対標準誤差が高いと見なす閾値。デフォルトは0.5。

• topn -- 提案する候補の最大数。デフォルトは3。

戻り値:

`FixCandidate`オブジェクトのリスト。スコアの高い順にソートされます。

regression.tklsq.tkfitdiag.propose_fix_candidates_from_diagnostics(diag: FitDiagnostics, *, corr_thr: float = 0.95, relerr_thr: float = 0.5, topn: int = 3) → List[FixCandidate]

FitDiagnostics から固定候補を提案するショートカット。

概要:

`FitDiagnostics`オブジェクトを利用して、パラメータの固定または外部拘束の候補を提案します。

詳細説明:

`diagnose_covariance`関数によって生成された`FitDiagnostics`オブジェクトから必要な情報を取り出し、 `propose_fix_candidates`関数を呼び出すための便利なショートカット関数です。

パラメータ:

• diag -- フィット診断結果を格納した`FitDiagnostics`オブジェクト。

• corr_thr -- 強相関と見なす相関係数の絶対値の閾値。デフォルトは0.95。

• relerr_thr -- 相対標準誤差が高いと見なす閾値。デフォルトは0.5。

• topn -- 提案する候補の最大数。デフォルトは3。

戻り値:

`FixCandidate`オブジェクトのリスト。スコアの高い順にソートされます。

regression.tklsq.tkfitdiag.summarize_eigenvectors(eigenvalues: Sequence[float], eigenvectors: ndarray, names: Sequence[str], *, topk: int = 3, compk: int = 3) → List[EigenSummary]

固有ベクトルの主要成分を読みやすくまとめる。

概要:

固有値と固有ベクトルから、主要な固有方向とその構成要素を分かりやすい形式でサマライズします。

詳細説明:

与えられた固有値と固有ベクトルから、上位の`topk`個の固有方向と、 各固有方向において寄与の大きい`compk`個のパラメータを抽出し、 `EigenSummary`オブジェクトのリストとして生成します。

パラメータ:

• eigenvalues -- 固有値のシーケンス。

• eigenvectors -- 固有ベクトルの行列。各列が1つの固有ベクトルに対応します。

• names -- パラメータ名のシーケンス。

• topk -- サマリーに含める上位の固有方向の数。デフォルトは3。

• compk -- 各固有方向で表示する主要なパラメータ成分の数。デフォルトは3。

戻り値:

主要成分のサマリーを表す`EigenSummary`オブジェクトのリスト。