ilamb3.analysis

Analysis Python classes are statistical comparisons between model and reference data. An anlaysis class must contain (1) an __init__ abstract method that contains the arguments needed to initialize the analysis, (2) a name method that returns a human-readable name for the analysis, (3) a required_variables method that returns the variables needed to perform the analysis, and (4) a __call__ method that performs the actual anlysis and returns a dataframe of scores, an xarray dataset of reference data, and an xarray dataset of comparison data.

Users can directly access the analysis classes in Python scripts, they can be used in the benchmark run YAML file, and default analyses can be toggled on and off in the ILAMB config.py.

Classes

`ILAMBAnalysis`¶

class ilamb3.analysis.ILAMBAnalysis(**kwargs)

Bases: ABC

Direct subclasses: area_analysis, bias_analysis, cycle_analysis, dispersion_analysis, hydro_analysis, nbp_analysis, relationship_analysis, rmse_analysis, runoff_sensitivity_analysis, spatial_distribution_analysis, timeseries_analysis

The ILAMB analysis base class.

An abstract base class (ABC) in python is a way to define the structure of an object that can be used in other parts of the system. In our case this means that in order for your analysis to be compatible in the ILAMB system, you need to write a class that has at minimum the following member functions with their arguments and return values.

method ilamb3.analysis.ILAMBAnalysis.__init__(**kwargs)

Initialize the analysis.

This is run when you initialize the analysis. Any options that your analysis method will require should be input and stored here as keywords.

method ilamb3.analysis.ILAMBAnalysis.name()

Return the name of the analysis.

When results from your analysis are presented in the data dashboard, this name will be used as the clickable section title. It should be a short but human-readable name.

method ilamb3.analysis.ILAMBAnalysis.required_variables()

Return the variables used in this analysis.

Your analysis must be able to provide a list of variables that are to be used. This is so we can query models with your function and learn which variables are to be used. The assumption is that the variables you require are part of a historical-like experiment. If your analysis requires variables from different experiments, this function can also return a dictionary of lists where they keys are the experiment names from which the lists of variables are required.

method ilamb3.analysis.ILAMBAnalysis.__call__(ref, com)

The function which performs the analysis.

The work of your analysis must accept a reference and comparison dataset. The user will need to package everything that each needs for the analysis upon submission. Inside this function you can use whatever you want to generate scalars and maps/curves for plotting. Once complete, ILAMB would like results in a pandas dataframe (for scalar information) as well as a dataset for the reference and comparison.

Parameters

ref (xr.Dataset) – The reference dataset.
com (xr.Dataset) – The comparison dataset.

Returns

pd.DataFrame – The scalars and scores to be returned.
xr.Dataset – The reference intermediate maps and curves to plot
xr.Dataset – The comparison intermediate maps and curves to plot

method ilamb3.analysis.ILAMBAnalysis.plots(df, ref, com, path)

The function which creates plots from analysis intermediate results.

ILAMB will run your __call__ method over all comparisons and build up a dataframe of scalars and a dictionary of intermediate result datasets. We will pass these into this function where you can generate plots.

Parameters

df (pd.DataFrame) – The scalars and scores from all comparisons.
ref (xr.Dataset) – The reference intermediate maps and curves to plot
com (dict[str,xr.Dataset]) – A dictionary of comparison intermediate maps and curves to plot, whose keys are the model names.
path (Path) – The path to prepend to filenames of the saved images.

Returns

pd.DataFrame – The dataframe of plots.

`area_analysis`¶

class ilamb3.analysis.area_analysis(required_variable, **kwargs)

Bases: ILAMBAnalysis

The ILAMB area comparison methodology.

Parameters

required_variable (str) – The name of the variable to be used in this analysis.

method ilamb3.analysis.area_analysis.__init__(required_variable, **kwargs)

method ilamb3.analysis.area_analysis.name()

Return the name of the analysis.

Returns

str – The name of the analysis.

method ilamb3.analysis.area_analysis.required_variables()

Return the list of variables required for this analysis.

Returns

list – The variable names used in this analysis.

method ilamb3.analysis.area_analysis.__call__(ref, com)

Apply the ILAMB bias methodology on the given datasets.

Parameters

ref (xr.Dataset) – The reference dataset.
com (xr.Dataset) – The comparison dataset.

Returns

pd.DataFrame – A dataframe with scalar and score information from the comparison.
xr.Dataset – A dataset containing reference grided information from the comparison.
xr.Dataset – A dataset containing comparison grided information from the comparison.

method ilamb3.analysis.area_analysis.plots(df, ref, com, path)

`bias_analysis`¶

