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.



Print summary of cascade


Get data values for a cascade


Get values for a cascade


Plot single or multiple cascade plot




Plot cascade for a single result


Plot stacked timeseries


Normalize cascade inputs


Sanitize input populations


Check if a cascade is valid



Ensemble for cascade plots



Error if cascade is not valid