Results

Typed result objects returned by pipeline elements. BaseResults is the shared base for every result; the DataFit family (ParameterEstimatorResult and its subtypes) carries fitted parameters plus cost history, and ValidationResult / PassthroughResult cover validation and plain parameter-values returns.

Typed result objects a pipeline element returns.

BaseResults is the shared base and carries the fitted parameter_values; the subclasses add what their kind of element produces — an optimizer’s cost history, a sampler’s chains, a validation’s summary stats. Every result round-trips through BaseResults.to_config() and from_config(), which dispatches on the stored type.

class ionworks.pipeline.results.BaseResults(parameter_values: dict | None = None, **_)

Bases: object

Base class for typed result objects returned by pipeline elements.

Subclasses set a unique type ClassVar and override to_config() to expose their payload fields.

type: ClassVar[str] = 'element_result'

attach_source(fetcher_map: dict) → None

Register zero-arg fetchers for the lazy fields.

A fetcher runs when its field is first read and its answer is cached. An empty answer is not cached, so a later read retries. It never overrides a value already set directly.

Parameters:

fetcher_map (dict) – Mapping of lazy field name (one of "overlay", "trace", "posterior", "series") to a zero-argument callable returning that field’s value.

Raises:

ValueError – If fetcher_map contains a key that isn’t a recognized lazy field.

set_source(**fetchers) → None

Keyword-argument alias for attach_source().

Parameters:

**fetchers – Same as fetcher_map in attach_source(), passed as keyword arguments, e.g. set_source(overlay=fetch_overlay).

explain_no_plots(message: str) → None

Set what plot_fit_results() says when no plots are stored.

Parameters:

message (str) – Replaces the default explanation.

property overlay: dict | None

The fit’s model-vs-data plots, keyed by objective name.

Each entry is {"type": <objective type>, "plots": [...]}, where type is the objective’s discriminator ("EIS", "CycleAgeing", …) and each plot carries named traces plus axis titles — the shape documented in ionworks.pipeline.plots.

Used by plot_fit_results(). None until populated (directly, or lazily via a fetcher registered with attach_source()).

property trace: list[dict] | None

list of {"best_cost", "cost", "inputs_unscaled"}.

Used by plot_trace(). None until populated (directly, or lazily via a fetcher registered with attach_source()).

Type:

Optimizer trace

property posterior: dict | None

Posterior sampling data, populated directly or lazily via a fetcher.

None until populated (directly, or lazily via a fetcher registered with attach_source()).

property series: dict | None

Raw model-vs-data time series, keyed by objective then source.

Each entry is {source: {channel: [values]}} where source is "optimal" or "baseline" and the channels are the objective’s full-resolution data and model traces (e.g. "Time [s]", "Voltage [V] (data)", "Voltage [V] (model)"). Unlike overlay (decimated plot data for figures), this is the numeric series to save or analyse.

None until populated (directly, or lazily via a fetcher registered with attach_source()).

property parameter_values: dict

to_config() → dict

classmethod from_config(config: dict) → ionworks.pipeline.BaseResults

Instantiate the right BaseResults subclass from a config dict.

Pops type, looks up the subclass via the module-level registry, recurses into children so nested results deserialize to the right subclass, and forwards the rest as kwargs.

Parameters:

config (dict) – A result config dict as produced by to_config().

Returns:

An instance of the registered subclass matching config["type"].

Return type:

BaseResults

Raises:

ValueError – If config does not contain a recognized type key.

plot_fit_results() → dict

Plot measured-vs-model data for each objective in overlay.

Each objective is drawn by the renderer for its type (ionworks.pipeline.plots.render()), so a fit’s figures look the same here as they do in the pipeline that produced them.

Returns:

{objective: (fig, axes)} for every objective in overlay that has plots. An objective the backend stored no plots for is left out rather than contributing an empty figure.

Return type:

dict

Raises:

• ValueError – If overlay is None, or if it yields nothing to draw.

• ImportError – If matplotlib (the plot extra) is not installed.

plot_trace()

