atomica.programs.Program

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

Bases: atomica.utils.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)

Return type

bool

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