sequince.result

sequince.result#

Attributes#

NormalizingConstantVarianceMethod

Classes#

`FixedLagLeeWhiteleyDiagnostics`	Diagnostics for a fixed-lag Lee--Whiteley normalizing-constant estimate.
`SMCResult`	Lightweight container exposing diagnostics for a completed SMC run.
`MetaSMCResult`	Aggregate results from a SMC run with a meta SMC step.
`NestedSamplingSMCResult`	Evidence and shell-weighted posterior view of an NS-SMC result.

Module Contents#

sequince.result.NormalizingConstantVarianceMethod#

class sequince.result.FixedLagLeeWhiteleyDiagnostics[source]#

Diagnostics for a fixed-lag Lee–Whiteley normalizing-constant estimate.

family_ess is the inverse concentration of the final normalized particle weight carried by each selected-lag ancestor. It lies between one and distinct_ancestors; low values indicate genealogical depletion.

requested_lag: int#

traced_resampling_events: int#

total_resampling_events: int#

distinct_ancestors: int#

family_ess: float#

class sequince.result.SMCResult[source]#

Lightweight container exposing diagnostics for a completed SMC run.

states: collections.abc.Sequence[sequince.state.ParticleState]#

context: sequince.steps.context.StepContext#

initial_state: sequince.state.ParticleState | None = None#

outputs: collections.abc.Sequence[tuple[Any, ...]] = ()#

append_state(state)[source]#

Return a new result with one additional state appended.

Parameters:: state (sequince.state.ParticleState)
Return type:: SMCResult

encode_for_hdf5(*, strict=False)[source]#

Return a portable HDF5 payload for this result.

By default, unrecognized output dataclasses are converted to dictionaries with a warning. strict=True rejects them instead.

Parameters:: strict (bool)
Return type:: dict[str, Any]

save(h5_file_or_group, path='result', *, strict=False)[source]#

Save this result below path in an open HDF5 handle.

Parameters:

h5_file_or_group (Any)
path (str)
strict (bool)

Return type:

None

save_to_file(file_path, path='result', *, strict=False)[source]#

Save this result to an HDF5 file without replacing existing data.

Parameters:

file_path (str | pathlib.Path)
path (str)
strict (bool)

Return type:

None

classmethod load_from_file(file_path, path='result')[source]#

Load a result from an HDF5 file.

Parameters:

file_path (str | pathlib.Path)
path (str)

Return type:

Self

classmethod load(h5_file_or_group, path='result')[source]#

Load a result from path in an open HDF5 handle.

Parameters:

h5_file_or_group (Any)
path (str)

Return type:

Self

get_meta_results(key=META_SMC_OUTPUT_KEY)[source]#

Return nested SMC results recorded by meta steps.

Parameters:: key (str)
Return type:: MetaSMCResult | None

property final_state: sequince.state.ParticleState#

Return the last state produced by the run.

Return type:: sequince.state.ParticleState

property evaluation_counts: sequince.target.EvaluationCounts#

Return the probabilistic work accumulated during the run.

Return type:: sequince.target.EvaluationCounts

log_normalizing_constant()[source]#

Return the log normalizing constant of the final state.

Return type:: sequince.typing.Array

log_evidence()[source]#

Alias for log_normalizing_constant() for ordinary SMC runs.

For NS-SMC, use as_nested_sampling_result() for shell evidence.

Return type:: sequince.typing.Array

log_normalizing_constant_variance(method='incremental', *, lag=None)[source]#

Estimate variance of the final log normalizing-constant estimate.

"incremental" sums the per-iteration variance diagnostics. The result ignores dependence between SMC iterations.

"lee-whiteley" uses the particle genealogy to estimate relative normalizing-constant variance, which is also a delta-method estimate of log normalizing-constant variance. This estimator requires constant particle count and multinomial resampling at every iteration.

"fixed-lag-lee-whiteley" This estimator truncates the Lee-Whiteley genealogical normalizing-constant variance estimate to the most recent lag resampling events. Particle families are therefore defined by their ancestors lag resampling events before the final population rather than by their time-zero ancestors.

Parameters:

method (NormalizingConstantVarianceMethod)
lag (int | None)

Return type:

sequince.typing.Array

log_evidence_variance(method='incremental', *, lag=None)[source]#

Alias for log_normalizing_constant_variance().

Parameters:

method (NormalizingConstantVarianceMethod)
lag (int | None)

Return type:

sequince.typing.Array

fixed_lag_lee_whiteley_diagnostics(lag)[source]#

Return diagnostics for a fixed-lag Lee–Whiteley estimate.

Parameters:: lag (int)
Return type:: FixedLagLeeWhiteleyDiagnostics

log_normalizing_constant_error(method='incremental', *, lag=None)[source]#

Return the standard error of the log normalizing constant.

Parameters:

method (NormalizingConstantVarianceMethod)
lag (int | None)

Return type:

sequince.typing.Array

log_evidence_error(method='incremental', *, lag=None)[source]#

Alias for log_normalizing_constant_error().

Parameters:

method (NormalizingConstantVarianceMethod)
lag (int | None)

