atomica.parameters

Implements data-based model parameters (ParameterSet)

A ParameterSet (or ‘parset’) is an intermediate representation of model parameters. The main role of the parset is to store the calibration values that are used to scale model parameters. Therefore, every parameter in the model appears in the parset, not just the parameters in the databook.

Classes

Parameter(name, ts) Class to hold one set of parameter values disaggregated by populations.
ParameterSet(framework, data[, name]) Collection of model parameters to run a simulation
class atomica.parameters.Parameter(name, ts)[source]

Class to hold one set of parameter values disaggregated by populations.

Parameters:
  • name (str) – The name of the parameter (should match framework code name)
  • ts (dict) – A dict where the key is population name and the value is a TimeSeries instance
_interpolation_method = None

Fallback interpolation method. It is _strongly_ recommended not to change this, but to call ``Parameter.smooth()` instead

has_values(pop_name)[source]

Check if any values are present

Returns True if this Parameter has values specified for the given population If the Parameter has an assumption, then the time value will be nan but a y-value will be present. If the Parameter normally has a function, then the y-value will be None. If a function Parameter has a scenario overwrite applied then actual values will be present. Essentially, if this function returns True, then the interpolate() method will return usable values

Parameters:pop_name (str) – The code name of a population
Return type:bool
Returns:True if any values are present for specified population, otherwise False
interpolate(tvec, pop_name)[source]

Return interpolated parameter values for a given population

The Parameter internally stores the interpolation method. The default is linear. It is possible to set it to ‘pchip’ or ‘previous’ or some other method. However, this would also also be applied to any parameter scenarios that have modified the parameter and require interpolation. Therefore, it is STRONGLY recommended not to modify the fallback interpolation method, but to instead call Parameter.smooth() in advance with the appropriate options, if the interpolation matters.

Parameters:
  • tvec – A scalar, list, or array or time values
  • pop_name (str) – The population to interpolate data for
Return type:

<built-in function array>

Returns:

An array with the interpolated values

meta_y_factor = None

Calibration scale factor for all populations

pops

Get populations contained in the Parameter

Returns:Generator/list of available populations
sample(constant)[source]

Perturb parameter based on uncertainties

This function modifies the parameter in-place. It would normally be called via ParameterSet.sample() which is responsible for copying this instance first.

Parameters:constant (bool) – If True, time series will be perturbed by a single constant offset. If False, an different perturbation will be applied to each time specific value independently.
Return type:None
skip_function = None

This can be a range of years [start,stop] between which the parameter function will not be evaluated

smooth(tvec, method='smoothinterp', pop_names=None, **kwargs)[source]

Smooth the parameter’s time values

Normally, Parameter instances contain temporally-sparse values from the databook. These are then interpolated to get the input parameter values at all model time points. The default interpolation is linear. However, sometimes it may be desired to make specific assumptions about the parameter value at intermediate times. These could be added directly to the Parameter’s underlying TimeSeries.

This method applies a smoothing method to the Parameter, modifying the underlying TimeSeries in-place. The operation is

  • Interpolated or smoothed values are generated for the requested times
  • All existing time points between and including the minimum and maximum values of tvec are removed
  • The time values generated in this function are inserted

For example, to apply pchip interpolation to generate intermediate values

>>> Parameter.smooth(P.settings.tvec, method='pchip',**kwargs)

As this goes through TimeSeries.interpolate the same rules apply for the conditions under which the interpolation function gets used - specifically, interpolation is used if there are at least two finite time values present, otherwise, the assumption or single value will be used.

Parameters:
  • tvec – New time points to add to the TimeSeries
  • method – Method for generation of smoothed/interpolated values, default uses sciris smoothinterp
  • pop_names – Optionally specify a list of populations to modify
  • kwargs – Optionally pass arguments to the generating function/class constructor
Returns:

ts = None

Population-specific data is stored in TimeSeries within this dict, keyed by population name

y_factor = None

Calibration scale factors for the parameter in each population

class atomica.parameters.ParameterSet(framework, data, name='default')[source]

Collection of model parameters to run a simulation

A ParameterSet contains a collection of Parameters required to run the simulation. The parameters contain scale factors used for calibration, so often a project will contain multiple ParameterSets corresponding to different calibrations.

Although parameters are constructed from ProjectData, there are two key differences

  • The ParameterSet contains calibration scale factors
  • The ParameterSet expands transfers and interactions into per-population parameters so they are stored on an equal basis (whereas ProjectData segregates them in TimeDependentValuesEntry and TimeDependentConnections due to the difference in how they are formatted in the databook
Parameters:
  • framework – A ProjectFramework instance
  • data – A ProjectData instance
  • name – Optionally specify the name of the parset
all_pars()[source]

Return an iterator over all Parameters

This is useful because transfers and interaction Parameter instances are stored in nested dictionaries, so it’s not trivial to iterate over all of them.

Returns:Generator over all Parameter instances contained in the ParameterSet
interactions = None

Stores the Parameter instances contained by this ParameterSet associated with framework interactions, keyed by source population

pars = None

Stores the Parameter instances contained by this ParameterSet associated with framework comps, characs, and parameters

pop_labels = None

List of corresponding full names for populations

pop_names = None

List of all population code names contained in the ParameterSet

pop_types = None

List of corresponding population types

sample(constant=True)[source]

Return a sampled copy of the ParameterSet

Parameters:constant – If True, time series will be perturbed by a single constant offset. If False, an different perturbation will be applied to each time specific value independently.
Returns:A new ParameterSet with perturbed values
transfers = None

Stores the Parameter instances contained by this ParameterSet associated with databook transfers, keyed by source population