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.


generate_framework_doc(framework, fname[, …]) Generate a framework documentation template file
sanitize_dataframe(df, required_columns, …)


ProjectFramework([inputs, name]) Base Framework class


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.

  • 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

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

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

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

Return characteristics dataframe

Return type:DataFrame
Returns:Dataframe containing all characteristics

Return compartments dataframe

Return type:DataFrame
Returns:Dataframe containing all compartments
created = None

Creation time


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

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

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

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

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

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

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


Return interactions dataframe

Return type:DataFrame
Returns:Dataframe containing all interactions
modified = None

Last modified time


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

Return parameters dataframe

Return type:DataFrame
Returns:Dataframe containing all parameters

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

  • 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:



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

  • F – A ProjectFramework instance
  • fname – The filename to write
  • databook_only – If True, only quantities appearing in the databook will be shown


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