Return type:

sequince.typing.Array

log_normalizing_constant_history()[source]#

Return the log normalizing-constant trajectory.

Return type:: sequince.typing.Array

log_evidence_history()[source]#

Alias for log_normalizing_constant_history().

Return type:: sequince.typing.Array

effective_sample_sizes()[source]#

Return the effective sample size (ESS) for every iteration.

Return type:: sequince.typing.Array

effective_sample_size_ratios()[source]#

Return ESS / n_particles for each iteration.

Return type:: sequince.typing.Array

metadata_history(key, *, default=math.nan)[source]#

Return an array containing a metadata field pulled from each state.

Parameters:

key (str)
default (Any)

Return type:

sequince.typing.Array | list[Any]

summary()[source]#

Return a concise dictionary of high-level diagnostics.

Return type:: dict[str, Any]

as_nested_sampling_result()[source]#

Interpret this run as a likelihood-constrained NS-SMC trajectory.

Return type:: NestedSamplingSMCResult

posterior_samples(*, n_samples=None, rng=None, method='weights')[source]#

Return samples from the weighted posterior represented by the final state.

Parameters:

n_samples (int | None) – Number of samples to return. For "weights", this uniformly down-selects the weighted particle population without replacement. For "rejection", this is an upper limit on the number of accepted particles. For "multinomial", exactly this many samples are drawn with replacement. If None, all weighted or rejection-thinned particles are returned, while multinomial sampling draws the same number of samples as there are particles.
rng (orng.RandomGenerator | numpy.random.Generator | int | None) – Random number generator or seed.
method (Literal['multinomial', 'rejection', 'weights']) –
Method used to construct the returned posterior representation:
- "weights": return weighted particles, optionally uniformly down-selected without replacement.
- "rejection": independently retain each particle with probability proportional to its weight, returning equal-weight unique samples.
- "multinomial": draw equal-weight samples with replacement according to the particle weights.

Returns:

samples – Posterior samples. Scalar particles are returned as a column with shape (n_samples, 1).
sample_weights – Normalized weights associated with samples.

Return type:

tuple[sequince.typing.Array, sequince.typing.Array]

weighted_mean(*, state_index=-1)[source]#

Return the weighted mean of the specified state (defaults to final).

Parameters:: state_index (int)
Return type:: sequince.typing.Array

weighted_covariance(*, state_index=-1, ddof=0)[source]#

Return the weighted covariance matrix for the specified state.

Parameters:

state_index (int)
ddof (int)

Return type:

sequince.typing.Array

apply_weighted(fn, *, state_index=-1)[source]#

Evaluate a function under the weighted empirical distribution.

Parameters:

fn (Callable[[Any], Any])
state_index (int)

Return type:

sequince.typing.Array

plot_log_normalizing_constant(*, ax=None, label_axes=True, **plot_kwargs)[source]#

Plot the log normalizing-constant trajectory.

Parameters:

ax (Any)
label_axes (bool)
plot_kwargs (Any)

Return type:

Any

plot_log_evidence(*, ax=None, label_axes=True, **plot_kwargs)[source]#

Alias for plot_log_normalizing_constant().

Parameters:

ax (Any)
label_axes (bool)
plot_kwargs (Any)

Return type:

Any

plot_effective_sample_size(*, normalize=False, ax=None, label_axes=True, **plot_kwargs)[source]#

Plot ESS or the ESS ratio across iterations.

Parameters:

normalize (bool)
ax (Any)
label_axes (bool)
plot_kwargs (Any)

Return type:

Any

plot_metadata_history(key, *, ax=None, default=math.nan, label_axes=True, **plot_kwargs)[source]#

Plot the evolution of a metadata entry stored in each state.

Parameters:

key (str)
ax (Any)
default (Any)
label_axes (bool)
plot_kwargs (Any)

Return type:

Any

plot_corner(*, state_index=-1, include_weights=False, parameter_inds=None, filename=None, **corner_kwargs)[source]#

Plot a corner plot of the particles in the specified state.

Parameters:

state_index (int) – Index of the state to plot (default is -1, the final state).
include_weights (bool) – If True, include particle weights in the corner plot.
parameter_inds (collections.abc.Sequence[int] | None) – Indices of the parameters to include in the corner plot. If None (default) all parameters are included.
filename (str | pathlib.Path | None) – If provided, the plot is saved to this file instead of being returned.
corner_kwargs (Any) – Additional keyword arguments passed to the corner function.

Returns:

The corner plot figure, if filename is not provided.

Return type:

fig

plot_trace(*, ax=None, parameter_inds=None, parameter_labels=None, filename=None, kind='violin', **plot_kwargs)[source]#

Plot a trace plot of the particles as a function of state index.

Parameters:

ax (Any) – Axis on which to plot. If None, a new figure and axis are created.
parameter_inds (collections.abc.Sequence[int] | None) – Indices of the parameters to include in the trace plot. If None (default) all parameters are included.
parameter_labels (collections.abc.Sequence[str] | None) – Labels for the parameters to include in the trace plot. If None (default) generic labels {x_i} are used.
filename (str | pathlib.Path | None) – If provided, the plot is saved to this file instead of being returned.
kind (str) – The kind of trace plot to create. Currently only “violin” or “scatter” are supported.
plot_kwargs (Any) – Additional keyword arguments passed to the ax.plot function.

