calibration module

This module contains a class that implements the main calibration method.

class surmise.calibration.calibrator(emu=None, y=None, x=None, thetaprior=None, yvar=None, method='directbayes', args={})

Bases: object

A class to represent a calibrator. Fits a calibrator model provided in calibrationmethods/[method].py where [method] is the user option with default listed above.

Tip

To use a new calibrator, just drop a new file to the calibrationmethods/ directory with the required formatting.

Example:

calibrator(emu=emu, y=y, x=x, thetaprior=thetaprior,
           method='directbayes', args=args)

Parameters:

• emu (surmise.emulation.emulator, optional) – An emulator class instance as defined in surmise.emulation. The default is None.

• y (numpy.ndarray, optional) – Array of observed values at x. The default is None.

• x (numpy.ndarray, optional) – An array of x values that match the definition of “emu.x”. Currently, existing methods supports only the case when x is a subset of “emu.x”. The default is None.

• thetaprior (class, optional) –

  class instance with two built-in functions. The default is None.

  Important

  If a calibration method requires sampling, then the prior distribution of the parameters should be included into the calibrator. In this case, thetaprior class should include two methods:

  • lpdf(theta)

    Returns the log of the pdf of a given theta with size (len(theta), 1)

  • rnd(n)

    Generates n random variable from a prior distribution.

  Example:

  class prior_example:
      def lpdf(theta):
          return sps.uniform.logpdf(
              theta[:, 0], 0, 1).reshape((len(theta), 1))
  
      def rnd(n):
          return np.vstack((sps.uniform.rvs(0, 1, size=n)))
  

• yvar (numpy.ndarray, optional) – The vector of observation variances at y. The default is None.

• method (str, optional) – A string that points to the file located in calibrationmethods/ you would like to use. The default is ‘directbayes’.

• args (dict, optional) – Optional dictionary containing options you would like to pass to [method].fit(x, theta, f, args) or [method].predict(x, theta args) The default is {}.

Raises:

ValueError – If the dimension of the data do not match with the fitted emulator.

Return type:

None.

fit(args=None)

Calls “calibrationmethods.[method].fit” where “[method]” is the user option.

Parameters:

args (dict) – A dictionary containing options you would like to pass

static load_from(filename)

static load_prediction(filename)

predict(x=None, args=None)

Returns predictions at x.

Example:

calibrator.predict(x=x, args=args)

Parameters:

• x (numpy.ndarray, optional) – An array of inputs to the model where to predict. The default is None.

• args (dict, optional) – A dictionary containing options. The default is None.

Returns:

An instance of calibration class prediction.

Return type:

surmise.calibration.prediction

save_to(filename)

Simple serialization and save function for calibrator object.

Example:

cal = calibrator(...)

cal.save_to('cal_example.pkl')

loaded_cal = calibrator.load_from('cal_example.pkl')

class surmise.calibration.prediction(info, cal)

Bases: object

A class to represent a calibration prediction. predict.info will give the dictionary from the method.

Example:

prediction.lpdf()

prediction.mean()

prediction.var()

prediction.rnd()

empirical_coverage(p=array([0.68, 0.9, 0.95, 0.99]))

Computes empirical coverage given predictions using samples collected from calibration.

lpdf(y=None, args=None)

Returns a log pdf given theta.

mean(args=None)

Returns the mean at all x in when building the prediction.

rnd(s=100, args=None)

Returns s random draws at all x in when building the prediction.

save_to(filename)

Simple serialization and save function for calibrator prediction object.

Example:

cal = calibrator(...)

calpred = cal.predict(...)

calpred.save_to('calpred_example.pkl')

loaded_calpred = calibrator.load_prediction('calpred_example.pkl')

var(args=None)

Returns the variance at all x in when building the prediction.

class surmise.calibration.thetadist(cal)

Bases: object

A class to represent a theta predictive distribution.

lpdf(theta=None, args=None)

Returns a log pdf given theta.

mean(args=None)

Returns mean of each element of theta found during calibration.

rnd(s=1000, args=None)

Returns s predictive draws for theta found during calibration.

var(args=None)

Returns predictive variance of each element of theta found during calibration.