container-overview

Visual schema reference for bossanova’s internal data containers — frozen attrs classes that flow between operations. Diagrams show core fields (the shape at creation). Optional inference fields added by .infer() are omitted; see Containers for the full API reference.

Quick Reference¶

Container	Fields	Optional	Source	Description
`ModelSpec`	8	0	specs	Immutable model configuration.
`SimulationSpec`	6	1	specs	Specification for data generation in simulation-first wor...
`VaryingSpec`	5	1	specs	Specification for random effect grouping in simulation.
`DataBundle`	14	6	data	Validated model data (valid observations only).
`REInfo`	10	1	data	Random effects metadata.
`FitState`	17	8	fit	Immutable fitting result.
`InferenceState`	15	5	inference	Inference results that augment params or estimates.
`JointTestState`	7	1	inference	Joint hypothesis test results for model terms.
`CVState`	15	9	inference	Cross-validation results for model evaluation.
`PredictionState`	13	12	prediction	Prediction results with optional intervals.
`MeeState`	23	16	marginal	Marginal effects / estimated marginal means results.
`SimulationInferenceState`	11	2	simulation	Simulation inference results for post-fit or power analys...
`VaryingState`	7	3	mixed	Random effects (BLUPs) for mixed models.
`VaryingSpreadState`	9	5	mixed	Variance components for mixed models.
`ExploreFormulaSpec`	10	8	explore	Parsed explore formula.
`Condition`	5	4	explore	A conditioning specification in explore formula.

Pipeline¶

How containers flow through the model lifecycle. Arrows show which method produces each container:

Config¶

Model and simulation specifications parsed from user input.

ModelSpec¶

Immutable model configuration.

Field	Type	Opt
`formula`	str
`response_var`	str
`fixed_terms`	tuple[str]
`family`	str
`link`	str
`has_random_effects`	bool
`method`	str
`random_terms`	tuple[str]

SimulationSpec¶

Specification for data generation in simulation-first workflows.

Field	Type	Opt
`n`	int
`distributions`	dict[str, Distribution]
`coef`	dict[str, float]
`sigma`	float
`re_spec`	dict[str, VaryingSpec]
`seed`	int \| None	✱

Contains: VaryingSpec

VaryingSpec¶

Specification for random effect grouping in simulation.

Field	Type	Opt
`n`	int
`sd`	float
`slope_sds`	dict[str, float]
`correlations`	dict[tuple[str, str], float]
`n_per`	int \| None	✱

Data¶

Validated model data ready for fitting.

DataBundle¶

Validated model data (valid observations only).

Field	Type	Opt
`X`	ndarray
`y`	ndarray
`X_names`	tuple[str]
`y_name`	str
`valid_mask`	ndarray
`n_total`	int
`Z`	csc_matrix \| None	✱
`weights`	ndarray \| None	✱
`offset`	ndarray \| None	✱
`factor_levels`	dict[str, tuple[str]]
`contrast_types`	dict[str, str]
`re_metadata`	REInfo \| None	✱
`response_levels`	tuple[str] \| None	✱
`rank_info`	RankInfo \| None	✱

Properties: has_random_effects() → bool, n() → int, p() → int, rank() → int

Contains: REInfo

REInfo¶

Random effects metadata.

Field	Type	Opt
`grouping_vars`	tuple[str]
`n_groups`	dict[str, int]
`group_indices`	dict[str, ndarray]
`term_names`	tuple[str]
`group_ids_list`	list[ndarray]
`n_groups_list`	list[int]
`re_structure`	str
`random_names`	list[str]
`X_re`	ndarray \| list[ndarray] \| None	✱
`metadata`	dict

Fit & Inference¶

Fitting results and statistical inference.

FitState¶

Immutable fitting result.

Field	Type	Opt
`coef`	ndarray
`vcov`	ndarray
`fitted`	ndarray
`residuals`	ndarray
`leverage`	ndarray
`df_resid`	float
`loglik`	float
`converged`	bool
`n_iter`	int
`sigma`	float \| None	✱
`dispersion`	float \| None	✱
`null_deviance`	float \| None	✱
`deviance`	float \| None	✱
`theta`	ndarray \| None	✱
`u`	ndarray \| None	✱
`irls_weights`	ndarray \| None	✱
`XtWX_inv`	ndarray \| None	✱

Inference¶

Statistical inference, joint tests, and cross-validation.

InferenceState¶

Inference results that augment params or estimates.

Field	Type	Opt
`se`	ndarray
`statistic`	ndarray
`df`	ndarray
`p_value`	ndarray
`ci_lower`	ndarray
`ci_upper`	ndarray
`conf_level`	float
`method`	str
`null`	float
`alternative`	str
`n_resamples`	int \| None	✱
`boot_samples`	ndarray \| None	✱
`perm_samples`	ndarray \| None	✱
`pre`	ndarray \| None	✱
`pre_sd`	ndarray \| None	✱

JointTestState¶

Joint hypothesis test results for model terms.

