Calibration

class Calibration(sim, calib_pars=None, fit_args=None, custom_fn=None, par_samplers=None, n_trials=None, n_workers=None, total_trials=None, name=None, db_name=None, keep_db=None, storage=None, label=None, die=False, verbose=True)

Bases: Analyzer

A class to handle calibration of Covasim simulations. Uses the Optuna hyperparameter optimization library (optuna.org), which must be installed separately (via pip install optuna).

Note: running a calibration does not guarantee a good fit! You must ensure that you run for a sufficient number of iterations, have enough free parameters, and that the parameters have wide enough bounds. Please see the tutorial on calibration for more information.

Parameters:

• sim (Sim) – the simulation to calibrate

• calib_pars (dict) – a dictionary of the parameters to calibrate of the format dict(key1=[best, low, high])

• fit_args (dict) – a dictionary of options that are passed to sim.compute_fit() to calculate the goodness-of-fit

• par_samplers (dict) – an optional mapping from parameters to the Optuna sampler to use for choosing new points for each; by default, suggest_float

• custom_fn (func) – a custom function for modifying the simulation; receives the sim and calib_pars as inputs, should return the modified sim

• n_trials (int) – the number of trials per worker

• n_workers (int) – the number of parallel workers (default: maximum

• total_trials (int) – if n_trials is not supplied, calculate by dividing this number by n_workers)

• name (str) – the name of the database (default: ‘covasim_calibration’)

• db_name (str) – the name of the database file (default: ‘covasim_calibration.db’)

• keep_db (bool) – whether to keep the database after calibration (default: false)

• storage (str) – the location of the database (default: sqlite)

• label (str) – a label for this calibration object

• die (bool) – whether to stop if an exception is encountered (default: false)

• verbose (bool) – whether to print details of the calibration

• kwargs (dict) – passed to cv.Calibration()

Returns:

A Calibration object

Example:

sim = cv.Sim(datafile='data.csv')
calib_pars = dict(beta=[0.015, 0.010, 0.020])
calib = cv.Calibration(sim, calib_pars, total_trials=100)
calib.calibrate()
calib.plot()

New in version 3.0.3.

Methods

run_sim(calib_pars, label=None, return_sim=False)

Create and run a simulation

run_trial(trial)

Define the objective for Optuna

worker()

Run a single worker

run_workers()

Run multiple workers in parallel

remove_db()

Remove the database file if keep_db is false and the path exists.

New in version 3.1.0.

make_study()

Make a study, deleting one if it already exists

calibrate(calib_pars=None, verbose=True, **kwargs)

Actually perform calibration.

Parameters:

• calib_pars (dict) – if supplied, overwrite stored calib_pars

• verbose (bool) – whether to print output from each trial

• kwargs (dict) – if supplied, overwrite stored run_args (n_trials, n_workers, etc.)

summarize()

Print out results from the calibration

parse_study()

Parse the study into a data frame – called automatically

to_json(filename=None)

Convert the data to JSON.

New in version 3.1.1.

plot_sims(**kwargs)

Plot sims, before and after calibration.

New in version 3.1.1: renamed from plot() to plot_sims().

plot_trend(best_thresh=2)

Plot the trend in best mismatch over time.

New in version 3.1.1.

plot_all()

Plot every point in the calibration. Warning, very slow for more than a few hundred trials.

New in version 3.1.1.

plot_best(best_thresh=2)

Plot only the points with lowest mismatch. New in version 3.1.1.

plot_stride(npts=200)

Plot a fixed number of points in order across the results.

New in version 3.1.1.