tkplot.py の技術ドキュメント

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

tkplot.py は、フィット結果の標準的なプロットを補助するために設計されたPythonライブラリです。主な目的は、データ、モデルのフィット前（初期パラメータ）の予測、およびフィット後（最適化されたパラメータ）の予測を重ねて描画することです。

このライブラリは、プロットの「細かい見た目」は、このライブラリの関数から返される matplotlib.figure.Figure および matplotlib.axes.Axes オブジェクトをアプリケーション側で調整できるよう、最小限の機能に絞られた「薄い」関数群として提供されています。これにより、柔軟なカスタマイズが可能となっています。

解決する課題としては、データフィットの進捗状況の可視化や、フィット結果の迅速な評価をサポートすることが挙げられます。

importする方法

tkplot.py を他のPythonプログラムから利用するには、通常のモジュールと同様に import ステートメントを使用します。

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

import tkplot

特定の関数のみをインポートする場合：

from tkplot import plot_fit_before_after, make_xcal

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

tkplot.py は以下の非標準ライブラリに依存しています。

NumPy: 数値計算、特に配列操作に使用されます。
Matplotlib: プロットの描画に使用されます。

これらのライブラリは pip コマンドを使用してインストールできます。

pip install numpy matplotlib

importできる変数と関数

tkplot.py から import できる変数と関数は以下の通りです。

変数

ArrayLike
- 型エイリアス: Sequence[float] | np.ndarray
- 説明: 浮動小数点数のシーケンス（リスト、タプルなど）またはNumPy配列を受け入れることを示す型ヒントとして使用されます。これにより、関数が受け入れる入力の柔軟性を表現します。

関数

make_xcal(x: ArrayLike, *, n: int = 401, xmin: Optional[float] = None, xmax: Optional[float] = None, margin: float = 0.0) -> np.ndarray
- 動作: プロット用の滑らかなX軸データ（等間隔の数値配列）を生成します。入力データ x の最小値と最大値を基に範囲を決定し、指定された点数 n で配列を作成します。オプションで、X軸の最小値、最大値、および範囲に対するマージンを設定できます。
- 引数:
  - x (ArrayLike): 元となるデータ点のX座標の配列またはシーケンス。このデータからX軸の範囲が決定されます。
  - n (int, デフォルト: 401): 生成されるX軸データ点の数。
  - xmin (Optional[float], デフォルト: None): X軸の最小値を明示的に指定します。None の場合、x の最小値が使用されます。
  - xmax (Optional[float], デフォルト: None): X軸の最大値を明示的に指定します。None の場合、x の最大値が使用されます。
  - margin (float, デフォルト: 0.0): X軸の範囲の (xmax - xmin) に対するマージンの割合。X軸の両端をこの割合だけ拡張します。
- 戻り値: np.ndarray: 生成された滑らかなX軸データ。
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)
- 動作: 観測データ、フィット前のモデル予測、およびオプションでフィット後のモデル予測を重ねてプロットします。エラーバーや誤差帯の表示もサポートします。プロットはファイルに保存したり、画面に表示したり、描画後に閉じるかを制御できます。この関数は内部で matplotlib.pyplot をインポートして利用します。
- 引数:
  - x (ArrayLike): 観測データ点のX座標。
  - y (ArrayLike): 観測データ点のY座標。
  - model_func (Callable[[np.ndarray, Mapping[str, float]], ArrayLike]): モデル関数。引数として (x_array, params_dict) を受け取り、対応するY値の配列を返します。
  - p_before (Mapping[str, float]): フィット前のモデルパラメータを格納した辞書。
  - p_after (Optional[Mapping[str, float]], デフォルト: None): フィット後のモデルパラメータを格納した辞書。指定された場合のみプロットされます。
  - xcal (Optional[ArrayLike], デフォルト: None): モデル予測のプロットに使用するX軸データ。None の場合、make_xcal を用いて自動生成されます。
  - yerr (Optional[ArrayLike], デフォルト: None): 観測データのエラーバーのY方向の誤差。指定された場合、エラーバーとして表示されます。
  - band (Optional[Mapping[str, ArrayLike]], デフォルト: None): 誤差帯のデータ。以下のいずれかの形式の辞書で指定します。
    - {"x": xband, "y_low": y_low, "y_high": y_high}
    - {"x": xband, "y_mean": y_mean, "sigma": sigma} (y_low と y_high は $y_{mean} \pm \sigma$ から計算されます)
  - xlabel (str, デフォルト: "x"): X軸のラベル。
  - ylabel (str, デフォルト: "y"): Y軸のラベル。
  - title (str, デフォルト: "fit result"): プロットのタイトル。
  - data_label (str, デフォルト: "data"): 観測データの凡例ラベル。
  - before_label (str, デフォルト: "before"): フィット前モデルの凡例ラベル。
  - after_label (str, デフォルト: "after"): フィット後モデルの凡例ラベル。
  - out_png (Optional[Union[str, Path]], デフォルト: None): プロットを保存するファイルパス。指定された場合、指定されたパスにPNG形式で保存されます。親ディレクトリが存在しない場合は作成されます。
  - show (bool, デフォルト: False): プロットを画面に表示するかどうか。
  - close (bool, デフォルト: True): 描画後に matplotlib.pyplot.close() を呼び出してFigureオブジェクトを閉じるかどうか。