Returns:

The trace plot axis, if filename is not provided.

Return type:

class sequince.result.MetaSMCResult[source]#

Aggregate results from a SMC run with a meta SMC step.

results: collections.abc.Sequence[SMCResult]#

encode_for_hdf5(*, strict=False)[source]#

Return the logical HDF5 payload for this meta-SMC result.

Parameters:: strict (bool)
Return type:: dict[str, Any]

save(h5_file_or_group, path='meta_result', *, strict=False)[source]#

Save this meta-SMC result in an open HDF5 handle.

Parameters:

h5_file_or_group (Any)
path (str)
strict (bool)

Return type:

None

classmethod load(h5_file_or_group, path='meta_result')[source]#

Load a meta-SMC result from an open HDF5 handle.

Parameters:

h5_file_or_group (Any)
path (str)

Return type:

Self

property final_result: SMCResult#

Return the final meta-step result.

Return type:: SMCResult

property final_state: sequince.state.ParticleState#

Return the final particle state from the last meta step.

Return type:: sequince.state.ParticleState

property all_states: list[sequince.state.ParticleState]#

Flatten particle states across all meta steps in execution order.

Return type:: list[sequince.state.ParticleState]

log_normalizing_constant_history()[source]#

Return the log normalizing-constant trajectory across meta steps.

Return type:: sequince.typing.Array

log_evidence_history()[source]#

Alias for log_normalizing_constant_history().

Return type:: sequince.typing.Array

plot_log_normalizing_constant(*, ax=None, label_axes=True, cmap='viridis', **plot_kwargs)[source]#

Plot the log normalizing-constant trajectory across meta steps.

Parameters:

ax (Any)
label_axes (bool)
cmap (str)
plot_kwargs (Any)

Return type:

Any

plot_log_evidence(*, ax=None, label_axes=True, cmap='viridis', **plot_kwargs)[source]#

Alias for plot_log_normalizing_constant().

Parameters:

ax (Any)
label_axes (bool)
cmap (str)
plot_kwargs (Any)

Return type:

Any

plot_metadata_history(key, *, ax=None, default=math.nan, label_axes=True, cmap='viridis', **plot_kwargs)[source]#

Plot metadata history across all meta steps.

Parameters:

key (str)
ax (Any)
default (Any)
label_axes (bool)
cmap (str)
plot_kwargs (Any)

Return type:

Any

summary()[source]#

Return a concise dictionary of high-level diagnostics.

Return type:: dict[str, Any]

class sequince.result.NestedSamplingSMCResult[source]#

Evidence and shell-weighted posterior view of an NS-SMC result.

The wrapped result’s final state is a constrained prior, not a posterior. Use this wrapper’s posterior_samples method for Bayesian inference.

result: SMCResult#

property states: collections.abc.Sequence[sequince.state.ParticleState]#

Return type:: collections.abc.Sequence[sequince.state.ParticleState]

property context: sequince.steps.context.StepContext#

Return type:: sequince.steps.context.StepContext

property final_state: sequince.state.ParticleState#

Return type:: sequince.state.ParticleState

property log_evidence: float#

Accumulated shell evidence, including the live tail if finalized.

Return type:: float

property complete: bool#

Return type:: bool

property stop_reason: str | None#

Readable stopping diagnostic for eager and functional executions.

Return type:: str | None

levels()[source]#

Return per-shell diagnostics, including a terminal shell if present.

Return type:: list[sequince.steps.constraints.NestedSamplingLevel]

threshold_history()[source]#

Return type:: sequince.typing.Array

survival_fraction_history()[source]#

Return type:: sequince.typing.Array

surviving_particles_history()[source]#

Return type:: sequince.typing.Array

log_prior_volume_history()[source]#

Return type:: sequince.typing.Array

log_prior_volume_increment_history()[source]#

Return type:: sequince.typing.Array

log_evidence_history()[source]#

Return type:: sequince.typing.Array

log_evidence_increment_history()[source]#

Return type:: sequince.typing.Array

shell_lower_threshold_history()[source]#

Return type:: sequince.typing.Array

shell_upper_threshold_history()[source]#

Return type:: sequince.typing.Array

posterior_samples(*, n_samples=None, rng=None, method='weights')[source]#

Return shell particles weighted by their contribution to evidence.

Parameters and return values follow SMCResult.posterior_samples. A finalized run with store_shell_particles=True is required. Particle weights are quadrature weights; their ESS does not measure MCMC independence or account for shared ancestors.

Parameters:

n_samples (int | None)
rng (orng.RandomGenerator | numpy.random.Generator | int | None)
method (Literal['multinomial', 'rejection', 'weights'])

Return type:

tuple[sequince.typing.Array, sequince.typing.Array]

summary()[source]#

Return type:: dict[str, Any]