Parameters API Reference¶

Parameter classes for defining probabilistic model components in SciStanPy.

This module provides the core parameter classes that serve as building blocks for constructing probabilistic models in SciStanPy. These classes represent random variables with specific probability distributions and handle the complex task of translating between Python model specifications, PyTorch modules, and Stan probabilistic programming language code.

The parameter classes are designed to be composable, allowing complex hierarchical models to be built through simple parameter relationships while maintaining mathematical rigor and computational efficiency.

The following distributions are currently supported in SciStanPy:

Continuous Multivariate¶

Dirichlet
ExpDirichlet

Discrete Univariate¶

Binomial
Poisson

Discrete Multivariate¶

Multinomial
MultinomialLogit
MultinomialLogTheta

Is there a distribution you need that isn’t listed here? Please open an issue or submit a PR!

Base Classes¶

class scistanpy.model.components.parameters.ParameterMeta(name, bases, namespace, /, **kwargs)[source]¶

Bases: ABCMeta

Metaclass for automatic CDF transform class generation.

Parameters:

name (str) – Name of the class being created
bases (tuple) – Base classes for the new class
attrs (dict) – Class attributes dictionary

This metaclass automatically creates cumulative distribution function (CDF) and related transform classes for each Parameter subclass, enabling automatic generation of probabilistic transforms and survival functions.

The metaclass creates four transform classes for each parameter and assigns them to the following class variables:

Parameter.CDF, based on the CDF class and describing the cumulative distribution function for the parameter.

Parameter.SF, based on the SurvivalFunction class and describing the survival function (1 - CDF) for the parameter.

Parameter.LOG_CDF, based on the LogCDF class and describing the logarithmic cumulative distribution function for the parameter.

Parameter.LOG_SF, based on the LogSurvivalFunction class and describing the logarithmic survival function for the parameter.

class scistanpy.model.components.parameters.Parameter(**kwargs)[source]¶

Bases: AbstractModelComponent

Base class for all probabilistic parameters in SciStanPy models.

This class provides the foundational infrastructure for representing random variables with specific probability distributions. It handles the complex mapping between Python model specifications and Stan code generation while providing integration with SciPy and PyTorch ecosystems.

Parameters:

kwargs – Distribution parameters (mu, sigma, etc. depending on subclass)

Raises:

NotImplementedError – If required class attributes are missing (i.e., if subclass was incorrectly defined)
TypeError – If required distribution parameters are missing

Variables:

STAN_DIST – Stan distribution name for code generation
HAS_RAW_VARNAME – Whether parameter uses a raw/transformed parameterization
SCIPY_DIST – Corresponding SciPy distribution class
TORCH_DIST – Corresponding PyTorch distribution class
STAN_TO_SCIPY_NAMES – Parameter name mapping for SciPy interface
STAN_TO_TORCH_NAMES – Parameter name mapping for PyTorch interface
STAN_TO_SCIPY_TRANSFORMS – Parameter transformation functions converting between Stan and SciPy parametrizations
CDF – Automatically generated CDF class.
SF – Automatically generated SurvivalFunction class.
LOG_CDF – Automatically generated LogCDF class.
LOG_SF – Automatically generated LogSurvivalFunction class.

class CDF(

x: custom_types.CombinableParameterType,

shape: tuple[custom_types.Integer, ...] | custom_types.Integer = (),

**params: custom_types.CombinableParameterType,

)¶

Bases: CDF

Subclass of CDF describing the cumulative distribution function for the parameter.

PARAMETER¶: alias of Parameter

HAS_RAW_VARNAME: bool = False¶: Whether the parameter intrinsically uses a raw/transformed parameterization.

class LOG_CDF(

x: custom_types.CombinableParameterType,

shape: tuple[custom_types.Integer, ...] | custom_types.Integer = (),

**params: custom_types.CombinableParameterType,

)¶

Bases: LogCDF

Subclass of LogCDF describing the log cumulative distribution function for the parameter.

PARAMETER¶: alias of Parameter

class LOG_SF(

x: custom_types.CombinableParameterType,

shape: tuple[custom_types.Integer, ...] | custom_types.Integer = (),

**params: custom_types.CombinableParameterType,

)¶

Bases: LogSurvivalFunction

Subclass of LogSurvivalFunction describing the log survival function for the parameter.

PARAMETER¶: alias of Parameter

SCIPY_DIST: type[stats.rv_continuous] | type[stats.rv_discrete] | None = None¶: Corresponding SciPy distribution class (e.g., scipy.stats.norm).

class SF(

x: custom_types.CombinableParameterType,

shape: tuple[custom_types.Integer, ...] | custom_types.Integer = (),

**params: custom_types.CombinableParameterType,

)¶

Bases: SurvivalFunction

Subclass of SurvivalFunction describing the survival function for the parameter.

PARAMETER¶: alias of Parameter

STAN_DIST: str = ''¶: Name of the distribution in Stan code (e.g. “normal”, “binomial”).

STAN_TO_SCIPY_NAMES: dict[str, str] = {}¶: There can be differences in parameter names between Stan and SciPy. This dictionary maps between the two naming conventions.

STAN_TO_SCIPY_TRANSFORMS: dict[str, Callable[[npt.NDArray], npt.NDArray]] = {}¶: Some distributions are parametrized differently between Stan and SciPy. This dictionary provides transformation functions to convert parameters from Stan’s parametrization to SciPy’s parametrization.

STAN_TO_TORCH_NAMES: dict[str, str] = {}¶: There can be differences in parameter names between Stan and PyTorch. This dictionary maps between the two naming conventions.

TORCH_DIST: type[dist.distribution.Distribution] | type[custom_torch_dists.CustomDistribution] | None = None¶: Corresponding PyTorch distribution class (e.g., torch.distributions.Normal).

as_observable() → Parameter[source]¶

Mark parameter as observable (representing observed data).

Returns:: Self-reference for method chaining
Return type:: Parameter

Observable parameters represent known data rather than unknown variables to be inferred. This method:

Sets the observable flag to True

Removes PyTorch parameterization (observables aren’t optimized)

Enables generation of appropriate Stan code for data blocks

This method will typically not be needed, as SciStanPy automatically assigns parameters with no children in the depenency graph as observables.

Example:

>>> y_obs = Normal(mu=mu_param, sigma=sigma_param).as_observable()

ccdf(**params: custom_types.CombinableParameterType) → cdfs.SurvivalFunction[source]¶

Create complementary CDF (survival function) transform.

Parameters:: params (custom_types.CombinableParameterType) – Distribution parameters (if called as class method) and parameter value.
Returns:: Survival function transform object
Return type:: cdfs.SurvivalFunction

Creates survival function (1 - CDF) transforms for survival analysis.

Note

This is a convenience method for building an instance of the SurvivalFunction subclass associated with the parameter. It can be used as either a class method, in which case parameters must be explicitly provided, or an instance method (in which case instance parameter values will be used).

Example:

>>> # As class method
>>> sf = Normal.ccdf(mu=0.0, sigma=1.0, x=data)
>>> # As instance method
>>> normal_param = Normal(mu=0.0, sigma=1.0)
>>> sf = normal_param.ccdf(x=data)

cdf(**params: custom_types.CombinableParameterType) → cdfs.CDF[source]¶

Create cumulative distribution function transform.

Parameters:: params (custom_types.CombinableParameterType) – Distribution parameters (if called as class method) and parameter value.
Returns:: CDF transform object
Return type:: cdfs.CDF

Note

This is a convenience method for building an instance of the CDF subclass associated with the parameter. It can be used as either a class method, in which case parameters must be explicitly provided, or an instance method (in which case instance parameter values will be used).

Example:

>>> # As class method
>>> cdf = Normal.cdf(mu=0.0, sigma=1.0, x=data)
>>> # As instance method
>>> normal_param = Normal(mu=0.0, sigma=1.0)
>>> cdf = normal_param.cdf(x=data)

property generated_varname: str¶

Variable name for posterior predictive sampling.

Returns:: Variable name with “_ppc” suffix for generated quantities
Return type:: str
Raises:: ValueError – If called on non-observable parameters

Observable parameters generate posterior predictive samples in the generated quantities block of Stan code using this modified variable name.

get_generated_quantities(index_opts: tuple[str, ...]) → str[source]¶

Generate Stan code for posterior predictive sampling.

Parameters:: index_opts (tuple[str, ...]) – Indexing options for multi-dimensional parameters
Returns:: Stan code for generated quantities block
Return type:: str

