Model API Reference

Core Model class for SciStanPy Bayesian modeling framework.

This module contains the fundamental Model class that serves as the primary interface for building, compiling, and executing Bayesian models in SciStanPy. The Model class orchestrates the composition of model components (Parameters, Constants, and Transformed Parameters) that define the probabilistic structure of the model.

The Model class uses a metaclass pattern to automatically register model components defined as instance attributes, enabling intuitive model construction through simple attribute assignment. It supports multiple backends including Stan for Hamiltonai Monte Carlo sampling and PyTorch for maximum likelihood estimation.

Core Model Class

class scistanpy.model.model.Model(
*args,
default_data: dict[str, ndarray[tuple[int, ...], dtype[_ScalarType_co]]] | None = None,
**kwargs,
)[source]

Bases: object

Primary interface for Bayesian model construction and analysis in SciStanPy.

The Model class provides a declarative interface for building Bayesian models by composing Parameters, Constants, and Transformed Parameters. It automatically handles component registration and validation, and provides methods for sampling, compilation, and analysis across multiple backends.

Parameters:

default_data (Optional[dict[str, npt.NDArray]]) – Default observed data for model observables. When provided, any instance method requiring data will use these if not otherwise provided. Defaults to None.

The class uses a metaclass pattern that automatically registers model components defined as instance attributes. Components are validated for naming conventions and automatically assigned model variable names.

Models are built by subclassing Model and defining components as instance attributes in the __init__ method. The metaclass automatically discovers and registers these components.

Example:
>>> class MyModel(Model):
...     def __init__(self):
...         super().__init__()
...         self.mu = ssp.parameters.Normal(0.0, 1.0)
...         self.sigma = ssp.parameters.HalfNormal(1.0)
...         self.y = ssp.parameters.Normal(self.mu, self.sigma, observable=True)
>>>
>>> model = MyModel()
>>> prior_samples = model.draw(n=1000)
>>> model.prior_predictive()  # Interactive dashboard for prior exploration
>>> mle_result = model.mle() # Maximum likelihood estimation
>>> mcmc_result = model.mcmc() # Hamiltonian Monte Carlo sampling in Stan

Note

All Parameters have a shape attribute that defines their dimensionality. For example, I can define a 2D array of parameters like this:

>>> import scistanpy as ssp
>>> self.beta = ssp.parameters.Normal(mu = 0.0, sigma = 1.0, shape=(3, 4))

This will create 12 independent Normal parameters arranged in a 3x4 array. All SciStanPy parameters and operations support broadcasting using the same rules as NumPy, so you can easily define complex hierarchical models with minimal code. For example, I can define a child parameter that depends on beta like this:

>>> self.alpha = ssp.parameters.Normal(mu = self.beta, sigma = 1.0, shape = (10, 3, 4))

This will create a 10x3x4 array of Normal parameters where each slice along the first dimension represents a set of parameters drawn from a Normal distribution whose mean is given by a single element of beta.

Hint

Follow these best practices when building models:

  1. Use descriptive component names that reflect their scientific meaning

  2. Set default_data for models with fixed datasets to streamline workflows

  3. Start with prior predictive checks before fitting to real data

  4. Use simulation methods to validate model implementation

  5. Choose appropriate backends for different tasks (PyTorch for MLE, Stan for MCMC)

  6. Validate models incrementally by building from simple to complex

property all_model_components: tuple[AbstractModelComponent, ...]

Get all model components including unnamed intermediate components.

Returns:

Tuple of all components sorted by variable name

Return type:

tuple[abstract_model_component.AbstractModelComponent, …]

This includes both explicitly named components and any intermediate components created during dependency resolution, providing complete visibility into the model’s computational graph.

property all_model_components_dict: dict[str, AbstractModelComponent]

Get all model components as a dictionary.

Returns:

Dictionary mapping variable names to all components

Return type:

dict[str, abstract_model_component.AbstractModelComponent]

This comprehensive mapping includes both named and intermediate components, enabling full programmatic access to the model structure.

property constant_dict: dict[str, Constant]

Get named constants as a dictionary.

Returns:

Dictionary mapping names to constant components

Return type:

dict[str, constants_module.Constant]

Provides convenient access to model constants for hyperparameter inspection and sensitivity analysis workflows.

