tklsq APIリファレンス

対象ソース: tklib2.zip（解析日: 2026-08-03）。この文書はソースコードを静的解析して生成しています。

APIの読み方

パッケージ公開APIは、原則としてトップレベルの __all__ に含まれる名前です。
モジュールAPIには、公開名（先頭が _ でない関数・クラス・メソッド）を列挙しています。
docstringがないAPIでは、シグネチャとソースパスを一次情報として扱ってください。
生成AIは、この文書に存在しない引数・戻り値・メソッドを推測で追加しないでください。

パッケージ公開API

from tklsq import (
    LeastSquaresResult,
    PredictionResult,
    ModelSelectionResult,
    BayesianLinearResult,
    polynomial_design_matrix,
    design_matrix_from_functions,
    add_intercept,
    linear_lsq,
    polynomial_lsq,
    predict_linear,
    predict_polynomial,
    parameter_prediction_variance,
    delta_method_variance,
    regression_scores,
    information_criteria,
)

名前	推奨用途
`LeastSquaresResult`	トップレベルから安定してimportできる公開API
`PredictionResult`	トップレベルから安定してimportできる公開API
`ModelSelectionResult`	トップレベルから安定してimportできる公開API
`BayesianLinearResult`	トップレベルから安定してimportできる公開API
`polynomial_design_matrix`	トップレベルから安定してimportできる公開API
`design_matrix_from_functions`	トップレベルから安定してimportできる公開API
`add_intercept`	トップレベルから安定してimportできる公開API
`linear_lsq`	トップレベルから安定してimportできる公開API
`polynomial_lsq`	トップレベルから安定してimportできる公開API
`predict_linear`	トップレベルから安定してimportできる公開API
`predict_polynomial`	トップレベルから安定してimportできる公開API
`parameter_prediction_variance`	トップレベルから安定してimportできる公開API
`delta_method_variance`	トップレベルから安定してimportできる公開API
`regression_scores`	トップレベルから安定してimportできる公開API
`information_criteria`	トップレベルから安定してimportできる公開API

モジュール一覧

モジュール	ソース	関数	クラス
`tklsq`	`tklsq/__init__.py`	0	0
`tklsq.tkdataio`	`tklsq/tkdataio.py`	5	0
`tklsq.tkfitdiag`	`tklsq/tkfitdiag.py`	8	3
`tklsq.tklsq`	`tklsq/tklsq.py`	24	4
`tklsq.tkminfit`	`tklsq/tkminfit.py`	7	1
`tklsq.tknlsq`	`tklsq/tknlsq.py`	7	1
`tklsq.tkparamio`	`tklsq/tkparamio.py`	24	0
`tklsq.tkplot`	`tklsq/tkplot.py`	4	0
`tklsq.tksynthetic`	`tklsq/tksynthetic.py`	5	1

`tklsq`

ソース: tklsq/__init__.py

tklsq: lightweight least-squares and fitting utilities.

このモジュールには静的解析で検出された公開関数・クラス・定数はありません。

`tklsq.tkdataio`

ソース: tklsq/tkdataio.py

tkdataio.py

軽量な表データ入出力ユーティリティ。

既存の tkVariousData/tkFit を置き換える目的ではなく、独立した小さな解析スクリプトを素早く作るための補助モジュール。

function `read_table`

def read_table(path: Union[str, Path], *, sheet_name = 0)

CSV/TSV/TXT/XLSX を pandas.DataFrame として読む。

function `read_xy`

def read_xy(path: Union[str, Path], x: ColumnKey = 0, y: ColumnKey = 1, *, sheet_name = 0, xmin: float = -1e+100, xmax: float = 1e+100, dropna: bool = True) -> Tuple[np.ndarray, np.ndarray, str, str]

表ファイルから x, y の2列を取り出す。

function `write_excel_tables`

def write_excel_tables(path: Union[str, Path], tables: Mapping[str, object], *, index: bool = False) -> None

複数テーブルを Excel の複数シートに保存する。

tables の値は pandas.DataFrame、dict、2D array のいずれかを想定。

function `save_json`

def save_json(path: Union[str, Path], data: object, *, indent: int = 2) -> None

JSON保存。NumPy型はPython型へ変換する。

function `load_json`

def load_json(path: Union[str, Path]) -> object

JSON読み込み。

`tklsq.tkfitdiag`

ソース: tklsq/tkfitdiag.py

tkfitdiag.py

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

線形/非線形を問わず、パラメータ共分散行列が得られた後に使う。主な用途:

共分散行列 -> 標準偏差・相関係数行列
共分散行列の固有値/固有ベクトルから、不確かな方向を調べる
J^T J の固有値/条件数から、同定しにくいパラメータ結合を調べる
相対誤差・強相関・不確かな固有方向への寄与から固定候補を提案する

class `EigenSummary`

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

データクラス相当の初期化フィールド

EigenSummary(rank: int, eigenvalue: float, components: List[Tuple[str, float]])

フィールド

名前	型	既定値
`rank`	`int`	`必須`
`eigenvalue`	`float`	`必須`
`components`	`List[Tuple[str, float]]`	`必須`

class `FixCandidate`

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

データクラス相当の初期化フィールド

FixCandidate(param: str, score: float, value: float, stderr: float, relerr: Optional[float], reasons: List[str])

フィールド

名前	型	既定値
`param`	`str`	`必須`
`score`	`float`	`必須`
`value`	`float`	`必須`
`stderr`	`float`	`必須`
`relerr`	`Optional[float]`	`必須`
`reasons`	`List[str]`	`必須`

