Upgrading to Newer Releases

Upgrading to 3.0

PyStan 3 is a complete rewrite. PyStan runs on Linux and macOS.

PyStan 3 makes numerous backwards-incompatible changes. Many of these changes are introduced to harmonize variable naming practices across the numerous interfaces to the Stan C++ library.

The scope of PyStan 3 is reduced in the interest of freeing up resources to dedicate to making the software more reliable and to guaranteeing timely releases. The default HMC sampler is supported. Variational inference, for example, is no longer supported.

PyStan 3 users aware of changes in variable, function, and method names should be able to upgrade without much difficulty. The basic programming “flow” is essentially unchanged.

Here’s how we draw from the posterior distribution in the eight schools model using PyStan 3:

import stan

schools_code = """data { ..."""
schools_data = {'J': 8, ... }

posterior = stan.build(schools_code, data=schools_data, random_seed=1)
fit = posterior.sample(num_chains=4, num_samples=1000)
fit["eta"]  # array with shape (8, 4000)

Compare this with similar PyStan 2 code:

import pystan

schools_code = """data { ..."""
schools_data = {'J': 8, ... }

sm = pystan.StanModel(model_code=schools_code)
fit = sm.sampling(data=schools_data, iter=1000, chains=4, seed=1)
fit.extract()["eta"]  # array with shape (2000, 8)

Notable changes

  • Use import stan instead of import pystan.

  • Data and random seed are provided earlier, to the build method. Previously these were provided before sampling.

  • Use num_samples to indicate number of desired draws.

  • Use fit["param"] instead of fit.extract()["param"]. The shape of the array returned will be different.

  • Draws are returned in a shape which reflects their shape in the Stan model. Number of draws is the trailing index.

  • The “stansummary” display is no longer supported. Support for displaying effective sample size is planned.

  • The check_hmc_diagnostics function is removed. Support for plugins has been added to allow for the development of a replacement. The function was removed from PyStan because it is not part of the Stan C++ library.

  • Microsoft Windows is not supported in PyStan 3. It was (partially) supported in PyStan 2.

  • The default, recommended HMC sampler is fully supported. Variational inference, maximization algorithms, and other sampling algorithms are not supported. Users who need these features should consider using different software (e.g., CmdStan, CmdStanPy, jax, PyTorch).