This method creates Stan code for the generated quantities block, enabling posterior predictive sampling.

get_generated_quantity_declaration(force_basetype: bool = True) → str[source]¶

Generate Stan variable declaration for generated quantities.

Parameters:: force_basetype (bool) – Whether to force base type declaration. For example, if True and the parameter is defined as a multidimensional float, the returned stan dtype will not be array[...Ndim - 1...] vector, but array[...NDim...] float. Defaults to True, as this is the format expected by generated quantities blocks.
Returns:: Stan variable declaration for posterior predictive sampling
Return type:: str

Creates appropriate variable declarations for the generated quantities block, enabling posterior predictive sampling with correct variable types and constraints.

get_raw_stan_parameter_declaration(force_basetype: bool = False) → str[source]¶

Generate Stan parameter declaration for raw (untransformed) variables.

Parameters:: force_basetype (bool) – Whether to force base type declaration. See get_generated_quantity_declaration for more information. Defaults to False.
Returns:: Stan parameter declaration for raw variables
Return type:: str

For parameters using non-centered or other reparameterizations, this generates declarations for the underlying raw variables that are transformed to create the actual parameters. The get_transformation_assignment function will return Stan code that converts this raw parameter to the desired parameter. For parameters that do not use a raw variable, this returns an empty string.

get_right_side( index_opts: tuple[str, ...] | None, start_dims: dict[str, custom_types.Integer] | None = None, end_dims: dict[str, custom_types.Integer] | None = None, offset_adjustment: int = 0, dist_suffix: str = '', ) → str[source]¶

Generate right-hand side of Stan statements.

Parameters:

index_opts (Optional[tuple[str, ...]]) – Options for indexing variable names (e.g., (‘i’, ‘j’, ‘k’, …)). If None, no indexing is applied.
start_dims (Optional[dict[str, custom_types.Integer]]) – First indexable dimension of parent model components. Defaults to None, meaning the first dimension is the first indexable dimension for all parents.
end_dims (Optional[dict[str, custom_types.Integer]]) – Last indexable dimension of parent model components. Defaults to None, meaning the last dimension is the last indexable dimension for all parents.
offset_adjustment (int) – Index offset adjustment. For example, if index_opts are (‘a’, ‘b’, ‘c’) and offset_adjustment is 1, the effective allowed indices will be (‘b’, ‘c’). This argument is critical for aligning dimensions between parent and child model components that have different numbers of dimensions (i.e., as a result of broadcasting). Defaults to 0.
dist_suffix (str) – Distribution function suffix (e.g., “_rng”). Defaults to “”.

Returns:

Stan distribution call string

Return type:

str

get_rng(seed: custom_types.Integer | None = None) → np.random.Generator[source]¶

Get random number generator for sampling operations.

Parameters:: seed (Optional[custom_types.Integer]) – Optional seed for reproducible generation. Defaults to None.
Returns:: NumPy random number generator
Return type:: np.random.Generator

Returns the global scistanpy.RNG if no seed is provided, otherwise creates a new generator with the specified seed.

get_target_incrementation(index_opts: tuple[str, ...]) → str[source]¶

Generate Stan target increment statement for log-probability.

Parameters:: index_opts (tuple[str, ...]) – Potential names for indexing variables (e.g., (‘i’, ‘j’, ‘k’, …)).
Returns:: Stan target increment statement (e.g., “y ~ normal(mu, sigma)” or target += normal_lpdf(y | mu, sigma)”).
Return type:: str

This method generates the Stan code that adds this parameter’s log-probability (e.g., “target += normal_lpdf(y | mu, sigma)” or “y ~ normal(mu, sigma)”) contribution to the target density.

get_torch_logprob(observed: torch.Tensor | None = None) → torch.Tensor[source]¶

Compute log-probability using PyTorch backend for gradient computation.

Parameters:

observed (Optional[torch.Tensor]) – Observed values for observable parameters. Defaults to None. Required if parameter is observable. Must be None if parameter is latent.

Returns:

Log-probability tensor with gradient tracking

Return type:

torch.Tensor

Raises:

ValueError – If observable parameter lacks observed values
ValueError – If latent parameter has observed values

This method computes log-probabilities using PyTorch distributions, enabling gradient-based optimization.

get_transformed_data_declaration() → str[source]¶

Generate the transformed data block of Stan code.

Returns:: Stan code for transformed data declarations (empty by default)
Return type:: str

Most parameters don’t require transformed data declarations. This method can be overridden by subclasses that need to declare transformed data variables.

init_pytorch( init_val: npt.NDArray | torch.Tensor | None = None, seed: custom_types.Integer | None = None, ) → None[source]¶

Initialize PyTorch parameter on unconstrained space for gradient-based optimization.

Parameters:

init_val (Optional[Union[npt.NDArray, torch.Tensor]]) – Initial parameter values on unconstrained space. Uniform between -1 and 1 if None. Defaults to None.
seed (Optional[custom_types.Integer]) – Random seed for initialization. Defaults to None.

Raises:

ValueError – If called on observable parameters
ValueError – If init_val shape doesn’t match parameter shape

This method sets up the parameter for PyTorch-based optimization by creating a trainable nn.Parameter. The initialization strategy uses uniform random values in [-1, 1] if no explicit values are provided.

Important

Initialization values are considered to be in unconstrained space, whether provided or otherwise. An appropriate transform is applied depending on the bounds of the distribution represented by the class to take it to a constrained space (e.g., exponentiation for positive distributions).

Note

Observable parameters cannot be initialized as they represent fixed data rather than learnable parameters.

property is_hyperparameter: bool¶

Check if parameter is a hyperparameter (has only constant parents).

Returns:: True if all parent parameters are constants
Return type:: bool

Hyperparameters are top-level parameters in the model hierarchy that depend only on fixed constants rather than other random variables.

log_ccdf(**params: custom_types.CombinableParameterType) → cdfs.LogSurvivalFunction[source]¶

Create logarithmic survival function transform.

Parameters:: params (custom_types.CombinableParameterType) – Distribution parameters (if called as class method) and parameter value.
Returns:: Log-survival function transform object
Return type:: cdfs.LogSurvivalFunction

Creates log-survival function transforms for numerical stability in extreme tail probability computations.

Note

This is a convenience method for building an instance of the LogSurvivalFunction subclass associated with the parameter. It can be used as either a class method, in which case parameters must be explicitly provided, or an instance method (in which case instance parameter values will be used).

log_cdf(**params: custom_types.CombinableParameterType) → cdfs.LogCDF[source]¶

Create logarithmic CDF transform.

Parameters:: params (custom_types.CombinableParameterType) – Distribution parameters (if called as class method) and parameter value.
Returns:: Log-CDF transform object
Return type:: cdfs.LogCDF

Creates log-CDF transforms for numerical stability in extreme tail probability computations.

Note

This is a convenience method for building an instance of the LogCDF subclass associated with the parameter. It can be used as either a class method, in which case parameters must be explicitly provided, or an instance method (in which case instance parameter values will be used).

property observable: bool¶

Check if parameter represents observed data.

Returns:: True if parameter is observable
Return type:: bool

Parameters are observable if explicitly marked as such or if they have no children (representing terminal nodes in the model graph).

property raw_varname: str¶

Get raw variable name for reparameterized parameters.

Returns:: Raw variable name with “_raw” suffix, or empty string if there is no raw variable name associated with the parameter.
Return type:: str

Some parameters use reparameterization techniques (like non-centered parameterization) that require separate raw variables in Stan code. This property returns the appropriate raw variable name when needed.

property torch_dist_instance: custom_types.SciStanPyDistribution¶

Get PyTorch distribution instance with current parameter values.

Returns:: Configured PyTorch distribution object
Return type:: custom_types.SciStanPyDistribution

Creates a PyTorch distribution instance using the current (constrained) parameter values, enabling gradient-based computations and optimization.

property torch_parametrization: torch.Tensor¶

Get PyTorch parameter tensor with appropriate constraints applied.

Returns:: Constrained parameter tensor for optimization
Return type:: torch.Tensor
Raises:: ValueError – If called on observable parameters

Returns the PyTorch parameter tensor with appropriate transformations applied to enforce bounds, simplex constraints, or other restrictions. The returned tensor is suitable for gradient-based optimization and obeys the bounds of the probability distribution.

write_dist_args(**to_format: str) → str[source]¶

Format distribution arguments for Stan code generation.

Parameters:: to_format (str) – Formatted parameter strings keyed by parameter name
Returns:: Comma-separated argument string for Stan distribution calls
Return type:: str

