kipe.plot module
Plots of the estimation history: kipe plot.
One subplot per parameter: the estimate after each assimilation step with its physical 1σ
range, over the steps of all outer iterations. The history is read from history.csv, which
the estimation writes as it runs, so a running estimation can be plotted too. If the run’s
plan is known from its provenance (kipe.provenance), the x axis spans the whole run
from the start, with all outer iterations marked.
Draws with matplotlib (plot_histories()) or as text in the terminal with plotext
(render_histories()), e.g., to follow an estimation on a cluster (watch_histories()).
- exception kipe.plot.PlotError[source]
Bases:
ExceptionThe history cannot be plotted, e.g., because it does not exist (yet).
- class kipe.plot.History(names: list[str], iteration: NDArray_f64, parameters: NDArray_f64, lower: NDArray_f64, upper: NDArray_f64, steps_per_iteration: int | None = None, iterations: int | None = None)[source]
Bases:
objectThe estimation history, as read from
history.csv.- names: list[str]
Names of the estimated parameters.
- iteration: NDArray_f64
Index of the outer iteration of each step, shape
(k,).
- parameters: NDArray_f64
The estimate after each step, as physical values, shape
(k, p).
- lower: NDArray_f64
Lower end of the physical 1σ range, shape
(k, p).
- upper: NDArray_f64
Upper end of the physical 1σ range, shape
(k, p).
- steps_per_iteration: int | None = None
Number of steps of each outer iteration, from the run’s plan; None if unknown.
- iterations: int | None = None
Number of outer iterations, from the run’s plan; None if unknown.
- property steps: int
Number of steps of the whole run if its plan is known, else of the history so far.
- kipe.plot.read_history(path: str | Path) History[source]
Read an estimation history from
history.csv, and the run’s plan next to it.The plan, the number of steps per outer iteration and of iterations, comes from the provenance of the run: the assimilation times in
run.yaml, the iterations instudy.yaml(the options the run started with).- Parameters:
path – path to
history.csv- Returns:
the history
- Raises:
PlotError – if the file does not exist or holds no steps yet
- kipe.plot.plot_histories(figure: Figure, histories: dict[str, History], truth: Parameters | None = None) None[source]
Plot estimation histories into a figure, one subplot per parameter.
With a single history, each subplot title shows the latest estimate and range; with a truth, also the true value.
- Parameters:
figure – the figure to draw into
histories – label -> history; all must estimate the same parameters
truth – true values, drawn as reference lines (e.g., in a twin experiment)
- Raises:
PlotError – if the histories estimate different parameters
- kipe.plot.render_histories(histories: Mapping[str, History], truth: Parameters | None = None, height: int | None = None, color: bool = True) str[source]
Render estimation histories as text for the terminal, one subplot per parameter.
Like
plot_histories(), with the 1σ range drawn as gray lines below and above the estimate. With a single history, each subplot title shows the latest estimate and range. Several histories or a truth get a legend below the plot.- Parameters:
histories – label -> history; all must estimate the same parameters
truth – true values, drawn as reference lines (e.g., in a twin experiment)
height – number of lines, legend included; if not given, 12 per parameter
color – whether to color the output with ANSI escape codes
- Returns:
the rendered plot
- Raises:
PlotError – if the histories estimate different parameters
- kipe.plot.watch_histories(paths: Mapping[str, Path], truth: Parameters | None = None, interval: float = 2.0) None[source]
Redraw estimation histories in the terminal as they grow, until Ctrl+C.
Fills the terminal; waits while a history does not exist yet or holds no steps.
- Parameters:
paths – label -> path to
history.csvtruth – true values, drawn as reference lines
interval – seconds between redraws
- Raises:
PlotError – if the histories estimate different parameters