property constants: tuple[Constant, ...]

Get all named constants in the model.

Returns:

Tuple of constant components

Return type:

tuple[constants_module.Constant, …]

Constants represent fixed values and hyperparameter specifications that do not change during inference or optimization procedures.

property default_data: dict[str, ndarray[tuple[int, ...], dtype[_ScalarType_co]]] | None

Get the default observed data for model observables.

Returns:

Dictionary mapping observable names to their default data

Return type:

dict[str, npt.NDArray] | None

Raises:

ValueError – If default data has not been set

Default data is used automatically by methods like mle() and mcmc() when no explicit data is provided, streamlining common workflows.

draw(
n: custom_types.Integer,
*,
named_only: Literal[True],
as_xarray: Literal[False],
seed: 'custom_types.Integer' | None,
) → dict[str, ndarray[tuple[int, ...], dtype[_ScalarType_co]]][source]
draw(
n: custom_types.Integer,
*,
named_only: Literal[False],
as_xarray: Literal[False],
seed: 'custom_types.Integer' | None,
) → dict[AbstractModelComponent, ndarray[tuple[int, ...], dtype[_ScalarType_co]]]
draw(
n: custom_types.Integer,
*,
named_only: Literal[True],
as_xarray: Literal[True],
seed: 'custom_types.Integer' | None,
) → Dataset
draw(
n: custom_types.Integer,
*,
named_only: Literal[False],
as_xarray: Literal[True],
seed: 'custom_types.Integer' | None,
) → Dataset

Draw samples from the model’s prior distribution.

This method generates samples from all elements of the model by traversing the dependency graph and sampling from each component.

Parameters:

  • n (custom_types.Integer) – Number of samples to draw from each component.

  • named_only (bool) – Whether to return only named components. Defaults to True.

  • as_xarray (bool) – Whether to return results as xarray Dataset. Defaults to False.

  • seed (Optional[custom_types.Integer]) – Random seed for reproducible sampling. Defaults to None.

Returns:

Sampled values in requested format

Return type:

Union[dict[str, npt.NDArray], dict[AbstractModelComponent, npt.NDArray], xr.Dataset]

Example:
>>> # Draw 1000 samples as dictionary
>>> samples = model.draw(1000)
>>> # Draw 1000 samples as an xarray Dataset
>>> dataset = model.draw(1000, as_xarray=True)
get_dimname_map() → dict[tuple['custom_types.Integer', 'custom_types.Integer'], str][source]

Generate mapping from dimension specifications to dimension names.

This method creates a dictionary that maps dimension level and size tuples to appropriate dimension names for xarray dataset construction. It ensures dimension names don’t conflict with model variable names.

Returns:

Dictionary mapping (level, size) tuples to dimension names

Return type:

dict[tuple[custom_types.Integer, custom_types.Integer], str]

The mapping is used to create consistent dimension naming across all xarray datasets generated from model samples, ensuring proper coordinate alignment and data structure.

Only dimensions with size > 1 are assigned names, as singleton dimensions are typically squeezed during xarray construction.

property has_default_data: bool

Check whether the model has default data configured.

Returns:

True if default data is set, False otherwise

Return type:

bool

This property is useful for conditional logic that depends on whether default data is available for automatic use in methods.

property hyperparameter_dict: dict[str, Parameter]

Get hyperparameters as a dictionary.

Returns:

Dictionary mapping names to hyperparameters

Return type:

dict[str, parameters_module.Parameter]

Provides convenient access to the model’s hyperparameters by name for prior specification and sensitivity analysis.

property hyperparameters: tuple[Parameter, ...]

Get hyperparameters (parameters with only constant parents).

Returns:

Tuple of parameters that depend only on constants

Return type:

tuple[parameters_module.Parameter, …]

Hyperparameters are the highest-level parameters in the model hierarchy, typically representing prior distribution parameters that are not derived from other random variables.

