API Reference

stan.build(program_code: str, data: Dict[str, int | float | Sequence[int | float]] = {}, random_seed: int | None = None) → Model[source]

Build (compile) a Stan program.

Parameters:

  • program_code – Stan program code describing a Stan model.

  • data – A Python dictionary or mapping providing the data for the model. Variable names are the keys and the values are their associated values. Default is an empty dictionary, suitable for Stan programs with no data block.

  • random_seed – Random seed, a positive integer for random number generation. Used to make sure that results can be reproduced.

Returns:

an instance of Model

Return type:

Model

Notes

C++ reserved words and Stan reserved words may not be used for variable names; see the Stan User’s Guide for a complete list.

class stan.model.Model(model_name: str, program_code: str, data: Dict[str, int | float | Sequence[int | float]], param_names: Tuple[str, ...], constrained_param_names: Tuple[str, ...], dims: Tuple[Tuple[int, ...]], random_seed: int | None)[source]

Stores data associated with and proxies calls to a Stan model.

Returned by build. Users will not instantiate this class directly.

constrain_pars(unconstrained_parameters: Sequence[float], include_tparams: bool = True, include_gqs: bool = True) → Sequence[float][source]
Transform a sequence of unconstrained parameters to their defined support,

optionally including transformed parameters and generated quantities.

Parameters:

  • unconstrained_parameters – A sequence of unconstrained parameters.

  • include_tparams – Boolean to control whether we include transformed parameters.

  • include_gqs – Boolean to control whether we include generated quantities.

Returns:

A sequence of constrained parameters, optionally including transformed parameters.

Note

The unconstrained parameters are passed to the write_array method of the model_base instance. See model_base.hpp in the Stan C++ library for details.

fixed_param(*, num_chains=4, **kwargs) → Fit[source]

Draw samples from the model using stan::services::sample::fixed_param.

Parameters in kwargs will be passed to the (Python wrapper of) stan::services::sample::fixed_param. Parameter names are identical to those used in CmdStan. See the CmdStan documentation for parameter descriptions and default values.

There is one exception: num_chains. num_chains is a PyStan-specific keyword argument. It indicates the number of independent processes to use when drawing samples.

Returns:

instance of Fit allowing access to draws.

Return type:

Fit

grad_log_prob(unconstrained_parameters: Sequence[float]) → float[source]
Calculate the gradient of the log posterior evaluated at

the unconstrained parameters.

Parameters:

unconstrained_parameters – A sequence of unconstrained parameters.

Returns:

The gradient of the log posterior evaluated at the unconstrained parameters.

Notes

The unconstrained parameters are passed to the log_prob_grad function in stan::model.

hmc_nuts_diag_e_adapt(*, num_chains=4, **kwargs) → Fit[source]

Draw samples from the model using stan::services::sample::hmc_nuts_diag_e_adapt.

Parameters in kwargs will be passed to the (Python wrapper of) stan::services::sample::hmc_nuts_diag_e_adapt. Parameter names are identical to those used in CmdStan. See the CmdStan documentation for parameter descriptions and default values.

There is one exception: num_chains. num_chains is a PyStan-specific keyword argument. It indicates the number of independent processes to use when drawing samples.

Returns:

instance of Fit allowing access to draws.

Return type:

Fit

log_prob(unconstrained_parameters: Sequence[float], adjust_transform: bool = True) → float[source]

Calculate the log probability of a set of unconstrained parameters.

Parameters:

  • unconstrained_parameters – A sequence of unconstrained parameters.

  • adjust_transform – Apply jacobian adjust transform.

Returns:

The log probability of the unconstrained parameters.

Notes

The unconstrained parameters are passed to the log_prob function in stan::model.

sample(*, num_chains=4, **kwargs) → Fit[source]

Draw samples from the model.

Parameters in kwargs will be passed to the default sample function. The default sample function is currently stan::services::sample::hmc_nuts_diag_e_adapt. Parameter names are identical to those used in CmdStan. See the CmdStan documentation for parameter descriptions and default values.

There is one exception: num_chains. num_chains is a PyStan-specific keyword argument. It indicates the number of independent processes to use when drawing samples.

Returns:

instance of Fit allowing access to draws.

Return type:

Fit

Examples

User-defined initial values for parameters must be provided for each chain. Typically they will be the same for each chain. The following example shows how user-defined initial parameters are provided:

>>> program_code = "parameters {real y;} model {y ~ normal(0,1);}"
>>> posterior = stan.build(program_code)
>>> fit = posterior.sample(num_chains=2, init=[{"y": 3}, {"y": 3}])
unconstrain_pars(constrained_parameters: Sequence[float]) → Sequence[float][source]
Reads constrained parameter values from their specified context and returns a

sequence of unconstrained parameter values.

Parameters:

constrained_parameters – Constrained parameter values and their specified context

Returns:

A sequence of unconstrained parameters.

Note

The unconstrained parameters are passed to the transform_inits method of the model_base instance. See model_base.hpp in the Stan C++ library for details.

class stan.fit.Fit(stan_outputs: Tuple[bytes, ...], num_chains: int, param_names: Tuple[str, ...], constrained_param_names: Tuple[str, ...], dims: Tuple[Tuple[int, ...]], num_warmup: int, num_samples: int, num_thin: int, save_warmup: bool)[source]

Stores draws from one or more chains.

Returned by methods of a Model. Users will not instantiate this class directly.

A Fit instance works like a Python dictionary. A user-friendly views of draws is available via to_frame.

to_frame()[source]

Return view of draws as a pandas DataFrame.

If pandas is not installed, a RuntimeError will be raised.

Returns:

DataFrame with num_draws rows and

num_flat_params columns.

Return type:

pandas.DataFrame

class stan.plugins.PluginBase[source]

Base class for PyStan plugins.

Plugin developers should create a class which subclasses PluginBase. This class must be referenced in their package’s entry points section.

on_post_sample(fit: Fit) → Fit[source]

Called with Fit instance when sampling has finished.

The plugin can report information about the samples contained in the Fit object. It may also add to or modify the Fit instance.

If the plugin only analyzes the contents of fit, it must return the fit.

Argument:

fit: Fit instance.

Returns:

The Fit instance.