Plot optimizer convergence from trace.

Draws the best-cost curve plus a per-parameter staircase of inputs_unscaled across iterations.

Returns:

(fig, axes) where axes has one subplot for the best-cost curve followed by one subplot per parameter.

Return type:

tuple

Raises:

• ValueError – If trace is None.

• ImportError – If matplotlib (the plot extra) is not installed.

class ionworks.pipeline.results.ConfidenceIntervalResult(parameter_values: dict | None = None, *, method: str = 'linear', confidence_level: float = 0.95, intervals: dict | None = None, covariance=None, **kwargs)

Bases: BaseResults

Per-parameter confidence interval bounds.

Mirrors ionworkspipeline.analysis.results.ConfidenceIntervalResult.

type: ClassVar[str] = 'ConfidenceIntervalResult'

property method: str

property confidence_level: float

property intervals: dict

property covariance

bounds_for(name: str) → tuple[float, float]

width(name: str) → float

to_config() → dict

class ionworks.pipeline.results.EnsembleResult(parameter_values: dict | None = None, *, x=None, method: str | None = None, **kwargs)

Bases: ParameterEstimatorResult

DataFit return for ensemble-of-points evaluators (grid search, point estimate, batch point estimate).

type: ClassVar[str] = 'EnsembleResult'

property x

property method: str | None

to_config() → dict

class ionworks.pipeline.results.OptimizationResult(parameter_values: dict | None = None, *, x=None, fun: float | None = None, success: bool | None = None, message: str | None = None, evaluations: int | None = None, iterations: int | None = None, **kwargs)

Bases: ParameterEstimatorResult

DataFit return for deterministic optimizers (CMA-ES, Scipy, …).

type: ClassVar[str] = 'OptimizationResult'

property x

property fun: float | None

property success: bool | None

property message: str | None

property evaluations: int | None

property iterations: int | None

to_config() → dict

class ionworks.pipeline.results.ParameterEstimatorResult(parameter_values: dict | None = None, *, cost: float | None = None, samples=None, costs=None, children: list[ParameterEstimatorResult] | None = None, initial_guess: dict | None = None, job_id: int | None = None, **kwargs)

Bases: BaseResults

DataFit-family result: an optimizer/sampler’s fitted parameters plus the cost history that produced them.

Mirrors ionworkspipeline.data_fits.results.ParameterEstimatorResult.

type: ClassVar[str] = 'ParameterEstimatorResult'

property cost: float | None

property samples

property costs

property children: list[ParameterEstimatorResult]

property initial_guess: dict | None

property job_id: int | None

best_results(num_results: int | None = None) → list[ParameterEstimatorResult]

Return the best num_results children, assumed ordered ascending by cost.

Parameters:

num_results (int, optional) – Number of children to return. Defaults to all of children.

Returns:

The first num_results entries of children.

Return type:

list of ParameterEstimatorResult

Raises:

ValueError – If num_results exceeds the number of available children.

to_config() → dict

class ionworks.pipeline.results.PassthroughResult(parameter_values: dict | None = None, **_)

Bases: BaseResults

Wraps elements that return a plain dict / parameter-values mapping.

type: ClassVar[str] = 'PassthroughResult'

class ionworks.pipeline.results.PosteriorResult(parameter_values: dict | None = None, *, chains=None, chains_storage_ref: str | None = None, log_pdfs=None, parameter_names: list[str] | None = None, burnin: int = 0, method: str | None = None, acceptance_rate: float | None = None, r_hat: dict[str, float] | None = None, ess: dict[str, float] | None = None, posterior_summary: dict[str, dict[str, float]] | None = None, **kwargs)

Bases: ParameterEstimatorResult

DataFit return for MCMC samplers (e.g. Pints).

type: ClassVar[str] = 'PosteriorResult'

property chains

(chain, draw, parameter) samples, or None when unavailable.

Populates on access like overlay / trace / posterior: a fit whose chains were offloaded rebuilds them from the posterior payload. to_config() still reports them as offloaded, so recovering here cannot inline them back onto the wire.