This method creates properly formatted argument lists for Stan distribution functions, ordering arguments according to Stan conventions and handling parameter name mappings.

Example:

>>> param = Normal(mu=0, sigma=1)
>>> param.write_dist_args(mu="mean", sigma="stddev")
'mean, stddev'

class scistanpy.model.components.parameters.ContinuousDistribution(**kwargs)[source]¶

Bases: Parameter, TransformableParameter

Base class for parameters with continuous sample spaces.

This class extends Parameter to provide functionality specific to continuous probability distributions. It also inherits transformation capabilities that enable complex hierarchical model construction using mathematical operators.

class scistanpy.model.components.parameters.DiscreteDistribution(**kwargs)[source]¶

Bases: Parameter

Base class for parameters with discrete sample spaces.

This class extends Parameter for discrete probability distributions, handling the specific requirements of integer-valued random variables.

Variables:

BASE_STAN_DTYPE – Stan data type for discrete variables (“int”)
LOWER_BOUND – Default lower bound for discrete values (0)

BASE_STAN_DTYPE: str = 'int'¶: Updated relative to Parameter to reflect that discrete parameters are represented as integers in Stan.

LOWER_BOUND: custom_types.Integer = 0¶: Updated relative to Parameter to reflect that all discrete distributions currently implemented in SciStanPy are defined for non-negative integers. This sets the default lower bound to 0.

Univariate Continuous Distributions¶

class scistanpy.model.components.parameters.Normal(

*,

mu: custom_types.ContinuousParameterType,

sigma: custom_types.ContinuousParameterType,

noncentered: bool = True,

**kwargs,

)[source]¶

Bases: ContinuousDistribution

Normal (Gaussian) distribution parameter.

Implements the normal distribution with location (mu) and scale (sigma) parameters. Supports automatic non-centered parameterization for improved sampling in hierarchical models.

Parameters:

mu (custom_types.ContinuousParameterType) – Location parameter (mean)
sigma (custom_types.ContinuousParameterType) – Scale parameter (standard deviation)
noncentered (bool) – Whether to use non-centered parameterization in hierarchical models. Defaults to True.
kwargs – Additional keyword arguments passed to parent class

Mathematical Definition:: \[P(x | \mu, \sigma) = \frac{1}{\sigma\sqrt{2\pi}} * \exp\left(-\frac{((x-\mu)/\sigma)^2}{2}\right)\]

Properties:

Support	\((-\infty, \infty)\)
Mean	\(\mu\)
Median	\(\mu\)
Mode	\(\mu\)
Variance	\(\sigma^2\)

In hierarchical models, the non-centered parametrization is used by default. In this case, a separate raw variable is introduced, and the actual parameter is defined as a transformation of this raw variable. This can lead to improved sampling efficiency in many scenarios:

\[\begin{split}\begin{align*} z &\sim \text{Normal}(0, 1) \\ x &= \mu + \sigma * z \end{align*}\end{split}\]

class CDF(

x: custom_types.CombinableParameterType,

shape: tuple[custom_types.Integer, ...] | custom_types.Integer = (),

**params: custom_types.CombinableParameterType,

)¶

Bases: CDF

PARAMETER¶: alias of Normal

property HAS_RAW_VARNAME: bool¶

Check if parameter uses non-centered parameterization.

Returns:: True if using non-centered parameterization
Return type:: bool

Non-centered parameterization is used when:

noncentered flag is True during initialization.
Parameter is not a hyperparameter
Parameter is not observable

class LOG_CDF(

x: custom_types.CombinableParameterType,

shape: tuple[custom_types.Integer, ...] | custom_types.Integer = (),

**params: custom_types.CombinableParameterType,

)¶

Bases: LogCDF

PARAMETER¶: alias of Normal

class LOG_SF(

x: custom_types.CombinableParameterType,

shape: tuple[custom_types.Integer, ...] | custom_types.Integer = (),

**params: custom_types.CombinableParameterType,

)¶

Bases: LogSurvivalFunction

PARAMETER¶: alias of Normal

POSITIVE_PARAMS: set[str] = {'sigma'}¶: Class variable giving the set of parent parameter names that must be positive.

SCIPY_DIST: type[stats.rv_continuous] | type[stats.rv_discrete] | None = <scipy.stats._continuous_distns.norm_gen object>¶: Corresponding SciPy distribution class (e.g., scipy.stats.norm).

class SF(

x: custom_types.CombinableParameterType,

shape: tuple[custom_types.Integer, ...] | custom_types.Integer = (),

**params: custom_types.CombinableParameterType,

)¶

Bases: SurvivalFunction

PARAMETER¶: alias of Normal

STAN_DIST: str = 'normal'¶: Name of the distribution in Stan code (e.g. “normal”, “binomial”).

STAN_TO_SCIPY_NAMES: dict[str, str] = {'mu': 'loc', 'sigma': 'scale'}¶: There can be differences in parameter names between Stan and SciPy. This dictionary maps between the two naming conventions.

STAN_TO_TORCH_NAMES: dict[str, str] = {'mu': 'loc', 'sigma': 'scale'}¶: There can be differences in parameter names between Stan and PyTorch. This dictionary maps between the two naming conventions.

TORCH_DIST¶: alias of Normal

get_right_side( index_opts: tuple[str, ...] | None, start_dims: dict[str, custom_types.Integer] | None = None, end_dims: dict[str, custom_types.Integer] | None = None, offset_adjustment: int = 0, dist_suffix: str = '', ) → str[source]¶

Generate distribution call for Stan code.

For non-centered parameterization, returns “std_normal()” for the raw variable. Otherwise uses the parent implementation.

get_target_incrementation(index_opts: tuple[str, ...]) → str[source]¶

Generate Stan target increment with appropriate variable names.

Parameters:: index_opts (tuple[str, ...]) – Potential names for indexing variables (e.g., (‘i’, ‘j’, ‘k’, …)).
Returns:: Stan target increment statement
Return type:: str

For non-centered parameterization, uses the raw variable name in the target increment while the transformed variable is computed in the transformed parameters block. Otherwise, uses the parent implementation.

get_transformation_assignment(index_opts: tuple[str, ...]) → str[source]¶

Generate Stan code for parameter transformation.

Parameters:: index_opts (tuple[str, ...]) – Potential names for indexing variables (e.g., (‘i’, ‘j’, ‘k’, …)).
Returns:: Stan transformation code.
Return type:: str

For non-centered parameterization, returns Stan code that defines the parameter as a transformation of a raw variable drawn from a unit normal distribution. Otherwise, uses the parent class default transformation.

property is_noncentered: bool¶

Check if parameter uses non-centered parameterization.

Returns:: True if using non-centered parameterization
Return type:: bool

Non-centered parameterization is used when:

noncentered flag is True during initialization.
Parameter is not a hyperparameter
Parameter is not observable

class scistanpy.model.components.parameters.HalfNormal(**kwargs)[source]¶

Bases: ContinuousDistribution

Half-normal distribution parameter (normal truncated at zero).

Implements the half-normal distribution, which is a normal distribution truncated to positive values. Commonly used for scale parameters.

Parameters:

sigma (custom_types.ContinuousParameterType) – Scale parameter
kwargs – Additional keyword arguments passed to parent class

Mathematical Definition:: \[P(x | \sigma) = \frac{2}{\sigma\sqrt{2\pi}} * \exp\left(-\frac{x^2}{2\sigma^2}\right) \text{ for } x \geq 0\]

Properties:

Support

\([0, \infty)\)

Mean

\(\sigma\sqrt{\dfrac{2}{\pi}}\)

Median

\(\sigma\sqrt{2}\operatorname{erf}^{-1}(0.5)\)

Mode

\(0\)

Variance

\(\sigma^2\left(1 - \dfrac{2}{\pi}\right)\)

LOWER_BOUND: custom_types.Float = 0.0¶: Class variable giving the lower bound constraint for component values. None if unbounded.

SCIPY_DIST: type[stats.rv_continuous] | type[stats.rv_discrete] | None = <scipy.stats._continuous_distns.halfnorm_gen object>¶: Corresponding SciPy distribution class (e.g., scipy.stats.norm).

STAN_DIST: str = 'normal'¶: Name of the distribution in Stan code (e.g. “normal”, “binomial”).

STAN_TO_SCIPY_NAMES: dict[str, str] = {'sigma': 'scale'}¶: There can be differences in parameter names between Stan and SciPy. This dictionary maps between the two naming conventions.

