A Clojure library that interfaces with the STAN statistical modeling platform as an external process.
This project uses the cmdstan command line interface to STAN.
Unfortunately, clj-stan is not very flexible in which version of
cmdstan it can use. To install cmdstan version 2.18.0, make sure
you have the necessary dependencies installed:
sudo apt-get install clang g++ libc++-dev
and then download the tar file cmdstan-2.18.0.tar.gz from
https://github.com/stan-dev/cmdstan/releases. Extract the archive, and
then run
make build -j4
in the resulting directory. The -j4 option parallelises the build,
which is advisable since it takes 10+ minutes and is quite CPU
intensive.
You must configure the environment variable $STAN_HOME to be the
path to the directory extracted from the release tar.
This process is scripted in the install directory. There is also a
Dockerfile there, which is intended to build a base image for
clojure apps that use clj-stan.
A simple way to check that things are correctly configured is to run the (fairly minimal) test suite:
me@machine:~/projects/clj-stan$ lein test
Suppose we have the following model written in the file
/models/bernoulli.stan:
data {
int<lower=0> N;
int<lower=0,upper=1> y[N];
}
parameters {
real<lower=0,upper=1> theta;
}
model {
theta ~ beta(0.5,0.5);
for (n in 1:N)
y[n] ~ bernoulli(theta);
}
which expresses a simple bernoulli trial model with the Jeffreys prior.
There are three core functions we will use:
(def bern (stan/make "/models/bernoulli.stan" "bern"))
will compile the model and return a record that wraps the resulting executable. This record implements two methods:
(stan/sample bern {:N 3 :y [0 1 1]})
the primary sampling method, returns a collection of samples from the posterior distribution of the model, and:
(stan/optimize bern {:N 3 :y [0 1 1]})
calls the optimization routine of the executable, which will find the MAP ('Maximum A Posteriori') estimate for the model.
Alternatively, the variational bayes approach can be used for model training
(stan/variational bern {:N 3 :y [0 1 1]} "fullrank")
The third parameter specifies the variational algorithm to be used,
which can be either meanfield (using a fully factored Gaussian for
the approximation) or fullrank (using a Gaussian with full-rank
covariance matrix for the optimization). The variational method
returns a map containing keys :mode and :samples.
See the cmdstan documentation at http://mc-stan.org/users/interfaces/cmdstan
Copyright (c) Metail and Thomas Athorne
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.