Draft of release announcement for PyStan 3

Developers
1

No showstopper bugs have surfaced so far. The plan is to release PyStan 3 on 25. March, as scheduled.

Here’s a draft of a release announcement. Comments are welcome.

PyStan 3.0 is now available on PyPI. PyStan 3 makes numerous backwards-incompatible changes and requires Python 3.7 or higher, running on Linux or macOS.

PyStan 3 is a complete rewrite. One motivation for the rewrite was to create a version of PyStan which would be easy to update when new Stan versions appear. PyStan 3.0 uses Stan 2.26.1, the most recent version available. New releases of PyStan should appear within 48 hours of new Stan releases.

Changes in PyStan 3

The PyStan interface has changed in several ways. One obvious change is that variable naming practices in PyStan now match those used in CmdStan. Other changes are described in “Upgrading to 3.0”.

For most users, the basic “flow” will be essentially the same. 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 the equivalent 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)

Complete documentation for PyStan is available at https://pystan.readthedocs.io.

Developer-facing changes

  • All code involving calls to Stan C++ functions has been placed in a new package, httpstan. PyStan is now a “frontend” for httpstan. This design allows developers to quickly make and test improvements to the user interface. Such changes do not require re-compiling any C++ code.
  • A plugin system has been added. The behavior of PyStan 3 should be easy to customize.
  • PyStan 3 is simpler than PyStan 2. With all of httpstan counted as part of PyStan 3, PyStan 3 uses 58% fewer lines of code than PyStan 2. As a result, PyStan should be easier to maintain. Contributors will also find that the code is easier to read.
  • PyStan 3 emphasizes simplicity and maintainability. This emphasis makes it easier to keep PyStan in sync with new releases of the Stan library. This emphasis potentially comes at the cost of user-friendliness and features.
  • License is now ISC. Previously GPL3 was used.

Acknowledgements

  • Many thanks to Ben Goodrich (@bgoodri). The PyStan 3 API follows recommendations set forth in “User Interface Guidelines for Developers”. Ben deserves credit for all the good ideas in the document.
  • Thanks to Jiale Zhi (@calio on GitHub) for donating the “stan” package on PyPI. Users who attempt to pip install stan will be told that they should install pystan instead.
6 Likes