tknlsq プログラム仕様

tknlsq.py

非線形最小二乗の小さな汎用ラッパー。

tknlsq.py 技術ドキュメント

設計方針

  • アプリ固有の物理モデルは外に置く

  • ここでは residual_func(params) -> residual vector を最小化する

  • 数値 Jacobian と cov ≈ s^2 (J^T J)^(-1) を共通化する

  • 固定パラメータを扱いやすくする

SciPy がある場合は scipy.optimize.least_squares を使う。 SciPy がない環境では ImportError を出す。

class regression.tklsq.tknlsq.NonlinearLSQResult(params: ndarray | Dict[str, float], params_free: ndarray, names: List[str], free_names: List[str], fixed_names: List[str], residuals: ndarray, jacobian: ndarray | None, cov_free: ndarray | None, stderr_free: ndarray | None, stderr: ndarray | None | Dict[str, float | None], sigma2_resid: float | None, dof: int, N: int, p_free: int, RSS: float, cost: float, success: bool, message: str, nfev: int | None = None, njev: int | None = None, status: int | None = None, warning: str = '', raw_result: object = None)[ソース]

ベースクラス: object

非線形最小二乗の結果を格納するデータクラス。

非線形最小二乗フィッティングの実行結果、計算されたパラメータ、統計情報などを保持します。

パラメータ:

  • params (Union[np.ndarray, Dict[str, float]]) -- 最適化された全パラメータ。入力が辞書形式だった場合は辞書、それ以外はNumPy配列。

  • params_free (np.ndarray) -- 最適化された自由パラメータのみのNumPy配列。

  • names (List[str]) -- 全パラメータの名前のリスト。

  • free_names (List[str]) -- 自由パラメータの名前のリスト。

  • fixed_names (List[str]) -- 固定パラメータの名前のリスト。

  • residuals (np.ndarray) -- 最適化後の残差ベクトル。

  • jacobian (Optional[np.ndarray]) -- 最適化された自由パラメータにおける残差関数のヤコビアン行列。None の場合もある。

  • cov_free (Optional[np.ndarray]) -- 自由パラメータの共分散行列。None の場合もある。

  • stderr_free (Optional[np.ndarray]) -- 自由パラメータの標準誤差のNumPy配列。None の場合もある。

  • stderr (Union[Optional[np.ndarray], Dict[str, Optional[float]]]) -- 全パラメータの標準誤差。入力が辞書形式だった場合は辞書、それ以外はNumPy配列。固定パラメータは0.0。None の場合もある。

  • sigma2_resid (Optional[float]) -- 残差の分散 (s^2 = RSS / dof)。None の場合もある。

  • dof (int) -- 残差の自由度 (N - p_free)。

  • N (int) -- 残差ベクトルの要素数。

  • p_free (int) -- 自由パラメータの数。

  • RSS (float) -- 残差平方和 (Residual Sum of Squares)。

  • cost (float) -- scipy.optimize.least_squares から返されるコスト (0.5 * RSS)。

  • success (bool) -- 最適化が成功したかどうかを示す真偽値。

  • message (str) -- 最適化の終了メッセージ。

  • nfev (Optional[int]) -- 関数評価の回数。

  • njev (Optional[int]) -- ヤコビアン評価の回数。

  • status (Optional[int]) -- scipy.optimize.least_squares からの終了ステータスコード。

  • warning (str) -- 発生した可能性のある警告メッセージ。

  • raw_result (object) -- scipy.optimize.least_squares から返される生の結果オブジェクト。

N: int
RSS: float
cost: float
cov_free: ndarray | None
dof: int
fixed_names: List[str]
free_names: List[str]
jacobian: ndarray | None
message: str
names: List[str]
nfev: int | None = None
njev: int | None = None
p_free: int
params: ndarray | Dict[str, float]
params_free: ndarray
raw_result: object = None
residuals: ndarray
sigma2_resid: float | None
property sigma_resid: float | None

残差の標準偏差 (s)。

戻り値:

残差の標準偏差。sigma2_residがNoneの場合はNone。

戻り値の型:

Optional[float]

status: int | None = None
stderr: ndarray | None | Dict[str, float | None]
stderr_free: ndarray | None
success: bool
warning: str = ''
regression.tklsq.tknlsq.covariance_from_jacobian(residuals: Sequence[float] | ndarray, J: ndarray, *, dof: int | None = None, rcond: float = 1e-12) → Tuple[ndarray | None, ndarray | None, float | None, str][ソース]

残差とヤコビアンからパラメータの共分散行列を近似的に計算する。