property chains_storage_ref: str | None

property x

Best-cost sample, for parity with scipy’s OptimizeResult.x.

Falls back to the posterior payload when the chains were offloaded. None when neither can supply samples and costs.

property log_pdfs

property parameter_names: list[str]

property burnin: int

Draws per chain this result was constructed with, and serializes.

Not necessarily the number marginal() dropped: when the chains were rebuilt from the posterior payload, that payload’s own sample_burnin applies instead. Read a marginal’s length rather than this field to know what was discarded.

property method: str | None

property acceptance_rate: float | None

property r_hat: dict[str, float] | None

property ess: dict[str, float] | None

property posterior_summary: dict[str, dict[str, float]] | None

Per-parameter {mean, std, median, q05, q95}, if provided.

marginal(name: str)

Flattened post-burnin samples for parameter name.

Parameters:

name (str) – Parameter name; must be one of parameter_names.

Returns:

1-D array of samples for name across all chains, with the first burnin draws of each chain dropped.

Return type:

numpy.ndarray

Raises:

• ValueError – If neither chains nor posterior can supply samples.

• KeyError – If name is not in parameter_names.

credible_interval(name: str, level: float = 0.95) → tuple[float, float]

Equal-tailed credible interval for parameter name at level.

Parameters:

• name (str) – Parameter name; must be one of parameter_names.

• level (float, optional) – Central probability mass to cover. Defaults to 0.95.

Returns:

(lower, upper) quantile bounds of the marginal distribution.

Return type:

tuple of float

posterior_mean() → dict[str, float]

Mean of each parameter’s post-burnin marginal.

Reads from posterior_summary when it is present, so it still works when the full chains were too large to inline; otherwise computes the mean from chains.

Returns:

{parameter_name: mean}.

Return type:

dict of str to float

to_config() → dict

class ionworks.pipeline.results.RegressionResult(parameter_values: dict | None = None, *, x=None, results=None, **kwargs)

Bases: ParameterEstimatorResult

DataFit return for Regressor optimizers.

type: ClassVar[str] = 'RegressionResult'

property x

property results

to_config() → dict

class ionworks.pipeline.results.SensitivityResult(parameter_values: dict | None = None, *, method: str = 'sobol', first_order: dict | None = None, total_order: dict | None = None, first_order_ci: dict | None = None, total_order_ci: dict | None = None, second_order: dict | None = None, second_order_ci: dict | None = None, evaluation_stats: dict | None = None, n_samples: int = 0, log_transformed: bool = False, **kwargs)

Bases: BaseResults

Per-parameter sensitivity indices.

Mirrors ionworkspipeline.analysis.results.SensitivityResult.

type: ClassVar[str] = 'SensitivityResult'

property method: str

property first_order: dict

property total_order: dict

property first_order_ci: dict | None

property total_order_ci: dict | None

property second_order: dict | None

property second_order_ci: dict | None

property evaluation_stats: dict

property n_samples: int

property log_transformed: bool

top_contributors(n: int = 5, kind: str = 'total')

bottom_contributors(n: int = 5, kind: str = 'total')

to_config() → dict

class ionworks.pipeline.results.ValidationResult(parameter_values: dict | None = None, *, validation_results: dict | None = None, summary_stats: dict | None = None, failed_objectives: dict[str, str] | None = None, **kwargs)

Bases: BaseResults

Result returned by iw.pipeline.Validation.

type: ClassVar[str] = 'ValidationResult'

property validation_results: dict

property summary_stats: dict

property failed_objectives: dict[str, str]

to_config() → dict

ionworks.pipeline.results.from_config(config: dict) → ionworks.pipeline.BaseResults

Instantiate the right BaseResults subclass from a config dict.

Convenience wrapper for BaseResults.from_config(), mirroring ionworkspipeline.results.parse_element_result; see it for the dispatch rules and what an unrecognized type raises.

Parameters:

config (dict) – A result config dict as produced by BaseResults.to_config().

Returns:

An instance of the registered subclass matching config["type"].

Return type:

BaseResults