class `FitDiagnostics`

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

データクラス相当の初期化フィールド

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_summary: List[EigenSummary], jtj: Optional[np.ndarray] = None, eig_jtj_values_asc: Optional[np.ndarray] = None, eig_jtj_vectors_asc: Optional[np.ndarray] = None, cond_jtj: Optional[float] = None, warning: str = '')

フィールド

名前	型	既定値
`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_summary`	`List[EigenSummary]`	`必須`
`jtj`	`Optional[np.ndarray]`	`None`
`eig_jtj_values_asc`	`Optional[np.ndarray]`	`None`
`eig_jtj_vectors_asc`	`Optional[np.ndarray]`	`None`
`cond_jtj`	`Optional[float]`	`None`
`warning`	`str`	`''`

function `covariance_to_correlation`

def covariance_to_correlation(cov: np.ndarray) -> Tuple[np.ndarray, np.ndarray]

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

function `eigen_sorted_symmetric`

def eigen_sorted_symmetric(A: np.ndarray, descending: bool = True) -> Tuple[np.ndarray, np.ndarray]

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

function `summarize_eigenvectors`

def summarize_eigenvectors(eigenvalues: Sequence[float], eigenvectors: np.ndarray, names: Sequence[str], *, topk: int = 3, compk: int = 3) -> List[EigenSummary]

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

function `diagnose_covariance`

def 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

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

Parameters

names, values パラメータ名と値。 cov パラメータ共分散行列。 jacobian 残差の Jacobian。渡すと J^T J の条件数と最小固有方向も評価する。

function `propose_fix_candidates`

def 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]

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

判断材料:

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

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

function `propose_fix_candidates_from_diagnostics`

def propose_fix_candidates_from_diagnostics(diag: FitDiagnostics, *, corr_thr: float = 0.95, relerr_thr: float = 0.5, topn: int = 3) -> List[FixCandidate]

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

function `format_fix_candidates`

def format_fix_candidates(candidates: Sequence[FixCandidate]) -> str

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

function `diagnostics_to_dict`

def diagnostics_to_dict(diag: FitDiagnostics) -> dict

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

`tklsq.tklsq`

ソース: tklsq/tklsq.py

tklsq.py

汎用線形回帰・誤差評価・モデル選択ユーティリティ。

設計方針

基本は線形最小二乗: y = X beta + eps
パラメータ誤差は cov(beta) = sigma^2 (X^T W X)^(-1)
推定値誤差は Var[y_mean] = diag(X_new cov(beta) X_new^T)
予測誤差は Var[y_pred] = Var[y_mean] + sigma^2
モデル選択は AIC/BIC/AICc と、必要に応じてベイズ evidence を使う

このファイルは tklib / matplotlib / openpyxl に依存しない「計算コア」です。入出力、グラフ、Excel保存は呼び出し側スクリプトに残す想定です。

class `LeastSquaresResult`

線形最小二乗の結果。

データクラス相当の初期化フィールド

LeastSquaresResult(beta: np.ndarray, beta_std: Optional[np.ndarray], cov_beta: Optional[np.ndarray], sigma2_resid: Optional[float], residuals: np.ndarray, y_fit: np.ndarray, N: int, p: int, dof: int, rank: int, RSS: float, WRSS: float, singular_values: np.ndarray, condition_number: float, error_estimation_enabled: bool, warning: str = '', known_sigma: bool = False)

フィールド

名前	型	既定値
`beta`	`np.ndarray`	`必須`
`beta_std`	`Optional[np.ndarray]`	`必須`
`cov_beta`	`Optional[np.ndarray]`	`必須`
`sigma2_resid`	`Optional[float]`	`必須`
`residuals`	`np.ndarray`	`必須`
`y_fit`	`np.ndarray`	`必須`
`N`	`int`	`必須`
`p`	`int`	`必須`
`dof`	`int`	`必須`
`rank`	`int`	`必須`
`RSS`	`float`	`必須`
`WRSS`	`float`	`必須`
`singular_values`	`np.ndarray`	`必須`
`condition_number`	`float`	`必須`
`error_estimation_enabled`	`bool`	`必須`
`warning`	`str`	`''`
`known_sigma`	`bool`	`False`

メソッド／プロパティ

property `LeastSquaresResult.sigma_resid`

def sigma_resid(self) -> Optional[float]

ソース内docstringはありません。シグネチャと実装を参照してください。

class `PredictionResult`

線形モデルの推定値・誤差バンド。

データクラス相当の初期化フィールド

PredictionResult(y_mean: np.ndarray, sigma_param: Optional[np.ndarray], sigma_pred: Optional[np.ndarray], var_param: Optional[np.ndarray], var_pred: Optional[np.ndarray])

フィールド

名前	型	既定値
`y_mean`	`np.ndarray`	`必須`
`sigma_param`	`Optional[np.ndarray]`	`必須`
`sigma_pred`	`Optional[np.ndarray]`	`必須`
`var_param`	`Optional[np.ndarray]`	`必須`
`var_pred`	`Optional[np.ndarray]`	`必須`

class `ModelSelectionResult`

複数モデル比較の結果。

データクラス相当の初期化フィールド

ModelSelectionResult(labels: List[str], scores: np.ndarray, weights: np.ndarray, best_index: int, criterion: str, results: Optional[List[LeastSquaresResult]] = None, log_evidences: Optional[np.ndarray] = None)

フィールド