mcmc(
*,
output_dir: str | None,
force_compile: bool,
stanc_options: dict[str, Any] | None,
cpp_options: dict[str, Any] | None,
user_header: str | None,
model_name: str | None,
inits: str | None,
data: dict[str, ndarray[tuple[int, ...], dtype[_ScalarType_co]]] | None,
delay_run: Literal[False],
**sample_kwargs,
) → hmc_results.SampleResults[source]
mcmc(
*,
output_dir: str | None,
force_compile: bool,
stanc_options: dict[str, Any] | None,
cpp_options: dict[str, Any] | None,
model_name: str | None,
user_header: str | None,
inits: str | None,
data: dict[str, ndarray[tuple[int, ...], dtype[_ScalarType_co]]] | None,
delay_run: Literal[True] | str,
**sample_kwargs,
) → None

Perform Hamiltonia Monte Carlo sampling using Stan backend.

This method compiles the model to Stan and executes Hamiltonian Monte Carlo sampling to generate posterior samples. It supports both immediate execution and delayed runs for batch processing.

Parameters:

  • output_dir (Optional[str]) – Directory for compilation and output files. Defaults to None, in which case all raw outputs will be saved to a temporary directory and be accessible only for the lifetime of this object.

  • force_compile (bool) – Whether to force recompilation of Stan model. Defaults to False.

  • stanc_options (Optional[dict[str, Any]]) – Options for Stan compiler. Defaults to None (uses DEFAULT_STANC_OPTIONS).

  • cpp_options (Optional[dict[str, Any]]) – Options for C++ compilation. Defaults to None (uses DEFAULT_CPP_OPTIONS).

  • user_header (Optional[str]) – Custom C++ header code. Defaults to None.

  • model_name (Optional[str]) – Name for compiled model. Defaults to ‘model’.

  • inits (Optional[str]) – Initialization strategy. See stan_model.StanModel for options. Defaults to None.

  • data (Optional[dict[str, npt.NDArray]]) – Observed data for observables. Uses default_data defined during initialization if not provided.

  • delay_run (Union[bool, str]) – Whether to delay execution. If True, a pickle file that can be used for delayed execution will be saved to output_dir. A string can also be provided to save the pickle file to an alternate location. Defaults to False (meaning immediate execution).

  • sample_kwargs – Additional arguments passed to Stan sampling. See the cmdstanpy.CmdStanModel.sample for options.

Returns:

MCMC results if delay_run=False, None if delayed

Return type:

Union[hmc_results.SampleResults, None]

Raises:

ValueError – If delay_run is True but output_dir is None

Note

When delay_run=True, the method saves sampling configuration to a pickle file instead of executing immediately. This enables batch processing and distributed computing workflows.

Example:
>>> # Immediate MCMC sampling
>>> results = model.mcmc(chains=4, iter_sampling=2000)
>>> # Delayed execution for batch processing
>>> model.mcmc(delay_run='batch_job.pkl', chains=8, iter_sampling=5000)
mle(
epochs: custom_types.Integer = 100000,
early_stop: custom_types.Integer = 10,
lr: custom_types.Float = 0.001,
data: dict[str, torch.Tensor | npt.NDArray] | None = None,
device: 'custom_types.Integer' | str = 'cpu',
seed: 'custom_types.Integer' | None = None,
mixed_precision: bool = False,
) → mle_module.MLE[source]

Compute maximum likelihood estimates of model parameters.

This method fits a PyTorch model to observed data by minimizing the negative log-likelihood, providing point estimates of all model parameters along with optimization diagnostics.

Parameters:

  • epochs (custom_types.Integer) – Maximum number of training epochs. Note that one step is one epoch as the model must be evaluated over all observable data to calculate loss. Defaults to 100000.

  • early_stop (custom_types.Integer) – Epochs without improvement before stopping. Defaults to 10.

  • lr (custom_types.Float) – Learning rate for optimization. Defaults to 0.001.

  • data (Optional[dict[str, Union[torch.Tensor, npt.NDArray]]]) – Observed data for observables. Uses default_data provided at initialization if not provided.

  • device (Union[custom_types.Integer, str]) – Computation device (‘cpu’, ‘cuda’, or device index). Defaults to ‘cpu’.

  • seed (Optional[custom_types.Integer]) – Random seed for reproducible optimization. Defaults to None.

  • mixed_precision (bool) – Whether to use mixed precision training. Defaults to False.

Returns:

MLE results with parameter estimates and diagnostics

Return type:

mle_module.MLE

