CmdStanPy

CmdStanPy is a lightweight Python interface to CmdStan. It provides classes and methods to perform Bayesian inference by wrapping the CmdStan file-based command line interface.

Key capabilities include:

• Compiling Stan models.
• Performing inference using various algorithms:
  • Exact Bayesian estimation via the NUTS-HMC sampler.
  • Approximate Bayesian estimation via Pathfinder and ADVI.
  • MAP estimation via optimization.
• Generating new quantities of interest from existing samples.
• Managing inference outputs, including extracting information, summarizing results, and saving outputs.

Because it uses minimal memory beyond what CmdStan itself requires, it is suitable for complex models and large datasets compared to PyStan or RStan.

Several major Python and statistical software packages leverage CmdStanPy or Stan models for their functionality:

• Prophet: A forecasting procedure for time series data using additive models with non-linear trends and seasonality.
• ArviZ: A package for exploratory analysis of Bayesian models, providing tools for posterior analysis, data storage, model checking, comparison, and diagnostics.
• BridgeStan: Provides efficient in-memory access (via Python, Julia, and R) to Stan model methods, including log densities, gradients, Hessians, and transforms.

To compile Stan programs, you need a modern C++ compiler and GNU-Make. Requirements vary by OS:

• Linux: Requires g++ 4.9.3 or newer. GNU-Make is usually pre-installed.
• MacOS: Requires Xcode and Xcode command line tools. Install them via xcode-select --install.
• Windows: Recommended toolchain is RTools 4.0 (which includes g++ 8 and Mingw). You can install this automatically via cmdstanpy.install_cmdstan(compiler=True).

Note for PyStan users: If you use the RTools toolchain, install CmdStanPy in a separate virtual environment from PyStan to avoid conflicts.

CmdStanPy is a lightweight pure-Python interface to CmdStan. It does not interface directly with C++; instead, it calls compiled CmdStan executables.

Key characteristics include:

• Development vs. Production: By default, it favors development mode by storing output files on a temporary filesystem. However, all aspects of a run can be specified for production/distributed workflows.
• Modular Design: CmdStanPy is responsible for producing MCMC samples or point estimates. It is designed to be used alongside other packages for downstream analysis and visualization.
• Low Memory Overhead: It primarily tracks CmdStan input and output files, using minimal memory beyond what the underlying CmdStan process requires.

CmdStanPy can be installed via PyPI or Conda Forge. It has minimal Python dependencies, requiring only numpy and pandas.

# Via PyPI
pip install cmdstanpy

# Via Conda Forge
conda install -c conda-forge cmdstanpy

You can install the CmdStanPy package using pip. Note that if you use this method, you must manually install CmdStan afterwards (see the 'Install CmdStan' section).

To install the base package:

pip install --upgrade cmdstanpy

To install with optional dependencies, such as xarray for n-dimensional labeled dataset outputs:

pip install --upgrade cmdstanpy[all]

Jupyter Notebook Users: If you use Jupyter, install ipywidgets to ensure progress bars (from tqdm) display correctly in the browser.

For debugging purposes, you can interact directly with the cmdstanpy logger to capture DEBUG level logs (which are hidden by default) and redirect them to a file. This involves accessing the cmdstanpy logger via the logging module, clearing existing handlers, and attaching a FileHandler.

import logging

cmdstanpy_logger = logging.getLogger("cmdstanpy")
cmdstanpy_logger.disabled = False
# remove all existing handlers
cmdstanpy_logger.handlers = []

cmdstanpy_logger.setLevel(logging.DEBUG)
handler = logging.FileHandler('all.log')
handler.setLevel(logging.DEBUG)
handler.setFormatter(
    logging.Formatter(
        '%(asctime)s - %(name)s - %(levelname)s - %(message)s',
        "%H:%M:%S",
    )
)
cmdstanpy_logger.addHandler(handler)

# Now running the model will write all logs to 'all.log'
fit = model.sample(data=data_file, show_progress=False)

To save time when starting new Bayesian statistical analysis or Stan-based Python projects, you can use community-maintained templates:

• bibat: A batteries-included template designed specifically for Bayesian statistical analysis projects.
• cookiecutter-cmdstanpy-wrapper: A cookiecutter template for integrating Stan models into Python packages. It includes support for pre-compiling models as part of the package distribution process.

To perform Bayesian inference using Hamiltonian Monte Carlo (HMC), use the sample method on a CmdStanModel instance. This method returns a CmdStanMCMC object.

Data can be provided as:

1. A filepath to a JSON file.
2. A Python dictionary mapping variable names to values.

By default, sample runs 4 sampler chains.

# Using a JSON data file
data_file = os.path.join('users-guide', 'examples', 'bernoulli.data.json')
fit = model.sample(data=data_file)