CDFs API Reference

Cumulative distribution function transformations for SciStanPy parameters.

This module provides specialized transformation classes for computing cumulative distribution functions (CDFs) and related probability functions for SciStanPy model parameters.

The module implements a unified interface for CDF-like computations across multiple computational backends (NumPy/SciPy, PyTorch) while automatically generating appropriate Stan code for each transformation.

CDF-like Transformation Types:
Each CDF class automatically handles backend-specific implementations:

  • NumPy/SciPy: Uses SciPy distribution methods with parameter transforms as needed

  • PyTorch: Uses PyTorch distribution objects with appropriate methods

  • Stan: Generates function calls with proper parameter ordering

The classes are not intended to be accessed directly. Instead, they are used as templates by the ParameterMeta metaclass to build ParameterMeta -specific classes on module import, which are assigned to the CDF, LOG_CDF, SF, and LOG_SF properties of each Parameter.

Base Class

All CDF-like classes inherit from a single base class:

class scistanpy.model.components.transformations.cdfs.CDFLike(
x: custom_types.CombinableParameterType,
shape: tuple[custom_types.Integer, ...] | custom_types.Integer = (),
**params: custom_types.CombinableParameterType,
)[source]

Bases: TransformedParameter

Base class for cumulative distribution function transformations.

This abstract base class provides the common infrastructure for all CDF-like transformations including parameter validation, backend selection, and Stan code generation. It cannot be instantiated directly but serves as the foundation for specific CDF transformation types.

Parameters:

  • x (custom_types.CombinableParameterType) – Input values for CDF evaluation

  • shape (Union[tuple[custom_types.Integer, ...], custom_types.Integer]) – Shape of the transformation output. Defaults to ().

  • params (custom_types.CombinableParameterType) – Distribution parameters required for the CDF computation

Raises:

TypeError – If unexpected or missing parameters are provided

The class provides a unified interface for computing probability functions across different computational backends while maintaining compatibility with the SciStanPy model component system.

Key Responsibilities:

  • Parameter validation against expected parameter sets

  • Backend detection and appropriate method dispatch

  • Parameter transformation for SciPy compatibility

  • Stan code generation for probability function calls

The class automatically handles the complexities of:

  • Converting between parameter naming conventions

  • Applying parameter transformations for different backends

  • Generating appropriate function calls for each backend

PARAMETER: parameters.Parameter

Reference to the Parameter subclass for which this CDFLike class applies. Should be set by the metaclass.

SCIPY_FUNC: str

Name of the SciPy method for this operation (e.g., ‘cdf’, ‘sf’, ‘log_cdf’, ‘log_sf’). Should be set by subclasses.

STAN_SUFFIX: str

Suffix for Stan function name generation (e.g., “cdf”). Should be set by subclasses.

TORCH_FUNC: str

Name of the PyTorch method for this operation (e.g., ‘cdf’, ‘log_cdf’, ‘log_sf’). Should be set by subclasses.

check_parameters(kwargset: set[str]) → None[source]

Validate that provided parameters match distribution requirements.

Parameters:

kwargset (set[str]) – Set of parameter names provided

Raises:

  • TypeError – If unexpected parameters are provided

  • TypeError – If required parameters are missing

This method ensures that the CDF transformation receives exactly the parameters required by the underlying probability distribution, with no additional or missing parameters.

abstractmethod run_np_torch_op(**draws)[source]

Execute the CDF-like operation using NumPy or PyTorch backend as appropriate.

Parameters:

draws (dict) – Dictionary of parameter draws for the operation

Returns:

CDFLike evaluation results

Return type:

Union[np.ndarray, torch.Tensor]

Raises:

TypeError – If unsupported module type is detected

This abstract method implements the core computational logic for evaluating the CDFLike transformation. It automatically detects the computational backend and applies appropriate parameter transformations.

Backend Handling:

  • NumPy: Uses SciPy distribution methods with parameter transforms

  • PyTorch: Creates distribution objects and calls appropriate methods

  • Other: Raises TypeError for unsupported backends

The method separates the evaluation point (x) from distribution parameters and handles backend-specific parameter naming and transformation requirements.

write_stan_operation(**kwargs) → str[source]

Generate Stan code for the CDFLike operation.

Parameters:

kwargs (dict[str, str]) – Formatted parameter strings for Stan code generation

Returns:

Stan function call string

Return type:

str

This method constructs the appropriate Stan function call for the CDF operation, using the distribution name, operation suffix, and properly ordered parameters.

The generated Stan code follows the pattern: distribution_suffix(x | param1, param2, …)

Where the parameters are ordered according to the distribution’s Stan parameter ordering conventions.

Concrete Classes

Each of the four CDF-like operations is implemented as a separate subclass of the base class:

class scistanpy.model.components.transformations.cdfs.CDF(
x: custom_types.CombinableParameterType,
shape: tuple[custom_types.Integer, ...] | custom_types.Integer = (),
**params: custom_types.CombinableParameterType,
)[source]