The optimization process:

  • Converts model to PyTorch and moves to specified device

  • Trains for epochs number of epochs or until there has been no improvement for early_stop number epochs.

  • Tracks loss trajectory for convergence assessment

  • Returns parameter estimates and fitted distributions

Example:
>>> # Basic MLE with default settings
>>> mle_result = model.mle(data=observed_data)
>>> # GPU-accelerated with custom settings
>>> mle_result = model.mle(data=obs, device='cuda', epochs=50000, lr=0.01)

Note

The mle method is much cheaper to run than mcmc and can be a useful first step for model validation and debugging. Also note that, via the scistanpy.model.results.mle.MLE object returned, you can bootstrap observed data to obtain uncertainty estimates about the observed data.

property named_model_components: tuple[AbstractModelComponent, ...]

Get all named model components.

Returns:

Tuple of named components

Return type:

tuple[abstract_model_component.AbstractModelComponent, …]

Named components are those explicitly assigned as instance attributes during model construction, as opposed to intermediate components created automatically during dependency resolution.

property named_model_components_dict: dict[str, AbstractModelComponent]

Get named model components as a dictionary.

Returns:

Dictionary mapping variable names to named components

Return type:

dict[str, abstract_model_component.AbstractModelComponent]

This provides convenient access to named components by their string names for programmatic model inspection and manipulation.

property observable_dict: dict[str, Parameter]

Get observable parameters as a dictionary.

Returns:

Dictionary mapping names to observable parameters

Return type:

dict[str, parameters_module.Parameter]

Enables convenient access to observable parameters for data specification and model validation workflows.

property observables: tuple[Parameter, ...]

Get all observable parameters in the model (observables are always named).

Returns:

Tuple of parameters marked as observable

Return type:

tuple[parameters_module.Parameter, …]

Observable parameters represent the data-generating components of the model - the variables for which observed data will be provided during inference procedures.

property parameter_dict: dict[str, Parameter]

Get non-observable parameters as a dictionary.

Returns:

Dictionary mapping names to non-observable parameters

Return type:

dict[str, parameters_module.Parameter]

Provides convenient named access to the model’s latent parameters for inspection and programmatic manipulation.

property parameters: tuple[Parameter, ...]

Get all non-observable parameters in the model.

Returns:

Tuple of parameter components that are not observables

Return type:

tuple[parameters_module.Parameter, …]

These are the latent variables and hyperparameters that will be inferred during MCMC sampling or optimized during MLE fitting.

prior_predictive(*, copy_model: bool = False) → Row[source]

Create interactive prior predictive check visualization.

This method generates an interactive dashboard for exploring the model’s prior predictive distribution. Users can adjust model hyperparameters via sliders and immediately see how changes affect prior predictions.

Parameters:

copy_model (bool) – Whether to copy model to avoid modifying original. Defaults to False, meaning the calling model is updated in place by changing slider values and clicking “update model”.

Returns:

Panel dashboard with interactive prior predictive visualization

Return type:

pn.Row

The dashboard includes:

  • Sliders for all adjustable model hyperparameters

  • Multiple visualization modes (ECDF, KDE, violin, relationship plots)

  • Real-time updates as parameters are modified

  • Options for different grouping and display configurations

This is useful for:

  • Prior specification and calibration

  • Understanding model behavior before data fitting

  • Identifying unrealistic prior assumptions

Example:
>>> # Create interactive dashboard
>>> dashboard = model.prior_predictive()
>>> dashboard.servable()  # For web deployment
>>> # Or display in Jupyter notebook
>>> dashboard
simulate_mcmc(
delay_run: Literal[False],
**kwargs,
) → tuple[dict[str, npt.NDArray], 'hmc_results.SampleResults'][source]
simulate_mcmc(delay_run: Literal[True], **kwargs) → None

Simulate data from model prior and perform Hamiltonian Monte Carlo sampling.

This method generates synthetic data from the model’s prior distribution and then performs full Bayesian inference via MCMC. It’s extremely helpful for model validation and posterior recovery testing.

Parameters:

  • delay_run (bool) – Whether to delay MCMC execution. Defaults to False.

  • kwargs – Additional keyword arguments passed to mcmc() method.

Returns:

Tuple of (simulated_data, mcmc_results) if delay_run=False, None if delay_run=True

Return type:

