Python Interface#

Installation#

From PyPI#

For convience, BridgeStan is uploaded to the Python Package Index each release.

pip install bridgestan

The first time you need it, the BridgeStan source code will be downloaded and placed in ~/.bridgestan/. If you prefer to use a source distribution of BridgeStan, consult the following section.

From Source#

This assumes you have followed the Getting Started guide to install BridgeStan’s pre-requisites and downloaded a copy of the BridgeStan source code.

To install the Python interface, you can either install it directly from Github with

pip install "git+https://github.com/roualdes/bridgestan.git#egg=bridgestan&subdirectory=python"

Or, since you have already downloaded the repository, you can run

pip install -e python/

from the BridgeStan folder.

To use the BridgeStan source you’ve manually downloaded instead of one the package will download for you, you must use set_bridgestan_path() or the $BRIDGESTAN environment variable.

Note that the Python package depends on Python 3.9+ and NumPy, and will install NumPy if it is not already installed.

Example Program#

An example program is provided alongside the Python interface code in example.py:

Show example.py
import bridgestan as bs
import numpy as np

stan = "../test_models/bernoulli/bernoulli.stan"
data = "../test_models/bernoulli/bernoulli.data.json"
model = bs.StanModel.from_stan_file(stan, data)

print(f"This model's name is {model.name()}.")
print(f"It has {model.param_num()} parameters.")

x = np.random.random(model.param_unc_num())
q = np.log(x / (1 - x))  # unconstrained scale
lp, grad = model.log_density_gradient(q, jacobian=False)
print(f"log_density and gradient of Bernoulli model: {(lp, grad)}")

API Reference#

StanModel interface#

class bridgestan.StanModel(model_lib: str, model_data: Optional[str] = None, *, seed: int = 1234, chain_id: int = 0)[source]#

A StanModel instance encapsulates a Stan model instantiated with data and provides methods to access parameter names, transforms, log densities, gradients, and Hessians.

The constructor method instantiates a Stan model and sets constant return values. The constructor arguments are

Parameters

  • model_lib – A path to a compiled shared object.

  • model_data – Either a JSON string literal or a path to a data file in JSON format ending in .json.

  • seed – A pseudo random number generator seed.

  • chain_id – A unique identifier for concurrent chains of pseudorandom numbers.

Raises
classmethod from_stan_file(stan_file: str, model_data: Optional[str] = None, *, stanc_args: List[str] = [], make_args: List[str] = [], seed: int = 1234, chain_id: int = 0)[source]#

Construct a StanModel instance from a .stan file, compiling if necessary.

This is equivalent to calling bridgestan.compile_model() and then the constructor of this class.

Parameters

  • stan_file – A path to a Stan model file.

  • model_data – A path to data in JSON format.

  • stanc_args – A list of arguments to pass to stanc3. For example, ["--O1"] will enable compiler optimization level 1.

  • make_args – A list of additional arguments to pass to Make. For example, ["STAN_THREADS=True"] will enable threading for the compiled model. If the same flags are defined in make/local, the versions passed here will take precedent.

  • seed – A pseudo random number generator seed.

  • chain_id – A unique identifier for concurrent chains of pseudorandom numbers.

Raises
log_density(theta_unc: ndarray[Any, dtype[float64]], *, propto: bool = True, jacobian: bool = True) → float[source]#

Return the log density of the specified unconstrained parameters, dropping constant terms that do not depend on the parameters if propto is True and including change of variables terms for constrained parameters if jacobian is True.

Parameters

  • theta_unc – Unconstrained parameter array.

  • propto – True if constant terms should be dropped from the log density.

  • jacobian – True if change-of-variables terms for constrained parameters should be included in the log density.

Returns

The log density.

Raises

RuntimeError – If the C++ Stan model throws an exception.

log_density_gradient(theta_unc: ndarray[Any, dtype[float64]], *, propto: bool = True, jacobian: bool = True, out: Optional[ndarray[Any, dtype[float64]]] = None) → Tuple[float, ndarray[Any, dtype[float64]]][source]#

Return a tuple of the log density and gradient of the specified unconstrained parameters, dropping constant terms that do not depend on the parameters if propto is True and including change of variables terms for constrained parameters if jacobian is True.

Parameters

  • theta_unc – Unconstrained parameter array.

  • propto – True if constant terms should be dropped from the log density.

  • jacobian – True if change-of-variables terms for constrained parameters should be included in the log density.

  • out – A location into which the gradient is stored. If provided, it must have shape (D, ) where D is the number of parameters. If not provided, a freshly allocated array is returned.

Returns

A tuple consisting of log density and gradient.

Raises

  • ValueError – If out is specified and is not the same shape as the gradient.

  • RuntimeError – If the C++ Stan model throws an exception.

log_density_hessian(theta_unc: ndarray[Any, dtype[float64]], *, propto: bool = True, jacobian: bool = True, out_grad: Optional[ndarray[Any, dtype[float64]]] = None, out_hess: Optional[ndarray[Any, dtype[float64]]] = None) → Tuple[float, ndarray[Any, dtype[float64]], ndarray[Any, dtype[float64]]][source]#

Return a tuple of the log density, gradient, and Hessian of the specified unconstrained parameters, dropping constant terms that do not depend on the parameters if propto is True and including change of variables terms for constrained parameters if jacobian is True.