class ilamb3.analysis.bias_analysis(required_variable, variable_cmap='viridis', method='Collier2018', regions=[None], seasons=None, use_uncertainty=True, spatial_sum=False, mass_weighting=False, quantile_database=None, quantile_threshold=70, table_unit=None, plot_unit=None, **kwargs)

Bases: ILAMBAnalysis

The ILAMB bias methodology.

Parameters

required_variable (str) – The name of the variable to be used in this analysis.
variable_cmap (str) – The colormap to use in plots of the comparison variable, optional.
method (str) – The name of the scoring methodology to use, either Collier2018 or RegionalQuantiles.
regions (list) – A list of region labels over which to apply the analysis.
seasons (list) – A list of season strings to calculate difference (bias) scalars. For valid strings, see xr.groupers.SeasonResampler.
use_uncertainty (bool) – Enable to utilize uncertainty information from the reference product if present.
spatial_sum (bool) – Enable to report a spatial sum in the period mean as opposed to a spatial mean. This is often preferred in carbon variables where the total global carbon is of interest.
mass_weighting (bool) – Enable to weight the score map integrals by the temporal mean of the reference dataset.
quantile_dbase (pd.DataFrame) – If using method='RegionalQuantiles', the dataframe containing the regional quantiles to be used to score the datasets.
quantile_threshold (int) – If using method='RegionalQuantiles', the threshold values to use from the quantile_dbase.

method ilamb3.analysis.bias_analysis.__init__(required_variable, variable_cmap='viridis', method='Collier2018', regions=[None], seasons=None, use_uncertainty=True, spatial_sum=False, mass_weighting=False, quantile_database=None, quantile_threshold=70, table_unit=None, plot_unit=None, **kwargs)

method ilamb3.analysis.bias_analysis.name()

Return the name of the analysis.

Returns

str – The name of the analysis.

method ilamb3.analysis.bias_analysis.required_variables()

Return the list of variables required for this analysis.

Returns

list – The variable names used in this analysis.

method ilamb3.analysis.bias_analysis.__call__(ref, com)

Apply the ILAMB bias methodology on the given datasets.

Parameters

ref (xr.Dataset) – The reference dataset.
com (xr.Dataset) – The dataset that will be compared to the reference.

Returns

pd.DataFrame – A dataframe with scalar and score information from the comparison.
xr.Dataset – A dataset containing reference gridded information from the comparison.
xr.Dataset – A dataset containing comparison gridded information from the comparison.

method ilamb3.analysis.bias_analysis.plots(df, ref, com, path)

Create plots for the bias analysis.

`cycle_analysis`¶

class ilamb3.analysis.cycle_analysis(required_variable, regions=[None], plot_unit=None, variable_cmap='viridis', **kwargs)

Bases: ILAMBAnalysis

The ILAMB annual cycle methodology.

Parameters

required_variable (str) – The name of the variable to be used in this analysis.
regions (list) – A list of region labels over which to apply the analysis.

method ilamb3.analysis.cycle_analysis.__init__(required_variable, regions=[None], plot_unit=None, variable_cmap='viridis', **kwargs)

method ilamb3.analysis.cycle_analysis.name()

Return the name of this analysis.

Returns

str – The name of this analysis.

method ilamb3.analysis.cycle_analysis.required_variables()

Return the list of variables required for this analysis.

Returns

list – The variable names used in this analysis.

method ilamb3.analysis.cycle_analysis.__call__(ref, com)

Apply the ILAMB bias methodology on the given datasets.

Parameters

ref (xr.Dataset) – The reference dataset.
com (xr.Dataset) – The comparison dataset.

Returns

pd.DataFrame – A dataframe with scalar and score information from the comparison.
xr.Dataset – A dataset containing reference grided information from the comparison.
xr.Dataset – A dataset containing comparison grided information from the comparison.

method ilamb3.analysis.cycle_analysis.plots(df, ref, com, path)

`dispersion_analysis`¶

class ilamb3.analysis.dispersion_analysis(required_variable, required_num_years=10, nbins=25, regions=[None], **kwargs)

Bases: ILAMBAnalysis

The ILAMB dispersion methodology.

Parameters

required_variable (str) – The name of the variable to be used in this analysis.
regions (list) – A list of region labels over which to apply the analysis.

method ilamb3.analysis.dispersion_analysis.__init__(required_variable, required_num_years=10, nbins=25, regions=[None], **kwargs)

method ilamb3.analysis.dispersion_analysis.required_variables()

Return the list of variables required for this analysis.

Returns

list – The variable names used in this analysis.

method ilamb3.analysis.dispersion_analysis.name()

method ilamb3.analysis.dispersion_analysis.__call__(ref, com)

Apply the methodology on the given datasets.

Parameters