Union[tuple[dict[str, npt.NDArray], hmc_results.SampleResults], None]

The method automatically updates the model name to indicate simulation when using the default name, helping distinguish simulated from real data analyses.

This is crucial for:

  • Validating MCMC implementation correctness

  • Testing posterior recovery in known-truth scenarios

  • Assessing sampler efficiency and convergence

  • Debugging model specification issues

Example:
>>> # Simulate and sample with immediate execution
>>> sim_data, mcmc_results = model.simulate_mcmc(chains=4, iter_sampling=1000)
simulate_mle(
**kwargs,
) → tuple[dict[str, ndarray[tuple[int, ...], dtype[_ScalarType_co]]], MLE][source]

Simulate data from model prior and fit via maximum likelihood.

This method performs a complete simulation study by first generating synthetic data from the model’s prior distribution, then fitting the model to this simulated data using maximum likelihood estimation.

Parameters:

kwargs – Keyword arguments passed to mle() method (except ‘data’)

Returns:

Tuple of (simulated_data, mle_results)

Return type:

tuple[dict[str, npt.NDArray], mle_module.MLE]

This is particularly useful for:

  • Model validation and debugging

  • Assessing parameter identifiability (e.g. by running multiple simulations)

  • Verifying implementation correctness

The simulated data is automatically passed to the MLE fitting procedure, overriding any data specification in kwargs.

Example:
>>> # Simulate and fit with custom settings
>>> sim_data, mle_fit = model.simulate_mle(epochs=10000, lr=0.01)
to_pytorch(seed: 'custom_types.Integer' | None = None) → nn_module.PyTorchModel[source]

Compile the model to a trainable PyTorch module.

This method converts the SciStanPy model into a PyTorch module that can be optimized using standard PyTorch training procedures for maximum likelihood estimation or variational inference. The inputs to this module (i.e., keyword arguments to its forward method) are all observed data; the output is the likelihood of that data given the current model parameters.

Parameters:

seed (Optional[custom_types.Integer]) – Random seed for reproducible compilation. Defaults to None.

Returns:

Compiled PyTorch model ready for training

Return type:

nn_module.PyTorchModel

The compiled model preserves the probabilistic structure while enabling gradient-based optimization of model parameters. It’s particularly useful for maximum likelihood estimation and can leverage GPU acceleration for large models.

to_stan(**kwargs) → StanModel[source]

Compile the model to Stan code for MCMC sampling.

This method automatically generates Stan probabilistic programming language code from the SciStanPy model specification and compiles it for Hamilitonian Monte-Carlo sampling.

Parameters:

kwargs – Additional compilation options passed to StanModel

Returns:

Compiled Stan model ready for MCMC sampling

Return type:

stan_model.StanModel

property transformed_parameter_dict: dict[str, TransformedParameter]

Get named transformed parameters as a dictionary.

Returns:

Dictionary mapping names to transformed parameters

Return type:

dict[str, transformed_parameters_module.TransformedParameter]

Enables convenient access to transformed parameters for model inspection and derived quantity analysis.

property transformed_parameters: tuple[TransformedParameter, ...]

Get all named transformed parameters in the model.

Returns:

Tuple of transformed parameter components

Return type:

tuple[transformed_parameters_module.TransformedParameter, …]

Transformed parameters are deterministic functions of other model components, representing computed quantities like sums, products, or other mathematical transformations.

Utility Methods

scistanpy.model.model.run_delayed_mcmc(filepath: str) → hmc_results.SampleResults[source]

Execute a delayed MCMC run from a pickled configuration file.

This function loads and executes MCMC sampling that was previously configured with Model.mcmc(delay_run=True). It’s useful for running computationally intensive sampling jobs in batch systems or separate processes.

Parameters:

filepath (str) – Path to the pickled MCMC configuration file

Returns:

MCMC sampling results with posterior draws and diagnostics

Return type:

hmc_results.SampleResults

The function automatically enables console output to provide progress feedback during the potentially long-running sampling process.

Example:
>>> # First, create delayed run
>>> model.mcmc(output_dir = ".", delay_run=True, chains=4, iter_sampling=2000)
>>> # Later, execute the run
>>> results = run_delayed_mcmc(f"{model.stan_executable_path}-delay.pkl")