superstats.transition#

Transition models for latent time-varying parameters.

class superstats.transition.AutoRegression(bounds=None, initial_prior=None, sigma=None, phi=None, delta=None)[source]#

Bases: StochasticTransition

AR(1) autoregressive transition.

Parameters:

boundstuple or None, optional, default: None: Lower and upper bounds for the latent state.
initial_priorPrior or None, optional, default: None: Prior for the initial latent state.
sigmafloat or Prior or None, optional, default: None: Standard deviation of the noise.
phifloat or Prior or None, optional, default: None: Autoregressive coefficient.
deltafloat or Prior, optional, default: 0.0: Additive drift term.

Parameters:

bounds (Tuple[float, float] | None)
initial_prior (Prior | None)
sigma (float | Prior | None)
phi (float | Prior | None)
delta (float | Prior | None)

Notes

Implements an AR(1): x_t = phi * x_{t-1} + delta + sigma * eps_t.

sample(batch_size, num_steps)[source]#

Draw batch_size AR(1) 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 local_params,: hyper_params, and fixed_params

Parameters:

batch_size (int)
num_steps (int)

Return type:

Dict[str, Any]

sample_one_step(x, params)[source]#

Advance a single AR(1) step.

Parameters:

xfloat: Previous latent state.
paramsdict: Expected keys: sigma, phi, delta.

Returns:

x_nextfloat - the next latent state

Parameters:

x (float)
params (Dict[str, Any])

Return type:

float

class superstats.transition.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.GaussianProcess(kernel='rbf', kernel_params=None, bounds=None, initial_prior=None)[source]#

Bases: StochasticTransition

Gaussian process transition model.

Draws each trajectory as a GP sample with mean start (from initial_prior) and covariance from kernel, then squashes the result into bounds via a scaled sigmoid.

Parameters:

