specs - bossanova

Configuration specifications for model and simulation.

Attributes:

Name	Type	Description
`FAMILIES`	`tuple[str, ...]`	Supported distribution families.
`FAMILY_DEFAULT_LINKS`	`dict[str, str]`	Default link functions per family.
`LINKS`	`tuple[str, ...]`	Supported link functions.
`METHODS`	`tuple[str, ...]`	Supported estimation methods.

Classes:

Name	Description
`Distribution`	Protocol for distribution objects that can generate random samples.
`ModelSpec`	Immutable model configuration.
`SimulationSpec`	Specification for data generation in simulation-first workflows.
`VaryingSpec`	Specification for random effect grouping in simulation.

Attributes¶

FAMILIES¶

FAMILIES: tuple[str, ...] = ('gaussian', 'binomial', 'poisson', 'gamma', 'tdist')

Supported distribution families.

FAMILY_DEFAULT_LINKS¶

FAMILY_DEFAULT_LINKS: dict[str, str] = {'gaussian': 'identity', 'binomial': 'logit', 'poisson': 'log', 'gamma': 'inverse', 'tdist': 'identity'}

Default link functions per family.

LINKS¶

LINKS: tuple[str, ...] = ('identity', 'log', 'logit', 'probit', 'inverse', 'cloglog')

Supported link functions.

METHODS¶

METHODS: tuple[str, ...] = ('ols', 'ml', 'reml')

Supported estimation methods.

Classes¶

Distribution¶

Bases: Protocol

Protocol for distribution objects that can generate random samples.

Any class implementing this protocol can be used to specify variable distributions in SimulationSpec. The protocol requires a single method that generates samples given a sample size and random number generator.

Examples:

>>> class Normal:
...     def __init__(self, mean: float = 0.0, sd: float = 1.0):
...         self.mean = mean
...         self.sd = sd
...     def sample(self, n: int, rng: np.random.Generator) -> np.ndarray:
...         return rng.normal(self.mean, self.sd, size=n)
...
>>> dist = Normal(0, 1)
>>> isinstance(dist, Distribution)
True

Functions:

Name	Description
`sample`	Generate n random samples.

Functions¶

sample¶

sample(n: int, rng: Any) -> Any

Generate n random samples.

Parameters:

Name	Type	Description	Default
`n`	`int`	Number of samples to generate.	required
`rng`	`Any`	Random number generator (numpy Generator or RNG wrapper).	required

Returns:

Type	Description
`Any`	Array of n samples from this distribution.

ModelSpec¶

Immutable model configuration.

Stores all model settings parsed from the formula and user-provided options. This is the core specification that drives fitting, inference, and prediction across all model types.

Created by: build_model_spec_from_formula() Consumed by: build_bundle_from_data(), fit_model(), dispatch_infer() Augmented by: Never

Attributes:

Name	Type	Description
`formula`	`str`	The model formula string (e.g., “y ~ x + treatment”).
`family`	`str`	Distribution family for the response variable.
`link`	`str`	Link function connecting linear predictor to response.
`has_random_effects`	`bool`	Whether the model includes random effects.
`method`	`str`	Estimation method (“ols”, “ml”, or “reml”).
`response_var`	`str`	The response variable name parsed from formula.
`fixed_terms`	`tuple[str, ...]`	Tuple of fixed effect term names.
`random_terms`	`tuple[str, ...]`	Tuple of random effect term specifications.

Examples:

>>> spec = ModelSpec(
...     formula="y ~ x",
...     response_var="y",
...     fixed_terms=("Intercept", "x"),
... )
>>> spec.family
'gaussian'

Attributes¶

family¶

family: str = field(default='gaussian', validator=(validators.in_(FAMILIES)))

fixed_terms¶

fixed_terms: tuple[str, ...] = field(converter=to_tuple, validator=is_tuple_of_str)

formula¶

formula: str = field(validator=(validators.instance_of(str)))

has_random_effects¶

has_random_effects: bool = field(default=False, validator=(validators.instance_of(bool)))

link¶

link: str = field(default=(Factory(lambda self: FAMILY_DEFAULT_LINKS.get(self.family, 'identity'), takes_self=True)), validator=(validators.in_(LINKS)))

method¶

method: str = field(default='ols', validator=(validators.in_(METHODS)))

random_terms¶

random_terms: tuple[str, ...] = field(factory=tuple, converter=to_tuple, validator=is_tuple_of_str)

response_var¶

response_var: str = field(validator=(validators.instance_of(str)))

SimulationSpec¶

Specification for data generation in simulation-first workflows.

Defines all parameters needed to generate a synthetic dataset from a model formula: sample size, variable distributions, true coefficients, residual variance, and random effect structure.

Created by: model.simulate(), simulation-first workflows Consumed by: generate_data_from_spec(), run_power_analysis() Augmented by: Never

Attributes:

Name	Type	Description
`n`	`int`	Total number of observations to generate. Must be > 0.
`distributions`	`dict[str, Distribution ]`	Dictionary mapping variable names to Distribution objects.
`coef`	`dict[str, float]`	Dictionary mapping coefficient names to their true values.
`sigma`	`float`	Residual standard deviation for Gaussian models. Defaults to 1.0.
`re_spec`	`dict[str, VaryingSpec ]`	Dictionary mapping grouping variable names to VaryingSpec objects.
`seed`	`int \| None`	Random seed for reproducibility.

Examples:

>>> spec = SimulationSpec(
...     n=100,
...     coef={"Intercept": 0, "x": 0.5},
...     sigma=1.0,
...     seed=42,
... )

Attributes¶

coef¶

coef: dict[str, float] = field(factory=dict)

distributions¶

distributions: dict[str, Distribution] = field(factory=dict)

n¶

n: int = field(validator=(validators.gt(0)))

re_spec¶

re_spec: dict[str, VaryingSpec] = field(factory=dict)

seed¶

seed: int | None = field(default=None, validator=is_optional_int)

sigma¶

sigma: float = field(default=1.0, validator=validate_sigma)

VaryingSpec¶

Specification for random effect grouping in simulation.

Defines how to generate random effect structure for a grouping variable. Supports random intercepts, random slopes, and correlations between them.

Created by: varying() Consumed by: generate_data_from_spec(), run_power_analysis() Augmented by: Never

Attributes:

Name	Type	Description
`n`	`int`	Number of groups (e.g., 50 subjects). Must be > 0.
`sd`	`float`	Standard deviation for random intercept. Defaults to 1.0.
`slope_sds`	`dict[str, float]`	Dictionary mapping term names to their random slope SDs.
`correlations`	`dict[tuple[str, str], float]`	Dictionary mapping pairs of terms to their correlations.
`n_per`	`int \| None`	Number of units per group for nested effects.

Examples:

>>> spec = VaryingSpec(n=50, sd=0.3)
>>> spec = VaryingSpec(
...     n=50,
...     sd=0.3,
...     slope_sds={"time": 0.1},
...     correlations={("Intercept", "time"): 0.2},
... )

Attributes¶

correlations¶

correlations: dict[tuple[str, str], float] = field(factory=dict, validator=validate_correlations)

n¶

n: int = field(validator=(validators.gt(0)))

n_per¶

n_per: int | None = field(default=None)

sd¶

sd: float = field(default=1.0, validator=(validators.ge(0.0)))

slope_sds¶

slope_sds: dict[str, float] = field(factory=dict, validator=validate_slope_sds)