Bases: CDFLike

Standard cumulative distribution function transformation.

Computes \(P(X \leq x)\) for a given distribution and evaluation point.

Parameters:

  • x (custom_types.CombinableParameterType) – Values at which to evaluate the CDF

  • shape (Union[tuple[custom_types.Integer, ...], custom_types.Integer]) – Shape of the output. Defaults to ().

  • params (custom_types.CombinableParameterType) – Distribution parameters

Mathematical Definition:
\[F(X) = P(X \leq x) = \int_{-\infty}^{x} f(t) dt\]

Where \(f(t)\) is the probability density function of the distribution.

Common Applications:

  • Computing tail probabilities

  • Implementing truncated distributions

  • Calculating quantiles and percentiles

  • Model validation through probability plots

Example:
>>> # Via parameter instance (typical usage)
>>> normal_param = Normal(mu=0.0, sigma=1.0)
>>> cdf_transform = normal_param.cdf(x=data_points)
>>>
>>> # Direct instantiation (less common)
>>> cdf_transform = Normal.CDF(x=values, mu=0.0, sigma=1.0)
PARAMETER: parameters.Parameter

Reference to the Parameter subclass for which this CDFLike class applies. Should be set by the metaclass.

SCIPY_FUNC: str = 'cdf'

Name of the SciPy method for this operation (e.g., ‘cdf’, ‘sf’, ‘log_cdf’, ‘log_sf’). Should be set by subclasses.

STAN_SUFFIX: str = 'cdf'

Suffix for Stan function name generation (e.g., “cdf”). Should be set by subclasses.

TORCH_FUNC: str = 'cdf'

Name of the PyTorch method for this operation (e.g., ‘cdf’, ‘log_cdf’, ‘log_sf’). Should be set by subclasses.

run_np_torch_op(**draws)[source]

Execute CDF computation using appropriate backend.

Parameters:

draws (dict) – Parameter draws for the computation

Returns:

CDF values P(X ≤ x)

Return type:

Union[np.ndarray, torch.Tensor]

This implementation uses the base class method directly as both NumPy and PyTorch provide direct CDF computation methods.

class scistanpy.model.components.transformations.cdfs.LogCDF(
x: custom_types.CombinableParameterType,
shape: tuple[custom_types.Integer, ...] | custom_types.Integer = (),
**params: custom_types.CombinableParameterType,
)[source]

Bases: CDFLike

Logarithmic cumulative distribution function transformation.

Computes \(\log(P(X \leq x)) = \log(F(x))\) for numerical stability when dealing with very small probabilities. This is essential for computations involving extreme tail probabilities.

Parameters:

  • x (custom_types.CombinableParameterType) – Values at which to evaluate the log CDF

  • shape (Union[tuple[custom_types.Integer, ...], custom_types.Integer]) – Shape of the output. Defaults to ().

  • params (custom_types.CombinableParameterType) – Distribution parameters

Mathematical Definition:
\[\log F(x) = \log(P(X \leq x))\]
Numerical Advantages:

  • Prevents underflow for very small probabilities

  • Enables stable computation in log-space

  • Essential for extreme value analysis

Common Applications:

  • Extreme value analysis and rare event modeling

  • Numerical optimization in log-space

  • MCMC sampling with extreme parameter values

  • Likelihood computations for tail events

The implementation handles backend-specific log CDF methods:

  • NumPy: Uses SciPy’s logcdf methods when available

  • PyTorch: Uses log_cdf methods or log(cdf) fallback

Example:
>>> # Extreme tail probability
>>> normal_param = Normal(mu=0, sigma=1)
>>> log_tail_prob = normal_param.log_cdf(x=extreme_values)
PARAMETER: parameters.Parameter

Reference to the Parameter subclass for which this CDFLike class applies. Should be set by the metaclass.

SCIPY_FUNC: str = 'logcdf'

Name of the SciPy method for this operation (e.g., ‘cdf’, ‘sf’, ‘log_cdf’, ‘log_sf’). Should be set by subclasses.

STAN_SUFFIX: str = 'lcdf'

Suffix for Stan function name generation (e.g., “cdf”). Should be set by subclasses.

TORCH_FUNC: str = 'log_cdf'

Name of the PyTorch method for this operation (e.g., ‘cdf’, ‘log_cdf’, ‘log_sf’). Should be set by subclasses.

run_np_torch_op(**draws)[source]

Execute log CDF computation with appropriate numerical handling.

Parameters:

draws (dict) – Parameter draws for the computation

Returns:

Log CDF values \(\log(P(X \leq x))\)

Return type:

Union[np.ndarray, torch.Tensor]

Raises:

TypeError – If unsupported output type is encountered

class scistanpy.model.components.transformations.cdfs.SurvivalFunction(
x: custom_types.CombinableParameterType,
shape: tuple[custom_types.Integer, ...] | custom_types.Integer = (),
**params: custom_types.CombinableParameterType,
)[source]

Bases: CDFLike

Survival function (complementary CDF) transformation.

