atomica.model.Parameter¶

class atomica.model.Parameter(pop, name)[source]¶

Bases: Variable

Integration object to represent Parameters

A parameter is a Variable that can have a value computed via an fcn_str and a list of dependent Variables. This is a Parameter in the cascade.xlsx sense - there is one Parameter object for every item in the Parameters sheet. A parameter that maps to multiple transitions (e.g. doth_rate) will have one parameter and multiple Link instances that depend on the same Parameter instance

Parameters:

pop – A Population instance corresponding to the population that will contain this parameter
name – The code name for this parameter

Attributes

`name`	Variable code name
`limits`	Can be a two element vector [min,max]
`pop_aggregation`	If not None, stores list of population aggregation information (special function, which weighting comp/charac and which interaction term to use)
`scale_factor`	This should be set to the product of the population-specific `y_factor` and the `meta_y_factor` from the ParameterSet
`links`	References to links that derive from this parameter
`fcn_str`	String representation of parameter function
`deps`	Dict of dependencies containing lists of integration objects
`derivative`	If True, the parameter function will be treated as a derivative and the value added on to the end
`skip_function`	Can optionally be set to a (start,stop) tuple of times.
`timescale`	For transition parameters, the `vals` stored by the parameter is effectively a rate.
`id`	Unique identifier for the integration object
`units`	The units for the quantity, used for plotting and for validation.
`pop`	Reference back to the Population containing this object

Methods

`constrain`	Constrain the parameter value to allowed range
`plot`	Produce a time series plot
`preallocate`	Preallocate data storage
`relink`
`set_dynamic`	Mark this parameter as needing evaluation for integration
`set_fcn`	Add a function to this parameter
`source_popsize`
`unlink`
`update`	Update the value of this Parameter

constrain(ti=None)[source]¶

Constrain the parameter value to allowed range

If Parameter.limits is not None, then the parameter values at the specified time will be clipped to the limits. If no time index is provided, clipping will be performed on all values in a vectorized operation. Vector clipping is used for data parameters that are not evaluated during integration, while index-specific clipping is used for dependencies that are calculated during integration.

Parameters:: ti – An integer index, or None (to operate on all time points)
Return type:: None

deps¶: Dict of dependencies containing lists of integration objects

derivative¶: If True, the parameter function will be treated as a derivative and the value added on to the end

fcn_str¶: String representation of parameter function

id¶: Unique identifier for the integration object

limits¶: Can be a two element vector [min,max]

links¶: References to links that derive from this parameter

property name: str¶

Variable code name

This is implemented as a property method because the id of the Variable is a tuple containing the population name and the variable code name, so this property method returns just the variable code name portion. That way, storage does not need to be duplicated.

Returns:: A code name

plot()¶

Produce a time series plot

This is a quick function to make a basic line plot of this Variable. Mainly intended for debugging. Production-ready plots should be generated using the plotting library functions instead

Return type:: None

pop¶: Reference back to the Population containing this object

pop_aggregation¶: If not None, stores list of population aggregation information (special function, which weighting comp/charac and which interaction term to use)

preallocate(tvec, dt)¶

Preallocate data storage

This method gets called just before integration, once the final sizes of the arrays are known. Performance is improved by preallocating the arrays. The tvec attribute is assigned as-is, so it is typically a reference to the array stored in the parent Model object. Thus, there is no duplication of storage there, and Variable.tvec is mainly for convenience when interpolating or plotting.

This method may be overloaded in derived classes to preallocate other variables specific to those classes.

Parameters:

tvec (array) – An array of time values
dt (float) – Time step size

Return type:

None

scale_factor¶: This should be set to the product of the population-specific y_factor and the meta_y_factor from the ParameterSet

set_dynamic(progset=None)[source]¶

Mark this parameter as needing evaluation for integration

If a parameter has a function and set_dynamic() has been called, that means the result of the function is required to drive a transition in the model. In this context, ‘dynamic’ means that the parameter depends on values that are only known during integration (i.e. compartment sizes). It could also depend on compartment sizes indirectly, if it depends on characteristics, or if it depends on parameters that depend on compartments or characteristics. If none of these are true, then the parameter function can be evaluated before integration starts, taking advantage of vector operations.

If a parameter is overwritten by a program in this simulation, then its value may change during integration, and we again need to make this parameter dynamic. Note that this doesn’t apply to the parameter being overwritten - if it gets overwritten, that has no bearing on when its function gets evaluated. But if a parameter depends on a value that has changed, then the function must be re-evaluated. Technically this only needs to be done after the time index where programs turn on, but it’s simpler just to mark it as dynamic for the entire simulation, the gains aren’t large enough to justify the extra complexity otherwise.

Parameters:: progset – A ProgramSet instance (the one contained in the Model containing this Parameter)
Return type:: None

set_fcn(fcn_str)[source]¶

Add a function to this parameter

This method adds a function to the parameter. The following steps are carried out

The function is parsed and stored in the ._fcn attribute (until the Parameter is pickled)

The dependencies are extracted, and are stored as references to the actual integration objects to increase performance during integration

If this is a transition parameter, then dependencies will have their dynamic flag updated

Parameters:

framework – A py:class:ProjectFramework instance, used to identify and retrieve interaction terms
fcn_str – The string containing the function to add

Return type:

None

skip_function¶: Can optionally be set to a (start,stop) tuple of times. Between these times, the parameter will not be updated so the parset value will be left unchanged

timescale¶: For transition parameters, the vals stored by the parameter is effectively a rate. The timescale attribute informs the time period corresponding to the units in which the rate has been provided. If the units are number or probability then the timescale corresponds to the denominator of the units e.g. probability/day (with timescale=1/365). If the units are duration then the timescale stores the units in which the duration has been specified e.g. duration=1 with timescale=1/52 is the same as duration=7 with timescale=1/365 The effective duration used in the simulation is duration*timescale with units of years (so it will behave correctly if one wanted to use 1/365.25 instead of 1/365)

units¶: The units for the quantity, used for plotting and for validation. Note that the default 'unknown' units are distinct to dimensionless units, which have value ''

update(ti=None)[source]¶

Update the value of this Parameter

If the parameter contains a function, this entails evaluating the function. Typically this is done at a single time point during integration, or over all time points for precomputing and postcomputing

Parameters:: ti – An int, or a numpy array with index values. If None, all time values will be used
Return type:: None