Python Interface#

Installation#

From PyPI#

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

pip install bridgestan

The first time you compile a model, the BridgeStan source code for your current version will be downloaded and placed in ~/.bridgestan/. If you prefer to use a source distribution of BridgeStan, consult the following section.

Note that the system pre-requisites from the Getting Started guide are still required and will not be automatically installed by this method.

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 numpy as np

import bridgestan as bs

# These paths are what they are because this example lives in a subfolder
# of the BridgeStan repository. If you're running this on your own, you
# will most likely want to delete the next line (to have BridgeStan
# download its sources for you) and change the paths on the following two
bs.set_bridgestan_path("..")

stan = "../test_models/bernoulli/bernoulli.stan"
data = "../test_models/bernoulli/bernoulli.data.json"
model = bs.StanModel(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 | PathLike, data: str | PathLike | None = None, *, seed: int = 1234, stanc_args: List[str] = [], make_args: List[str] = [], capture_stan_prints: bool = True, warn: bool = True, model_data: str | None = None)[source]#

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

Construct a StanModel object for a compiled Stan model and data given constructor arguments.

Parameters:

model_lib – A system path to compiled shared object or a .stan file to be compiled.
data – Data for the model. Either a JSON string literal or a system path to a data file in JSON format ending in .json. If the model does not require data, this can be either the empty string or None (the default).
seed – A pseudo random number generator seed, used for RNG functions in the transformed data block.
stanc_args – A list of arguments to pass to stanc3 if the model is not compiled. For example, ["--O1"] will enable compiler optimization level 1.
make_args – A list of additional arguments to pass to Make if the model is not compiled. 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.
capture_stan_prints –
If True, capture all print statements from the Stan model and print them from Python. This has no effect if the model does not contain any print statements, but may have a performance impact if it does. If False, print statements from the Stan model will be sent to cout and will not be seen in Jupyter or capturable with contextlib.redirect_stdout().

Note: If this is set for a model, any other models instantiated from the same shared library will also have the callback set, even if they were created before this model.
warn – If False, the warning about re-loading the same shared object is suppressed.
model_data – Deprecated former name for data.

Raises:

FileNotFoundError or PermissionError – If model_lib is not readable or data is specified and not a path to a readable file.
RuntimeError – If there is an error instantiating the model from C++.

classmethod from_stan_file(stan_file: str, model_data: str | None = None, *, stanc_args: List[str] = [], make_args: List[str] = [], seed: int = 1234, capture_stan_prints: bool = True)[source]#

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

DEPRECATED: You should use the constructor on a .stan file instead.

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, used for RNG functions in the transformed data block.
capture_stan_prints – If True, capture all print statements from the Stan model and print them from Python. This has no effect if the model does not contain any print statements, but may have a performance impact if it does. If False, print statements from the Stan model will be sent to cout and will not be seen in Jupyter or capturable with contextlib.redirect_stdout.

Raises:

FileNotFoundError or PermissionError – If stan_file does not exist or is not readable.
ValueError – If BridgeStan cannot be located.
RuntimeError – If compilation fails.

log_density(theta_unc: ndarray[Any, dtype[float64]] | LP_c_double | Array[c_double], *, 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.

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.

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.

Return a tuple of the log density and the product of the Hessian with the specified vector.

Parameters:

theta_unc – Unconstrained parameter array.
v – Vector to multiply by the Hessian.
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 product 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 the log density and the product.

Raises:

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

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.

model_version() → Tuple[int, int, int][source]#: Return the BridgeStan version of the compiled model.

name() → str[source]#

Return the name of the Stan model.

Returns:: The name of Stan model.

new_rng(seed) → StanRNG[source]#

Return a new PRNG for use in param_constrain`().

Parameters:: seed – A seed for the PRNG.
Returns:: A new PRNG wrapper.

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.
rng – A StanRNG object to use for generating random numbers, see new_rng`(). Must be specified if include_gq is True.

Returns:

The constrained parameter array.

Raises:

ValueError – If out is specified and is not the same shape as the return.
ValueError – If rng is None and include_gq is True.
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.

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.

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 | PathLike, *, 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 checks that the path to BridgeStan is valid and will error if not. 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:

FileNotFoundError or PermissionError – If stan_file does not exist or is not readable.
ValueError – If BridgeStan cannot be located.
RuntimeError – If compilation fails.

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

Set the path to BridgeStan.

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