atomica.framework.ProjectFramework

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

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 (Optional[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: sciris.sc_odict.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.

Return type

odict

Returns

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

property characs: pandas.core.frame.DataFrame

Return characteristics dataframe

Return type

DataFrame

Returns

Dataframe containing all characteristics

property comps: pandas.core.frame.DataFrame

Return compartments dataframe

Return type

DataFrame

Returns

Dataframe containing all compartments

created

Creation time

get_charac(charac_name)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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: pandas.core.frame.DataFrame

Return interactions dataframe

Return type

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.

Return type

str

Returns

The name of the framework

property pars: pandas.core.frame.DataFrame

Return parameters dataframe

Return type

DataFrame

Returns

Dataframe containing all parameters

property pop_types: sciris.sc_odict.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.

Return type

odict

Returns

A dictionary with the population types defined in the framework

save(fname)[source]

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()[source]

Return content as a Sciris Spreadsheet

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

uid

Unique identifier

version

Current Atomica version