tkparamio.py 技術ドキュメント
ライブラリの機能や目的
tkparamio.py は、フィッティングパラメータの管理に特化したPythonライブラリです。特に、最適化計算などで用いられるパラメータの初期値、範囲制約、最適化対象フラグなどをCSV形式で読み書きし、関連する補助関数を提供することを目的としています。
このライブラリは以下の課題を解決します。
パラメータの一元管理: 最適化に用いる多数のパラメータとその属性（初期値、制約、最適化フラグなど）をCSVファイルとして一元的に管理できます。
構造化されたデータアクセス: CSVから読み込んだパラメータデータをPythonの辞書形式 (
ParamTable) で扱いやすく変換し、必要な情報（最適化対象のパラメータ名、境界値など）を容易に抽出できます。範囲制約の自動適用: パラメータが定義された範囲（
pmin,pmax）を超えた場合に、その逸脱度合いに応じたペナルティを自動的に計算する機能を提供し、最適化アルゴリズムに組み込むことを容易にします。初期値・結果の更新: 最適化計算の初期値としてCSVを読み込み、計算後の結果をCSVに書き戻すなど、パラメータのライフサイクル全体をサポートします。
CSVファイルは以下の標準的なカラム構成を想定しています。
varname: パラメータ名 (必須)optid: 非線形最適化の対象とするか (1で対象、0で固定)optid_lin: 線形最適化の対象とするか (1で対象、0で固定)p0: パラメータの初期値、または現在の値pmin: パラメータの最小値。有限値の場合、範囲外ペナルティが適用されます。pmax: パラメータの最大値。有限値の場合、範囲外ペナルティが適用されます。kpenalty: 範囲逸脱時のペナルティ係数。
また、stderr, note, unit などのオプションカラムもサポートしており、CSVに記述されている場合は読み書き時に維持されます。
importする方法
tkparamio.py を他のPythonプログラムから利用するには、通常のPythonモジュールと同様に import ステートメントを使用します。
import tkparamio
または、特定の関数や変数のみをインポートすることも可能です。
from tkparamio import read_param_csv, write_param_csv
必要な非標準ライブラリとインストール方法
tkparamio.py は以下の非標準ライブラリに依存しています。
numpy: 数値計算（特に
np.nan,np.inf,np.isfiniteの利用）に用いられます。
これらのライブラリは pip コマンドを使用してインストールできます。
pip install numpy
importできる変数と関数
型エイリアス
ParamRow説明: パラメータの1行（1つのパラメータ）を表す辞書の型エイリアスです。キーは文字列、値はPythonオブジェクト (
object) です。型:
Dict[str, object]
ParamTable説明: 全パラメータのテーブルを表す辞書の型エイリアスです。キーはパラメータ名（文字列）、値は
ParamRow型です。型:
Dict[str, ParamRow]
定数
REQUIRED_COLUMNS説明: パラメータCSVファイルに必須とされるカラム名のリストです。
値:
["varname", "optid", "optid_lin", "p0", "pmin", "pmax", "kpenalty"]
DEFAULT_COLUMNS説明: CSVファイルを新規作成する際や、カラムが明示的に指定されない場合にデフォルトで含まれるカラム名のリストです。
REQUIRED_COLUMNSにstderrを追加したものです。値:
["varname", "optid", "optid_lin", "p0", "pmin", "pmax", "kpenalty", "stderr"]
関数
parse_float(value, default: float = np.nan) -> float動作: 指定された値を浮動小数点数に変換します。値が
Noneまたは空文字列の場合は、指定されたデフォルト値を返します。引数:
value: 浮動小数点数に変換する値。任意の型を受け入れますが、文字列として解釈されます。default:valueが変換できない場合（Noneまたは空文字列）に返すデフォルトの浮動小数点数。デフォルトはnp.nanです。
戻り値: 変換された浮動小数点数。
parse_int(value, default: int = 0) -> int動作: 指定された値を整数に変換します。値が
Noneまたは空文字列の場合は、指定されたデフォルト値を返します。浮動小数点数として解釈可能な文字列も整数に変換されます。引数:
value: 整数に変換する値。任意の型を受け入れますが、文字列として解釈されます。default:valueが変換できない場合（Noneまたは空文字列）に返すデフォルトの整数。デフォルトは0です。
戻り値: 変換された整数。
normalize_param_row(row: Mapping[str, object]) -> ParamRow動作: CSVから読み込まれたパラメータの1行（辞書）を標準形式に正規化します。必須カラムの存在をチェックし、適切な型変換（
intやfloat）を行います。余分なカラムはそのまま保持されます。引数:
row: CSVの1行を表す辞書。
戻り値: 正規化された
ParamRow辞書。例外:
ValueError:varnameが存在しない、または空の場合。
rows_from_defaults(defaults: Sequence[Mapping[str, object]]) -> ParamTable動作: デフォルトパラメータ定義のリストから
ParamTableを作成します。各行はnormalize_param_rowによって正規化されます。引数:
defaults: デフォルトパラメータ定義の辞書のシーケンス（リストなど）。
戻り値: パラメータ名でキー付けされた
ParamTable辞書。
create_param_csv(path: Union[str, Path], defaults: Sequence[Mapping[str, object]], *, overwrite: bool = False, columns: Optional[Sequence[str]] = None) -> None動作: 指定されたデフォルト値に基づいて新しいパラメータCSVファイルを作成します。ファイルが既に存在し、
overwriteがFalseの場合は何も行いません。引数:
path: 作成するCSVファイルのパス（文字列またはpathlib.Pathオブジェクト）。defaults: パラメータのデフォルト値を定義する辞書のシーケンス。overwrite:Trueの場合、既存のファイルを上書きします。デフォルトはFalseです。columns: 出力するカラム名のシーケンス。指定しない場合、DEFAULT_COLUMNSにデフォルト値に含まれる追加カラムが加わります。
戻り値: なし。
read_param_csv(path: Union[str, Path], *, defaults: Optional[Sequence[Mapping[str, object]]] = None, create_if_missing: bool = True) -> ParamTable動作: 指定されたパスからパラメータCSVファイルを読み込み、
ParamTable形式で返します。ファイルが存在しない場合、defaultsが与えられcreate_if_missingがTrueであれば、ファイルを自動生成してから読み込みます。引数:
path: 読み込むCSVファイルのパス（文字列またはpathlib.Pathオブジェクト）。defaults: ファイルが存在しない場合にcreate_param_csvで使用されるデフォルト値のシーケンス。デフォルトはNoneです。create_if_missing:Trueの場合、ファイルが存在しないときにdefaultsを用いて作成を試みます。デフォルトはTrueです。
戻り値: 読み込まれた
ParamTable辞書。例外:
FileNotFoundError: ファイルが存在せず、かつdefaultsがないかcreate_if_missingがFalseの場合。ValueError: CSVファイルが空であるか、必須カラムが不足している場合。
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動作:
ParamTableを指定されたパスにCSVファイルとして保存します。valuesやstderrが渡された場合、それらのカラムの値を更新して書き込みます。引数:
path: 保存するCSVファイルのパス（文字列またはpathlib.Pathオブジェクト）。params: 保存するパラメータを含むParamTable。values: パラメータ名と新しい値の辞書。指定された場合、対応するパラメータのp0カラムを更新します。デフォルトはNoneです。stderr: パラメータ名と標準誤差の辞書。指定された場合、対応するパラメータのstderrカラムを更新します（Noneは空欄として出力）。デフォルトはNoneです。columns: 出力するカラム名のシーケンス。指定しない場合、DEFAULT_COLUMNSにparamsに含まれる追加カラムが加わります。
戻り値: なし。
_row_for_csv(row: Mapping[str, object], columns: Sequence[str]) -> Dict[str, object]動作: CSVに出力するために、
np.nan値を空文字列に変換する内部補助関数です。通常、ライブラリ利用者が直接importして利用することを想定していません。引数:
row: パラメータの1行を表す辞書。columns: 出力するカラム名のシーケンス。
戻り値:
np.nanが空文字列に置換された辞書。
values_from_params(params: Mapping[str, Mapping[str, object]]) -> Dict[str, float]動作:
ParamTableから、各パラメータのp0の値のみを抽出して、{name: value}形式の辞書を作成します。引数:
params: 元となるParamTable。
戻り値: パラメータ名と値の辞書。
update_param_values(params: ParamTable, values: Mapping[str, float], *, inplace: bool = False) -> ParamTable動作:
ParamTable内のパラメータのp0値を更新します。引数:
params: 更新対象のParamTable。values: 更新するパラメータ名と新しい値の辞書。inplace:Trueの場合、元のparamsオブジェクトを直接変更します。Falseの場合、新しいParamTableを作成して返します。デフォルトはFalseです。
戻り値: 更新された
ParamTable。
nonlinear_param_names(params: Mapping[str, Mapping[str, object]]) -> List[str]動作:
optid=1とマークされている非線形最適化対象のパラメータ名のリストを返します。引数:
params: 検査対象のParamTable。
戻り値: 非線形最適化対象のパラメータ名のリスト。
linear_param_names(params: Mapping[str, Mapping[str, object]]) -> List[str]動作:
optid_lin=1とマークされている線形最適化対象のパラメータ名のリストを返します。引数:
params: 検査対象のParamTable。
戻り値: 線形最適化対象のパラメータ名のリスト。
free_param_names(params: Mapping[str, Mapping[str, object]]) -> List[str]動作:
optid=1またはoptid_lin=1とマークされている、非線形または線形の最適化対象のパラメータ名のリストを返します。引数:
params: 検査対象のParamTable。
戻り値: 最適化対象のパラメータ名のリスト。
fixed_param_names(params: Mapping[str, Mapping[str, object]]) -> List[str]動作:
optid=0かつoptid_lin=0とマークされている、固定（最適化対象外）パラメータ名のリストを返します。引数:
params: 検査対象のParamTable。
戻り値: 固定パラメータ名のリスト。
bounds_from_params(params: Mapping[str, Mapping[str, object]], names: Optional[Sequence[str]] = None) -> Dict[str, Tuple[float, float]]動作:
ParamTableから、各パラメータのpminとpmaxの値を使用して、境界値の辞書を作成します。pminまたはpmaxが有限でない（np.nan）場合は、それぞれ-np.infまたはnp.infに変換されます。引数:
params: 元となるParamTable。names: 境界値を抽出するパラメータ名のシーケンス。指定しない場合、すべてのパラメータが対象となります。
戻り値: パラメータ名と
(pmin, pmax)タプルの辞書。
bounds_penalty(params: Mapping[str, Mapping[str, object]], values: Mapping[str, float], *, names: Optional[Sequence[str]] = None) -> float動作: 現在のパラメータ値が
pmin/pmaxで定義された範囲外にある場合に、二乗ペナルティを計算して返します。ペナルティは$kpenalty \times (value - pmin)^2$または$kpenalty \times (value - pmax)^2$で計算されます。引数:
params: 境界値とペナルティ係数を含むParamTable。values: 現在のパラメータ値の辞書。names: ペナルティを計算するパラメータ名のシーケンス。指定しない場合、すべてのパラメータが対象となります。
戻り値: 計算されたペナルティの合計値。
format_params(values: Mapping[str, float], *, stderr: Optional[Mapping[str, Optional[float]]] = None, names: Optional[Sequence[str]] = None, title: Optional[str] = None) -> str動作: パラメータとその標準誤差（オプション）を整形し、表示用の文字列を生成します。
引数:
values: パラメータ名と値の辞書。stderr: パラメータ名と標準誤差の辞書。Noneの場合、標準誤差は表示されません。デフォルトはNoneです。names: 表示するパラメータ名のシーケンス。指定しない場合、valuesのすべてのパラメータが表示されます。title: 表示の冒頭に追加するタイトル文字列。デフォルトはNoneです。
戻り値: 整形された表示文字列。
range_warnings(params: Mapping[str, Mapping[str, object]], values: Mapping[str, float], *, names: Optional[Sequence[str]] = None) -> List[str]動作: 現在のパラメータ値が
pmin/pmaxで定義された範囲外にある場合に、警告メッセージのリストを生成します。引数:
params: 境界値を含むParamTable。values: 現在のパラメータ値の辞書。names: 範囲チェックを行うパラメータ名のシーケンス。指定しない場合、すべてのパラメータが対象となります。
戻り値: 範囲外のパラメータに関する警告文字列のリスト。
main scriptとして実行したときの動作
tkparamio.py は、直接スクリプトとして実行された場合の特定の動作（if __name__ == "__main__": ブロック）を持っていません。このライブラリは、他のPythonプログラムからモジュールとしてインポートされ、その機能が利用されることを想定して設計されています。