atomica.parameters.Initialization

class atomica.parameters.Initialization(values=None, year=None, init_y_factor_hash=None, dt=None)

Bases: object

This class stores initial compartment sizes

In some cases it may be desirable to explicitly set initial compartment sizes rather than having them calculated based on the databook values/characteristics. An example of this could be wanting to initialize the model using steady-state compartment sizes computed from a prior model run. This class facilitates storing/applying the initial compartment sizes as well as capturing metadata for validation purposes.

Construct an Initialization with explicit initial values

This function can be used to explicitly set initial compartment sizes. More typically, the initial compartment sizes would be drawn from a previous model run. In that case, construct the Initialization using the Initialization.from_result() method, passing in the parset and result. For users, this is typically handled via ParameterSet.set_initialization(result) which allows easily passing a result into the ParameterSet to set the initialization in one step.

Parameters:

• values – Provide a dictionary of values with compartment sizes. Keys should be tuples with (comp_name,pop_name) and values should be either scalars (for normal compartments) or arrays (for timed compartments). The size of the arrays for timed compartments will reflect both the duration of the timed compartment and the simulation step size (noting that if timed compartments are being used, the Initialization instance will not be reusable if the simulation step size is subsequently changed, and will need to be re-created using the new step size).

• year – Optionally specify the year used to generate the initialization (for provenance)

• init_y_factor_hash – Optionally specify the y-factor hash. If supplied, this will be checked against the parset when the initialization is applied

• dt – Optionally specify the timestep used to generate the initialization (for provenance)

Methods

apply	Insert saved values into compartments
from_excel	Construct an initialization from saved spreadsheet
from_result	Construct an initialization based on a Result
hash_y_factors	Hash y-factors used for initialization
to_excel

apply(pop, framework=None, parset=None)

Insert saved values into compartments

The Initialization may contain a hash of the y-factors for initialization compartments/characteristics that were used when the Initialization was generated, if the Initialization was generated based on a previous Result. When applying the initialization, if a framework and parset are provided, then the y-factors will be checked to determine if there are any differences in the initialization y-factors or not, and a warning will be displayed if so.

Parameters:

• pop – An at.model.Population instance

• framework – Optionally specify a framework object containing the specification of which comps/characs are used for initialization

• parset – Optionally specify the requested parset for initialization containing Y-factors to compare to the saved Y-factors

Return type:

None

classmethod from_excel(excelfile)

Construct an initialization from saved spreadsheet

Parameters:

excelfile (ExcelFile) – A pd.ExcelFile containing an ‘Initialization’ sheet

Returns:

classmethod from_result(res, parset=None, year=None)

Construct an initialization based on a Result

This method is used to create an Initialization instance when the initial compartment sizes are drawn from the state of a previously-run model. This facilitates initializing the model after numerically converging to a steady state or after an initial transient has passed.

Parameters:

• res – An Atomica Result instance

• parset – Optionally specify a ParameterSet instance containing y-factor values. If provided, subsequent use of the initialization will check if the y-factors have changed since the initialization was saved and display a warning if so.

• year – Optionally specify the year to draw compartment sizes from in the result. If not provided, the last time point will be used. The year must exactly match a year contained in the result.

Returns:

A new Initialization instance

static hash_y_factors(framework, parset)

Hash y-factors used for initialization

This method calculates a hash of the y-factors for the purpose of identifying if they have changed since the Initialization was originally created.

Parameters:

• framework – An at.Framework instance containing setup weights for compartments/characteristics

• parset – An at.ParameterSet instance containing y-factors

Return type:

str

Returns:

A hash computed from the y-factors used for normal compartment initialization