atomica.programs.Program¶

class atomica.programs.Program(name, label=None, target_pops=None, target_comps=None, currency='$')[source]¶

Bases: NamedItem

Representation of a single program

A Program object is instantiated for every program listed on the ‘Program Targeting’ sheet in the program book. The Program object contains

Collections of targeted populations and compartments from the targeting sheet in the program book
The time-dependent program properties on the spending data sheet (such as total spend and unit cost)

Parameters:

name – Short name of the program
label – Full name of the program
target_pops – List of population code names for pops targeted by the program
target_comps – List of compartment code names for compartments targeted by the program
currency – The currency to use (for display purposes only) - normally this would be set to ProgramSet.currency by ProgramSet.add_program()
name – Short name of the program
label – Full name of the program
target_pops – List of population code names for pops targeted by the program
target_comps – List of compartment code names for compartments targeted by the program
currency – The currency to use (for display purposes only) - normally this would be set to ProgramSet.currency by ProgramSet.add_program()

NamedItem constructor

A name must be a string

Parameters:: name

Attributes

`is_one_off`	Flag for one-off programs
`name`	Short name of program
`label`	Full name of the program
`target_pops`	List of populations targeted by the program
`target_comps`	Compartments targeted by the program - used for calculating coverage denominators
`baseline_spend`	A TimeSeries with any baseline spending data - currently not exposed in progbook
`spend_data`	TimeSeries with spending data for the program
`unit_cost`	TimeSeries with unit cost of the program
`capacity_constraint`	TimeSeries with capacity constraint for the program
`saturation`	TimeSeries with saturation constraint that is applied to fractional coverage
`coverage`	TimeSeries with capacity of program - optional - if not supplied, cost function is assumed to be linear

Methods

`copy`
`get_capacity`	Return timestep capacity
`get_prop_covered`	Return proportion of people covered
`get_spend`	Retrieve program spending
`sample`	Perturb program values based on uncertainties

baseline_spend¶: A TimeSeries with any baseline spending data - currently not exposed in progbook

capacity_constraint¶: TimeSeries with capacity constraint for the program

coverage¶: TimeSeries with capacity of program - optional - if not supplied, cost function is assumed to be linear

get_capacity(tvec, spending, dt)[source]¶

Return timestep capacity

This method returns the number of people covered at each timestep. For one-off programs, this means the annual capacity is multiplied by the timestep size. Whether timestep scaling takes place or not is determined based on the units of the unit cost ($/person or $/person/year where the former is used for one-off programs).

The method takes in the spending value to support overwrites in spending value by program instructions (in which case, spending should be drawn from the instructions rather than the program’s spending data). This is handled in ProgramSet.get_capacities()

This method returns the program’s timestep capacity - that is, the capacity of the program per timestep, at specified points in time. The spending and capacity constraint are automatically adjusted depending on the units of the unit cost and capacity constraint such that the calculation returns capacity in units of ‘people’ (not ‘people/year’)

Parameters:

tvec – A scalar, list, or array of times
spending – A vector of spending values (in units of ‘$/year’), the same size as tvec
dt – The time step size (required because the number covered at each time step potentially depends on the spending per-timestep)

Returns:

Array the same size as tvec, with capacity in units of ‘people’

get_prop_covered(tvec, capacity, eligible)[source]¶

Return proportion of people covered

The time vector tvec is required to interpolate the saturation values. The capacity and eligible variables are assumed to correspond to the same time points and thus the array sizes should match the size of the time array.

Parameters:

tvec – An array of times
capacity – An array of number of people covered (e.g. the output of Program.get_capacity()) This should be in units of ‘people’, rather than ‘people/year’ although it may be a timestep-sensitive value if the capacity follows from a timestep-adjusted spend.
eligible – The number of people eligible for the program (computed from a model object or a Result)

Returns:

The fractional coverage (used to compute outcomes)

get_spend(year=None, total=False)[source]¶

Retrieve program spending

Parameters:

year – Scalar, list, or array of years to retrieve spending in
total (bool) – If True, the baseline spend will be added to the spending data

Return type:

array

Returns:

Array of spending values

property is_one_off: bool¶

Flag for one-off programs

A one-off program is a program where the cost is incurred once, per person impacted. For example, a treatment program where after treatment the person is no longer eligible for treatment. In contrast, a non-one-off program (a continuous program) is one where a person reached by the program remains eligible - for example, ART. In addition, one-off programs are typically linked to transition parameters, while continuous programs are typically linked to non-transition parameters.

Whether a program is one-off or not depends on whether the unit cost is specified as - Cost per person (one-off) - Cost per person per year (continuous)

Returns:: True if program is a one-off program

label¶: Full name of the program

name¶: Short name of program

sample(constant)[source]¶

Perturb program values based on uncertainties

Calling this function will perturb the original values based on their uncertainties. The values will change in-place. Normally, this method would be called by ProgramSet.sample() which will copy the Program 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

saturation¶: TimeSeries with saturation constraint that is applied to fractional coverage

spend_data¶: TimeSeries with spending data for the program

target_comps¶: Compartments targeted by the program - used for calculating coverage denominators

target_pops¶: List of populations targeted by the program

unit_cost¶: TimeSeries with unit cost of the program