名前	型	既定値
`labels`	`List[str]`	`必須`
`scores`	`np.ndarray`	`必須`
`weights`	`np.ndarray`	`必須`
`best_index`	`int`	`必須`
`criterion`	`str`	`必須`
`results`	`Optional[List[LeastSquaresResult]]`	`None`
`log_evidences`	`Optional[np.ndarray]`	`None`

メソッド／プロパティ

property `ModelSelectionResult.best_label`

def best_label(self) -> str

ソース内docstringはありません。シグネチャと実装を参照してください。

class `BayesianLinearResult`

ベイズ線形回帰の事後分布。

データクラス相当の初期化フィールド

BayesianLinearResult(mean: np.ndarray, cov: np.ndarray, alpha: float, beta: float, sigma_noise: float, log_evidence: Optional[float] = None, n_iter: int = 0, converged: bool = False)

フィールド

名前	型	既定値
`mean`	`np.ndarray`	`必須`
`cov`	`np.ndarray`	`必須`
`alpha`	`float`	`必須`
`beta`	`float`	`必須`
`sigma_noise`	`float`	`必須`
`log_evidence`	`Optional[float]`	`None`
`n_iter`	`int`	`0`
`converged`	`bool`	`False`

function `polynomial_design_matrix`

def polynomial_design_matrix(x: ArrayLike, order: Optional[int] = None, basis_indices: Optional[Sequence[int]] = None) -> np.ndarray

多項式基底の設計行列を作る。

Parameters

x : array-like 1次元の説明変数。 order : int, optional 0, 1, ..., order の全基底を使う。 basis_indices : sequence of int, optional 任意のべき指数を指定する。例: [0, 1, 3]。

Returns

X : ndarray, shape (N, p)

function `design_matrix_from_functions`

def design_matrix_from_functions(x: ArrayLike, basis_functions: Sequence) -> np.ndarray

任意の基底関数リストから設計行列を作る。

basis_functions の各要素は f(x_array) を返す関数、または np.vectorize 可能な f(x_scalar) を想定する。

function `add_intercept`

def add_intercept(X: np.ndarray) -> np.ndarray

設計行列の先頭列に定数項を追加する。

function `linear_lsq`

def linear_lsq(X: np.ndarray, y: ArrayLike, *, weights: Optional[ArrayLike] = None, known_sigma: bool = False, rcond: Optional[float] = None, cond_warning: float = 1000000000000.0) -> LeastSquaresResult

線形最小二乗を行い、可能なら共分散行列と誤差を計算する。

Parameters

X : ndarray, shape (N, p) 設計行列。 y : array-like, shape (N,) 観測値。 weights : array-like, optional 重み。通常は 1/sigma_y^2 を指定する。 None の場合は等重み。 known_sigma : bool True の場合、weights が絶対的な 1/sigma_y^2 であるとみなし、 cov(beta) = (X^T W X)^(-1) とする。 False の場合、残差から sigma^2 を推定して掛ける。 rcond : float or None np.linalg.lstsq の cutoff。 cond_warning : float 条件数がこの値を超えると warning に追記する。

Notes

rank deficient または N-p<=0 の場合でも beta は返す。ただし unbiased な残差分散とパラメータ誤差は返さず、 beta_std, cov_beta, sigma2_resid は None になる。

function `polynomial_lsq`

def polynomial_lsq(x: ArrayLike, y: ArrayLike, order: Optional[int] = None, *, basis_indices: Optional[Sequence[int]] = None, weights: Optional[ArrayLike] = None, known_sigma: bool = False, rcond: Optional[float] = None) -> LeastSquaresResult

多項式線形回帰の便利関数。

function `parameter_prediction_variance`

def parameter_prediction_variance(X_new: np.ndarray, cov_beta: np.ndarray) -> np.ndarray

Var[y_mean] = diag(X_new cov_beta X_new^T) を計算する。

function `predict_linear`

def predict_linear(X_new: np.ndarray, result: LeastSquaresResult, *, sigma2_noise: Optional[float] = None, include_noise: bool = True) -> PredictionResult

線形回帰結果から、推定値と誤差バンドを計算する。

function `predict_polynomial`

def predict_polynomial(x_new: ArrayLike, result: LeastSquaresResult, order: Optional[int] = None, *, basis_indices: Optional[Sequence[int]] = None, sigma2_noise: Optional[float] = None, include_noise: bool = True) -> PredictionResult

多項式回帰結果から、推定値と誤差バンドを計算する。

function `measurement_std`

def measurement_std(y: ArrayLike, ddof: int = 1) -> float

観測値全体の標準偏差を測定ばらつきの目安として返す。

function `delta_method_variance`

def delta_method_variance(jacobian: np.ndarray, cov_beta: np.ndarray) -> np.ndarray

デルタ法: Var[g(beta)] = J cov(beta) J^T の対角を返す。

jacobian は shape (N, p) または (p,) を想定する。派生量、例えば活性化エネルギーや移動度の log 変換後の誤差伝播に使える。

function `regression_scores`

def regression_scores(y: ArrayLike, y_fit: ArrayLike, p: int = 0) -> Dict[str, float]

基本的な回帰スコアを返す。

従来の N, p, RSS, RMSE, R2, adj_R2 に加え、互換性を壊さず MAE と max_abs_error を追加している。

function `gaussian_log_likelihood_from_rss`

def gaussian_log_likelihood_from_rss(RSS: float, N: int, sigma2: Optional[float] = None) -> float

Gaussian residual を仮定した log likelihood。

sigma2=None の場合、MLE sigma2=RSS/N を使う。