共分散は cov ≈ s^2 * (J^T J)^(-1) の形式で近似される。ここで s^2 = RSS / dof。 自由度 (dof) が0以下の場合、共分散と標準誤差は None を返す。 J^T J が特異行列の場合、擬似逆行列 (pinv) を使用する。

パラメータ:

  • residuals (ArrayLike) -- 最適化後の残差ベクトル。

  • J (np.ndarray) -- 残差関数のヤコビアン行列。

  • dof (Optional[int]) -- 残差の自由度 (N - パラメータ数)。None の場合、residuals.size - J.shape[1] で計算される。

  • rcond (float) -- 擬似逆行列計算時に使用される、特異値の相対的なしきい値。

戻り値:

共分散行列、標準誤差ベクトル、残差分散 s^2、警告メッセージのタプル。 自由度が0以下の場合は (None, None, None, warning) が返される。

戻り値の型:

Tuple[Optional[np.ndarray], Optional[np.ndarray], Optional[float], str]

例外:

ValueError -- Jが2Dでない場合、またはJの行数と残差のサイズが一致しない場合。

regression.tklsq.tknlsq.delta_method_band(output_func: Callable[[ndarray], Sequence[float] | ndarray], p: Sequence[float] | ndarray, cov: ndarray, *, nsigma: float = 1.0, rel_step: float = 1e-06, abs_step: float = 1e-12) → Tuple[ndarray, ndarray, ndarray, ndarray][ソース]

デルタ法を用いて、出力関数 y=f(p) の値、信頼帯の下限、上限、標準偏差を計算する。

y0 - nsigma * sigma_y と y0 + nsigma * sigma_y で信頼帯を計算する。 信頼帯は nsigma に応じて調整される（例: nsigma=1 で1シグマ帯）。

パラメータ:

  • output_func (Callable[[np.ndarray], ArrayLike]) -- パラメータベクトルを受け取り、出力量のベクトルを返す関数。

  • p (ArrayLike) -- 出力を評価するパラメータの点。

  • cov (np.ndarray) -- パラメータ p の共分散行列。

  • nsigma (float) -- 信頼帯の幅を決定するためのシグマ値の倍数。

  • rel_step (float) -- 数値ヤコビアン計算の相対ステップサイズ。

  • abs_step (float) -- 数値ヤコビアン計算の最小絶対ステップサイズ。

戻り値:

出力値 y0、信頼帯の下限 y_low、信頼帯の上限 y_high、出力の標準偏差 sigma_y のタプル。

戻り値の型:

Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]

regression.tklsq.tknlsq.delta_method_variance(output_func: Callable[[ndarray], Sequence[float] | ndarray], p: Sequence[float] | ndarray, cov: ndarray, *, rel_step: float = 1e-06, abs_step: float = 1e-12) → Tuple[ndarray, ndarray, ndarray][ソース]

デルタ法を用いて、パラメータの共分散から出力関数の分散を計算する。

出力関数 y = f(p) の分散 Var(y) を、 Var(y) ≈ J * Cov(p) * J^T (ここで J は f のヤコビアン) として近似する。

パラメータ:

  • output_func (Callable[[np.ndarray], ArrayLike]) -- パラメータベクトルを受け取り、出力量のベクトルを返す関数。

  • p (ArrayLike) -- 出力を評価するパラメータの点。

  • cov (np.ndarray) -- パラメータ p の共分散行列。

  • rel_step (float) -- 数値ヤコビアン計算の相対ステップサイズ。

  • abs_step (float) -- 数値ヤコビアン計算の最小絶対ステップサイズ。

戻り値:

出力値のベクトル y0、出力の分散のベクトル var_y、出力関数のヤコビアン grads のタプル。

戻り値の型:

Tuple[np.ndarray, np.ndarray, np.ndarray]

例外:

ValueError -- cov の形状が p のサイズと一致しない場合。

regression.tklsq.tknlsq.nonlinear_lsq(residual_func: Callable[[ndarray | Dict[str, float]], Sequence[float] | ndarray], p0: Sequence[float] | Mapping[str, float], *, names: Sequence[str] | None = None, fixed: Sequence[str] | Mapping[str, float] | None = None, bounds=None, loss: str = 'linear', max_nfev: int | None = None, rel_step: float = 1e-06, abs_step: float = 1e-12, use_result_jac: bool = True, scipy_kwargs: dict | None = None) → NonlinearLSQResult[ソース]

非線形最小二乗フィッティングを実行する。

residual_func(params) -> 1D residual vector を最小化する。 内部で scipy.optimize.least_squares を使用する。 p0 が辞書の場合、residual_func には辞書が渡される。 p0 がリスト/配列の場合、residual_func には np.ndarray が渡される。