- 戻り値: Tuple[Figure, Axes]: matplotlib.figure.Figure オブジェクトと matplotlib.axes.Axes オブジェクトのタプル。
plot_band(ax, band: Mapping[str, ArrayLike], *, color: str = "tab:blue", alpha: float = 0.18, label: str = "uncertainty")
- 動作: 既存の matplotlib.axes.Axes オブジェクトに誤差帯（エラーバンド）を追加します。誤差帯は $y_{low}$ から $y_{high}$ の範囲を塗りつぶす fill_between で表現されます。
- 引数:
  - ax: 誤差帯を追加する matplotlib.axes.Axes オブジェクト。
  - band (Mapping[str, ArrayLike]): 誤差帯のデータ。plot_fit_before_after 関数と同様に、以下のいずれかの形式の辞書で指定します。
    - {"x": xband, "y_low": y_low, "y_high": y_high}
    - {"x": xband, "y_mean": y_mean, "sigma": sigma}
    - 辞書には必ず 'x' キーが含まれている必要があり、'y_low'/'y_high' のペアまたは 'y_mean'/'sigma' のペアのいずれかが含まれている必要があります。
  - color (str, デフォルト: "tab:blue"): 誤差帯の色。
  - alpha (float, デフォルト: 0.18): 誤差帯の透明度。
  - label (str, デフォルト: "uncertainty"): 誤差帯の凡例ラベル。
- 戻り値: なし。ax オブジェクトを直接変更します。
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
- 動作: フィット最適化の途中経過をプロットし、画像ファイルとして保存します。これは通常、最適化アルゴリズムのコールバック関数から呼び出されることを想定しています。plot_fit_before_after 関数を内部的に利用してプロットを生成します。
- 引数:
  - iteration (int): 現在のイテレーション（繰り返し）回数。ファイル名やプロットタイトルに使用されます。
  - x (ArrayLike): 観測データ点のX座標。
  - y (ArrayLike): 観測データ点のY座標。
  - model_func (Callable[[np.ndarray, Mapping[str, float]], ArrayLike]): モデル関数。plot_fit_before_after と同じ形式。
  - p_before (Mapping[str, float]): フィット開始時、または前回のイテレーションのモデルパラメータ。
  - p_current (Mapping[str, float]): 現在のイテレーションのモデルパラメータ。plot_fit_before_after の p_after として渡されます。
  - out_dir (Union[str, Path], デフォルト: "."): 画像ファイルを保存するディレクトリ。存在しない場合は作成されます。
  - prefix (str, デフォルト: "fit_progress"): 保存されるファイル名のプレフィックス。ファイル名は "{prefix}_{iteration:04d}.png" の形式になります。
  - **kwargs: plot_fit_before_after 関数に渡される追加のキーワード引数。
- 戻り値: Path: 保存された画像ファイルの完全なパス。

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

tkplot.py は、if __name__ == "__main__": ブロックを持たないため、このファイルを直接Pythonインタプリタで実行しても、特別な処理は行われません。ライブラリとして他のスクリプトからインポートして利用することを前提としています。

python tkplot.py

上記コマンドを実行しても、何も出力されず、エラーも発生しません。