kernel{“rbf”, “linear”} or Kernel, default “rbf”: Kernel used to build the covariance matrix. Either a registered name or a Kernel instance, including composites built via +/* (e.g. RBFKernel(name=”trend”) + RBFKernel(name=”local”)).
kernel_paramsdict, optional: Maps kernel hyperparameter names (see kernel.hyperparam_names, e.g. “length_scale”, “amplitude” for the default RBF kernel) to a Prior (sampled per-batch) or a fixed float. Any name not given here falls back to DEFAULT_HYPER_PRIORS, same as RandomWalk’s sigma/delta. Combining two kernels of the same type requires an explicit name= on each (see Kernel), which prefixes their hyperparameter names accordingly.
boundstuple or None, optional, default: None: Lower and upper bounds for the latent state.
initial_priorPrior or None, optional, default: None: Prior for the initial latent state.

Parameters:

kernel (Literal['rbf', 'linear', 'periodic'] | ~superstats.transition.stochastic.kernel.kernel.Kernel)
kernel_params (Dict[str, Prior | float | int | None] | None)
bounds (Sequence[float] | None)
initial_prior (Prior | None)

Notes

The sample method returns a dict with keys local_params, hyper_params and fixed_params, matching RandomWalk.

sample(batch_size, num_steps)[source]#

Draw batch_size Gaussian process 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 local_params,: hyper_params, and fixed_params

Parameters:

batch_size (int)
num_steps (int)

Return type:

Dict[str, Any]

class superstats.transition.Jump(bounds=None, initial_prior=None, p_jump=1.0, proposal_prior=None)[source]#

Bases: StochasticTransition

Simple jump process: stay or jump to a proposal draw.

Parameters:

boundstuple or None, optional, default: None: Lower and upper bounds for the latent state.
initial_priorPrior or None, optional, default: None: Prior for the initial latent state.
p_jumpfloat or Prior, optional, default: 1.0: Probability of jumping at each step (or a Prior to infer per-batch).
proposal_priorPrior or None, optional, default: None: Prior from which to draw proposal values when a jump occurs. Falls back to a standard normal Prior if not provided.

Parameters:

bounds (Tuple[float, float] | None)
initial_prior (Prior | None)
p_jump (float | Prior)
proposal_prior (Prior | None)

Notes

At each step the process either stays at the previous value or jumps to an independent proposal sampled from proposal_prior.

sample(batch_size, num_steps)[source]#

Draw batch_size jump-process 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 local_params,: hyper_params, and fixed_params

Parameters:

batch_size (int)
num_steps (int)

Return type:

Dict[str, Any]

sample_one_step(x, params)[source]#

Take one step of the jump process.

Parameters:

xfloat: Previous latent state.
paramsdict: Expected key: p_jump.

Returns:

x_nextfloat - the next latent state

Parameters:

x (float)
params (Dict[str, Any])

Return type:

float

class superstats.transition.LevyFlight(bounds=None, initial_prior=None, sigma=None, delta=None, alpha=None, beta=None)[source]#

Bases: StochasticTransition

Lévy-flight transition with alpha-stable noise and optional drift.

Like a random walk, but the Gaussian increments are replaced with alpha-stable increments, introducing a stability index alpha that controls tail heaviness. alpha=2 recovers Gaussian-like behavior; smaller alpha produces heavy-tailed jumps.

Parameters:

boundstuple or None, optional, default: None: Lower and upper bounds for the latent state.
initial_priorPrior or None, optional, default: None: Prior for the initial latent state.
sigmafloat or Prior or None, optional, default: None: Scale of the alpha-stable increments.
deltafloat or Prior or None, optional, default: None: Additive drift term.
alphafloat or Prior or None, optional, default: None: Stability index in (0, 2] controlling tail heaviness.
betafloat or Prior or None, optional, default: None: Skewness in [-1, 1]. Defaults to 0 (symmetric) if left unset.

Parameters:

bounds (Sequence[float, float] | None)
initial_prior (Prior | None)
sigma (float | Prior | None)
delta (float | Prior | None)
alpha (float | Prior | None)
beta (float | Prior | None)

Notes

The sample method returns a dict with keys local_params, hyper_params and fixed_params. Use sample_one_step to advance a single time-step given numeric params.

sample(batch_size, num_steps)[source]#

Draw batch_size Lévy-flight 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 local_params,: hyper_params, and fixed_params

Parameters:

batch_size (int)
num_steps (int)

Return type:

Dict[str, Any]

sample_one_step(x, params)[source]#

Advance a single step of the Lévy flight.

Parameters:

xfloat: Previous latent state.
paramsdict: Expected keys: sigma, delta, alpha, beta.

Returns:

x_nextfloat - the next latent state

Parameters:

x (float)
params (Dict[str, Any])

Return type:

float

class superstats.transition.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.Mixture(transitions, mixture_weights=None, bounds=None, initial_prior=None, names=None)[source]#

Bases: StochasticTransition

Mixture over multiple transitions, switching regimes at each step.

Parameters:

transitionssequence of Transition: The component transitions to mix between. Must contain at least two. Each transition must not define its own bounds or initial_prior (these are shared with the mixture instead); a Jump component must use p_jump=1 since mixture weights already define the jump probability.
mixture_weightsPrior or tuple of float or None, optional, default: None: Fixed simplex weights, a dirichlet Prior to infer them per batch, or None for uniform weights over the components.
boundstuple or None, optional, default: None: Lower and upper bounds for the latent state, shared across all component transitions.
initial_priorPrior or None, optional, default: None: Prior for the initial latent state, shared across all component transitions. Required at sample time.
namessequence of str or None, optional, default: None: Names for each component, used to prefix hyperparameter keys. Defaults to each component’s transition_name.

Raises:

ValueError: If fewer than two transitions are given, if any transition defines its own bounds or initial_prior, if a Jump component defines p_jump, if names doesn’t match the number of transitions, or if mixture_weights is a list/tuple with the wrong length or negative values.
TypeError: If mixture_weights is a scalar, or not one of tuple/list/Prior/None.

Parameters:

transitions (Sequence[StochasticTransition])
mixture_weights (Prior | Tuple[float, ...] | None)
bounds (Sequence[float] | None)
initial_prior (Prior | None)
names (Sequence[str] | None)

sample(batch_size, num_steps)[source]#

Draw batch_size mixture 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 local_params, regimes,: hyper_params, and fixed_params

Raises:

ValueError: If initial_prior was not specified in Mixture(…).

Parameters:

batch_size (int)
num_steps (int)

Return type:

Dict[str, Any]

class superstats.transition.OrnsteinUhlenbeck(bounds=None, initial_prior=None, sigma=None, mu=None, theta=None)[source]#

Bases: StochasticTransition

Ornstein-Uhlenbeck mean-reverting transition.

Parameters:

boundstuple or None, optional, default: None: Lower and upper bounds for the latent state.
initial_priorPrior or None, optional, default: None: Prior for the initial latent state.
sigmafloat or Prior or None, optional, default: None: Diffusion scale.
mufloat or Prior or None, optional, default: None: Long-run mean to revert towards.
thetafloat or Prior or None, optional, default: None: Mean-reversion speed.

Parameters:

bounds (Tuple[float, float] | None)
initial_prior (Prior | None)
sigma (float | Prior | None)
mu (float | Prior | None)
theta (float | Prior | None)

Notes

Implements an OU process: x_t = x_{t-1} + theta * (mu - x_{t-1}) + sigma * eps_t.

sample(batch_size, num_steps)[source]#

Draw batch_size Ornstein-Uhlenbeck 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 local_params,: hyper_params, and fixed_params

Parameters:

batch_size (int)
num_steps (int)

Return type:

Dict[str, Any]

sample_one_step(x, params)[source]#

Advance a single OU step.

Parameters:

xfloat: Previous latent state.
paramsdict: Expected keys: mu, theta, sigma.

Returns:

x_nextfloat - the next latent state

Parameters:

x (float)
params (Dict[str, Any])

Return type:

float

class superstats.transition.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

class superstats.transition.RandomWalk(bounds=None, initial_prior=None, sigma=None, delta=None)[source]#

Bases: StochasticTransition

Random walk transition with Gaussian noise and optional drift.

Parameters:

boundstuple or None, optional, default: None: Lower and upper bounds for the latent state.
initial_priorPrior or None, optional, default: None: Prior for the initial latent state.
sigmafloat or Prior or None, optional, default: None: Standard deviation of the Gaussian increments.
deltafloat or Prior, optional, default: 0.0: Additive drift term.

Parameters:

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

Notes

The sample method returns a dict with keys local_params, hyper_params and fixed_params. Use sample_one_step to advance a single time-step given numeric params.

sample(batch_size, num_steps)[source]#

Draw batch_size random-walk 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 local_params,: hyper_params, and fixed_params

Parameters:

batch_size (int)
num_steps (int)

Return type:

Dict[str, Any]

sample_one_step(x, params)[source]#

Advance a single step of the random walk.

Parameters:

xfloat: Previous latent state.
paramsdict: Expected keys: sigma, delta.

Returns:

x_nextfloat - the next latent state

Parameters:

x (float)
params (Dict[str, Any])

Return type:

float

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

Bases: ABC

Base class for stochastic 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 initial latent states. 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 hyperparameter names to either a Prior (to be sampled per-batch) or a scalar fixed value. Populated by subclasses.
transition_namestr: Short model name, such as "rw" or "ar1".

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 at least keys local_params: (ndarray of shape (batch_size, steps)), hyper_params, and fixed_params describing sampled and fixed hyperparameters

Parameters:

batch_size (int)
num_steps (int)

Return type:

Dict[str, Any]

Modules

`deterministic`	Deterministic transition models for latent time-varying parameters.
`stochastic`	Transition models for latent time-varying parameters.