# tklsq APIリファレンス

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

## APIの読み方

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

## パッケージ公開API

```python
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`

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

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

### function `read_xy`

```python
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`

```python
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`

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

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

### function `load_json`

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

JSON読み込み。

## `tklsq.tkfitdiag`

ソース: `tklsq/tkfitdiag.py`

tkfitdiag.py

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

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

### class `EigenSummary`

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

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

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

**フィールド**

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

### class `FixCandidate`

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

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

```python
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`

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

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

```python
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`

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

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

### function `eigen_sorted_symmetric`

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

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

### function `summarize_eigenvectors`

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

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

### function `diagnose_covariance`

```python
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`

```python
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`

```python
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`

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

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

### function `diagnostics_to_dict`

```python
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`

線形最小二乗の結果。

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

```python
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`

```python
def sigma_resid(self) -> Optional[float]
```

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

### class `PredictionResult`

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

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

```python
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`

複数モデル比較の結果。

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

```python
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`

```python
def best_label(self) -> str
```

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

### class `BayesianLinearResult`

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

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

```python
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`

```python
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`

```python
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`

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

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

### function `linear_lsq`

```python
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`

```python
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`

```python
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`

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

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

### function `predict_polynomial`

```python
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`

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

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

### function `delta_method_variance`

```python
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`

```python
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`

```python
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`

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

AIC, AICc, BIC を計算する。

### function `normalized_weights_from_scores`

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

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

### function `select_models_by_ic`

```python
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`

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

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

### function `basis_index_candidates`

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

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

### function `bayesian_posterior`

```python
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`

```python
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`

```python
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`

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

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

### function `posterior_model_probabilities`

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

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

### function `select_models_by_evidence`

```python
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`

```python
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 ベース最小二乗の結果。

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

```python
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`

```python
def sigma_resid(self) -> Optional[float]
```

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

### function `pack_values`

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

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

### function `unpack_values`

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

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

### function `residuals_to_objective`

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

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

### function `solve_linear_block`

```python
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`

```python
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`

```python
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`

```python
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`

非線形最小二乗の結果。

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

```python
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`

```python
def sigma_resid(self) -> Optional[float]
```

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

### function `numerical_jacobian`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

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

NonlinearLSQResult から free parameter values を返す。

### function `result_free_cov`

```python
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`

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

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

### function `parse_int`

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

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

### function `normalize_param_row`

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

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

### function `rows_from_defaults`

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

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

### function `create_param_csv`

```python
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`

```python
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`

```python
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`

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

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

### function `update_param_values`

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

ParamTable の p0 を更新する。

### function `nonlinear_param_names`

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

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

### function `linear_param_names`

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

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

### function `free_param_names`

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

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

### function `fixed_param_names`

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

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

### function `bounds_from_params`

```python
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`

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

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

### function `format_params`

```python
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`

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

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

### function `param_scale`

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

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

### function `transform_value`

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

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

### function `inverse_transform_value`

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

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

### function `pack_optim_values`

```python
def pack_optim_values(values, params, names)
```

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

### function `unpack_optim_values`

```python
def unpack_optim_values(q, base_values, params, names)
```

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

### function `validate_param_scales`

```python
def validate_param_scales(params, names = None)
```

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

### function `initial_simplex_from_dp`

```python
def initial_simplex_from_dp(values, params, names)
```

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

## `tklsq.tkplot`

ソース: `tklsq/tkplot.py`

tkplot.py

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

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

### function `make_xcal`

```python
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`

```python
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`

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

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

### function `save_progress_plot`

```python
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`

合成データ一式。

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

```python
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`

```python
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`

```python
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`

```python
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`

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

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

### function `synthetic_summary`

```python
def synthetic_summary(data: SyntheticData) -> str
```

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