Field	Type	Opt
`terms`	tuple[str]
`df1`	ndarray
`statistic`	ndarray
`p_value`	ndarray
`test_type`	str
`ss_type`	str
`df2`	ndarray \| None	✱

CVState¶

Cross-validation results for model evaluation.

Field	Type	Opt
`k`	int
`mse`	float
`rmse`	float
`mae`	float
`r_squared`	float
`deviance`	float \| None	✱
`accuracy`	float \| None	✱
`sensitivity`	float \| None	✱
`specificity`	float \| None	✱
`f1`	float \| None	✱
`auc`	float \| None	✱
`fold_metrics`	dict[str, ndarray]
`oos_predictions`	ndarray \| None	✱
`oos_residuals`	ndarray \| None	✱
`fold_assignments`	ndarray \| None	✱

Prediction¶

Prediction results.

PredictionState¶

Prediction results with optional intervals.

Field	Type	Opt
`fitted`	ndarray
`link`	ndarray \| None	✱
`X_pred`	ndarray \| None	✱
`config`	PredictionConfig \| None	✱
`se`	ndarray \| None	✱
`ci_lower`	ndarray \| None	✱
`ci_upper`	ndarray \| None	✱
`interval_type`	str \| None	✱
`conf_level`	float \| None	✱
`grid`	DataFrame \| None	✱
`cv_fitted`	ndarray \| None	✱
`cv_residual`	ndarray \| None	✱
`cv_fold`	ndarray \| None	✱

Properties: has_cv() → bool, has_inference() → bool

Exploration¶

Marginal effects exploration.

MeeState¶

Marginal effects / estimated marginal means results.

Field	Type	Opt
`grid`	DataFrame
`estimate`	ndarray
`explore_formula`	str
`focal_var`	str
`type`	str
`how`	str
`effect_scale`	str
`L_matrix`	ndarray \| None	✱
`contrast_method`	str \| None	✱
`n_contrast_levels`	int \| None	✱
`link`	str \| None	✱
`L_matrix_link`	ndarray \| None	✱
`_boot_X_plus`	ndarray \| None	✱
`_boot_X_minus`	ndarray \| None	✱
`_boot_delta`	float \| None	✱
`inference_method`	str \| None	✱
`se`	ndarray \| None	✱
`df`	ndarray \| None	✱
`statistic`	ndarray \| None	✱
`p_value`	ndarray \| None	✱
`ci_lower`	ndarray \| None	✱
`ci_upper`	ndarray \| None	✱
`conf_level`	float \| None	✱

Properties: has_inference() → bool

Simulation¶

Simulation inference summaries.

SimulationInferenceState¶

Simulation inference results for post-fit or power analysis simulations.

Field	Type	Opt
`sim_type`	str
`n_sims`	int
`sim_mean`	ndarray \| None	✱
`sim_sd`	ndarray \| None	✱
`sim_quantiles`	dict[str, ndarray]
`power`	dict[str, float]
`coverage`	dict[str, float]
`bias`	dict[str, float]
`rmse`	dict[str, float]
`alpha`	float
`true_coef`	dict[str, float]

Mixed Models¶

Random effects (BLUPs) and variance components.

VaryingState¶

Random effects (BLUPs) for mixed models.

Field	Type	Opt
`grid`	DataFrame
`effects`	dict[str, ndarray]
`grouping_var`	str
`n_groups`	int
`pi_lower`	dict[str, ndarray] \| None	✱
`pi_upper`	dict[str, ndarray] \| None	✱
`conf_level`	float \| None	✱

Properties: has_inference() → bool

VaryingSpreadState¶

Variance components for mixed models.

Field	Type	Opt
`components`	DataFrame
`sigma2`	float
`tau2`	dict[str, float]
`rho`	dict[str, float]
`icc`	float \| None	✱
`ci_lower`	dict[str, float] \| None	✱
`ci_upper`	dict[str, float] \| None	✱
`conf_level`	float \| None	✱
`ci_method`	str \| None	✱

Properties: has_inference() → bool

Explore¶

Parsed formula structures.

ExploreFormulaSpec¶

Parsed explore formula.

Field	Type	Opt
`focal_var`	str
`contrast_type`	str \| None	✱
`contrast_degree`	int \| None	✱
`contrast_ref`	str \| None	✱
`contrast_level_ordering`	tuple[str] \| None	✱
`contrast_expr`	ContrastExpr \| None	✱
`conditions`	tuple[Condition, ...]
`focal_at_values`	tuple[float \| str, ...] \| None	✱
`focal_at_range`	int \| None	✱
`focal_at_quantile`	int \| None	✱

Properties: has_conditions() → bool, has_contrast() → bool, has_contrast_expr() → bool, has_rhs_contrasts() → bool

Contains: Condition

Condition¶

A conditioning specification in explore formula.

Field	Type	Opt
`var`	str
`at_values`	tuple \| None	✱
`at_range`	int \| None	✱
`at_quantile`	int \| None	✱
`contrast_expr`	ContrastExpr \| None	✱