function `information_criteria`

def information_criteria(result: LeastSquaresResult, *, k: Optional[int] = None) -> Dict[str, float]

AIC, AICc, BIC を計算する。

function `normalized_weights_from_scores`

def normalized_weights_from_scores(scores: ArrayLike, *, lower_is_better: bool = True) -> np.ndarray

AIC/BIC や -log evidence から相対重みを計算する。

function `select_models_by_ic`

def select_models_by_ic(candidates: CandidateType, y: ArrayLike, *, labels: Optional[Sequence[str]] = None, criterion: str = 'BIC', weights: Optional[ArrayLike] = None, rcond: Optional[float] = None) -> ModelSelectionResult

候補設計行列を AIC/AICc/BIC で比較する。

function `polynomial_candidates`

def polynomial_candidates(x: ArrayLike, max_order: int, *, min_order: int = 0) -> Dict[str, np.ndarray]

0..max_order の多項式候補を dict として作る。

function `basis_index_candidates`

def basis_index_candidates(x: ArrayLike, models: Sequence[Sequence[int]]) -> Dict[str, np.ndarray]

任意の多項式べき指数リストから候補設計行列を作る。

function `bayesian_posterior`

def bayesian_posterior(X: np.ndarray, y: ArrayLike, *, alpha: float = 1.0, beta: float = 1.0, mu0: Optional[ArrayLike] = None, prior_cov: Optional[np.ndarray] = None) -> BayesianLinearResult

線形ガウスモデルの事後平均・共分散を計算する。

prior: beta_vec ~ N(mu0, prior_cov / alpha) noise: y|beta_vec ~ N(X beta_vec, I / beta)

function `bayesian_log_evidence`

def bayesian_log_evidence(X: np.ndarray, y: ArrayLike, *, alpha: float = 1.0, beta: float = 1.0, mu0: Optional[ArrayLike] = None, prior_cov: Optional[np.ndarray] = None) -> float

線形ガウスモデルの log evidence を計算する。

prior: beta_vec ~ N(mu0, prior_cov / alpha) noise: y|beta_vec ~ N(X beta_vec, I / beta)

N が大きい場合は O(N^3) なので、候補数・データ数が大きい用途では高速版の追加を検討する。

function `empirical_bayes_linear`

def empirical_bayes_linear(X: np.ndarray, y: ArrayLike, *, alpha0: float = 1.0, beta0: Optional[float] = None, sigma_noise0: float = 1.0, mu0: Optional[ArrayLike] = None, max_iter: int = 100, tol: float = 0.0001, eps: float = 1e-300) -> BayesianLinearResult

MacKay型の evidence maximization で alpha, beta を推定する。

現在は等方 prior beta_vec ~ N(mu0, I/alpha) 用。

function `predict_bayesian`

def predict_bayesian(X_new: np.ndarray, result: BayesianLinearResult, *, include_noise: bool = True) -> PredictionResult

ベイズ線形回帰結果から予測平均・分散を計算する。

function `posterior_model_probabilities`

def posterior_model_probabilities(log_evidences: ArrayLike, log_priors: Optional[ArrayLike] = None) -> np.ndarray

log evidence と log prior から事後モデル確率を計算する。

function `select_models_by_evidence`

def select_models_by_evidence(candidates: CandidateType, y: ArrayLike, *, labels: Optional[Sequence[str]] = None, alpha: float = 1.0, beta: float = 1.0, log_priors: Optional[ArrayLike] = None) -> ModelSelectionResult

候補設計行列を Bayesian log evidence で比較する。

function `ard_select`

def ard_select(X: np.ndarray, y: ArrayLike, *, threshold: float = 0.001, fit_intercept: bool = False, **kwargs) -> Dict[str, object]

sklearn の ARDRegression を使った疎な基底選択。

sklearn がない環境では ImportError を出す。ライブラリ本体の必須依存に sklearn を入れないため、ここで局所 import する。

`tklsq.tkminfit`

ソース: tklsq/tkminfit.py

class `MinimizeLSQResult`

minimize ベース最小二乗の結果。

データクラス相当の初期化フィールド

MinimizeLSQResult(params: Dict[str, float], params_free: np.ndarray, names: List[str], free_names: List[str], optimized_names: List[str], linear_names: List[str], residuals: np.ndarray, jacobian: Optional[np.ndarray], cov_free: Optional[np.ndarray], stderr_free: Optional[np.ndarray], stderr: Dict[str, Optional[float]], sigma2_resid: Optional[float], dof: int, N: int, p_free: int, RSS: float, objective: float, success: bool, message: str, nfev: Optional[int] = None, nit: Optional[int] = None, warning: str = '', raw_result: object, linear_result: object)

フィールド

名前	型	既定値
`params`	`Dict[str, float]`	`必須`
`params_free`	`np.ndarray`	`必須`
`names`	`List[str]`	`必須`
`free_names`	`List[str]`	`必須`
`optimized_names`	`List[str]`	`必須`
`linear_names`	`List[str]`	`必須`
`residuals`	`np.ndarray`	`必須`
`jacobian`	`Optional[np.ndarray]`	`必須`
`cov_free`	`Optional[np.ndarray]`	`必須`
`stderr_free`	`Optional[np.ndarray]`	`必須`
`stderr`	`Dict[str, Optional[float]]`	`必須`
`sigma2_resid`	`Optional[float]`	`必須`
`dof`	`int`	`必須`
`N`	`int`	`必須`
`p_free`	`int`	`必須`
`RSS`	`float`	`必須`
`objective`	`float`	`必須`
`success`	`bool`	`必須`
`message`	`str`	`必須`
`nfev`	`Optional[int]`	`None`
`nit`	`Optional[int]`	`None`
`warning`	`str`	`''`
`raw_result`	`object`	`必須`
`linear_result`	`object`	`必須`