STAN_TO_TORCH_NAMES: dict[str, str] = {'sigma': 'scale'}¶: There can be differences in parameter names between Stan and PyTorch. This dictionary maps between the two naming conventions.

class scistanpy.model.components.parameters.UnitNormal(**kwargs)[source]¶

Bases: Normal

Standard normal distribution (mu=0, sigma=1).

Implements the standard normal distribution with fixed parameters. This is a convenience class for the commonly used N(0,1) distribution.

Parameters:: kwargs – Additional keyword arguments passed to parent class

Mathematical Definition:: \[P(x) = \frac{e^{-\frac{x^2}{2}}}{\sqrt{2\pi}}\]

Properties:

Support	\((-\infty, \infty)\)
Mean	\(0\)
Median	\(0\)
Mode	\(0\)
Variance	\(1\)

STAN_DIST: str = 'std_normal'¶: Name of the distribution in Stan code (e.g. “normal”, “binomial”).

class scistanpy.model.components.parameters.LogNormal(**kwargs)[source]¶

Bases: ContinuousDistribution

Log-normal distribution parameter.

Implements the log-normal distribution where \(\log(X)\) follows a normal distribution. Commonly used for modeling positive quantities with multiplicative effects.

Parameters:

mu (custom_types.ContinuousParameterType) – Location parameter for underlying normal
sigma (custom_types.ContinuousParameterType) – Scale parameter for underlying normal
kwargs – Additional keyword arguments passed to parent class

Mathematical Definition:: \[\begin{split}\begin{align*} \text{If } Y &\sim \text{Normal}(\mu, \sigma), \text{then } \\ \\ X &\sim \text{LogNormal}(\mu, \sigma), \text{where } \\ \\ P(x | \mu, \sigma) &= \frac{1}{x\sigma\sqrt{2\pi}} * \exp\left(-\frac{(\ln(x)-\mu)^2}{2\sigma^2}\right) \text{ for } x > 0 \end{align*}\end{split}\]

Properties:

Support

\((0, \infty)\)

Mean

\(\exp\left(\mu + \frac{\sigma^2}{2}\right)\)

Median

\(\exp(\mu)\)

Mode

\(\exp(\mu - \sigma^2)\)

Variance

\(\left(\exp(\sigma^2) - 1\right) \exp\left(2\mu + \sigma^2\right)\)

LOWER_BOUND: custom_types.Float = 0.0¶: Class variable giving the lower bound constraint for component values. None if unbounded.

POSITIVE_PARAMS: set[str] = {'sigma'}¶: Class variable giving the set of parent parameter names that must be positive.

SCIPY_DIST: type[stats.rv_continuous] | type[stats.rv_discrete] | None = <scipy.stats._continuous_distns.lognorm_gen object>¶: Corresponding SciPy distribution class (e.g., scipy.stats.norm).

STAN_DIST: str = 'lognormal'¶: Name of the distribution in Stan code (e.g. “normal”, “binomial”).

STAN_TO_SCIPY_NAMES: dict[str, str] = {'mu': 'scale', 'sigma': 's'}¶: There can be differences in parameter names between Stan and SciPy. This dictionary maps between the two naming conventions.

STAN_TO_SCIPY_TRANSFORMS: dict[str, Callable[[npt.NDArray], npt.NDArray]] = {'mu': <function _exp_transform>}¶: Some distributions are parametrized differently between Stan and SciPy. This dictionary provides transformation functions to convert parameters from Stan’s parametrization to SciPy’s parametrization.

STAN_TO_TORCH_NAMES: dict[str, str] = {'mu': 'loc', 'sigma': 'scale'}¶: There can be differences in parameter names between Stan and PyTorch. This dictionary maps between the two naming conventions.

TORCH_DIST¶: alias of LogNormal

class scistanpy.model.components.parameters.Beta(**kwargs)[source]¶

Bases: ContinuousDistribution

Beta distribution parameter.

Implements the beta distribution with shape parameters alpha and beta. The distribution has support on (0, 1) and is commonly used for modeling probabilities and proportions.

Parameters:

alpha (custom_types.ContinuousParameterType) – First shape parameter (concentration)
beta (custom_types.ContinuousParameterType) – Second shape parameter (concentration)
kwargs – Additional keyword arguments passed to parent class

Mathematical Definition:

\[\begin{split}\begin{align*} P(x | \alpha, \beta) &= \frac{\Gamma(\alpha + \beta)}{\Gamma(\alpha)\Gamma(\beta)} * x^{\alpha - 1} (1 - x)^{\beta - 1} \text{ for } 0 < x < 1 \\ \text{where } \Gamma(z) &= \int_0^\infty t^{z-1} e^{-t} dt \end{align*}\end{split}\]

Properties:

Support

\((0, 1)\)

Mean

\(\frac{\alpha}{\alpha + \beta}\)

Mode

\(\frac{\alpha - 1}{\alpha + \beta - 2}\) for \(\alpha, \beta > 1\)

Variance

\(\frac{\alpha \beta}{(\alpha + \beta)^2 (\alpha + \beta + 1)}\)

Common Applications:

Prior distributions for probabilities
Modeling proportions and percentages
Bayesian A/B testing
Mixture model component weights

LOWER_BOUND: custom_types.Float = 0.0¶: Class variable giving the lower bound constraint for component values. None if unbounded.

POSITIVE_PARAMS: set[str] = {'alpha', 'beta'}¶: Class variable giving the set of parent parameter names that must be positive.

SCIPY_DIST: type[stats.rv_continuous] | type[stats.rv_discrete] | None = <scipy.stats._continuous_distns.beta_gen object>¶: Corresponding SciPy distribution class (e.g., scipy.stats.norm).

STAN_DIST: str = 'beta'¶: Name of the distribution in Stan code (e.g. “normal”, “binomial”).

STAN_TO_SCIPY_NAMES: dict[str, str] = {'alpha': 'a', 'beta': 'b'}¶: There can be differences in parameter names between Stan and SciPy. This dictionary maps between the two naming conventions.

STAN_TO_TORCH_NAMES: dict[str, str] = {'alpha': 'concentration1', 'beta': 'concentration0'}¶: There can be differences in parameter names between Stan and PyTorch. This dictionary maps between the two naming conventions.

UPPER_BOUND: custom_types.Float = 1.0¶: Class variable giving the upper bound constraint for component values. None if unbounded.

class scistanpy.model.components.parameters.Gamma(**kwargs)[source]¶

Bases: ContinuousDistribution

Gamma distribution parameter.

Implements the gamma distribution with shape (alpha) and rate (beta) parameters. Commonly used for modeling positive continuous quantities with specific shape characteristics.

Parameters:

alpha (custom_types.ContinuousParameterType) – Shape parameter
beta (custom_types.ContinuousParameterType) – Rate parameter
kwargs – Additional keyword arguments passed to parent class

Mathematical Definition:: \[\begin{split}\begin{align*} P(x | \alpha, \beta) &= \frac{\beta^\alpha}{\Gamma(\alpha)} * x^{\alpha - 1} e^{-\beta x} \text{ for } x > 0 \\ \text{where } \Gamma(z) &= \int_0^\infty t^{z-1} e^{-t} dt \end{align*}\end{split}\]

Properties:

Support

\((0, \infty)\)

Mean

\(\frac{\alpha}{\beta}\)

Mode

\(\frac{\alpha - 1}{\beta}\) for \(\alpha > 1\)

Variance

\(\frac{\alpha}{\beta^2}\)

LOWER_BOUND: custom_types.Float = 0.0¶: Class variable giving the lower bound constraint for component values. None if unbounded.

POSITIVE_PARAMS: set[str] = {'alpha', 'beta'}¶: Class variable giving the set of parent parameter names that must be positive.

SCIPY_DIST: type[stats.rv_continuous] | type[stats.rv_discrete] | None = <scipy.stats._continuous_distns.gamma_gen object>¶: Corresponding SciPy distribution class (e.g., scipy.stats.norm).

STAN_DIST: str = 'gamma'¶: Name of the distribution in Stan code (e.g. “normal”, “binomial”).

STAN_TO_SCIPY_NAMES: dict[str, str] = {'alpha': 'a', 'beta': 'scale'}¶: There can be differences in parameter names between Stan and SciPy. This dictionary maps between the two naming conventions.

STAN_TO_SCIPY_TRANSFORMS: dict[str, Callable[[npt.NDArray], npt.NDArray]] = {'beta': <function _inverse_transform>}¶: Some distributions are parametrized differently between Stan and SciPy. This dictionary provides transformation functions to convert parameters from Stan’s parametrization to SciPy’s parametrization.