ref (xr.Dataset) – The reference dataset.
com (xr.Dataset) – The comparison dataset.

Returns

pd.DataFrame – A dataframe with scalar and score information from the comparison.
xr.Dataset – A dataset containing reference grided information from the comparison.
xr.Dataset – A dataset containing comparison grided information from the comparison.

method ilamb3.analysis.dispersion_analysis.plots(df, ref, com, path)

`hydro_analysis`¶

class ilamb3.analysis.hydro_analysis(required_variable, regions=None, output_path=None, **kwargs)

Bases: ILAMBAnalysis

method ilamb3.analysis.hydro_analysis.__init__(required_variable, regions=None, output_path=None, **kwargs)

method ilamb3.analysis.hydro_analysis.name()

Return the name of this analysis.

Returns

str – The name of this analysis.

method ilamb3.analysis.hydro_analysis.required_variables()

Return the list of variables required for this analysis.

Returns

list – The variable names used in this analysis.

method ilamb3.analysis.hydro_analysis.__call__(ref, com)

Apply the ILAMB bias methodology on the given datasets.

method ilamb3.analysis.hydro_analysis.plots(df, ref, com, path)

`nbp_analysis`¶

class ilamb3.analysis.nbp_analysis(evaluation_year=None, **kwargs)

Bases: ILAMBAnalysis

The ILAMB net biome production scoring methodology.

Parameters

evaluation_year (int, optional) – The year at which to report a difference and score. If not given, the last year of the reference dataset.

method ilamb3.analysis.nbp_analysis.__init__(evaluation_year=None, **kwargs)

method ilamb3.analysis.nbp_analysis.name()

Return the name of this analysis.

Returns

str – The name of this analysis.

method ilamb3.analysis.nbp_analysis.required_variables()

Return the variable names required in this analysis.

Returns

list – A list of the required variables, here always [nbp].

Notes

This analysis also accepts the variable netAtmosLandCO2Flux. If you are running this routine inside an ILAMB analysis and need to use this variable, register it with the model as a synonym.

method ilamb3.analysis.nbp_analysis.__call__(ref, com)

Apply the ILAMB bias methodology on the given datasets.

Parameters

ref (xr.Dataset) – The reference dataset.
com (xr.Dataset) – The comparison dataset.

Returns

pd.DataFrame – A dataframe with scalar and score information from the comparison.
xr.Dataset – A dataset containing reference grided information from the comparison.
xr.Dataset – A dataset containing comparison grided information from the comparison.

method ilamb3.analysis.nbp_analysis.plots(df, ref, com, path)

`relationship_analysis`¶

class ilamb3.analysis.relationship_analysis(dep_variable, ind_variable, regions=[None], **kwargs)

Bases: ILAMBAnalysis

The ILAMB relationship methodology.

Parameters

dep_variable (str) – The name of the dependent variable to be used in this analysis.
ind_variable (str) – The name of the independent variable to be used in this analysis.
regions: list[str | None] = [None], – The regions overwhich to perform the analysis.

method ilamb3.analysis.relationship_analysis.__init__(dep_variable, ind_variable, regions=[None], **kwargs)

method ilamb3.analysis.relationship_analysis.name()

Return the name of this analysis.

Returns

str – The name of this analysis.

method ilamb3.analysis.relationship_analysis.required_variables()

Return the list of variables required for this analysis.

Returns

list – The variable names used in this analysis.

method ilamb3.analysis.relationship_analysis.__call__(ref, com)

Apply the ILAMB relationship methodology on the given datasets.

Parameters

ref (xr.Dataset) – The reference dataset.
com (xr.Dataset) – The comparison dataset.

Returns

pd.DataFrame – A dataframe with scalar and score information from the comparison.
xr.Dataset – A dataset containing reference grided information from the comparison.
xr.Dataset – A dataset containing comparison grided information from the comparison.

method ilamb3.analysis.relationship_analysis.plots(df, ref, com, path)

`rmse_analysis`¶

class ilamb3.analysis.rmse_analysis(required_variable, score_basis='series', regions=[None], use_uncertainty=True, table_unit=None, plot_unit=None, **kwargs)

Bases: ILAMBAnalysis

The ILAMB RMSE methodology.

Parameters

required_variable (str) – The name of the variable to be used in this analysis.
method (str) – The name of the scoring methodology to use, either Collier2018 or RegionalQuantiles.
regions (list) – A list of region labels over which to apply the analysis.
use_uncertainty (bool) – Enable to utilize uncertainty information from the reference product if present.
quantile_dbase (pd.DataFrame) – If using method='RegionalQuantiles', the dataframe containing the regional quantiles to be used to score the datasets.
quantile_threshold (int) – If using method='RegionalQuantiles', the threshold values to use from the quantile_dbase.

