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_schema.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_mapdict

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

messagestr

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_schema.plots.

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

property trace: list[dict] | None

Optimizer trace: list of {"best_cost", "cost", "inputs_unscaled"}.

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

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) → 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

configdict

A result config dict as produced by to_config().

Returns

BaseResults

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

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_schema.plots.render()), so a fit’s figures look the same here as they do in the pipeline that produced them.

Returns

dict

{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.

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

tuple

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

Raises

ValueError

If trace is None.

ImportError

If matplotlib (the plot extra) is not installed.

class ionworks_schema.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_schema.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_schema.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_schema.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_resultsint, optional

Number of children to return. Defaults to all of children.

Returns

list of ParameterEstimatorResult

The first num_results entries of children.

Raises

ValueError

If num_results exceeds the number of available children.

to_config() → dict

class ionworks_schema.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_schema.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

namestr

Parameter name; must be one of parameter_names.

Returns

numpy.ndarray

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

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

namestr

Parameter name; must be one of parameter_names.

levelfloat, optional

Central probability mass to cover. Defaults to 0.95.

Returns

tuple of float

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

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

dict of str to float

{parameter_name: mean}.

to_config() → dict

class ionworks_schema.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_schema.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_schema.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 iws.Validation.

type: ClassVar[str] = 'ValidationResult'

property validation_results: dict

property summary_stats: dict

property failed_objectives: dict[str, str]

to_config() → dict

ionworks_schema.results.from_config(config: dict) → 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

configdict

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

Returns

BaseResults

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