パラメータ:

  • residual_func (Callable[[Union[np.ndarray, Dict[str, float]]], ArrayLike]) -- パラメータを受け取り、残差の1Dベクトルを返す関数。 受け取るパラメータの型は p0 の形式によって異なる (NumPy配列または辞書)。

  • p0 (ParamsLike) -- 初期パラメータ。シーケンス（リスト、NumPy配列など）または名前と値のマップ（辞書）。

  • names (Optional[Sequence[str]]) -- パラメータ名のシーケンス。p0 がシーケンスの場合に必須。 p0 が辞書の場合、この引数はオプションで、キーの順序を決定するために使用できる。

  • fixed (Optional[Union[Sequence[str], Mapping[str, float]]]) -- 固定するパラメータの定義。 パラメータ名のシーケンス（p0 から値を取得）。 または、{name: value} の辞書（指定された値で固定）。

  • bounds (Optional[Union[Mapping[str, Tuple[float, float]], Tuple[ArrayLike, ArrayLike]]]) -- パラメータの境界条件。 None (無制限)、{name: (lower, upper)} の辞書、 または (lower_bounds, upper_bounds) のタプル。 lower_bounds と upper_bounds は p0 と同じ形式か、自由パラメータの数に合わせたシーケンス。

  • loss (str) -- scipy.optimize.least_squares に渡される損失関数 ('linear', 'soft_l1', 'huber', 'cauchy', 'arctan')。

  • max_nfev (Optional[int]) -- 関数評価の最大回数。None の場合、least_squares のデフォルトを使用。

  • rel_step (float) -- 数値ヤコビアン計算の相対ステップサイズ。

  • abs_step (float) -- 数値ヤコビアン計算の最小絶対ステップサイズ。

  • use_result_jac (bool) -- scipy.optimize.least_squares から返されるヤコビアンを使用するかどうか。 True の場合、res.jac があればそれを使用し、なければ numerical_jacobian をフォールバックする。 False の場合、常に numerical_jacobian を使用する。

  • scipy_kwargs (Optional[dict]) -- scipy.optimize.least_squares に渡す追加のキーワード引数辞書。

戻り値:

非線形最小二乗フィッティングの結果を格納した NonlinearLSQResult オブジェクト。

戻り値の型:

NonlinearLSQResult

例外:

ImportError -- scipy がインストールされていない場合。

regression.tklsq.tknlsq.numerical_jacobian(fun_vec: Callable[[ndarray], Sequence[float] | ndarray], p: Sequence[float] | ndarray, *, rel_step: float = 1e-06, abs_step: float = 1e-12) → ndarray[ソース]

中心差分法を用いてベクトル関数のヤコビアンを数値的に計算する。

fun_vec(p) -> 残差ベクトル が与えられたとき、J[i, j] = d residual_i / d p_j となるヤコビアン行列を計算する。 微分のステップサイズは rel_step * (abs(p[j]) + 1.0) + abs_step で計算され、 これは相対ステップと絶対ステップを組み合わせた頑健な方法である。

パラメータ:

  • fun_vec (Callable[[np.ndarray], ArrayLike]) -- パラメータベクトルを受け取り、残差ベクトルを返す関数。

  • p (ArrayLike) -- ヤコビアンを評価するパラメータの点。

  • rel_step (float) -- 相対ステップサイズ。パラメータ値の大きさに応じてステップサイズが決定される。

  • abs_step (float) -- 最小絶対ステップサイズ。パラメータ値が0に近い場合でも最小限のステップを保証する。

戻り値:

計算されたヤコビアン行列。J[i, j] = d residual_i / d p_j。

戻り値の型:

np.ndarray

例外:

ValueError -- fun_vecの出力サイズが数値微分中に変更された場合。

regression.tklsq.tknlsq.result_free_cov(result: NonlinearLSQResult) → ndarray | None[ソース]

NonlinearLSQResult オブジェクトから自由パラメータの共分散行列を返す。

パラメータ:

result (NonlinearLSQResult) -- 非線形最小二乗フィッティングの結果オブジェクト。

戻り値:

自由パラメータの共分散行列。共分散が計算されなかった場合は None。

戻り値の型:

Optional[np.ndarray]

regression.tklsq.tknlsq.result_free_values(result: NonlinearLSQResult) → ndarray[ソース]

NonlinearLSQResult オブジェクトから最適化された自由パラメータ値のNumPy配列を返す。

パラメータ:

result (NonlinearLSQResult) -- 非線形最小二乗フィッティングの結果オブジェクト。

戻り値:

最適化された自由パラメータ値のNumPy配列。

戻り値の型:

np.ndarray