method ilamb3.analysis.rmse_analysis.__init__(required_variable, score_basis='series', regions=[None], use_uncertainty=True, table_unit=None, plot_unit=None, **kwargs)

method ilamb3.analysis.rmse_analysis.name()

Return the name of this analysis.

Returns

str – The name of this analysis.

method ilamb3.analysis.rmse_analysis.required_variables()

Return the list of variables required for this analysis.

Returns

list – The variable names used in this analysis.

method ilamb3.analysis.rmse_analysis.__call__(ref, com)

Apply the ILAMB RMSE methodology on the given datasets.

Parameters

ref (xr.Dataset) – The reference dataset.
com (xr.Dataset) – The comparison dataset.

Returns

pd.DataFrame – A dataframe with scalar and score information from the comparison.
xr.Dataset – A dataset containing reference grided information from the comparison.
xr.Dataset – A dataset containing comparison grided information from the comparison.

method ilamb3.analysis.rmse_analysis.plots(df, ref, com, path)

`runoff_sensitivity_analysis`¶

class ilamb3.analysis.runoff_sensitivity_analysis(output_path=None, **kwargs)

Bases: ILAMBAnalysis

Runoff sensitivity to temperature and precipitation per river basin.

Parameters

basin_source (str) – The source file for the basins to use in the analysis.

method ilamb3.analysis.runoff_sensitivity_analysis.__init__(output_path=None, **kwargs)

method ilamb3.analysis.runoff_sensitivity_analysis.name()

Return the name of this analysis.

Returns

str – The name of this analysis.

method ilamb3.analysis.runoff_sensitivity_analysis.required_variables()

Return the variable names required in this analysis.

method ilamb3.analysis.runoff_sensitivity_analysis.__call__(ref, com, basins=None)

method ilamb3.analysis.runoff_sensitivity_analysis.plots(df, ref, com, path)

Return figures of the reference and comparison data.

`spatial_distribution_analysis`¶

class ilamb3.analysis.spatial_distribution_analysis(required_variable, regions=[None], **kwargs)

Bases: ILAMBAnalysis

The ILAMB spatial distribution methodology.

Parameters

required_variable (str) – The name of the variable to be used in this analysis.
regions (list) – A list of region labels over which to apply the analysis.

method ilamb3.analysis.spatial_distribution_analysis.__init__(required_variable, regions=[None], **kwargs)

method ilamb3.analysis.spatial_distribution_analysis.name()

Return the name of this analysis.

Returns

str – The name of this analysis.

method ilamb3.analysis.spatial_distribution_analysis.required_variables()

Return the list of variables required for this analysis.

Returns

list – The variable names used in this analysis.

method ilamb3.analysis.spatial_distribution_analysis.__call__(ref, com)

Apply the ILAMB spatial distribution methodology on the given datasets.

Parameters

ref (xr.Dataset) – The reference dataset.
com (xr.Dataset) – The comparison dataset.

Returns

pd.DataFrame – A dataframe with scalar and score information from the comparison.
xr.Dataset – A dataset containing reference grided information from the comparison.
xr.Dataset – A dataset containing comparison grided information from the comparison.

method ilamb3.analysis.spatial_distribution_analysis.plots(df, ref, com, path)

`timeseries_analysis`¶

class ilamb3.analysis.timeseries_analysis(required_variable, **kwargs)

Bases: ILAMBAnalysis

method ilamb3.analysis.timeseries_analysis.__init__(required_variable, **kwargs)

method ilamb3.analysis.timeseries_analysis.name()

method ilamb3.analysis.timeseries_analysis.required_variables()

method ilamb3.analysis.timeseries_analysis.__call__(ref, com)

method ilamb3.analysis.timeseries_analysis.plots(df, ref, com, path)

Functions

`add_overall_score`¶

function ilamb3.analysis.add_overall_score(df)

Synthesize an average ‘Overall’ score from all scores in the dataframe.

ILAMBAnalysis¶

area_analysis¶

bias_analysis¶

cycle_analysis¶

dispersion_analysis¶

hydro_analysis¶

nbp_analysis¶

relationship_analysis¶

rmse_analysis¶

runoff_sensitivity_analysis¶

spatial_distribution_analysis¶

timeseries_analysis¶

add_overall_score¶

`ILAMBAnalysis`¶

`area_analysis`¶

`bias_analysis`¶

`cycle_analysis`¶

`dispersion_analysis`¶

`hydro_analysis`¶

`nbp_analysis`¶

`relationship_analysis`¶

`rmse_analysis`¶

`runoff_sensitivity_analysis`¶

`spatial_distribution_analysis`¶

`timeseries_analysis`¶

`add_overall_score`¶