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.