A surface language for programming Stan models using python syntax
Project description
YAPS
Yaps is a new surface language for Stan. It allows to write Stan programs using Python syntax. For example, consider the following Stan program:
data {
int<lower=0,upper=1> x[10];
}
parameters {
real<lower=0,upper=1> theta;
}
model {
theta ~ uniform(0,1);
for (i in 1:10)
x[i] ~ bernoulli(theta);
}
It can be rewritten in Python has follows:
import yaps
from yaps.lib import int, real, uniform, bernoulli
@yaps.model
def coin(x: int(lower=0, upper=1)[10]):
theta: real(lower=0, upper=1) <~ uniform(0, 1)
for i in range(10):
x[i] <~ bernoulli(theta)
The @yaps.model
decorator indicates that the function following it
is a Stan program. While being syntactically Python, it should be
semantically reinterpreted as Stan.
The argument of the function corresponds to the data
block. The
type of the data must be declared. Here, you can see that x
is an
array of integers between 0
and 1
(int(lower=0, upper=1)[10]
).
Parameters are declared as variables with their type in the body of
the function. Their prior can be defined using the sampling operator
<~
(or is
).
The body of the function corresponds to the Stan model. Python syntax
is used for the imperative constructs of the model, like the for
loop in the example. The operator <~
is used to represent sampling
and x.T[a,b]
for truncated distribution.
Other Stan blocks can be introduced using the with
syntax of Python.
For example, the previous program could also be written as follows:
@yaps.model
def coin(x: int(lower=0, upper=1)[10]):
with parameters:
theta: real(lower=0, upper=1)
with model:
theta <~ uniform(0, 1)
for i in range(10):
x[i] <~ bernoulli(theta)
The corresponding Stan program can be displayed using the print
function:
print(coin)
Finally, it is possible to launch the inference on the defined model applied to some data:
flips = [0, 1, 0, 0, 0, 0, 0, 0, 0, 1]
posterior = yaps.infer(coin(x=flips), iter=1000)
It returns posterior
, a dictionary containing the value of the parameters:
print("theta: {:.3f}".format(posterior.theta.mean()))
Yaps is built on top on PyStan. It provides a lighter syntax to Stan programs. It allows to take advantage of Python tooling for syntax highlighting, indentation, error reporting, ...
Install
Yaps depends on the following python packages:
- astor
- graphviz
- antlr4-python3-runtime
- pystan
To install Yaps and all its dependencies run:
pip install yaps
To install from source, first clone the repo, then:
pip install .
Tools
We provide a tool to compile Stan files to yaps syntax:
For instance, if path/to/coin.stan
contain the stan model presented at the beginning, then:
stan2yaps path/to/coin.stan
outputs:
# -------------
# tests/stan/coin.stan
# -------------
@yaps.model
def stan_model(x: int(lower=0, upper=1)[10]):
theta: real
theta is uniform(0.0, 1.0)
for i in range(1, 10):
x[(i),] is bernoulli(theta)
print(x)
Compilers from Yaps to Stan and from Stan to Yaps can also be invoked programmatically using the following functions:
yaps.from_stan(code_string=None, code_file=None) # Compile a Stan model to Yaps
yaps.to_stan(code_string=None, code_file=None) # Compile a Yaps model to Stan
For Developers
To build the parser, you need to install antlr before installing the package. You will also need to install the nose package to run the tests. For instance using homebrew:
brew install antlr
pip install nose
make
make test
To test the round trip on only one file, after the install:
yaps-roundtrip path/to/file.stan
Documentation
The documentation is written with Sphinx, using a Markdown parser, and the readthedoc theme. You thus need to install the following packages:
pip install sphinx sphinx_rtd_theme recommonmark
Then to generate the documentation:
make doc
Distribution
To create a new distribution you need the following packages:
pip install setuptools wheel twine
Then to build the a new distribution and upload it:
make distrib
make upload
Note: you need valid PyPI credentials to upload the package.
License
Yaps is distributed under the terms of the Apache 2.0 License, see LICENSE.txt
Contributions
Yaps is still at an early phase of development and we welcome contributions. Contributors are expected to submit a 'Developer's Certificate of Origin' which can be found in DCO1.1.txt.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.