atomica.results.Result

class atomica.results.Result(model, parset=None, name=None)[source]

Bases: NamedItem

Storage for single simulation result

A Result object (similar to the raw_result in Optima HIV) stores a complete simulation run. In Atomica, a Result is a lightweight wrapper around a Model object. During a simulation, the Model object contains integration objects like compartments, links, and parameters, which store values for each quantity at every time step. The methods in the Model class are oriented at performing the calculations required to simulate the model. A Result object contains within it a single Model object, which in turn contains all of the integration objects together with the data they contain and the relationships between them, as well as the programs.ProgramSet and programs.ProgramInstructions that were used to perform the simulation. The methods of the Result class are oriented at plotting and exporting.

Parameters
  • model – A single model.Model instance (after integration

  • parset – A parameters.ParameterSet instance

  • name – The name to use for the new Result object

NamedItem constructor

A name must be a string

Parameters

name

Attributes

dt

Return simulation timestep

framework

Return framework from Result

pop_labels

Return all population full names

t

Return simulation time vector

used_programs

Flag whether programs were used or not

Methods

charac_names

Return list of characteristic names

check_for_nans

Check if any NaNs/Infs are present

comp_names

Return compartment names within a population

copy

export_raw

Save raw outputs

get_alloc

Return spending allocation

get_coverage

Return program coverage

get_equivalent_alloc

Return minimal spending allocation for a given year based on the coverage

get_variable

Retrieve integration objects

link_names

Return list of link names

par_names

Return list of parameter names

plot

Produce framework-defined plot

charac_names(pop_name)[source]

Return list of characteristic names

This method returns all of the characteristic names available within a specified population

Parameters

pop_name (str) – The name of one of the populations in the Result

Return type

list

Returns

List of characteristic code names

check_for_nans(verbose=True)[source]

Check if any NaNs/Infs are present

Parameters

verbose – Print NaN/Inf quantities

Return type

bool

Returns

True if any quantities contain NaNs/Infs

comp_names(pop_name)[source]

Return compartment names within a population

Parameters

pop_name (str) – The code name of one of the populations

Return type

list

Returns

List of code names of all compartments within that population

property dt: float

Return simulation timestep

Return type

float

Returns

The simulation timestep (scalar)

export_raw(filename=None)[source]

Save raw outputs

This method produces a single Pandas DataFrame with all of the raw model values, and then optionally saves it to an Excel file.

Parameters

filename – The file name of the Excel file to write. If not provided, no file will be written

Return type

DataFrame

Returns

A DataFrame with all model outputs

property framework

Return framework from Result

Returns

A ProjectFramework instance

get_alloc(year=None)[source]

Return spending allocation

If the result was generated using programs, this method will return the spending on all programs in the requested years.

Parameters

year – Optionally specify a scalar or list/array of years to return budget values for. Otherwise, uses all simulation times

Return type

dict

Returns

Dictionary keyed by program name with arrays of spending values

get_coverage(quantity='fraction', year=None)[source]

Return program coverage

This function is the primary function to use when wanting to query coverage values. All coverage quantities are accessible via the Result object because the compartment sizes and thus eligible people are known.

Caution - capacity and number covered are returned in units of ‘people/year’. They need to be accumulated by integration rather than summation.

Parameters
  • quantity (str) – One of - ‘capacity’ - Program capacity in units of ‘people/year’ (for all types of programs) - ‘eligible’ - The number of people eligible for the program (coverage denominator) in units of ‘people’ - ‘fraction’ - capacity/eligible, the fraction coverage (maximum value is 1.0) - this quantity is dimensionless - ‘number’ - The number of people covered (fraction*eligible) returned in units of ‘people/year’

  • year – Optionally specify a scalar or list/array of years to return budget values for. Otherwise, uses all simulation times

Return type

dict

Returns

Requested values in dictionary {prog_name:value} in requested years

get_equivalent_alloc(year=None)[source]

Return minimal spending allocation for a given year based on the coverage

If the result was generated using programs, this method will return the spending on all programs in the requested years.

Parameters

year – Optionally specify a scalar or list/array of years to return budget values for. Otherwise, uses all simulation times

Return type

dict

Returns

Dictionary keyed by program name with arrays of spending values

get_variable(name, pops=None)[source]

Retrieve integration objects

This method retrieves an integration object from the model for a given population. It serves as a shortcut for ``model.Population.get_variable()` by incorporating the population lookup in the same step.

Parameters
  • pops (Optional[str]) – The name of a population

  • name (str) – The name of a variable

Return type

list

Returns

A list of matching variables (integration objects)

Return list of link names

This method returns all of the link names available within a specified population. The names will be unique (so duplicate links will only appear once in the list of names)

Parameters

pop_name (str) – The name of one of the populations in the Result

Return type

list

Returns

List of link code names

par_names(pop_name)[source]

Return list of parameter names

This method returns all of the parameter names available within a specified population

Parameters

pop_name (str) – The name of one of the populations in the Result

Return type

list

Returns

List of parameter code names

plot(plot_name=None, plot_group=None, pops=None, project=None)[source]

Produce framework-defined plot

This method plots a single Result instance using the plots defined in the framework.

If plot_group is not None, then plot_name is ignored If plot_name and plot_group are both None, then all plots will be displayed

Parameters
  • plot_name – The name of a single plot in the Framework

  • plot_group – The name of a plot group

  • pops – A population aggregation supposed by PlotData (e.g. ‘all’)

  • project – A Project instance used to plot data and full names

Returns

List of figure objects

property pop_labels

Return all population full names

The full names/labels are returned in the same order as the names in Result.pop_names

Returns

List of population full names

property t: array

Return simulation time vector

Return type

array

Returns

Array of all time points available in the result

property used_programs: bool

Flag whether programs were used or not

Return type

bool

Returns

True if a progset and program instructions were present. Note that programs will be considered active even if the start/stop years in the instructions don’t overlap the simulation years (so no overwrite actually took place).