atomica.cascade

Utility functions for working with cascades

Cascades are defined in a ProjectFramework object. This module implements functions that are useful for working with the cascades, including

  • Validation

  • Plotting

  • Value extraction

On the plotting side, the two key functions are

  • plot_single_cascade() which makes a single cascade plot complete with shaded regions between bars, and conversion arrows

  • plot_multi_cascade() which makes a scenario comparison type cascade plot with bars grouped by cascade stage (not possible with normal plotting.plot_bars())

The plot takes in as arguments the cascade and populations. Users can specify cascades as

  • The name of a cascade in the Framework

  • The index of a cascade in the Framework

  • A list of comps/characs in stage order, with stage names matching the comps/characs

  • A ordered dict with {stage:comps/characs}, with a customized stage name. This is referred to in code as a cascade dict

The first two representations map to cascades defined in the framework, while the last two representations relate to defining custom cascades on the fly. They are therefore sanitized in two stages

  • sanitize_cascade_inputs() turns cascade indices into names, and cascade lists into dicts. Returning string names for predefined cascades allows the name to be used in the title of plots

  • get_cascade_outputs() turns cascade names into cascade dicts

The dictionary representation is always required when retrieving the values of cascades. There are two types of value retrieval:

  • get_cascade_vals() which returns values for each cascade stage from a model result

  • get_cascade_data() which attempts to compute values for each cascade stage from a ProjectData instance. This is used when plotting data points on the cascade plot. Compartments and characteristics are automatically summed as required. Data points will only be displayed if the data has values for all of the included quantities in the year being plotted.

Functions

cascade_summary

Print summary of cascade

get_cascade_data

Get data values for a cascade

get_cascade_vals

Get values for a cascade

plot_cascade

Plot single or multiple cascade plot

plot_multi_cascade

plot_single_cascade

Plot cascade for a single result

plot_single_cascade_series

Plot stacked timeseries

sanitize_cascade

Normalize cascade inputs

sanitize_pops

Sanitize input populations

validate_cascade

Check if a cascade is valid

Classes

CascadeEnsemble

Ensemble for cascade plots

Exceptions

InvalidCascade

Error if cascade is not valid