STAN_TO_TORCH_NAMES: dict[str, str] = {'alpha': 'concentration', 'beta': 'rate'}¶: There can be differences in parameter names between Stan and PyTorch. This dictionary maps between the two naming conventions.

class scistanpy.model.components.parameters.InverseGamma(**kwargs)[source]¶

Bases: ContinuousDistribution

Inverse gamma distribution parameter.

Implements the inverse gamma distribution, commonly used as a conjugate prior for variance parameters in Bayesian analysis.

Parameters:

alpha (custom_types.ContinuousParameterType) – Shape parameter
beta (custom_types.ContinuousParameterType) – Scale parameter
kwargs – Additional keyword arguments passed to parent class

Mathematical Definition:: \[\begin{split}\begin{align*} P(x | \alpha, \beta) &= \frac{\beta^\alpha}{\Gamma(\alpha)} * x^{-\alpha - 1} e^{-\beta / x} \text{ for } x > 0 \\ \text{where } \Gamma(z) &= \int_0^\infty t^{z-1} e^{-t} dt \end{align*}\end{split}\]

Properties:

Support

\((0, \infty)\)

Mean

\(\frac{\beta}{\alpha - 1}\) for \(\alpha > 1\)

Mode

\(\frac{\beta}{\alpha + 1}\)

Variance

\(\frac{\beta^2}{(\alpha - 1)^2(\alpha - 2)}\) for \(\alpha > 2\)

Common Applications:

Conjugate prior for normal variance
Hierarchical modeling of scale parameters
Bayesian regression variance modeling

LOWER_BOUND: custom_types.Float = 0.0¶: Class variable giving the lower bound constraint for component values. None if unbounded.

POSITIVE_PARAMS: set[str] = {'alpha', 'beta'}¶: Class variable giving the set of parent parameter names that must be positive.

SCIPY_DIST: type[stats.rv_continuous] | type[stats.rv_discrete] | None = <scipy.stats._continuous_distns.invgamma_gen object>¶: Corresponding SciPy distribution class (e.g., scipy.stats.norm).

STAN_DIST: str = 'inv_gamma'¶: Name of the distribution in Stan code (e.g. “normal”, “binomial”).

STAN_TO_SCIPY_NAMES: dict[str, str] = {'alpha': 'a', 'beta': 'scale'}¶: There can be differences in parameter names between Stan and SciPy. This dictionary maps between the two naming conventions.

STAN_TO_TORCH_NAMES: dict[str, str] = {'alpha': 'concentration', 'beta': 'rate'}¶: There can be differences in parameter names between Stan and PyTorch. This dictionary maps between the two naming conventions.

class scistanpy.model.components.parameters.Exponential(**kwargs)[source]¶

Bases: ContinuousDistribution

Exponential distribution parameter.

Implements the exponential distribution with rate parameter beta. Commonly used for modeling waiting times and survival analysis.

Parameters:

beta (custom_types.ContinuousParameterType) – Rate parameter
kwargs – Additional keyword arguments passed to parent class

Mathematical Definition:: \[\begin{align*} P(x | \beta) &= \beta e^{-\beta x} \text{ for } x \geq 0 \end{align*}\]

Properties:

Support

\([0, \infty)\)

Mean

\(\frac{1}{\beta}\)

Mode

\(0\)

Variance

\(\frac{1}{\beta^2}\)

LOWER_BOUND: custom_types.Float = 0.0¶: Class variable giving the lower bound constraint for component values. None if unbounded.

POSITIVE_PARAMS: set[str] = {'beta'}¶: Class variable giving the set of parent parameter names that must be positive.

SCIPY_DIST: type[stats.rv_continuous] | type[stats.rv_discrete] | None = <scipy.stats._continuous_distns.expon_gen object>¶: Corresponding SciPy distribution class (e.g., scipy.stats.norm).

STAN_DIST: str = 'exponential'¶: Name of the distribution in Stan code (e.g. “normal”, “binomial”).

STAN_TO_SCIPY_NAMES: dict[str, str] = {'beta': 'scale'}¶: There can be differences in parameter names between Stan and SciPy. This dictionary maps between the two naming conventions.

STAN_TO_SCIPY_TRANSFORMS: dict[str, Callable[[npt.NDArray], npt.NDArray]] = {'beta': <function _inverse_transform>}¶: Some distributions are parametrized differently between Stan and SciPy. This dictionary provides transformation functions to convert parameters from Stan’s parametrization to SciPy’s parametrization.

STAN_TO_TORCH_NAMES: dict[str, str] = {'beta': 'rate'}¶: There can be differences in parameter names between Stan and PyTorch. This dictionary maps between the two naming conventions.

class scistanpy.model.components.parameters.ExpExponential(**kwargs)[source]¶

Bases: Exponential

Exp-Exponential distribution (log of exponential random variable).

Implements the distribution of \(Y\) where \(\exp(Y) \sim \text{Exponential}(\beta)\).

Parameters:

beta (custom_types.ContinuousParameterType) – Rate parameter for the underlying exponential
kwargs – Additional keyword arguments passed to parent class

Mathematical Definition:

\[\begin{split}\begin{align*} \text{If } X &\sim \text{Exponential}(\beta), \text{then } \\ \\ Y &= \log(X) \sim \text{ExpExponential}(\beta), \text{where } \\ \\ P(y | \beta) &= \beta * \exp(y - \beta * \exp(y)) \text{ for } y \in (-\infty, \infty) \end{align*}\end{split}\]

Properties:

Support: \((-\infty, \infty)\)
Related to Gumbel distribution family
Useful for log-scale modeling of exponential processes

This distribution requires custom Stan functions for implementation (see Stan Functions Library Reference) which are automatically included in any Stan program defined using this distribution.

LOWER_BOUND: custom_types.Float = None¶: Class variable giving the lower bound constraint for component values. None if unbounded.

SCIPY_DIST: type[stats.rv_continuous] | type[stats.rv_discrete] | None = <scistanpy.model.components.custom_distributions.custom_scipy_dists.LogUnivariateScipyTransform object>¶: Corresponding SciPy distribution class (e.g., scipy.stats.norm).

STAN_DIST: str = 'expexponential'¶: Name of the distribution in Stan code (e.g. “normal”, “binomial”).

STAN_TO_SCIPY_NAMES: dict[str, str] = {'beta': 'scale'}¶: There can be differences in parameter names between Stan and SciPy. This dictionary maps between the two naming conventions.

STAN_TO_SCIPY_TRANSFORMS: dict[str, Callable[[npt.NDArray], npt.NDArray]] = {'beta': <function _inverse_transform>}¶: Some distributions are parametrized differently between Stan and SciPy. This dictionary provides transformation functions to convert parameters from Stan’s parametrization to SciPy’s parametrization.

STAN_TO_TORCH_NAMES: dict[str, str] = {'beta': 'rate'}¶: There can be differences in parameter names between Stan and PyTorch. This dictionary maps between the two naming conventions.

TORCH_DIST¶: alias of ExpExponential

get_supporting_functions() → list[str][source]¶

Return list of required Stan function includes.

Returns:: List containing the expexponential.stanfunctions include
Return type:: list[str]

This distribution requires custom Stan functions for proper implementation of the exp-exponential density and random number generation.

class scistanpy.model.components.parameters.Lomax(**kwargs)[source]¶

Bases: ContinuousDistribution

Lomax distribution (Pareto Type II with location=0).

Implements the Lomax distribution, which is a special case of the Pareto Type II distribution with location parameter set to 0.

Parameters:

lambda_ (custom_types.ContinuousParameterType) – Scale parameter
alpha (custom_types.ContinuousParameterType) – Shape parameter
kwargs – Additional keyword arguments passed to parent class

Mathematical Definition:: \[\begin{align*} P(x | \lambda, \alpha) &= \frac{\alpha}{\lambda} * \left(1 + \frac{x}{\lambda}\right)^{-\alpha - 1} \text{ for } x \geq 0 \end{align*}\]

Properties:

Support

\([0, \infty)\)

Mean

\(\frac{\lambda}{\alpha - 1}\) for \(\alpha > 1\)

Mode

\(0\)

Variance

\(\frac{\lambda^2}{(\alpha - 1)^2(\alpha - 2)}\) for \(\alpha > 2\)

Common Applications:

Modeling income distributions
Network analysis (degree distributions)
Reliability engineering
Extreme value modeling

LOWER_BOUND: 'custom_types.Float' | 'custom_types.Integer' | None = 0.0¶: Class variable giving the lower bound constraint for component values. None if unbounded.