メソッド／プロパティ

property `MinimizeLSQResult.sigma_resid`

def sigma_resid(self) -> Optional[float]

ソース内docstringはありません。シグネチャと実装を参照してください。

function `pack_values`

def pack_values(values: Mapping[str, float], names: Sequence[str]) -> np.ndarray

ソース内docstringはありません。シグネチャと実装を参照してください。

function `unpack_values`

def unpack_values(p_free: ArrayLike, base_values: Mapping[str, float], free_names: Sequence[str]) -> Dict[str, float]

ソース内docstringはありません。シグネチャと実装を参照してください。

function `residuals_to_objective`

def residuals_to_objective(residuals: ArrayLike, *, penalty: float = 0.0) -> float

ソース内docstringはありません。シグネチャと実装を参照してください。

function `solve_linear_block`

def solve_linear_block(y: ArrayLike, params: Mapping[str, Mapping[str, object]], p_current: Mapping[str, float], design_matrix_func: Callable[[Mapping[str, float], Sequence[str]], np.ndarray], *, lin_names: Optional[Sequence[str]] = None, weights: Optional[ArrayLike] = None) -> Tuple[Dict[str, float], object]

ソース内docstringはありません。シグネチャと実装を参照してください。

function `estimate_covariance_for_params`

def estimate_covariance_for_params(residual_func: Callable[[Mapping[str, float]], ArrayLike], params_fit: Mapping[str, float], free_names: Sequence[str], *, rel_step: float = 1e-06, abs_step: float = 1e-12)

ソース内docstringはありません。シグネチャと実装を参照してください。

function `minimize_lsq`

def minimize_lsq(residual_func: Callable[[Mapping[str, float]], ArrayLike], params: Mapping[str, Mapping[str, object]], *, free_names: Optional[Sequence[str]] = None, method: str = 'Nelder-Mead', use_penalty: bool = True, maxiter: Optional[int] = None, options: Optional[dict] = None, callback: Optional[Callable[[np.ndarray], None]] = None, print_interval: int = 0, rel_step: float = 1e-06, abs_step: float = 1e-12) -> MinimizeLSQResult

ソース内docstringはありません。シグネチャと実装を参照してください。

function `variable_projection_lsq`

def variable_projection_lsq(y: ArrayLike, params: Mapping[str, Mapping[str, object]], model_func: Callable[[Mapping[str, float]], ArrayLike], design_matrix_func: Callable[[Mapping[str, float], Sequence[str]], np.ndarray], *, nonlin_names: Optional[Sequence[str]] = None, lin_names: Optional[Sequence[str]] = None, method: str = 'Nelder-Mead', use_penalty: bool = True, weights: Optional[ArrayLike] = None, maxiter: Optional[int] = None, options: Optional[dict] = None, callback: Optional[Callable[[np.ndarray], None]] = None, print_interval: int = 0, rel_step: float = 1e-06, abs_step: float = 1e-12) -> MinimizeLSQResult

ソース内docstringはありません。シグネチャと実装を参照してください。

`tklsq.tknlsq`

ソース: tklsq/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 `NonlinearLSQResult`

非線形最小二乗の結果。

データクラス相当の初期化フィールド

NonlinearLSQResult(params: Union[np.ndarray, Dict[str, float]], params_free: np.ndarray, names: List[str], free_names: List[str], fixed_names: List[str], residuals: np.ndarray, jacobian: Optional[np.ndarray], cov_free: Optional[np.ndarray], stderr_free: Optional[np.ndarray], stderr: Union[Optional[np.ndarray], Dict[str, Optional[float]]], sigma2_resid: Optional[float], dof: int, N: int, p_free: int, RSS: float, cost: float, success: bool, message: str, nfev: Optional[int] = None, njev: Optional[int] = None, status: Optional[int] = None, warning: str = '', raw_result: object)

フィールド

名前	型	既定値
`params`	`Union[np.ndarray, Dict[str, float]]`	`必須`
`params_free`	`np.ndarray`	`必須`
`names`	`List[str]`	`必須`
`free_names`	`List[str]`	`必須`
`fixed_names`	`List[str]`	`必須`
`residuals`	`np.ndarray`	`必須`
`jacobian`	`Optional[np.ndarray]`	`必須`
`cov_free`	`Optional[np.ndarray]`	`必須`
`stderr_free`	`Optional[np.ndarray]`	`必須`
`stderr`	`Union[Optional[np.ndarray], Dict[str, Optional[float]]]`	`必須`
`sigma2_resid`	`Optional[float]`	`必須`
`dof`	`int`	`必須`
`N`	`int`	`必須`
`p_free`	`int`	`必須`
`RSS`	`float`	`必須`
`cost`	`float`	`必須`
`success`	`bool`	`必須`
`message`	`str`	`必須`
`nfev`	`Optional[int]`	`None`
`njev`	`Optional[int]`	`None`
`status`	`Optional[int]`	`None`
`warning`	`str`	`''`
`raw_result`	`object`	`必須`

メソッド／プロパティ

property `NonlinearLSQResult.sigma_resid`

def sigma_resid(self) -> Optional[float]

ソース内docstringはありません。シグネチャと実装を参照してください。

