`barracuda.diagnostics`¶

Data-only diagnostics for SMC evidence, posterior summaries, baseline lethal probabilities, and empirical trajectory states.

Posterior, SMC, and trajectory diagnostic summaries.

All helpers return NumPy, pandas, or xarray-compatible objects and never draw figures. They are therefore suitable for notebooks, batch validation jobs, and downstream plotting libraries.

Attributes¶

all `module-attribute` ¶

__all__ = ['diagnostic_flags', 'population_p0_draws', 'population_p0_summary', 'posterior_diagnostics', 'smc_evidence_summary', 'smc_log_evidence_by_chain', 'trajectory_state_summary']

Functions:¶

_positive_int ¶

_positive_int(value: Any, name: str, *, allow_none: bool = False) -> int | None

_probability ¶

_probability(value: Any, name: str, *, inclusive: bool = False) -> float

smc_log_evidence_by_chain ¶

smc_log_evidence_by_chain(idata: Any) -> DataFrame

Extract the final finite SMC log marginal likelihood for every chain.

BARRACUDA stores one final value per chain, but this parser also accepts older inference files containing a stage dimension or an attribute fallback. Chains with no finite value are retained with NaN so incomplete output cannot silently masquerade as a lower-chain run.

smc_evidence_summary ¶

smc_evidence_summary(idata: Any) -> Series

Summarize between-chain stability of the SMC evidence estimate.

posterior_diagnostics ¶

posterior_diagnostics(idata: Any, *, var_names: Sequence[str] | None = None, hdi_prob: float = 0.95) -> DataFrame

Return an ArviZ posterior summary with stable parameter columns.

R-hat is undefined for one chain and remains NaN. Effective sample sizes should be interpreted cautiously for weighted/resampled SMC draws; the table is a diagnostic aid, not an automatic validity certificate.

diagnostic_flags ¶

diagnostic_flags(diagnostics: DataFrame, *, min_ess_bulk: float = 100.0, min_ess_tail: float = 100.0, max_r_hat: float = 1.01) -> DataFrame

Add transparent ESS/R-hat flags to a posterior diagnostic table.

Missing R-hat values (for example one-chain SMC output) are marked r_hat_available=False and are not treated as a pass.

population_p0_draws ¶

population_p0_draws(idata: Any, *, n_parameter_draws: int | None = 1000, n_population_draws: int = 1000, seed: int | None = None) -> ndarray

Draw baseline lethal probabilities from a trajectory population.

For every retained posterior pair (mu_eta, sigma_eta), the function samples latent cell propensities and applies the logistic transform. The returned two-dimensional array preserves parameter-draw rows.

population_p0_summary ¶

population_p0_summary(idata: Any, *, n_parameter_draws: int | None = 1000, n_population_draws: int = 1000, seed: int | None = None) -> Series

Summarize simulated baseline lethal probabilities.

trajectory_state_summary ¶

trajectory_state_summary(frame: DataFrame) -> DataFrame

Aggregate observed lethal decisions at every pre-contact state.

frame may be any compact/wide/long trajectory format accepted by :func:barracuda.trajectories.normalize_trajectory_frame, or an already expanded frame returned by expanded_trajectory_frame.

barracuda.diagnostics¶