POSITIVE_PARAMS: set[str] = {'alpha', 'lambda_'}¶: Class variable giving the set of parent parameter names that must be positive.

SCIPY_DIST: type[stats.rv_continuous] | type[stats.rv_discrete] | None = <scipy.stats._continuous_distns.lomax_gen object>¶: Corresponding SciPy distribution class (e.g., scipy.stats.norm).

STAN_DIST: str = 'pareto_type_2'¶: Name of the distribution in Stan code (e.g. “normal”, “binomial”).

STAN_TO_SCIPY_NAMES: dict[str, str] = {'alpha': 'c', 'lambda_': 'scale'}¶: There can be differences in parameter names between Stan and SciPy. This dictionary maps between the two naming conventions.

STAN_TO_TORCH_NAMES: dict[str, str] = {'alpha': 'alpha', 'lambda_': 'lambda_'}¶: There can be differences in parameter names between Stan and PyTorch. This dictionary maps between the two naming conventions.

TORCH_DIST¶: alias of Lomax

class scistanpy.model.components.parameters.ExpLomax(**kwargs)[source]¶

Bases: ContinuousDistribution

Exp-Lomax distribution (log of Lomax random variable).

Implements the distribution of \(Y\) where \(\exp(Y) \sim \text{Lomax}(\lambda, \alpha)\).

Parameters:

lambda_ (custom_types.ContinuousParameterType) – Scale parameter for underlying Lomax
alpha (custom_types.ContinuousParameterType) – Shape parameter for underlying Lomax
kwargs – Additional keyword arguments passed to parent class

Mathematical Definition:: \[\begin{split}\begin{align*} \text{If } X &\sim \text{Lomax}(\lambda, \alpha), \text{then } \\ \\ Y &= \log(X) \sim \text{ExpLomax}(\lambda, \alpha), \text{where } \\ \\ P(y | \lambda, \alpha) &= \frac{\alpha}{\lambda} * \exp(y) * \left(1 + \frac{\exp(y)}{\lambda}\right)^{-\alpha - 1} \text{ for } y \in (-\infty, \infty) \end{align*}\end{split}\]

This distribution requires custom Stan functions for implementation (see Stan Functions Library Reference) which are automatically included in any Stan program defined using this distribution.

LOWER_BOUND: 'custom_types.Float' | 'custom_types.Integer' | None = None¶: Class variable giving the lower bound constraint for component values. None if unbounded.

POSITIVE_PARAMS: set[str] = {'alpha', 'lambda_'}¶: Class variable giving the set of parent parameter names that must be positive.

SCIPY_DIST: type[stats.rv_continuous] | type[stats.rv_discrete] | None = <scistanpy.model.components.custom_distributions.custom_scipy_dists.LogUnivariateScipyTransform object>¶: Corresponding SciPy distribution class (e.g., scipy.stats.norm).

STAN_DIST: str = 'explomax'¶: Name of the distribution in Stan code (e.g. “normal”, “binomial”).

STAN_TO_SCIPY_NAMES: dict[str, str] = {'alpha': 'c', 'lambda_': 'scale'}¶: There can be differences in parameter names between Stan and SciPy. This dictionary maps between the two naming conventions.

STAN_TO_TORCH_NAMES: dict[str, str] = {'alpha': 'alpha', 'lambda_': 'lambda_'}¶: There can be differences in parameter names between Stan and PyTorch. This dictionary maps between the two naming conventions.

TORCH_DIST¶: alias of ExpLomax

Univariate Discrete Distributions¶

class scistanpy.model.components.parameters.Binomial(**kwargs)[source]¶

Bases: DiscreteDistribution

Binomial distribution parameter.

Implements the binomial distribution for modeling the number of successes in a fixed number of independent Bernoulli trials.

Parameters:

N (custom_types.DiscreteParameterType) – Number of trials
theta (custom_types.ContinuousParameterType) – Success probability
kwargs – Additional keyword arguments passed to parent class

Mathematical Definition:: \[\begin{align*} P(X = k | N, \theta) &= \binom{N}{k} \theta^k (1 - \theta)^{N - k} \text{ for } k = 0, 1, ..., N \end{align*}\]

Properties:

Support

\(\{0, 1, 2, ..., N\}\)

Mean

\(N \theta\)

Variance

\(N \theta (1 - \theta)\)

Mode

\(\lfloor (N + 1) \theta \rfloor\)

Common Applications:

Number of successes in fixed trials
Proportion data with known denominators

POSITIVE_PARAMS: set[str] = {'N', 'theta'}¶: Class variable giving the set of parent parameter names that must be positive.

SCIPY_DIST: type[stats.rv_continuous] | type[stats.rv_discrete] | None = <scipy.stats._discrete_distns.binom_gen object>¶: Corresponding SciPy distribution class (e.g., scipy.stats.norm).

STAN_DIST: str = 'binomial'¶: Name of the distribution in Stan code (e.g. “normal”, “binomial”).

STAN_TO_SCIPY_NAMES: dict[str, str] = {'N': 'n', 'theta': 'p'}¶: There can be differences in parameter names between Stan and SciPy. This dictionary maps between the two naming conventions.

STAN_TO_TORCH_NAMES: dict[str, str] = {'N': 'total_count', 'theta': 'probs'}¶: There can be differences in parameter names between Stan and PyTorch. This dictionary maps between the two naming conventions.

class scistanpy.model.components.parameters.Poisson(**kwargs)[source]¶

Bases: DiscreteDistribution

Poisson distribution parameter.

Implements the Poisson distribution for modeling count data with a single rate parameter.

Parameters:

lambda (custom_types.ContinuousParameterType) – Rate parameter (mean number of events)
kwargs – Additional keyword arguments passed to parent class

Mathematical Definition:: \[\begin{align*} P(X = k | \lambda) &= \frac{\lambda^k e^{-\lambda}}{k!} \text{ for } k = 0, 1, 2, ... \end{align*}\]

Properties:

Support

\(\{0, 1, 2, ...\}\)

Mean

\(\lambda\)

Variance

\(\lambda\)

Mode

\(\lfloor \lambda \rfloor\)

Common Applications:

Event counting (arrivals, defects, etc.)
Modeling rare events
Count regression
Queueing theory

POSITIVE_PARAMS: set[str] = {'lambda_'}¶: Class variable giving the set of parent parameter names that must be positive.

SCIPY_DIST: type[stats.rv_continuous] | type[stats.rv_discrete] | None = <scipy.stats._discrete_distns.poisson_gen object>¶: Corresponding SciPy distribution class (e.g., scipy.stats.norm).

STAN_DIST: str = 'poisson'¶: Name of the distribution in Stan code (e.g. “normal”, “binomial”).

STAN_TO_SCIPY_NAMES: dict[str, str] = {'lambda_': 'mu'}¶: There can be differences in parameter names between Stan and SciPy. This dictionary maps between the two naming conventions.

STAN_TO_TORCH_NAMES: dict[str, str] = {'lambda_': 'rate'}¶: There can be differences in parameter names between Stan and PyTorch. This dictionary maps between the two naming conventions.

Multivariate Continuous Distributions¶

Bases: ContinuousDistribution

Dirichlet distribution parameter.

Implements the Dirichlet distribution for modeling probability simplexes. The distribution generates vectors that sum to 1, making it ideal for modeling categorical probabilities and mixture weights.

Parameters:

alpha (Union[AbstractModelComponent, npt.ArrayLike]) – Concentration parameters (can be scalar or array-like). If scalar, will be converted to the appropriate shape given by the shape kwarg.
kwargs – Additional keyword arguments including ‘shape’ if alpha is scalar

Mathematical Definition:: \[\begin{split}\begin{align*} P(x | \alpha) &= \frac{\Gamma(\sum_{i=1}^K \alpha_i)}{\prod_{i=1}^K \Gamma(\alpha_i)} \prod_{i=1}^K x_i^{\alpha_i - 1} \text{ for } x_i > 0, \sum_{i=1}^K x_i = 1 \\ \text{where } \Gamma(z) &= \int_0^\infty t^{z-1} e^{-t} dt \end{align*}\end{split}\]

Properties:

Support

\(\{x : \sum_{i=1}^K x_i = 1, x_i > 0\}\)

Mean

\(E[X_i] = \frac{\alpha_i}{\sum_{j=1}^K \alpha_j}\)

Mode

\(\frac{\alpha_i - 1}{\sum_{j=1}^K \alpha_j - K}\) for all \(\alpha_i > 1\)