function `numerical_jacobian`

def numerical_jacobian(fun_vec: Callable[[np.ndarray], ArrayLike], p: ArrayLike, *, rel_step: float = 1e-06, abs_step: float = 1e-12) -> np.ndarray

中心差分でベクトル関数の Jacobian を計算する。

fun_vec(p) -> residual vector, J[i, j] = d residual_i / d p_j

function `covariance_from_jacobian`

def covariance_from_jacobian(residuals: ArrayLike, J: np.ndarray, *, dof: Optional[int] = None, rcond: float = 1e-12) -> Tuple[Optional[np.ndarray], Optional[np.ndarray], Optional[float], str]

残差 Jacobian からパラメータ共分散を近似する。

cov ≈ s^2 (J^T J)^(-1), s^2 = RSS / dof

dof <= 0 の場合、cov と stderr は None を返す。

function `nonlinear_lsq`

def nonlinear_lsq(residual_func: Callable[[Union[np.ndarray, Dict[str, float]]], ArrayLike], p0: ParamsLike, *, names: Optional[Sequence[str]] = None, fixed: Optional[Union[Sequence[str], Mapping[str, float]]] = None, bounds = None, loss: str = 'linear', max_nfev: Optional[int] = None, rel_step: float = 1e-06, abs_step: float = 1e-12, use_result_jac: bool = True, scipy_kwargs: Optional[dict] = None) -> NonlinearLSQResult

非線形最小二乗を実行する。

residual_func は residual_func(params) -> 1D residual vector を返す関数。

p0 が dict の場合、residual_func には dict が渡される。 p0 が list/array の場合、residual_func には np.ndarray が渡される。

fixed は固定パラメータ名のリスト、または {name: value} の辞書。

function `delta_method_variance`

def delta_method_variance(output_func: Callable[[np.ndarray], ArrayLike], p: ArrayLike, cov: np.ndarray, *, rel_step: float = 1e-06, abs_step: float = 1e-12) -> Tuple[np.ndarray, np.ndarray, np.ndarray]

出力量 y=f(p) の分散をデルタ法で計算する。

Returns

y0 : ndarray, shape (N,) var_y : ndarray, shape (N,) grads : ndarray, shape (N, M)

function `delta_method_band`

def delta_method_band(output_func: Callable[[np.ndarray], ArrayLike], p: ArrayLike, cov: np.ndarray, *, nsigma: float = 1.0, rel_step: float = 1e-06, abs_step: float = 1e-12) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]

デルタ法で y, y_low, y_high, sigma_y を返す。

function `result_free_values`

def result_free_values(result: NonlinearLSQResult) -> np.ndarray

NonlinearLSQResult から free parameter values を返す。

function `result_free_cov`

def result_free_cov(result: NonlinearLSQResult) -> Optional[np.ndarray]

NonlinearLSQResult から free parameter covariance を返す。

`tklsq.tkparamio`

ソース: tklsq/tkparamio.py

tkparamio.py

フィッティングパラメータ CSV の読み書きと補助関数。

CSV columns: varname,optid,optid_lin,p0,pmin,pmax,kpenalty

optional columns: stderr, note, unit など

方針:

optid=1 : 非線形最適化対象
optid_lin=1 : 線形最適化対象
pmin/pmax が有限値なら、kpenalty * deviation^2 で範囲ペナルティを加える

公開定数・モジュール変数

名前	型/値
`REQUIRED_COLUMNS`	`['varname', 'optid', 'optid_lin', 'p0', 'pmin', 'pmax', 'kpenalty']`

function `parse_float`

def parse_float(value, default: float = np.nan) -> float

空欄を default として float 化する。

function `parse_int`

def parse_int(value, default: int = 0) -> int

空欄を default として int 化する。

function `normalize_param_row`

def normalize_param_row(row: Mapping[str, object]) -> ParamRow

CSV 1行を標準形式に正規化する。余分な列は保存する。

function `rows_from_defaults`

def rows_from_defaults(defaults: Sequence[Mapping[str, object]]) -> ParamTable

デフォルトパラメータ定義のリストから ParamTable を作る。

function `create_param_csv`

def create_param_csv(path: Union[str, Path], defaults: Sequence[Mapping[str, object]], *, overwrite: bool = False, columns: Optional[Sequence[str]] = None) -> None

デフォルト値からパラメータ CSV を作る。

function `read_param_csv`

def read_param_csv(path: Union[str, Path], *, defaults: Optional[Sequence[Mapping[str, object]]] = None, create_if_missing: bool = True) -> ParamTable

パラメータ CSV を読む。

defaults が与えられていて CSV が存在しない場合は、自動生成してから読む。

function `write_param_csv`

def write_param_csv(path: Union[str, Path], params: Mapping[str, Mapping[str, object]], *, values: Optional[Mapping[str, float]] = None, stderr: Optional[Mapping[str, Optional[float]]] = None, columns: Optional[Sequence[str]] = None) -> None

パラメータ CSV を保存する。

values を渡すと p0 を更新する。 stderr を渡すと stderr 列を更新する。

function `values_from_params`

def values_from_params(params: Mapping[str, Mapping[str, object]]) -> Dict[str, float]

p0 から {name: value} を作る。

function `update_param_values`

def update_param_values(params: ParamTable, values: Mapping[str, float], *, inplace: bool = False) -> ParamTable

ParamTable の p0 を更新する。

function `nonlinear_param_names`

def nonlinear_param_names(params: Mapping[str, Mapping[str, object]]) -> List[str]

