tkparamio プログラム仕様

tkparamio.py

フィッティングパラメータ CSV の読み書きと補助関数を提供するモジュール。

このモジュールは、フィッティングパラメータをCSVファイル形式で管理するための機能を提供します。 パラメータの読み書き、デフォルト値からの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 で範囲ペナルティを加える

tkparamio.py 技術ドキュメント

regression.tklsq.tkparamio.bounds_from_params(params: Mapping[str, Mapping[str, object]], names: Sequence[str] | None = None) → Dict[str, Tuple[float, float]]

パラメータの最小値 (pmin) と最大値 (pmax) から境界値の辞書を作成します。

各パラメータの pmin と pmax を抽出し、(-inf, inf) をデフォルトとして 境界タプル (lo, hi) を作成します。names が指定された場合、そのパラメータのみが対象となります。

パラメータ:

• params -- ParamTable 形式のパラメータデータ。

• names -- 境界値を取得するパラメータ名のシーケンス。指定しない場合はすべてのパラメータが対象になります。

戻り値:

パラメータ名がキー、(pmin, pmax) タプルが値の辞書。

regression.tklsq.tkparamio.bounds_penalty(params: Mapping[str, Mapping[str, object]], values: Mapping[str, float], *, names: Sequence[str] | None = None) → float

パラメータが指定された境界 (pmin, pmax) から逸脱した場合の二乗ペナルティを計算します。

各パラメータについて、現在の値 (values) が pmin または pmax の範囲外にある場合に、 kpenalty * deviation^2 の形式でペナルティを計算し、その合計を返します。 pmin や pmax が非有限値の場合は、その境界は適用されません。

パラメータ:

• params -- ParamTable 形式のパラメータデータ（pmin, pmax, kpenalty を含む）。

• values -- 現在のパラメータ値。

• names -- ペナルティ計算の対象とするパラメータ名のシーケンス。指定しない場合はすべてのパラメータが対象になります。

戻り値:

計算された合計ペナルティ値。

regression.tklsq.tkparamio.create_param_csv(path: str | Path, defaults: Sequence[Mapping[str, object]], *, overwrite: bool = False, columns: Sequence[str] | None = None) → None

デフォルト値を使用してパラメータCSVファイルを作成します。

指定されたパスにCSVファイルを作成します。ファイルが既に存在し overwrite が False の場合、ファイルは作成されません。columns が指定されない場合、 デフォルトカラムと既存の追加カラムが自動的に含まれます。

パラメータ:

• path -- 出力するCSVファイルのパス。

• defaults -- CSVに書き込むデフォルトパラメータのリスト。

• overwrite -- ファイルが既に存在する場合に上書きするかどうか。デフォルトは False。

• columns -- CSVのヘッダーとして使用するカラム名のシーケンス。指定しない場合は自動決定されます。

戻り値:

None

regression.tklsq.tkparamio.fixed_param_names(params: Mapping[str, Mapping[str, object]]) → List[str]

最適化対象外となる固定パラメータ名（optid=0 かつ optid_lin=0）のリストを返します。

ParamTable 内の各パラメータ行をチェックし、optid と optid_lin の両方が 0 に設定されているパラメータ名のみを抽出します。

パラメータ:

params -- ParamTable 形式のパラメータデータ。

戻り値:

固定パラメータ名のリスト。

regression.tklsq.tkparamio.format_params(values: Mapping[str, float], *, stderr: Mapping[str, float | None] | None = None, names: Sequence[str] | None = None, title: str | None = None) → str

パラメータと標準誤差を整形された文字列として出力します。

各パラメータについて、値とオプションで標準誤差を組み合わせた行を生成します。 標準誤差が利用できない、または非有限値の場合、値のみが表示されます。 names が指定された場合、そのパラメータのみが対象となり、指定された順序で表示されます。 title を追加できます。

パラメータ:

• values -- パラメータ名とその値のマッピング。

• stderr -- オプションでパラメータ名とその標準誤差のマッピング。 None の場合は標準誤差は表示されません。

• names -- 表示するパラメータ名のシーケンス。指定しない場合は values のすべてのキーが対象になります。

• title -- 出力文字列の冒頭に追加するタイトル。

戻り値:

整形されたパラメータ情報の複数行文字列。

regression.tklsq.tkparamio.free_param_names(params: Mapping[str, Mapping[str, object]]) → List[str]

非線形または線形最適化の対象となるすべてのパラメータ名のリストを返します。

ParamTable 内の各パラメータ行をチェックし、optid または optid_lin の いずれかが 1 に設定されているパラメータ名のみを抽出します。

パラメータ:

params -- ParamTable 形式のパラメータデータ。

戻り値:

非線形または線形最適化対象のパラメータ名のリスト。

regression.tklsq.tkparamio.linear_param_names(params: Mapping[str, Mapping[str, object]]) → List[str]

線形最適化の対象となるパラメータ名（optid_lin=1）のリストを返します。

ParamTable 内の各パラメータ行をチェックし、optid_lin が 1 に設定されている パラメータ名のみを抽出します。

パラメータ:

params -- ParamTable 形式のパラメータデータ。

戻り値:

線形最適化対象のパラメータ名のリスト。

regression.tklsq.tkparamio.nonlinear_param_names(params: Mapping[str, Mapping[str, object]]) → List[str]

非線形最適化の対象となるパラメータ名（optid=1）のリストを返します。

ParamTable 内の各パラメータ行をチェックし、optid が 1 に設定されている パラメータ名のみを抽出します。

パラメータ:

params -- ParamTable 形式のパラメータデータ。

戻り値:

非線形最適化対象のパラメータ名のリスト。

regression.tklsq.tkparamio.normalize_param_row(row: Mapping[str, object]) → Dict[str, object]

