atomica.framework.ProjectFramework

class atomica.framework.ProjectFramework(inputs=None, name=None, validate=True)

Bases: object

Base Framework class

The object that defines the transition-network structure of models generated by a project.

Parameters:

• inputs – A string (which will load an Excel file from disk) or an sc.Spreadsheet. If not provided, the internal sheets will be set to an empty dict ready for content

• name (str) – Optionally explicitly set the framework name. Otherwise, it will be assigned from the ‘about’ sheet, if present

• validate (bool) – If True (default) then the framework will be validated upon loading. This can be overridden if operating on invalid/partial frameworks is required. However, the framework should still be validated before it is used.

Attributes

cascades	Return dict with all cascades
characs	Return characteristics dataframe
comps	Return compartments dataframe
interactions	Return interactions dataframe
name	Return framework name
pars	Return parameters dataframe
pop_types	Return available population types
uid	Unique identifier
version	Current Atomica version
gitinfo	Atomica Git version information, if being run in a Git repository
created	Creation time
modified	Last modified time
sheets	Stores a dict of Pandas dataframes organized by sheet from the Excel file
spreadsheet	A sc.Spreadsheet object containing the original Excel file

Methods

get_charac	Retrieve characteristic by code name
get_charac_includes	Expand characteristics into compartments
get_comp	Retrieve compartment by code name
get_databook_units	Return the user-facing units for a quantity given a code name
get_interaction	Retrieve interaction by code name
get_label	Get full name/label from code name
get_par	Retrieve parameter by code name
get_variable	Retrieve variable from framework
save	Save framework to disk
to_spreadsheet	Return content as a Sciris Spreadsheet

property cascades: odict

Return dict with all cascades

If the Cascades sheet is present, return an odict where the key is the name of the cascade and the value is the corresponding dataframe.

Note that the fallback cascade (automatically produced if no cascades are present in the original Excel file) is also included here. Therefore, downstream code does not need to differentiate between explicitly defined cascades or automatically generated cascades.

Returns:

A dict keyed by cascade name, containing a pd.DataFrame with the definition of each cascade from the framework

property characs: DataFrame

Return characteristics dataframe

Returns:

Dataframe containing all characteristics

property comps: DataFrame

Return compartments dataframe

Returns:

Dataframe containing all compartments

created

Creation time

get_charac(charac_name)

Retrieve characteristic by code name

Parameters:

charac_name (str) – Code name of an characteristic

Return type:

Series

Returns:

The row of the characteristics dataframe corresponding to the requested characteristic

get_charac_includes(includes)

Expand characteristics into compartments

To initialize the model, it is necessary to map characteristics to the compartments they contain. Characteristics may contain other characteristics, but eventually all characteristics can be represented as a collection of compartments. This method takes in either a single code name, or a list of code names. It then goes through all of the code names, and recursively replaces any characteristic code names with the compartments contained in the characteristic.

The final return value is then a list of all of the compartment names that are included in the original includes. Typical usage of this function is to pass in a single characteristic name e.g.

>>> Framework.get_charac_includes('alive')

Parameters:

includes – A single code name, or list of codenames, containing only compartments and/or characteristics

Return type:

list

Returns:

A list of compartment names

get_comp(comp_name)

Retrieve compartment by code name

Parameters:

comp_name (str) – Code name of an compartment

Return type:

Series

Returns:

The row of the compartments dataframe corresponding to the requested compartment

get_databook_units(code_name)

Return the user-facing units for a quantity given a code name

This function returns the units specified in the Framework for quantities defined in the Framework. The units for a quantity are:

• For compartments, number

• For characteristics, number or fraction depending on whether a denominator is present

• For parameters, return either the explicitly specified units plus a timescale, or an empty string

• Otherwise, return the inapplicable string (e.g. ‘N.A.’)

This function computes the units dynamically based on the content of the DataFrames. This ensures that it stays in sync with the actual content - for example, if a denominator is programatically added to a characteristic, the units don’t also need to be manually updated.

Note that at this stage in computation, the units are mainly for managing presentation in the databook. For example, a characteristic with a denominator is technically dimensionless, but we need it to be reported in the databook as a fraction for data entry. Similarly, while the Framework stores the internal units and timescale for a parameter (e.g. ‘probability’ and ‘1/365’) this function will return ‘probability (per day)’ for use in the databook.

Parameters:

code_name (str) – Code name of a quantity supported by ProjectFramework.get_variable()

Return type:

str

Returns:

String containing the units of the quantity

get_interaction(interaction_name)

Retrieve interaction by code name

Parameters:

interaction_name (str) – Code name of an interaction

Return type:

Series

Returns:

The row of the interactions dataframe corresponding to the requested interaction

get_label(name)

Get full name/label from code name

This method converts a code name into a full name. If the name is already a full name, then it will be returned unchanged. Thus this function can be used to normalize inputs and guarantee full names.

Example usage:

>>> Framework.get_label('b_rate')
'Number of births'
>>> Framework.get_label('Number of births')
'Number of births'

Parameters:

name – A code name or full name

Returns:

The corresponding full name/label

get_par(par_name)

Retrieve parameter by code name

Parameters:

par_name (str) – Code name of an parameter

Return type:

Series

Returns:

The row of the parameters dataframe corresponding to the requested parameter

get_variable(name)

Retrieve variable from framework

This method retrieves compartments, characteristics, parameters, and interactions based on code names or full names. The entire row from the framework file is returned. This method can be used when accessing attributes of quantities defined in the framework.

In general, the more specialized methods Framework.get_comp(), Framework.get_charac(), Framework.get_par() and Framework.get_interaction() should be used if you know in advance which of these variables is desired, and are happy to look up by code name only. These methods are faster and will return errors if a variable of the incorrect type is requested.

Parameters:

name (str) – Code name or full name

Return type:

tuple

Returns:

A tuple containing (Series,type) where - Series is a Pandas Series corresponding to the row in the framework defining the requested variable - type is a string identifying the type of variable that was returned e.g. ‘comp’ for compartment. The

strings match FS.KEY_COMPARTMENT etc.

gitinfo

Atomica Git version information, if being run in a Git repository

property interactions: DataFrame

Return interactions dataframe

Returns:

Dataframe containing all interactions

modified

Last modified time

property name: str

Return framework name

The framework name is returned from the ‘about’ sheet in the framework file rather than being stored separately.

Returns:

The name of the framework

property pars: DataFrame

Return parameters dataframe

Returns:

Dataframe containing all parameters

property pop_types: odict

Return available population types

This returns a dictionary representation of the dataframe on the ‘Population types’ sheet of the framework, where the key is the population type code name, and the value is a dictionary with all of the attributes (columns) in the dataframe.

Returns:

A dictionary with the population types defined in the framework

save(fname)

Save framework to disk

This function writes a spreadsheet based on the actual dataframes present. This allows programmatic modifications to frameworks to be viewed in Excel.

To save the original framework file (if one was loaded in) use ProjectFramework.original.save()

Parameters:

fname – File name to write on disk

Return type:

None

sheets

Stores a dict of Pandas dataframes organized by sheet from the Excel file

spreadsheet

A sc.Spreadsheet object containing the original Excel file

to_spreadsheet()

Return content as a Sciris Spreadsheet

This :rtype: Spreadsheet :return: A sciris.Spreadsheet instance

uid

Unique identifier

version

Current Atomica version