optid=1 のパラメータ名を返す。

function `linear_param_names`

def linear_param_names(params: Mapping[str, Mapping[str, object]]) -> List[str]

optid_lin=1 のパラメータ名を返す。

function `free_param_names`

def free_param_names(params: Mapping[str, Mapping[str, object]]) -> List[str]

非線形または線形の最適化対象パラメータ名を返す。

function `fixed_param_names`

def fixed_param_names(params: Mapping[str, Mapping[str, object]]) -> List[str]

optid=0 かつ optid_lin=0 のパラメータ名を返す。

function `bounds_from_params`

def bounds_from_params(params: Mapping[str, Mapping[str, object]], names: Optional[Sequence[str]] = None) -> Dict[str, Tuple[float, float]]

pmin/pmax から bounds 辞書を作る。

function `bounds_penalty`

def bounds_penalty(params: Mapping[str, Mapping[str, object]], values: Mapping[str, float], *, names: Optional[Sequence[str]] = None) -> float

pmin/pmax からの逸脱に対する二乗ペナルティを返す。

function `format_params`

def format_params(values: Mapping[str, float], *, stderr: Optional[Mapping[str, Optional[float]]] = None, names: Optional[Sequence[str]] = None, title: Optional[str] = None) -> str

パラメータと標準誤差を表示用文字列にする。

function `range_warnings`

def range_warnings(params: Mapping[str, Mapping[str, object]], values: Mapping[str, float], *, names: Optional[Sequence[str]] = None) -> List[str]

範囲外パラメータの警告文を返す。

function `param_scale`

def param_scale(params, name: str) -> str

ソース内docstringはありません。シグネチャと実装を参照してください。

function `transform_value`

def transform_value(value: float, scale: str) -> float

ソース内docstringはありません。シグネチャと実装を参照してください。

function `inverse_transform_value`

def inverse_transform_value(value: float, scale: str) -> float

ソース内docstringはありません。シグネチャと実装を参照してください。

function `pack_optim_values`

def pack_optim_values(values, params, names)

ソース内docstringはありません。シグネチャと実装を参照してください。

function `unpack_optim_values`

def unpack_optim_values(q, base_values, params, names)

ソース内docstringはありません。シグネチャと実装を参照してください。

function `validate_param_scales`

def validate_param_scales(params, names = None)

ソース内docstringはありません。シグネチャと実装を参照してください。

function `initial_simplex_from_dp`

def initial_simplex_from_dp(values, params, names)

ソース内docstringはありません。シグネチャと実装を参照してください。

`tklsq.tkplot`

ソース: tklsq/tkplot.py

tkplot.py

フィット結果の標準プロット補助。

細かい見た目はアプリ側で調整できるよう、 Figure/Axes を返す薄い関数にしている。

function `make_xcal`

def make_xcal(x: ArrayLike, *, n: int = 401, xmin: Optional[float] = None, xmax: Optional[float] = None, margin: float = 0.0) -> np.ndarray

プロット用の滑らかな x 軸を作る。

function `plot_fit_before_after`

def plot_fit_before_after(x: ArrayLike, y: ArrayLike, model_func: Callable[[np.ndarray, Mapping[str, float]], ArrayLike], p_before: Mapping[str, float], *, p_after: Optional[Mapping[str, float]] = None, xcal: Optional[ArrayLike] = None, yerr: Optional[ArrayLike] = None, band: Optional[Mapping[str, ArrayLike]] = None, xlabel: str = 'x', ylabel: str = 'y', title: str = 'fit result', data_label: str = 'data', before_label: str = 'before', after_label: str = 'after', out_png: Optional[Union[str, Path]] = None, show: bool = False, close: bool = True)

データ、フィット前、フィット後を重ねて描画する。

model_func: y = model_func(x_array, params_dict)

band: {"x": xband, "y_low": y_low, "y_high": y_high} または {"x": xband, "y_mean": y_mean, "sigma": sigma}

function `plot_band`

def plot_band(ax, band: Mapping[str, ArrayLike], *, color: str = 'tab:blue', alpha: float = 0.18, label: str = 'uncertainty')

既存Axesに誤差帯を追加する。

function `save_progress_plot`

def save_progress_plot(iteration: int, x: ArrayLike, y: ArrayLike, model_func: Callable[[np.ndarray, Mapping[str, float]], ArrayLike], p_before: Mapping[str, float], p_current: Mapping[str, float], *, out_dir: Union[str, Path] = '.', prefix: str = 'fit_progress', **kwargs) -> Path

フィット途中の画像を保存する。callback から呼ぶ想定。

`tklsq.tksynthetic`

ソース: tklsq/tksynthetic.py

tksynthetic.py

最小二乗プログラムの動作確認用の内部生成データユーティリティ。

class `SyntheticData`

合成データ一式。

データクラス相当の初期化フィールド

SyntheticData(x: np.ndarray, y: np.ndarray, y_clean: np.ndarray, y_noise: np.ndarray, true_params: dict, noise_std: float, seed: Optional[int] = None)

フィールド

名前	型	既定値
`x`	`np.ndarray`	`必須`
`y`	`np.ndarray`	`必須`
`y_clean`	`np.ndarray`	`必須`
`y_noise`	`np.ndarray`	`必須`
`true_params`	`dict`	`必須`
`noise_std`	`float`	`必須`
`seed`	`Optional[int]`	`None`

function `make_x_grid`

def make_x_grid(xmin: float = 0.0, xmax: float = 1.0, n: int = 50, *, kind: str = 'linear') -> np.ndarray

