Stan Models Module

Module defining estimation models using PyStan for estimation.

PyStan is a python package for Bayesian inference with an efficient Hamiltonian Monte Carlo sampler under the hood (see pystan documentation http://pystan.readthedocs.io/en/latest/). The Monte Carlo sampler can be used for MAP (maximum a posteriori) estimation, or full Bayesian inference.

Models are defined in a specialized statistical programming language and compiled to an computationally fast and efficient sampler.

This module defines a class that interfaces all models that use Stan for inference.

Warning

Since compilation is necessary, the first run of a Stan Estimation model will seem very slow. Compiled versions are stored so a second use of the estimation model will not incur in such expensive overhead.

Compilation is hardware and python version dependant, so no pre-compiled models are shipped with a standard ollin installation.

ollin.estimation.stanmodels.COMPILED_PATH

str – Path of all compiled models.

class ollin.estimation.stanmodels.StanModel[source]

Class interface for estimation models that use PyStan.

All estimation models that use PyStan must inherit from this class and implement estimate() and prepare_data methods().

name

str – Name of model.

stancode

str – String containing the code in Stan language that defines the statistical model to use.

stanmodel

pystan.StanModel – Compiled stanmodel object to use in inference.

compile_and_save()[source]

Compile Stan code and save in compiled model directory.

estimate(detection, method='MAP', priors=None)[source]

Estimate using detection data and stan model.

Detection data is prepared using prepare_data() method and fed to pystan model. The model then samples from the posterior distribution (if method == ‘sample’) or optimizes for the parameters in the posterior distribution (if method == ‘MAP’).

Any estimation model that inherits from this class must extend this method to extract the relevant information from the stanmodel output.

Parameters:
  • detection (ollin.core.detection.Detection) – Detection data from which to make estimate.
  • method ({'MAP', 'sample'}, optional) – Method for inference. If ‘MAP’, Stan will try to find the parameters at which likelihood of the posterior distribution is a maximum. If ‘sample’, Stan will run the Hamiltonian Monte Carlo sampler to return a large sample of the posterior distribution. Defaults to ‘MAP’.
  • priors (dict, optional) – Dictionary holding all information of priors parameters.
Returns:

result – If method = ‘MAP’ it will return a dictionary with the parameter values at which a maximum (local) of the posterior likelihood was found. If method = ‘sample’ it will a pystan.StanFit4Model object that contains all information of the sampling. See http://pystan.readthedocs.io/en/latest/api.html#pystan.StanModel.sampling.
Return type:

dict or pystan.StanFit4Model
load_model()[source]

Load and return compiled model.

If no compiled version is found it will compile the model and save it.

prepare_data(detection, priors)[source]

Prepare the data to feed to the Stan model.

See the pystan.StanModel.sampling() documentation for further information (http://pystan.readthedocs.io/en/latest/api.html#pystan.StanModel).

Parameters:
  • detection (Detection) – Detection data.
  • priors (dict) – Any priors parameters information should be stored here.
Returns:

data – All inputs for variables defined in the Stan model must be contained in this dictionary.
Return type:

dict