Variance

\(\frac{\alpha_i (\sum_{j=1}^K \alpha_j - \alpha_i)} {(\sum_{j=1}^K \alpha_j)^2 (\sum_{j=1}^K \alpha_j + 1)}\) for all \(\alpha_i > 1\)

Covariance

\(\frac{-\alpha_i \alpha_j}{(\sum_{k=1}^K \alpha_k)^2 (\sum_{k=1}^K \alpha_k + 1)}\) for all \(i \neq j\) and \(\alpha_i, \alpha_j > 1\)

Common Applications:

Modeling categorical probabilities

Note

SciStanPy’s implementation of the Dirichlet distribution allows for defining concentration parameters (\(\alpha\)) as either scalar values or arrays. If a scalar is provided, the shape keyword argument must also be specified to define the dimensionality of the simplex–the scalar will be expanded to a uniform array of that shape. This flexibility enables both symmetric Dirichlet distributions (where all components have the same concentration) and asymmetric distributions with distinct concentration parameters for each component.

BASE_STAN_DTYPE: Literal['real', 'int', 'simplex'] = 'simplex'¶: Class variable giving the base Stan data type for this component.

IS_SIMPLEX: bool = True¶: Class variable giving whether this component represents a simplex (elements over last dim sum to 1).

POSITIVE_PARAMS: set[str] = {'alpha'}¶: Class variable giving the set of parent parameter names that must be positive.

SCIPY_DIST: type[stats.rv_continuous] | type[stats.rv_discrete] | None = <scistanpy.model.components.custom_distributions.custom_scipy_dists.CustomDirichlet object>¶: Corresponding SciPy distribution class (e.g., scipy.stats.norm).

STAN_DIST: str = 'dirichlet'¶: Name of the distribution in Stan code (e.g. “normal”, “binomial”).

STAN_TO_SCIPY_NAMES: dict[str, str] = {'alpha': 'alpha'}¶: There can be differences in parameter names between Stan and SciPy. This dictionary maps between the two naming conventions.

STAN_TO_TORCH_NAMES: dict[str, str] = {'alpha': 'concentration'}¶: There can be differences in parameter names between Stan and PyTorch. This dictionary maps between the two naming conventions.

Bases: Dirichlet

Exp-Dirichlet distribution (log of Dirichlet random variable).

Implements the distribution of \(Y\) where \(\exp(Y) ~ \text{Dirichlet}(\alpha)\). This provides a log-simplex parameterization that can be more numerically stable for extreme concentration parameters and extremely high-dimensional simplexes, like those encountered when modeling deep mutational scanning data.

Parameters:

alpha (Union[AbstractModelComponent, npt.ArrayLike]) – Concentration parameters for underlying Dirichlet
kwargs – Additional keyword arguments including ‘shape’ if alpha is scalar

Mathematical Definition:

\[\begin{split}\begin{align*} \text{If } X &\sim \text{Dirichlet}(\alpha), \text{then } \\ \\ Y &= \log(X) \sim \text{ExpDirichlet}(\alpha), \text{where } \\ \\ P(y | \alpha) &= \frac{\sqrt{K}}{\exp{(y_K)}}\frac{\Gamma(\sum_{i=1}^K \alpha_i)}{\prod_{i=1}^K \Gamma(\alpha_i)} \prod_{i=1}^K \exp(y_i \alpha_i) \text{ for } y_i \in (-\infty, \infty), \sum_{i=1}^K \exp(y_i) = 1 \\ \text{where } \Gamma(z) &= \int_0^\infty t^{z-1} e^{-t} dt \end{align*}\end{split}\]

Properties:

Log-probability is computed in the log-simplex space
More numerically stable for extreme concentration parameters
Suitable for high-dimensional simplexes
Useful for modeling compositional data on log scale

Note

The Exp-Dirichlet distribution is not natively supported in Stan, so this implementation includes custom Stan functions for the probability density, transformations, and random number generation. These functions are automatically included in any Stan program defined using this distribution. Special thanks to Sean Pinkney for assistance with deriving the log probability density function for the distribution; thanks also to Bob Carpenter and others for developing the log-simplex constraint used in SciStanPy. See here for derivations and here for transforms.

Note

When used as a hyperparameter (i.e., \(\alpha\) is constant), the normalization constant of the distribution is also constant and can be ignored during MCMC sampling to improve computational efficiency. This implementation automatically detects when the Exp-Dirichlet is used as a hyperparameter and switches to the unnormalized version of the distribution in such cases. If \(\alpha\) is not constant, the normalized version is used.

BASE_STAN_DTYPE: Literal['real', 'int', 'simplex'] = 'real'¶: Class variable giving the base Stan data type for this component.

HAS_RAW_VARNAME: bool = True¶: Whether the parameter intrinsically uses a raw/transformed parameterization.

IS_LOG_SIMPLEX: bool = True¶: Class variable giving whether this component represents a log-simplex (exponentials over last dim sum to 1).

IS_SIMPLEX: bool = False¶: Class variable giving whether this component represents a simplex (elements over last dim sum to 1).

LOWER_BOUND: 'custom_types.Float' | 'custom_types.Integer' | None = None¶: Class variable giving the lower bound constraint for component values. None if unbounded.

SCIPY_DIST: type[stats.rv_continuous] | type[stats.rv_discrete] | None = <scistanpy.model.components.custom_distributions.custom_scipy_dists.ExpDirichlet object>¶: Corresponding SciPy distribution class (e.g., scipy.stats.norm).

STAN_DIST: str = 'expdirichlet'¶: Name of the distribution in Stan code (e.g. “normal”, “binomial”).

STAN_TO_SCIPY_NAMES: dict[str, str] = {'alpha': 'alpha'}¶: There can be differences in parameter names between Stan and SciPy. This dictionary maps between the two naming conventions.

STAN_TO_TORCH_NAMES: dict[str, str] = {'alpha': 'concentration'}¶: There can be differences in parameter names between Stan and PyTorch. This dictionary maps between the two naming conventions.

TORCH_DIST¶: alias of ExpDirichlet

UPPER_BOUND: 'custom_types.Float' | 'custom_types.Integer' | None = 0.0¶: Class variable giving the upper bound constraint for component values. None if unbounded.

Multivariate Discrete Distributions¶

class scistanpy.model.components.parameters.Multinomial(**kwargs)[source]¶

Bases: _MultinomialBase

Standard multinomial distribution parameter.

Implements the multinomial distribution with probability vector \(\theta\) and number of trials \(N\). Models the number of observations in each category for a fixed number of trials.

Parameters:

theta (custom_types.ContinuousParameterType) – Probability vector (must sum to 1)
N (custom_types.DiscreteParameterType) – Number of trials
kwargs – Additional keyword arguments passed to parent class

Mathematical Definition:

\[\begin{split}\begin{align*} P(X = x | N, \theta) &= \frac{N!}{\prod_{i=1}^K x_i!} \prod_{i=1}^K \theta_i^{x_i} \text{ for } x_i \geq 0, \sum_{i=1}^K x_i = N \\ \end{align*}\end{split}\]

Properties:

Support	\(\{x : \sum x_i = N, x_i \geq 0\}\)
Mean	\(N \theta_i\)
Variance	\(N \theta_i (1 - \theta_i)\)
Covariance	\(-N \theta_i \theta_j\)

Common Applications:

Categorical count data
Multinomial logistic regression
Natural language processing (word counts)
Genetics (allele frequencies)
Marketing (customer choice modeling)

SCIPY_DIST: type[stats.rv_continuous] | type[stats.rv_discrete] | None = <scistanpy.model.components.custom_distributions.custom_scipy_dists.CustomMultinomial object>¶: Corresponding SciPy distribution class (e.g., scipy.stats.norm).

SIMPLEX_PARAMS: set[str] = {'theta'}¶: Class variable giving the set of parent parameter names that must be simplexes. The sum over the last dimension for any parent parameter named here must equal 1.

STAN_DIST: str = 'multinomial'¶: Name of the distribution in Stan code (e.g. “normal”, “binomial”).

STAN_TO_SCIPY_NAMES: dict[str, str] = {'N': 'n', 'theta': 'p'}¶: There can be differences in parameter names between Stan and SciPy. This dictionary maps between the two naming conventions.

STAN_TO_TORCH_NAMES: dict[str, str] = {'N': 'total_count', 'theta': 'probs'}¶: There can be differences in parameter names between Stan and PyTorch. This dictionary maps between the two naming conventions.

