How to write a new utility routine
In this tutorial, we describe how to include a new utility (specifically, a sampler)
to the surmise’s framework. We illustrate this with metropolis_hastings
–a
well-known sampler located in the directory \utilitiesmethods
.
In surmise, all utilities inherit from the base class surmise.utilities.sampler
.
Note that for now, we only have samplers as utilities. Later, we plan to have
different classes (such as surmise.utilities.optimizer
) that can be
used during calibration.
A sampler takes the function returning the log of the posterior of given theta as an input, and returns a dictionary including a random sample of thetas from the posterior distribution.
Mandatory functions
sampler()
is the only obligatory function for a sampler.
The metropolis_hastings.sampler()
is given below for an illustration:
- metropolis_hastings.sampler(logpost_func, draw_func, numsamp=2000, theta0=None, stepType='normal', stepParam=None, burnSamples=1000, verbose=False, **mh_options)[source]
- Parameters:
logpost_func (function) – a function returns the log of the posterior for a given theta.
draw_func (function) – a function returns random draws of initial design theta
numsamp (int, optional) – number of samples to draw. The default is 2000.
theta0 (array, optional) – initial theta value. The default is None.
stepType (str, optional) – either ‘uniform’ or ‘normal’. The default is ‘normal’.
stepParam (array, optional) – scaling parameter. The default is None.
**mh_options (dict) – additional options.
- Returns:
sampler_info – returns numsamp random draws from posterior.
- Return type:
dict
Once the base class surmise.utilities.sampler
is initialized,
surmise.utilities.sampler.draw_samples()
method calls the developer’s
sampler’s sampler()
function, and places all information into the dictionary, and returns it.
Optional functions
None. This section is under development.