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

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 (str) – The name of a population
name (str) – The name of a variable

Return type:

list

Returns:

A list of matching variables (integration objects)

link_names(pop_name)[source]¶

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

Returns:: Array of all time points available in the result

property used_programs: bool¶

Flag whether programs were used or not

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).