tksynthetic.py ライブラリ技術ドキュメント

ライブラリの機能や目的

tksynthetic.py は、最小二乗法プログラムの動作確認やテストに使用するための、内部生成データユーティリティを提供するPythonライブラリです。特定のモデル関数に基づいてノイズを含む合成データを生成し、そのデータを分析やアルゴリズムの検証に利用することを目的としています。主な機能は以下の通りです。

線形または対数スケールの独立変数 (\(x\)) グリッドの生成。
与えられたモデル関数と真のパラメータから、ノイズ付きの従属変数 (\(y\)) データを生成。
繰り返し測定のような形式でデータを生成。
生成された合成データをCSVファイルとして保存。
生成データの概要情報を整形された文字列として提供。

このライブラリは、複雑なデータ生成プロセスを抽象化し、ユーザーがモデルの特性やノイズの影響を評価するためのデータセットを容易に作成できるようにすることで、最小二乗法やその他のデータフィッティングアルゴリズムの開発・デバッグを支援します。

importする方法

tksynthetic.py ライブラリをPythonプログラムにインポートするには、以下の方法を使用します。

ライブラリ全体をインポートする場合:

import tksynthetic

特定の関数やクラスのみをインポートする場合:

from tksynthetic import generate_noisy_data, SyntheticData

必要な非標準ライブラリとインストール方法

tksynthetic.py を実行するためには、以下の非標準ライブラリが必要です。

numpy: 数値計算を効率的に行うためのライブラリです。特に配列操作や乱数生成に利用されています。

これらのライブラリは、Pythonのパッケージマネージャーである pip を使用してインストールできます。

pip install numpy

importできる変数と関数

tksynthetic.py ライブラリからインポートできる主な変数（型エイリアス）とデータクラス、関数は以下の通りです。

変数（型エイリアス）

ArrayLike
- 説明: Sequence[float] または np.ndarray のいずれかを示す型エイリアスです。関数が配列形式の引数を受け入れることを明示するために使用されます。

データクラス

SyntheticData
- 説明: @dataclass デコレータで定義されたデータクラスで、生成された合成データ一式をカプセル化します。以下の属性を持ちます。
  - x: np.ndarray - 独立変数（入力）のデータ点。
  - y: np.ndarray - ノイズを含む従属変数（出力）のデータ点。
  - y_clean: np.ndarray - ノイズを含まない、モデル関数によって生成された理想的な従属変数のデータ点。
  - y_noise: np.ndarray - y から y_clean を引いたノイズ成分。
  - true_params: dict - データを生成するために使用された真のモデルパラメータ。
  - noise_std: float - ノイズの標準偏差。
  - seed: Optional[int] - 乱数生成器のシード値。

関数

make_x_grid(xmin: float = 0.0, xmax: float = 1.0, n: int = 50, *, kind: str = "linear") -> np.ndarray
- 動作: 指定された範囲 xmin から xmax の間で n 個のデータ点を持つ \(x\) グリッドを生成します。
- 引数:
  - xmin: グリッドの最小値。デフォルトは 0.0。
  - xmax: グリッドの最大値。デフォルトは 1.0。
  - n: グリッド内の点の数。デフォルトは 50。
  - kind: グリッドの種類。"linear" (等間隔) または "log" (対数間隔) を指定します。デフォルトは "linear"。"log" の場合、xmin と xmax は \(0\) より大きい必要があります。
- 戻り値: np.ndarray - 生成された \(x\) グリッド。
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) の形式で呼び出せるモデル関数。\(x\) 配列とパラメータの辞書を受け取り、ノイズを含まない \(y\) 値を返す必要があります。
  - x: 独立変数のデータ点。ArrayLike 型。
  - true_params: モデル関数の真のパラメータを格納した辞書。
  - noise_std: ノイズの標準偏差。デフォルトは 0.05。
  - seed: 乱数生成器のシード値。None の場合、ランダムなシードを使用します。デフォルトは 0。
  - noise: ノイズの種類。"normal" (正規分布) または "uniform" (一様分布) を指定します。デフォルトは "normal"。一様分布の場合、ノイズの半幅は \(\sigma\sqrt{3}\) で計算されます。
  - relative_noise: True の場合、ノイズは y_clean の絶対値に比例してスケールされます。デフォルトは False。
- 戻り値: SyntheticData - 生成された合成データを含むデータクラスインスタンス。
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\) 値に対して複数回の測定（繰り返しデータ）をシミュレートして生成します。各繰り返し測定には独立した正規ノイズが追加されます。
- 引数:
  - model_func: generate_noisy_data と同様のモデル関数。
  - x: 独立変数のデータ点。ArrayLike 型。
  - true_params: モデル関数の真のパラメータを格納した辞書。
  - noise_std: ノイズの標準偏差。デフォルトは 0.05。
  - seed: 乱数生成器のシード値。None の場合、ランダムなシードを使用します。デフォルトは 0。
  - n_replicates: 繰り返し測定の回数。デフォルトは 3。
- 戻り値: SyntheticData - 生成された繰り返し合成データを含むデータクラスインスタンス。
save_xy_csv(path: Union[str, Path], data: SyntheticData, *, include_clean: bool = True) -> None
- 動作: SyntheticData オブジェクトの内容をCSVファイルに保存します。
- 引数:
  - path: 保存先のファイルパス。文字列または pathlib.Path オブジェクト。
  - data: 保存する SyntheticData オブジェクト。
  - include_clean: True の場合、y_clean と y_noise 列もCSVに含めます。デフォルトは True。
- 戻り値: None
synthetic_summary(data: SyntheticData) -> str
- 動作: SyntheticData オブジェクトの主要な情報を整形された文字列として返します。データのN、xとyの範囲、ノイズの標準偏差、シード、および真のパラメータが含まれます。
- 引数:
  - data: 概要を取得する SyntheticData オブジェクト。
- 戻り値: str - データの概要文字列。

main scriptとして実行したときの動作

tksynthetic.py ライブラリは、単独のスクリプトとして直接実行された場合の特定の動作は定義されていません（つまり、if __name__ == "__main__": ブロックが存在しません）。したがって、このファイルを直接実行しても何も出力されず、特定の処理も行われません。本ライブラリは、他のPythonプログラムからインポートされて利用されることを前提として設計されています。