Parameters

Parameter

The Parameter class is a low-level container for time varying data, which also includes scaling factors that can be used in calibration. Its attributes include:

self.t = t                              # Time data.
self.y = y                              # Value data.
self.y_format = y_format                # Value format data (e.g. Probability, Fraction or Number).
self.y_factor = y_factor                # Scaling factor of data. Corresponds to different transformations whether format is fraction or number.
self.autocalibrate = autocalibrate      # A set of boolean flags corresponding to y_factor that denote whether this parameter can be autocalibrated.

That is, a parameter object is instantiated for every parameter in the cascade, but it contains as many time series as there are in the databook. So these are separated by storing y, y_format and y_factor in odicts where the population name is the key.

insertValuePair(t, y, pop_label)
removeValueAt(t, pop_label)

These functions are fairly self-explanatory, but note that insertion is performed by appending which means that the values may be out of order.

interpolate(tvec , pop_label , extrapolate_nan )

This is the function that actually does the parameter interpolation. Note that it takes in a population label which means that it only operates on one of the time series at a time. The interpolated values are returned without altering the internal data.

Warning - Inflation incorporates multiplication by the y-factor

The y-factor provides a mechanism to multiplicatively scale the data values without changing the original input values. The code notes that the scaling is different depending on whether it is a fraction or a number but in code, the transformation in interpolate() suggests it is just the same multiplication. Specifically, the

Potential simplifications

• The databook format suggests we could have a single time array and store NaNs for missing values? Then the size would be guaranteed. In fact, we could then use a matrix instead of an odict to store the parameters. But it could be inconvenient to decouple the populations too strongly, as it could become hard to keep track of which populations the data correspond to in the absence of the project object. Perhaps the ParameterSet should be the one storing the populations? Depends on the split in responsibilities across the two classes

ParameterSet

self.pars['cascade'] = an array of Parameter objects initialized from data['linkpars']
self.pars['characs'] = an array of Parameter objects initialized from data['characs']
self.transfers = odict of Parameter objects initialized from data['transfers']
self.contacts = direct copy of data['contacts']

getPar(self, label) - returns cascade parameter or characteristic 

Note that while 'Parameters' in the cascade Excel file are used to refer specifically to the quantities defined in the 'Parameters' sheet, the Parameter object is used to store 'Parameters', 'Characteristics' and 'Transfers'.

Methods

makePars

This method performs the mapping from the data odict to internal parameters

inflate(tvec)

Inflation does interpolation on all of the parameters and on all populations AND replaces the data in-place.

Note - the fact that this is done in-place means that the data fields in the parameter object are not guaranteed to be a faithful copy of the data entered by the user

Warning - because inflate() uses interpolate() the inflated values include the y-factor, but the y-factor is not overwritten. Thus subsequent simulations will apply the y-factor a second time. Perhaps this is intentional, but of course 'inflation' will only occur if the y-factor is greater than 1

extractEntryPoints(proj_settings)

This function returns an array of Y-factors associated with every characteristic that is marked as an entry point for a compartment. The return value is (init_compartments,charac_labels) where charac_labels is a tuple with both the characteristic ID and the population ID.

update(self, par_vec, par_pop_labels,isYFactor)

This changes the Y-value or Y-factor for a parameter based on par_pop_labels which is an array of label-population tuples (lookup is via getPar). This method is called when perform automatic calibration (via performAutoFit()).

Saving and loading methods exist that operate on CSV files

Potential simplifications

• extractEntryPoints looks like it could be implemented at the Project level? Or perhaps just a standalone function?
• Operator overloading for << and + is potentially confusing

Connection to model.py

At initialization in Model.build()

• ParameterSet.pars['cascade'] has interpolated values, y_format and y_factor copied into Model.pops[pop_index].links i.e. it is copied into a link object
• ParameterSet.pars['characs'] goes through the decomposition calculation to populate Model.pops[pop_index].getComp(seed_label).popsize[0] i.e. the initial population size for each compartment
• ParameterSet.transfers is used to construct extra link objects that are appened into Model.pops[pop_index].links where pop_index is the source population for the transfer. The link_ids tag is automatically computed as a string with the source and target populations
• ParameterSet.contacts is copied straight into Model.contacts

Note that this conversion is done by model.py rather than parameters.py because the conversion requires the project settings to allocate links to transitions or outputs appropriately.