superstats.transition.deterministic#

Deterministic transition models for latent time-varying parameters.

class superstats.transition.deterministic.DeterministicTransition(bounds=None, initial_prior=None)[source]#

Bases: ABC

Base class for deterministic transition models.

Subclasses implement deterministic dynamics for a single scalar latent parameter. Subclasses must implement sample to generate complete trajectories from resolved parameter values.

Parameters:

boundstuple or np.ndarray or None, optional, default: None: Lower and upper bounds for the latent state, applied via scaled_sigmoid. Falls back to DEFAULT_BOUNDS if not provided.
initial_priorPrior or None, optional, default: None: Prior used to draw the initial latent state. Falls back to DEFAULT_INITIAL_PRIOR if not provided.

Attributes:

boundsnp.ndarray: Resolved lower and upper bounds for the latent state.
initial_priorPrior: Resolved prior used to draw initial latent states.
hyper_specsdict: Mapping from parameter names to either a Prior (sampled per batch), a scalar fixed value, or None to use a deterministic default. Subclasses populate this mapping.
transition_namestr: Short model name, such as "linear".

Parameters:

bounds (Sequence[float, float] | None)
initial_prior (Prior | None)

dtype#: alias of float32

abstract sample(batch_size, num_steps)[source]#

Generate batch_size latent trajectories of length num_steps.

Parameters:

batch_sizeint: Number of independent trajectories to draw.
num_stepsint: Number of time steps per trajectory (including initial state).

Returns:

resultdict - dictionary with keys deterministic_params,: hyper_params, and fixed_params. deterministic_params is an ndarray of shape (batch_size, steps).

Parameters:

batch_size (int)
num_steps (int)

Return type:

Dict[str, Any]

sample_from_parameters(params, batch_size, num_steps)[source]#

Generate trajectories from already-resolved transition parameters.

Subclasses used with posterior predictive resimulation should override this method. params contains the subclass’s own hyperparameter names, independent of any name used by a JointPrior.

Parameters:

params (Dict[str, ndarray | float])
batch_size (int)
num_steps (int)

Return type:

ndarray

class superstats.transition.deterministic.Linear(bounds=None, intercept=None, beta=None, normalize_steps=True)[source]#

Bases: DeterministicTransition

Deterministic linear transition with an intercept and slope.

Parameters:

boundssequence of two floats or None, optional, default: None: Lower and upper bounds for the deterministic trajectory. Tuples and lists are accepted.
interceptfloat, Prior, or None, optional, default: None: Starting value of the trajectory. A Prior samples one intercept per trajectory; None uses the deterministic default prior.
betafloat, Prior, or None, optional, default: None: Change across the trajectory when normalize_steps=True. A Prior samples one slope per trajectory; None uses the deterministic default prior.
normalize_stepsbool, optional, default: True: If True, use a time axis from 0 to 1. If False, use integer step indices, so the slope is applied at every step.

Parameters:

bounds (Sequence[float, float] | None)
intercept (float | Prior | None)
beta (float | Prior | None)
normalize_steps (bool)

Notes

The sample method returns a dict with keys deterministic_params, hyper_params, and fixed_params. Trajectory values are clipped to bounds.

sample(batch_size, num_steps)[source]#

Draw batch_size linear trajectories of length num_steps.

Parameters:

batch_sizeint: Number of independent trajectories to draw.
num_stepsint: Number of time steps per trajectory.

Returns:

resultdict - dictionary with keys deterministic_params,: hyper_params, and fixed_params

Parameters:

batch_size (int)
num_steps (int)

Return type:

Dict[str, Any]

sample_from_parameters(params, batch_size, num_steps)[source]#

Generate trajectories from already-resolved transition parameters.

Subclasses used with posterior predictive resimulation should override this method. params contains the subclass’s own hyperparameter names, independent of any name used by a JointPrior.

Parameters:

params (Dict[str, ndarray | float])
batch_size (int)
num_steps (int)

Return type:

ndarray

class superstats.transition.deterministic.Polynomial(bounds=None, intercept=None, betas=None, degree=2, normalize_steps=True)[source]#

Bases: DeterministicTransition

Deterministic polynomial transition with an intercept and beta weights.

Parameters:

boundssequence of two floats or None, optional, default: None: Lower and upper bounds for the deterministic trajectory. Tuples and lists are accepted.
interceptfloat, Prior, or None, optional, default: None: Constant term of the polynomial. A Prior samples one intercept per trajectory; None uses the deterministic default prior.
betasfloat, Prior, sequence of float/Prior/None, or None: Polynomial coefficients for the non-constant terms. If a single scalar or Prior is provided, the same specification is used for every beta. If a sequence is provided, it must have length degree and each element is used for the corresponding beta weight.
degreeint, optional, default: 2: Number of polynomial terms beyond the intercept. For example, degree=1 reproduces a linear model, while the default degree=2 gives a quadratic model.
normalize_stepsbool, optional, default: True: If True, use a time axis from 0 to 1. If False, use integer step indices, so higher-order terms are evaluated on raw step numbers.

Parameters:

bounds (Sequence[float, float] | None)
intercept (float | Prior | None)
betas (float | Prior | Sequence[float | Prior | None] | None)
degree (int)
normalize_steps (bool)

Notes

The sample method returns a dict with keys deterministic_params, hyper_params, and fixed_params. Trajectory values are clipped to bounds.

sample(batch_size, num_steps)[source]#

Draw batch_size polynomial trajectories of length num_steps.

Parameters:

batch_size (int)
num_steps (int)

Return type:

Dict[str, Any]

sample_from_parameters(params, batch_size, num_steps)[source]#

Generate trajectories from resolved intercept and beta terms.

Parameters:

params (Dict[str, ndarray | float])
batch_size (int)
num_steps (int)

Return type:

ndarray

Modules

`deterministic_transition`	Base interface and shared helpers for deterministic transitions.
`linear`	Linear deterministic transition.
`polynomial`	Polynomial deterministic transition.