Parameters

  • theta_unc – Unconstrained parameter array.

  • propto – True if constant terms should be dropped from the log density.

  • jacobian – True if change-of-variables terms for constrained parameters should be included in the log density.

  • out_grad – A location into which the gradient is stored. If provided, it must have shape (D, ) where D is the number of parameters. If not provided, a freshly allocated array is returned.

  • out_hess – A location into which the Hessian is stored. If provided, it must have shape (D, D), where D is the number of parameters. If not provided, a freshly allocated array is returned.

Returns

A tuple consisting of the log density, gradient, and Hessian.

Raises

  • ValueError – If out_grad is specified and is not the same shape as the gradient or if out_hess is specified and it is not the same shape as the Hessian.

  • RuntimeError – If the C++ Stan model throws an exception.

model_info() → str[source]#

Return compilation information about the model. For example, this includes the current Stan version and important compiler settings.

Returns

Information about the compiled Stan model.

name() → str[source]#

Return the name of the Stan model.

Returns

The name of Stan model.

param_constrain(theta_unc: ndarray[Any, dtype[float64]], *, include_tp: bool = False, include_gq: bool = False, out: Optional[ndarray[Any, dtype[float64]]] = None) → ndarray[Any, dtype[float64]][source]#

Return the constrained parameters derived from the specified unconstrained parameters as an array, optionally including the transformed parameters and/or generated quantitities as specified. Including generated quantities uses the PRNG and may update its state. Setting out avoids allocation of a new array for the return value.

Parameters

  • theta_unc – Unconstrained parameter array.

  • include_tp – True to include transformed parameters.

  • include_gq – True to include generated quantities.

  • out – A location into which the result is stored. If provided, it must have shape (D, ), where D is the number of constrained parameters. If not provided or None, a freshly allocated array is returned.

Returns

The constrained parameter array.

Raises

  • ValueError – If out is specified and is not the same shape as the return.

  • RuntimeError – If the C++ Stan model throws an exception.

param_names(*, include_tp: bool = False, include_gq: bool = False) → List[str][source]#

Return the indexed names of the parameters, including transformed parameters and/or generated quantities as indicated. For containers, indexes are separated by periods (.). For example, the scalar a has indexed name a, the vector entry a[1] has indexed name a.1 and the matrix entry a[2, 3] has indexed name a.2.3. Parameter order of the output is column major and more generally last-index major for containers.

Parameters

  • include_tp – True to include transformed parameters.

  • include_gq – True to include generated quantities.

Returns

The indexed names of the parameters.

param_num(*, include_tp: bool = False, include_gq: bool = False) → int[source]#

Return the number of parameters, including transformed parameters and/or generated quantities as indicated.

Parameters

  • include_tp – True to include the transformed parameters.

  • include_gq – True to include the generated quantities.

Returns

The number of parameters.

param_unc_names() → List[str][source]#

Return the indexed names of the unconstrained parameters. For example, a scalar unconstrained parameter b has indexed name b and a vector entry b[3] has indexed name b.3.

Returns

The indexed names of the unconstrained parameters.

param_unc_num() → int[source]#

Return the number of unconstrained parameters.

Returns

The number of unconstrained parameters.

param_unconstrain(theta: ndarray[Any, dtype[float64]], *, out: Optional[ndarray[Any, dtype[float64]]] = None) → ndarray[Any, dtype[float64]][source]#

Return the unconstrained parameters derived from the specified constrained parameters. Setting out avoids allocation of a new array for the return value.

Parameters

  • theta – Constrained parameter array.

  • out – A location into which the result is stored. If provided, it must have shape (D, ), where D is the number of unconstrained parameters. If not provided or None, a freshly allocated array is returned.

Raises

  • ValueError – If out is specified and is not the same shape as the return.

  • RuntimeError – If the C++ Stan model throws an exception.

param_unconstrain_json(theta_json: str, *, out: Optional[ndarray[Any, dtype[float64]]] = None) → ndarray[Any, dtype[float64]][source]#

Return an array of the unconstrained parameters derived from the specified JSON formatted data. See the CmdStan Reference Manual for the schema definition used.

Parameters

  • theta_json – The JSON encoded constrained parameters.

  • out – A location into which the result is stored. If provided, it must have shape (D, ), where D is the number of unconstrained parameters. If not provided or None, a freshly allocated array is returned.

Returns

The unconstrained parameter array.

Raises

  • ValueError – If out is specified and is not the same shape as the return value.

  • RuntimeError – If the C++ Stan model throws an exception.

Compilation utilities#

bridgestan.compile_model(stan_file: str, *, stanc_args: List[str] = [], make_args: List[str] = []) → Path[source]#

Run BridgeStan’s Makefile on a .stan file, creating the .so used by the StanModel class.

This function assumes that the path to BridgeStan is valid. This can be set with set_bridgestan_path().

Parameters

  • stan_file – A path to a Stan model file.

  • stanc_args – A list of arguments to pass to stanc3. For example, ["--O1"] will enable compiler optimization level 1.

  • make_args – A list of additional arguments to pass to Make. For example, ["STAN_THREADS=True"] will enable threading for the compiled model. If the same flags are defined in make/local, the versions passed here will take precedent.

Raises
bridgestan.set_bridgestan_path(path: str) → None[source]#

Set the path to BridgeStan.

This should point to the top-level folder of the repository.

By default this is set to the value of the environment variable BRIDGESTAN, or to the folder above the location of this package (which, assuming a source installation, corresponds to the repository root).