tkplot プログラム仕様

tkplot.py

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

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

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

regression.tklsq.tkplot.make_xcal(x: Sequence[float] | ndarray, *, n: int = 401, xmin: float | None = None, xmax: float | None = None, margin: float = 0.0) → ndarray[ソース]

プロット用の滑らかな x 軸を生成します。

与えられたデータ点 x の範囲に基づいて、プロットに適した均一な間隔のx軸を生成します。 最小値、最大値、またはマージンを調整して、表示範囲を制御できます。

パラメータ:

  • x (ArrayLike) -- 既存のxデータ。このデータの範囲がデフォルトのx軸範囲の基準となります。

  • n (int) -- 生成するx軸の点の数。デフォルトは401点です。

  • xmin (Optional[float]) -- x軸の最小値を明示的に指定します。Noneの場合、`x`の最小値が使用されます。

  • xmax (Optional[float]) -- x軸の最大値を明示的に指定します。Noneの場合、`x`の最大値が使用されます。

  • margin (float) -- x軸の範囲に対するマージンの割合。0.1を指定すると、範囲の10%が両端に追加されます。

戻り値:

プロット用に生成された滑らかなx軸のデータ。

戻り値の型:

np.ndarray

regression.tklsq.tkplot.plot_band(ax, band: Mapping[str, Sequence[float] | ndarray], *, color: str = 'tab:blue', alpha: float = 0.18, label: str = 'uncertainty')[ソース]

既存のAxesオブジェクトに誤差帯（不確実性帯域）を追加します。

モデルの予測の信頼区間や、データの不確かさを視覚的に表現するために使用します。 `band`辞書には、xデータとyの低/高値、またはyの平均値と標準偏差を含める必要があります。

パラメータ:

  • ax (matplotlib.axes.Axes) -- 誤差帯を追加するmatplotlibのAxesオブジェクト。

  • band (Mapping[str, ArrayLike]) -- 誤差帯に関する情報を含む辞書。 {"x": xband, "y_low": y_low, "y_high": y_high} または {"x": xband, "y_mean": y_mean, "sigma": sigma} の形式である必要があります。

  • color (str) -- 誤差帯の塗りつぶし色。

  • alpha (float) -- 誤差帯の透明度。0.0（完全に透明）から1.0（完全に不透明）の範囲。

  • label (str) -- 誤差帯の凡例ラベル。

例外:

ValueError -- `band`辞書に必要なキー（'x'、および'y_low'/'y_high'または'y_mean'/'sigma'）が含まれていない場合。

戻り値:

なし (Axesを直接変更します)。

戻り値の型:

None

regression.tklsq.tkplot.plot_fit_before_after(x: Sequence[float] | ndarray, y: Sequence[float] | ndarray, model_func: Callable[[ndarray, Mapping[str, float]], Sequence[float] | ndarray], p_before: Mapping[str, float], *, p_after: Mapping[str, float] | None = None, xcal: Sequence[float] | ndarray | None = None, yerr: Sequence[float] | ndarray | None = None, band: Mapping[str, Sequence[float] | ndarray] | None = 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: str | Path | None = None, show: bool = False, close: bool = True)[ソース]

データ、フィット前、フィット後を重ねて描画します。

観測データ、フィット前のモデル予測、フィット後のモデル予測を一つのグラフ上に表示します。 オプションで、データの誤差棒やモデルの誤差帯を追加することも可能です。 生成されたFigureとAxesオブジェクトを返却し、さらに画像ファイルとして保存したり、 画面に表示したりすることもできます。

パラメータ:

  • x (ArrayLike) -- 観測データのx座標。

  • y (ArrayLike) -- 観測データのy座標。

  • model_func (Callable[[np.ndarray, Mapping[str, float]], ArrayLike]) -- モデル関数。y = model_func(x_array, params_dict) の形式で呼び出されます。

  • p_before (Mapping[str, float]) -- フィット前のモデルパラメータを含む辞書。

  • p_after (Optional[Mapping[str, float]]) -- (オプション) フィット後のモデルパラメータを含む辞書。指定しない場合、フィット後の曲線はプロットされません。

  • xcal (Optional[ArrayLike]) -- (オプション) モデル曲線を描画するためのx軸データ。指定しない場合、`make_xcal`によって自動生成されます。

  • yerr (Optional[ArrayLike]) -- (オプション) データのy方向の誤差。指定した場合、エラーバーがプロットされます。

  • band (Optional[Mapping[str, ArrayLike]]) -- (オプション) モデルの不確実性帯域に関する情報を含む辞書。 {"x": xband, "y_low": y_low, "y_high": y_high} または {"x": xband, "y_mean": y_mean, "sigma": sigma} の形式。

  • xlabel (str) -- x軸のラベル文字列。

  • ylabel (str) -- y軸のラベル文字列。

  • title (str) -- プロットのタイトル文字列。

  • data_label (str) -- データ点に表示する凡例ラベル。

  • before_label (str) -- フィット前の曲線に表示する凡例ラベル。

  • after_label (str) -- フィット後の曲線に表示する凡例ラベル。

  • out_png (Optional[Union[str, Path]]) -- (オプション) プロットを保存するPNGファイルのパス。指定しない場合、ファイルは保存されません。

  • show (bool) -- プロットを表示するかどうか。Trueの場合、`plt.show()`が呼び出されます。

  • close (bool) -- プロットを閉じるかどうか。Trueの場合、`plt.close(fig)`が呼び出されます。 `show=True`の場合でも、明示的に閉じたい場合に利用します。

戻り値:

生成されたmatplotlibのFigureオブジェクトとAxesオブジェクト。

戻り値の型:

Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

regression.tklsq.tkplot.save_progress_plot(iteration: int, x: Sequence[float] | ndarray, y: Sequence[float] | ndarray, model_func: Callable[[ndarray, Mapping[str, float]], Sequence[float] | ndarray], p_before: Mapping[str, float], p_current: Mapping[str, float], *, out_dir: str | Path = '.', prefix: str = 'fit_progress', **kwargs) → Path[ソース]

フィット途中の画像を保存します。主にコールバック関数からの呼び出しを想定しています。

フィットアルゴリズムの各イテレーションでのモデルの適合状況を視覚的に追跡するために、 指定されたディレクトリにPNG画像としてプロットを保存します。 ファイル名はイテレーション番号に基づいて自動的に生成され、進行状況を容易に確認できます。

パラメータ:

  • iteration (int) -- 現在のフィットイテレーション番号。ファイル名に埋め込まれます。

  • x (ArrayLike) -- 観測データのx座標。

  • y (ArrayLike) -- 観測データのy座標。

  • model_func (Callable[[np.ndarray, Mapping[str, float]], ArrayLike]) -- モデル関数。y = model_func(x_array, params_dict) の形式で呼び出されます。

  • p_before (Mapping[str, float]) -- フィット開始前のモデルパラメータを含む辞書。プロットの「before」曲線に使用されます。

  • p_current (Mapping[str, float]) -- 現在のイテレーションにおけるモデルパラメータを含む辞書。プロットの「after」曲線に使用されます。

  • out_dir (Union[str, Path]) -- (オプション) 画像ファイルを保存する出力ディレクトリのパス。

  • prefix (str) -- (オプション) 保存される画像ファイルのプレフィックス。 ファイル名は prefix_0001.png のようになります。

  • kwargs -- plot_fit_before_after に渡される追加のキーワード引数。

戻り値:

保存された画像ファイルの完全なパス。

戻り値の型:

Path