atomica.framework

Implements Framework functionality

A Framework contains all of the information defining a model that can be run using Atomica. This module implements the ProjectFramework class, which provides a Python representation of a Framework file.

Functions

generate_framework_doc(framework, fname[, …])

Generate a framework documentation template file

sanitize_dataframe(df, required_columns, …)

Classes

ProjectFramework([inputs, name])

Base Framework class

Exceptions

InvalidFramework

exception atomica.framework.InvalidFramework[source]
class atomica.framework.ProjectFramework(inputs=None, name=None)[source]

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

_process_transitions()[source]

Parse transition sheet

This method parses the dataframes associated with the transition sheet into an edge-list representation, stored in ProjectFramework.transitions.

The dictionary has the form {par_name:(from_comp,to_comp)}. The dictionary is flat, so there is a single transition structure for the entire model regardless of population type.

This method expects a sheet called ‘Transitions’ to be present and correctly filled out

Return type

None

_validate()[source]

Check contents of the framework

This function validates the content of Framework. There are two aspects to this

  • Adding in any missing values using appropriate defaults

  • Checking that the provided information is internally consistent

This method is called automatically during construction, and therefore any changes made during validation will occur prior to users interacting with the ProjectFramework

If the framework contains invalid content, this function call will result in an error being raised.

Return type

None

property cascades

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

Return characteristics dataframe

Return type

DataFrame

Returns

Dataframe containing all characteristics

property comps

Return compartments dataframe

Return type

DataFrame

Returns

Dataframe containing all compartments

created = None

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 = None

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

property interactions

Return interactions dataframe

Return type

DataFrame

Returns

Dataframe containing all interactions

modified = None

Last modified time

property name

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

Return parameters dataframe

Return type

DataFrame

Returns

Dataframe containing all parameters

property pop_types

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(filename=None, folder=None)[source]

Save original spreadsheet

Parameters
  • filename (Optional[str]) – Optionally specify name of file to write - defaults to framework name

  • folder (Optional[str]) – Optionally specify directory to write to

Return type

str

Returns

The full path to the file that was written

sheets = None

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

spreadsheet = None

A sc.Spreadsheet object containing the original Excel file

uid = None

Unique identifier

version = None

Current Atomica version

atomica.framework.generate_framework_doc(framework, fname, databook_only=False)[source]

Generate a framework documentation template file

This function takes in a Framework and a file name, and writes a Markdown template file for the framework

Parameters
  • F – A ProjectFramework instance

  • fname – The filename to write

  • databook_only – If True, only quantities appearing in the databook will be shown

Returns

None

atomica.framework.sanitize_dataframe(df, required_columns, defaults, valid_content)[source]