TORCH_DIST¶: alias of Multinomial

class scistanpy.model.components.parameters.MultinomialLogit(**kwargs)[source]¶

Bases: _MultinomialBase

Multinomial distribution with logit parameterization.

Implements the multinomial distribution parameterized by logits (\(\gamma\)) rather than probabilities. Logits are unconstrained real values that are transformed to probabilities via the softmax function. This parameterization is useful for models that naturally work with logits, such as logistic regression extensions.

Parameters:

gamma (custom_types.ContinuousParameterType) – Logit vector (unconstrained real values)
N (custom_types.DiscreteParameterType) – Number of trials
kwargs – Additional keyword arguments passed to parent class

Mathematical Definition:: \[\begin{split}\begin{align*} \theta_i &= \frac{\exp(\gamma_i)}{\sum_{j=1}^K \exp(\gamma_j)} \\ \\ X &\sim \text{Multinomial}(N, \theta) \end{align*}\end{split}\]

Warning

It is easy to create non-identifiable models using this parameterization. Make sure to include appropriate priors or constraints on logits to ensure model identifiability.

SCIPY_DIST: type[stats.rv_continuous] | type[stats.rv_discrete] | None = <scistanpy.model.components.custom_distributions.custom_scipy_dists.MultinomialLogit object>¶: Corresponding SciPy distribution class (e.g., scipy.stats.norm).

STAN_DIST: str = 'multinomial_logit'¶: Name of the distribution in Stan code (e.g. “normal”, “binomial”).

STAN_TO_SCIPY_NAMES: dict[str, str] = {'N': 'n', 'gamma': 'logits'}¶: There can be differences in parameter names between Stan and SciPy. This dictionary maps between the two naming conventions.

STAN_TO_TORCH_NAMES: dict[str, str] = {'N': 'total_count', 'gamma': 'logits'}¶: There can be differences in parameter names between Stan and PyTorch. This dictionary maps between the two naming conventions.

TORCH_DIST¶: alias of MultinomialLogit

class scistanpy.model.components.parameters.MultinomialLogTheta(

*,

log_theta: custom_types.ContinuousParameterType,

N: custom_types.DiscreteParameterType,

**kwargs,

)[source]¶

Bases: _MultinomialBase

Multinomial distribution with log-probability parameterization.

Implements the multinomial distribution in terms of the log of the theta parameter. This parameterization is useful for models that naturally work with log-probabilities. It can use the ExpDirichlet distribution as a prior to enforce the log-simplex constraint and keep computations completely in the log-probability space. This is extremely useful for high-dimensional multinomials where categories may have very small probabilities (e.g., deep mutational scanning data).

Parameters:

log_theta (custom_types.ContinuousParameterType) – Log probability vector (log-simplex constraint)
N (custom_types.DiscreteParameterType) – Number of trials
kwargs – Additional keyword arguments passed to parent class

Mathematical Definition:: \[\begin{split}\begin{align*} \theta_i &= \exp(\log{\theta_i}) \quad \text{(with normalization: } \sum_j \exp(\log{\theta_j}) = 1) \\ X &\sim \text{Multinomial}(N, \theta) \end{align*}\end{split}\]

Note

This distribution is not natively supported in Stan, so this implementation includes custom Stan functions for the probability density and random number generation. These functions are automatically included in any Stan program defined using this distribution.

Hint

When used to model observed data (i.e., as an observable parameter), the multinomial coefficient is automatically calculated and included in the transformed data block of Stan code. This improves computational efficiency by eliminating redundant calculations during MCMC sampling.

LOG_SIMPLEX_PARAMS: set[str] = {'log_theta'}¶: Class variable giving the set of parent parameter names that must be log-simplexes. The sum of exponentials over the last dimension for any parent parameter named here must equal 1

SCIPY_DIST: type[stats.rv_continuous] | type[stats.rv_discrete] | None = <scistanpy.model.components.custom_distributions.custom_scipy_dists.MultinomialLogTheta object>¶: Corresponding SciPy distribution class (e.g., scipy.stats.norm).

STAN_DIST: str = 'multinomial_logtheta'¶: Name of the distribution in Stan code (e.g. “normal”, “binomial”).

STAN_TO_SCIPY_NAMES: dict[str, str] = {'N': 'n', 'log_theta': 'log_p'}¶: There can be differences in parameter names between Stan and SciPy. This dictionary maps between the two naming conventions.

STAN_TO_TORCH_NAMES: dict[str, str] = {'N': 'total_count', 'log_theta': 'log_probs'}¶: There can be differences in parameter names between Stan and PyTorch. This dictionary maps between the two naming conventions.

TORCH_DIST¶: alias of MultinomialLogTheta

property coefficient: LogMultinomialCoefficient | None¶

Get the multinomial coefficient component if it exists.

Returns:: Multinomial coefficient component or None
Return type:: Optional[LogMultinomialCoefficient]

The coefficient is automatically created for observable parameters and removed when the parameter gains other children, optimizing computation by pre-calculating constant terms.

Utilities¶

class scistanpy.model.components.parameters.ClassOrInstanceMethod(func)[source]¶

Bases: object

Descriptor used as a decorator to enable dual class/instance method behavior.

This descriptor allows methods to behave differently when called as class methods versus instance methods, enabling flexible parameter handling for CDF-like functions that can use either explicit parameters or instance parameter values.

Parameters:: func (Callable) – Function to wrap with dual behavior

When called as an instance method, the descriptor automatically uses the instance’s parameter values. When called as a class method, it requires explicit parameter specification.

__get__(instance, owner)[source]¶

Return appropriate method based on call context.

Parameters:

instance – Instance object if called as instance method, None for class method
owner – Class that owns the method

Returns:

Configured method with appropriate parameter handling

Return type:

Callable

The returned method automatically handles parameter passing based on whether it’s called as a class or instance method, validating required parameters and applying appropriate transformations.

Parameters API Reference¶

Continuous Univariate¶

Continuous Multivariate¶

Discrete Univariate¶

Discrete Multivariate¶

Base Classes¶

Univariate Continuous Distributions¶

Univariate Discrete Distributions¶

Multivariate Continuous Distributions¶

Multivariate Discrete Distributions¶

Utilities¶

SciStanPy

Navigation

Related Topics

Support	\([0, \infty)\)
Mean	\(\sigma\sqrt{\dfrac{2}{\pi}}\)
Median	\(\sigma\sqrt{2}\operatorname{erf}^{-1}(0.5)\)
Mode	\(0\)
Variance	\(\sigma^2\left(1 - \dfrac{2}{\pi}\right)\)

Support	\((0, \infty)\)
Mean	\(\exp\left(\mu + \frac{\sigma^2}{2}\right)\)
Median	\(\exp(\mu)\)
Mode	\(\exp(\mu - \sigma^2)\)
Variance	\(\left(\exp(\sigma^2) - 1\right) \exp\left(2\mu + \sigma^2\right)\)

Support	\((0, 1)\)
Mean	\(\frac{\alpha}{\alpha + \beta}\)
Mode	\(\frac{\alpha - 1}{\alpha + \beta - 2}\) for \(\alpha, \beta > 1\)
Variance	\(\frac{\alpha \beta}{(\alpha + \beta)^2 (\alpha + \beta + 1)}\)

Support	\(\{0, 1, 2, ..., N\}\)
Mean	\(N \theta\)
Variance	\(N \theta (1 - \theta)\)
Mode	\(\lfloor (N + 1) \theta \rfloor\)

Support	\(\{0, 1, 2, ...\}\)
Mean	\(\lambda\)
Variance	\(\lambda\)
Mode	\(\lfloor \lambda \rfloor\)

Support	\(\{x : \sum_{i=1}^K x_i = 1, x_i > 0\}\)
Mean	\(E[X_i] = \frac{\alpha_i}{\sum_{j=1}^K \alpha_j}\)
Mode	\(\frac{\alpha_i - 1}{\sum_{j=1}^K \alpha_j - K}\) for all \(\alpha_i > 1\)
Variance	\(\frac{\alpha_i (\sum_{j=1}^K \alpha_j - \alpha_i)} {(\sum_{j=1}^K \alpha_j)^2 (\sum_{j=1}^K \alpha_j + 1)}\) for all \(\alpha_i > 1\)
Covariance	\(\frac{-\alpha_i \alpha_j}{(\sum_{k=1}^K \alpha_k)^2 (\sum_{k=1}^K \alpha_k + 1)}\) for all \(i \neq j\) and \(\alpha_i, \alpha_j > 1\)