パラメータの行データを標準形式に正規化します。

varname の存在を確認し、必須カラム (optid, optid_lin, p0, pmin, pmax, kpenalty) の値を適切な型に変換します。stderr が存在する場合はこれも変換します。 余分な列は保持されます。

パラメータ:

row -- 変換するパラメータの行データ（辞書形式）。

戻り値:

正規化されたパラメータ行データ。

例外:

ValueError -- varname が存在しない、または空の場合に発生します。

regression.tklsq.tkparamio.parse_float(value, default: float = nan) → float

値を浮動小数点数に変換し、空欄やNoneの場合はデフォルト値を適用します。

文字列の空白をトリムし、空の場合は default を返します。

パラメータ:

• value -- 変換対象の値。

• default -- 変換に失敗した場合や空欄の場合に返すデフォルト値。デフォルトは np.nan。

戻り値:

変換された浮動小数点数。

regression.tklsq.tkparamio.parse_int(value, default: int = 0) → int

値を整数に変換し、空欄やNoneの場合はデフォルト値を適用します。

文字列の空白をトリムし、空の場合は default を返します。 浮動小数点数として解釈可能な文字列も整数に変換します。

パラメータ:

• value -- 変換対象の値。

• default -- 変換に失敗した場合や空欄の場合に返すデフォルト値。デフォルトは0。

戻り値:

変換された整数。

regression.tklsq.tkparamio.range_warnings(params: Mapping[str, Mapping[str, object]], values: Mapping[str, float], *, names: Sequence[str] | None = None) → List[str]

パラメータが指定された境界 (pmin, pmax) から逸脱している場合の警告メッセージのリストを返します。

各パラメータについて、現在の値 (values) が pmin または pmax の範囲外にある場合に、 警告文字列を生成します。pmin や pmax が非有限値の場合は、その境界は適用されません。

パラメータ:

• params -- ParamTable 形式のパラメータデータ（pmin, pmax を含む）。

• values -- 現在のパラメータ値。

• names -- 警告チェックの対象とするパラメータ名のシーケンス。指定しない場合はすべてのパラメータが対象になります。

戻り値:

範囲外パラメータに対する警告メッセージのリスト。

regression.tklsq.tkparamio.read_param_csv(path: str | Path, *, defaults: Sequence[Mapping[str, object]] | None = None, create_if_missing: bool = True) → Dict[str, Dict[str, object]]

パラメータCSVファイルを読み込み、ParamTable を返します。

CSVファイルが存在しない場合、defaults が提供されており create_if_missing が True であれば、create_param_csv を使用してファイルを自動生成してから読み込みます。 必須カラムの存在が検証されます。

パラメータ:

• path -- 読み込むCSVファイルのパス。

• defaults -- CSVファイルが存在しない場合に、ファイルの自動生成に使用するデフォルトパラメータのリスト。

• create_if_missing -- CSVファイルが存在しない場合に自動生成するかどうか。デフォルトは True。

戻り値:

読み込まれたパラメータデータを含む ParamTable。

例外:

• FileNotFoundError -- ファイルが存在せず、自動生成も行われない場合に発生します。

• ValueError -- CSVファイルが空であるか、必須カラムが不足している場合に発生します。

regression.tklsq.tkparamio.rows_from_defaults(defaults: Sequence[Mapping[str, object]]) → Dict[str, Dict[str, object]]

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

与えられた各行を normalize_param_row で正規化し、varname をキーとして ParamTable に格納します。

パラメータ:

defaults -- デフォルトパラメータの行データのシーケンス。

戻り値:

パラメータ名がキーの ParamTable。

regression.tklsq.tkparamio.update_param_values(params: Dict[str, Dict[str, object]], values: Mapping[str, float], *, inplace: bool = False) → Dict[str, Dict[str, object]]

ParamTable 内のパラメータの初期値 (p0) を更新します。

values で指定されたパラメータの p0 値を更新します。inplace が True の場合、 元の ParamTable が変更されます。False の場合、新しい ParamTable が作成されて返されます。

パラメータ:

• params -- 更新対象の ParamTable。

• values -- 更新するパラメータ名と新しい値のマッピング。

• inplace -- 更新をインプレースで行うかどうか。デフォルトは False。

戻り値:

更新された ParamTable。

regression.tklsq.tkparamio.values_from_params(params: Mapping[str, Mapping[str, object]]) → Dict[str, float]

ParamTable からパラメータ名とその初期値 (p0) の辞書を作成します。

各パラメータ行の p0 値を浮動小数点数として抽出します。

パラメータ:

params -- ParamTable 形式のパラメータデータ。

戻り値:

パラメータ名がキー、p0 値が値の辞書。

regression.tklsq.tkparamio.write_param_csv(path: str | Path, params: Mapping[str, Mapping[str, object]], *, values: Mapping[str, float] | None = None, stderr: Mapping[str, float | None] | None = None, columns: Sequence[str] | None = None) → None

パラメータデータをCSVファイルに保存します。

指定されたパスにCSVファイルを書き込みます。values が提供された場合、 対応するパラメータの p0 値が更新されます。stderr が提供された場合、 対応する stderr 列が更新されます。columns が指定されない場合、 デフォルトカラムと既存の追加カラムが自動的に含まれます。

パラメータ:

• path -- 出力するCSVファイルのパス。

• params -- 保存するパラメータデータを含む ParamTable。

• values -- 更新するパラメータ名とその新しい値のマッピング。対応する p0 が上書きされます。

• stderr -- オプションで更新するパラメータ名とその新しい標準誤差のマッピング。 対応する stderr が上書きされます。None を指定すると np.nan として扱われます。

• columns -- CSVのヘッダーとして使用するカラム名のシーケンス。指定しない場合は自動決定されます。

戻り値:

None