API Reference

birm.data

Ragged multi-metric training data on a shared daily grid.

MetricData dataclass

Observations for one response metric on the shared grid.

Parameters:

Name	Type	Description	Default
values	ndarray	Observed values \(Y^{(j)}\), length n_j (NaNs dropped).	required
idx	ndarray	Integer positions into the shared grid, length n_j, strictly increasing.	required
exog	dict[str, ndarray]	Exogenous columns \(X^{(j)}\), each length n_j and aligned 1:1 with values.	dict()

Panel dataclass

Shared daily grid plus per-metric ragged observations.

Parameters:

Name	Type	Description	Default
grid	DatetimeIndex	Contiguous daily grid spanning min to max over all sources.	required
load	ndarray	Training load \(w_t\), dense length T (an unlisted day is 0.0 = rest).	required
metrics	dict[str, MetricData]	Response metrics, each with its own values, grid positions, and exog.	required
scaling	dict[str, tuple[float, float]]	(center, scale) per standardized series, for back-transform. Empty until standardize is called.	dict()

T property

Number of days on the shared grid.

Returns:

Type	Description
int	Length of grid.

densest()

Metric with the most observations (auto-pinned to \(\gamma \equiv 1\)).

Returns:

Type	Description
str	Name of the metric with the largest number of observed days.

from_long(df, date, metric, value, load, exog=None) classmethod

Build a Panel from one tidy long table.

Each row carries a (date, metric, value) reading; the metric's exog columns ride on the same rows. Missingness is implied by absent (date, metric) rows.

Parameters:

Name	Type	Description	Default
df	DataFrame	Long-form table with ISO-date, metric-label, and value columns.	required
date	str	Name of the ISO-date column.	required
metric	str	Name of the metric-label column.	required
value	str	Name of the value column.	required
load	str	Metric label that denotes the training load \(w_t\).	required
exog	dict[str, list[str]]	Per-metric exogenous column names, read off that metric's rows.	None

Returns:

Type	Description
Panel	Validated panel.

from_sheets(sheets, date, load, exog=None) classmethod

Build a Panel from one sheet per metric.

Each sheet has a date column, a value column named after the metric, and that metric's own exog columns; blank cells mark unobserved days.

Parameters:

Name	Type	Description	Default
sheets	dict[str, DataFrame]	Mapping of metric name to its wide sheet.	required
date	str	Name of the ISO-date column present in every sheet.	required
load	str	Sheet name that denotes the training load \(w_t\).	required
exog	dict[str, list[str]]	Per-metric exogenous columns, found within each metric's own sheet.	None

Returns:

Type	Description
Panel	Validated panel.

standardize()

Center/scale each response and its exog, rescale load to average-day units.

Each response metric's values and exog columns are z-scored (center/scale stored in scaling for back-transform); load is rescaled by its own mean so gains stay \(O(1)\).

Returns:

Type	Description
Panel	A new standardized panel.

birm.model

The impulse-response model specification.

IRModel dataclass

Declarative spec of the shared-stock multivariate impulse-response model.

Selects one impulse-response core \(R_t\) and attaches one observation layer per Metric. Call fit with a Panel to sample.

Parameters:

Name	Type	Description	Default
load	Load	The training-load driver \(w_t\).	required
core	str	Impulse-response core; one of banister (Banister 1975), busso (fatigue gain grows with recent load), ceddia (diminishing-returns fitness gain and decay times that grow with session load, Ceddia 2026), or fitness-only (no fatigue).	required
metrics	tuple[Metric, ...]	Response metrics sharing the single latent stock.	required
priors	dict[str, Prior]	Optional overrides for named model parameters (e.g. k_D, rho_G, tau_v).	dict()
parameterization	str	Latent-stock prior geometry; one of informed or direct. informed (default) samples the identifiable reparameterized margins (\(\theta, \lambda_F, \lambda_G, \lambda_\rho\)) so the gain ratio and timescale ordering \(\tau_v < \tau_G < \tau_F\) (at every load, for Ceddia) and \(k_G > k_F\) hold with certainty (off the \(\tau_F = \tau_G\) ridge). direct instead samples \(k_F\), \(k_G\), \(\tau_F\), \(\tau_G\) (and Busso \(\tau_v\), Ceddia \(\rho_F, \rho_G\)) independently from weakly-informative HalfNormal/LogNormal priors over wide ranges, with no ordering or gain-ratio constraint -- the ill-conditioned baseline the reparameterization is designed to fix.	'informed'

build_model(panel)

Assemble the PyMC model binding this spec to panel.

Validates the spec against the panel, builds the shared latent stock \(R_t\) from the selected cores, then attaches one observation layer and obs_<name> likelihood per metric.

Parameters:

Name	Type	Description	Default
panel	Panel	Observations to bind, with metric names matching this spec's Metric names.	required

Returns:

Type	Description
Model	The assembled model, ready to sample.

fit(panel, sampler=None)

Validate this spec against panel, build the model, and sample the posterior.

Checks that every spec metric exists in the panel with resolvable exog columns, warns on unused panel metrics, assembles the PyMC model via build_model, then samples.

Parameters:

Name	Type	Description	Default
panel	Panel	Observations to fit, with metric names matching this spec's Metric names.	required
sampler	dict[str, Any]	Overrides merged over the R&D defaults (_SAMPLER_DEFAULTS: nutpie NUTS, draws=1000, tune=2500, chains=4, target_accept=0.99), passed through to pymc.sample.	None

Returns:

Type	Description
Any	An arviz.InferenceData with the posterior and per-metric obs_<name> likelihoods.

Raises:

Type	Description
ValueError	If a spec metric is missing from the panel, or references an exog column that metric does not carry.

Load dataclass

The training-load driver \(w_t\) of the latent stock shared across metrics.

Parameters:

Name	Type	Description	Default
name	str	Series name identifying the load in the Panel.	required

Metric dataclass

One response series \(Y^{(j)}\) as a noisy readout of the shared stock.

Parameters:

Name	Type	Description	Default
name	str	Metric name; must match a key in Panel.metrics.	required
link	str	Link function \(l^{(j)}\); one of identity, log, logit.	'identity'
exog	tuple[str, ...]	Exogenous predictor columns \(X^{(j)}\) (-> \beta), read off this metric's rows.	()
ar1	bool	Whether to include the orthogonalized lag-1 process \(u^{(j)}\).	False
intercept	bool	Whether to include the intercept \(\alpha^{(j)}\).	True
gamma	float	Fixed scale \(\gamma^{(j)}\). If None the densest metric is auto-pinned to \(\gamma \equiv 1\) and the rest are estimated.	None
offset	bool	Whether to read this metric's stock at a shifted time \(r_{t-d}\) with an integer lag \(d\) (support \(\{0,\dots,14\}\) if causal, else \([-14,14]\)) under a 0-centered discrete Gaussian prior, marginalized out via logsumexp. The shift applies to the stock term only; any ar1 residual and exogenous terms stay contemporaneous.	False

Prior dataclass

A named prior distribution with its keyword parameters.

Parameters:

Name	Type	Description	Default
dist	str	PyMC distribution name (e.g. "Normal", "HalfNormal").	required
params	dict[str, Any]	Keyword arguments passed through to the distribution.	dict()