Computes \(P(X \gt x) = 1 - P(X \leq x)\) for a given distribution and evaluation point.

Parameters:

  • x (custom_types.CombinableParameterType) – Values at which to evaluate the survival function

  • shape (Union[tuple[custom_types.Integer, ...], custom_types.Integer]) – Shape of the output. Defaults to ().

  • params (custom_types.CombinableParameterType) – Distribution parameters

Mathematical Definition:
\[S(x) = P(X \gt x) = 1 - F(x) = \int_{x}^{\infty} f(t) dt\]

Where \(F(x)\) is the CDF and \(f(t)\) is the probability density function.

Common Applications:

  • Survival analysis and time-to-event modeling

  • Reliability engineering and failure analysis

  • Risk assessment and hazard modeling

  • Complementary probability calculations

The implementation automatically handles backend differences:

  • NumPy: Uses SciPy’s direct survival function methods

  • PyTorch: Computes 1 - CDF

Example:
>>> # Survival analysis
>>> survival_times = Exponential(rate=0.1)
>>> survival_prob = survival_times.ccdf(x=time_points)
PARAMETER: parameters.Parameter

Reference to the Parameter subclass for which this CDFLike class applies. Should be set by the metaclass.

SCIPY_FUNC: str = 'sf'

Name of the SciPy method for this operation (e.g., ‘cdf’, ‘sf’, ‘log_cdf’, ‘log_sf’). Should be set by subclasses.

STAN_SUFFIX: str = 'ccdf'

Suffix for Stan function name generation (e.g., “cdf”). Should be set by subclasses.

TORCH_FUNC: str = 'cdf'

Name of the PyTorch method for this operation (e.g., ‘cdf’, ‘log_cdf’, ‘log_sf’). Should be set by subclasses.

run_np_torch_op(**draws)[source]

Execute survival function computation with backend-specific handling.

Parameters:

draws (dict) – Parameter draws for the computation

Returns:

Survival function values \(P(X \gt x)\)

Return type:

Union[np.ndarray, torch.Tensor]

Raises:

TypeError – If unsupported output type is encountered

This method handles the difference between NumPy and PyTorch:

  • NumPy: SciPy provides direct survival function methods

  • PyTorch: Computes 1 - CDF

class scistanpy.model.components.transformations.cdfs.LogSurvivalFunction(
x: custom_types.CombinableParameterType,
shape: tuple[custom_types.Integer, ...] | custom_types.Integer = (),
**params: custom_types.CombinableParameterType,
)[source]

Bases: CDFLike

Logarithmic survival function transformation.

Computes \(\log(P(X > x)) = \log(1 - F(x))\) for numerical stability when dealing with survival probabilities that may be very close to zero or one. Essential for stable survival analysis computations.

Parameters:

  • x (custom_types.CombinableParameterType) – Values at which to evaluate the log survival function

  • shape (Union[tuple[custom_types.Integer, ...], custom_types.Integer]) – Shape of the output. Defaults to ().

  • params (custom_types.CombinableParameterType) – Distribution parameters

Mathematical Definition:
\[\log S(x) = \log(P(X > x)) = \log(1 - F(x))\]

Where \(F(x)\) is the CDF.

Numerical Advantages:

  • Prevents underflow for probabilities near 0 or 1

  • Maintains precision for extreme survival times

  • Enables stable log-space arithmetic

  • Critical for numerical stability in survival models

Common Applications:

  • Survival analysis with extreme event times

  • Reliability engineering with high reliability systems

  • Hazard modeling with rare failure events

  • Log-likelihood computations for survival models

The implementation provides numerically stable computation:

  • NumPy: Uses SciPy’s logsf methods for direct computation

  • PyTorch: Uses log_sf methods or \(\text{log1p}(-cdf)\) as fallback

PARAMETER: parameters.Parameter

Reference to the Parameter subclass for which this CDFLike class applies. Should be set by the metaclass.

SCIPY_FUNC: str = 'logsf'

Name of the SciPy method for this operation (e.g., ‘cdf’, ‘sf’, ‘log_cdf’, ‘log_sf’). Should be set by subclasses.

STAN_SUFFIX: str = 'lccdf'

Suffix for Stan function name generation (e.g., “cdf”). Should be set by subclasses.

TORCH_FUNC: str = 'log_sf'

Name of the PyTorch method for this operation (e.g., ‘cdf’, ‘log_cdf’, ‘log_sf’). Should be set by subclasses.

run_np_torch_op(**draws)[source]

Execute log survival function computation with numerical stability.

Parameters:

draws (dict) – Parameter draws for the computation

Returns:

Log survival function values \(\log(P(X \gt x))\)

Return type:

Union[np.ndarray, torch.Tensor]

Raises:

TypeError – If unsupported output type is encountered

This method ensures numerical stability by:

  • Using native log survival function methods when available

  • Using \(\text{log1p}(-cdf)\) for PyTorch when direct methods unavailable

  • Handling precision issues near probability boundaries