README.rst
1PyStan: The Python Interface to Stan
2====================================
3
4.. image:: https://raw.githubusercontent.com/stan-dev/logos/master/logo.png
5 :alt: Stan logo
6 :scale: 50 %
7
8|pypi| |travis| |appveyor| |zenodo|
9
10**PyStan** provides a Python interface to Stan, a package for Bayesian inference
11using the No-U-Turn sampler, a variant of Hamiltonian Monte Carlo.
12
13For more information on `Stan <http://mc-stan.org>`_ and its modeling language,
14see the Stan User's Guide and Reference Manual at `http://mc-stan.org/
15<http://mc-stan.org/>`_.
16
17Important links
18---------------
19
20- HTML documentation: https://pystan.readthedocs.org
21- Issue tracker: https://github.com/stan-dev/pystan/issues
22- Source code repository: https://github.com/stan-dev/pystan
23- Stan: http://mc-stan.org/
24- Stan User's Guide and Reference Manual (pdf) available at http://mc-stan.org
25
26Related projects
27----------------
28
29- Scikit-learn integration: `pystan-sklearn <https://github.com/rgerkin/pystan-sklearn>`_ by @rgerkin.
30
31Similar projects
32----------------
33
34- PyMC: http://pymc-devs.github.io/pymc/
35
36Detailed Installation Instructions
37----------------------------------
38Detailed installation instructions can be found in the
39`doc/installation_beginner.md <https://github.com/chendaniely/pystan/blob/develop/doc/installation_beginner.rst/>`_ file.
40
41Quick Installation (Linux and macOS)
42------------------------------------
43
44`NumPy <http://www.numpy.org/>`_ and `Cython <http://www.cython.org/>`_
45(version 0.22 or greater) are required. `matplotlib <http://matplotlib.org/>`_
46is optional.
47
48PyStan and the required packages may be installed from the `Python Package Index
49<https://pypi.python.org/pypi>`_ using ``pip``.
50
51::
52
53 pip install pystan
54
55Alternatively, if Cython (version 0.22 or greater) and NumPy are already
56available, PyStan may be installed from source with the following commands
57
58::
59
60 git clone --recursive https://github.com/stan-dev/pystan.git
61 cd pystan
62 python setup.py install
63
64If you encounter an ``ImportError`` after compiling from source, try changing
65out of the source directory before attempting ``import pystan``. On Linux and
66OS X ``cd /tmp`` will work.
67
68Example
69-------
70
71::
72
73 import pystan
74 import numpy as np
75 import matplotlib.pyplot as plt
76
77 schools_code = """
78 data {
79 int<lower=0> J; // number of schools
80 real y[J]; // estimated treatment effects
81 real<lower=0> sigma[J]; // s.e. of effect estimates
82 }
83 parameters {
84 real mu;
85 real<lower=0> tau;
86 real eta[J];
87 }
88 transformed parameters {
89 real theta[J];
90 for (j in 1:J)
91 theta[j] = mu + tau * eta[j];
92 }
93 model {
94 eta ~ normal(0, 1);
95 y ~ normal(theta, sigma);
96 }
97 """
98
99 schools_dat = {'J': 8,
100 'y': [28, 8, -3, 7, -1, 1, 18, 12],
101 'sigma': [15, 10, 16, 11, 9, 11, 10, 18]}
102
103 sm = pystan.StanModel(model_code=schools_code)
104 fit = sm.sampling(data=schools_dat, iter=1000, chains=4)
105
106 print(fit)
107
108 eta = fit.extract(permuted=True)['eta']
109 np.mean(eta, axis=0)
110
111 # if matplotlib is installed (optional, not required), a visual summary and
112 # traceplot are available
113 fit.plot()
114 plt.show()
115
116.. |pypi| image:: https://badge.fury.io/py/pystan.png
117 :target: https://badge.fury.io/py/pystan
118 :alt: pypi version
119
120.. |travis| image:: https://travis-ci.org/stan-dev/pystan.png?branch=master
121 :target: https://travis-ci.org/stan-dev/pystan
122 :alt: travis-ci build status
123
124.. |appveyor| image:: https://ci.appveyor.com/api/projects/status/github/stan-dev/pystan?branch=master
125 :target: https://ci.appveyor.com/project/ariddell/pystan/branch/master
126 :alt: appveyor-ci build status
127.. |zenodo| image:: https://zenodo.org/badge/10256919.svg
128 :target: https://zenodo.org/badge/latestdoi/10256919
129 :alt: zenodo citation DOI
130