線形または対数 x グリッドを作る。

function `generate_noisy_data`

def generate_noisy_data(model_func: Callable[[np.ndarray, Mapping[str, float]], ArrayLike], x: ArrayLike, true_params: Mapping[str, float], *, noise_std: float = 0.05, seed: Optional[int] = 0, noise: str = 'normal', relative_noise: bool = False) -> SyntheticData

モデル関数からノイズ付きデータを生成する。

model_func: y_clean = model_func(x_array, true_params)

function `generate_replicates`

def generate_replicates(model_func: Callable[[np.ndarray, Mapping[str, float]], ArrayLike], x: ArrayLike, true_params: Mapping[str, float], *, noise_std: float = 0.05, seed: Optional[int] = 0, n_replicates: int = 3) -> SyntheticData

同じ x に対する繰り返し測定風データを生成する。

function `save_xy_csv`

def save_xy_csv(path: Union[str, Path], data: SyntheticData, *, include_clean: bool = True) -> None

合成データを CSV に保存する。

function `synthetic_summary`

def synthetic_summary(data: SyntheticData) -> str

合成データの概要を文字列化する。

tklsq APIリファレンス

APIの読み方

パッケージ公開API

モジュール一覧

tklsq

tklsq.tkdataio

function read_table

function read_xy

function write_excel_tables

function save_json

function load_json

tklsq.tkfitdiag

class EigenSummary

class FixCandidate

class FitDiagnostics

function covariance_to_correlation

function eigen_sorted_symmetric

function summarize_eigenvectors

function diagnose_covariance

Parameters

function propose_fix_candidates

function propose_fix_candidates_from_diagnostics

function format_fix_candidates

function diagnostics_to_dict

tklsq.tklsq

設計方針

class LeastSquaresResult

property LeastSquaresResult.sigma_resid

class PredictionResult

class ModelSelectionResult

property ModelSelectionResult.best_label

class BayesianLinearResult

function polynomial_design_matrix

Parameters

Returns

function design_matrix_from_functions

function add_intercept

function linear_lsq

Parameters

Notes

function polynomial_lsq

function parameter_prediction_variance

function predict_linear

function predict_polynomial

function measurement_std

function delta_method_variance

function regression_scores

function gaussian_log_likelihood_from_rss

function information_criteria

function normalized_weights_from_scores

function select_models_by_ic

function polynomial_candidates

function basis_index_candidates

function bayesian_posterior

function bayesian_log_evidence

function empirical_bayes_linear

function predict_bayesian

function posterior_model_probabilities

function select_models_by_evidence

function ard_select

tklsq.tkminfit

class MinimizeLSQResult

property MinimizeLSQResult.sigma_resid

function pack_values

function unpack_values

function residuals_to_objective

function solve_linear_block

function estimate_covariance_for_params

function minimize_lsq

function variable_projection_lsq

tklsq.tknlsq

設計方針

class NonlinearLSQResult

property NonlinearLSQResult.sigma_resid

function numerical_jacobian

function covariance_from_jacobian

function nonlinear_lsq

function delta_method_variance

Returns

function delta_method_band

`tklsq`

`tklsq.tkdataio`

function `read_table`

function `read_xy`

function `write_excel_tables`

function `save_json`

function `load_json`

`tklsq.tkfitdiag`

class `EigenSummary`

class `FixCandidate`

class `FitDiagnostics`

function `covariance_to_correlation`

function `eigen_sorted_symmetric`

function `summarize_eigenvectors`

function `diagnose_covariance`

function `propose_fix_candidates`

function `propose_fix_candidates_from_diagnostics`

function `format_fix_candidates`

function `diagnostics_to_dict`

`tklsq.tklsq`

class `LeastSquaresResult`

property `LeastSquaresResult.sigma_resid`

class `PredictionResult`

class `ModelSelectionResult`

property `ModelSelectionResult.best_label`

class `BayesianLinearResult`

function `polynomial_design_matrix`

function `design_matrix_from_functions`

function `add_intercept`

function `linear_lsq`

function `polynomial_lsq`

function `parameter_prediction_variance`

function `predict_linear`

function `predict_polynomial`

function `measurement_std`

function `delta_method_variance`

function `regression_scores`

function `gaussian_log_likelihood_from_rss`

function `information_criteria`

function `normalized_weights_from_scores`

function `select_models_by_ic`

function `polynomial_candidates`

function `basis_index_candidates`

function `bayesian_posterior`

function `bayesian_log_evidence`

function `empirical_bayes_linear`

function `predict_bayesian`

function `posterior_model_probabilities`

function `select_models_by_evidence`

function `ard_select`

`tklsq.tkminfit`

class `MinimizeLSQResult`

property `MinimizeLSQResult.sigma_resid`

function `pack_values`

function `unpack_values`

function `residuals_to_objective`

function `solve_linear_block`

function `estimate_covariance_for_params`

function `minimize_lsq`

function `variable_projection_lsq`

`tklsq.tknlsq`

class `NonlinearLSQResult`

property `NonlinearLSQResult.sigma_resid`

function `numerical_jacobian`

function `covariance_from_jacobian`

function `nonlinear_lsq`

function `delta_method_variance`

function `delta_method_band`

function `result_free_values`

function `result_free_cov`

`tklsq.tkparamio`

function `parse_float`

function `parse_int`

function `normalize_param_row`

function `rows_from_defaults`

function `create_param_csv`

function `read_param_csv`

function `write_param_csv`

function `values_from_params`

function `update_param_values`