Ocean diagnostics toolkit#

Welcome to the API documentation for the ocean diagnostics tool kit. This toolkit is built to assist in the evaluation of models of the ocean.

This toolkit is part of ESMValTool v2.

Author: Lee de Mora (PML): ledm@pml.ac.uk

Diagnostic for fig 3.24 in Chapter 3 of IPCC AR6 WGI.

This diagnostic either calculates bias with respect to the reference dataset or plots the data and the reference dataset. The diagnostic accepts the groups of the 1D datasets (with exception of the resolved mask). The additional keywords for the diagnostic provided through the recipe: bias: an option boolean flag showing if bias is calculated, default: false mask: an optional dictionary if the data should be masked, default: false mask is a dictionary and should contain keywords: flag: flag showing if the data should be masked type: type of mask, accepted values: ‘simple’ and ‘resolved’ group: name of the variable group with resolved mask (needed only if type=’resolved’) statistics: a dictionary with the statistics which will be plotted. Needs keywords ‘best_guess’: a string with the statistical operator, and ‘borders’ a list with the statistics to be the borders for teh shading. mpl_style: name of the matplotlib style file (optional) caption: figure caption (optional) color_style: optional name of the color style, colors are defined for variable groups.

The resolved mask can have as many dimensions as one needs.

Initial development by: Lee de Mora (PML): ledm@pml.ac.uk
Revised and corrected (15.01.2021): Elizaveta Malinina (CCCma): elizaveta.malinina-rieger@ec.gc.ca
Rewritten and adapted to main branch v2.12+ (08.03.2025):: Elizaveta Malinina (CCCma) elizaveta.malinina-rieger@ec.gc.ca

Classes:

Data4Analyis(name, group, cfg, mask_meta)

Data class which later will be used for plotting.

Functions:

`create_provenance`(caption)	Create provenance dictionary.
`main`(cfg)	Diagnostic itself.
`plot_bias_plot`(data_list, cfg)	Plot the diagnostic figure.

class esmvaltool.diag_scripts.ocean.diagnostic_biases.Data4Analyis(name: str, group: list, cfg: dict, mask_meta: list[dict] | None)[source]#

Bases: object

Data class which later will be used for plotting.

name#

name of the data group for which class is created

Type:: str

bias#

flag, showing if bias should be calculated

Type:: bool

mask#

flag if data should be masked

Type:: bool

mask_type#

type of the mask: ‘simple’ or ‘resolved’

Type:: str

reference#

name of the reference dataset

Type:: str

ref_cube#

iris cube with the reference dataset data

Type:: iris.cube.Cube

data#

iris cubelist with the data

Type:: iris.cube.CubeList

best_guess#

iris cube with the best guess to be plotted

Type:: iris.cube.Cube

border1#

iris cube with the bottom/top for the shading

Type:: iris.cube.Cube

border2#

iris cube with the top/bottom for the shading

Type:: iris.cube.Cube

Methods:

`calculate_statistics`(stats, cfg)	Calculate statistics which later will be plotted.
`determine_reference`(group)	Determine the reference dataset from the data group.
`mask_data`(mask_meta)	Masks data.
`obtain_data`(group, mask_meta)	Obtain data for further statistics calculation.

calculate_statistics(stats: dict, cfg: dict)[source]#

Calculate statistics which later will be plotted.

Parameters:

stats – dictionary with the statistics which will be calculated. Dictionary should have keywords ‘best_guess’ and ‘borders’.
cfg – Config dictionary coming from ESMValCore

determine_reference(group: list)[source]#

Determine the reference dataset from the data group.

Parameters:: group – List with the metadata of the variable group
Raises:: ValueError – if more than one or no reference datasets have been provided

mask_data(mask_meta: list[dict] | None)[source]#

Masks data.

Parameters:: mask_meta – List with the mask_metadata in case mask_type=’resolved’
Raises:: ValueError – if more than one datasets for resolved mask are provided or if data cubes have more than one dimension or if an unsupported type of mask is provided

obtain_data(group: list, mask_meta: list[dict] | None)[source]#

Obtain data for further statistics calculation.

Parameters:

group – List with the metadata of the variable group
mask_meta – List with the mask_metadata in case mask_type=’resolved’

esmvaltool.diag_scripts.ocean.diagnostic_biases.create_provenance(caption: str)[source]#: Create provenance dictionary.

esmvaltool.diag_scripts.ocean.diagnostic_biases.main(cfg: dict)[source]#: Diagnostic itself.

esmvaltool.diag_scripts.ocean.diagnostic_biases.plot_bias_plot(data_list: list[Data4Analyis], cfg: dict)[source]#

Plot the diagnostic figure.

Parameters:

data_list – List with the data classes which will be plotted
cfg – Config dictionary coming from ESMValCore

Maps diagnostics#

Diagnostic to produce images of a map with coastlines from a cube. These plost show latitude vs longitude and the cube value is used as the colour scale.

Note that this diagnostic assumes that the preprocessors do the bulk of the hard work, and that the cube received by this diagnostic (via the settings.yml and metadata.yml files) has no time component, a small number of depth layers, and a latitude and longitude coordinates.

An approproate preprocessor for a 3D+time field would be:

preprocessors:
  prep_map:
    extract_levels:
      levels:  [100., ]
       scheme: linear_extrap
    climate_statistics:
      operator: mean

Note that this recipe may not function on machines with no access to the internet, as cartopy may try to download the shapefiles. The solution to this issue is the put the relevant cartopy shapefiles on a disk visible to your machine, then link that path to ESMValTool via the auxiliary_data_dir variable. The cartopy masking files can be downloaded from:

https://www.naturalearthdata.com/downloads/

Here, cartopy uses the 1:10, physical coastlines and land files:

110m_coastline.dbf  110m_coastline.shp  110m_coastline.shx
110m_land.dbf  110m_land.shp  110m_land.shx

This tool is part of the ocean diagnostic tools package in the ESMValTool.

Author: Lee de Mora (PML): ledm@pml.ac.uk

Functions:

`main`(cfg)	Load the config file, and send it to the plot makers.
`make_map_contour`(cfg, metadata, filename)	Make a simple contour map plot for an individual model.
`make_map_plots`(cfg, metadata, filename)	Make a simple map plot for an individual model.
`multi_model_contours`(cfg, metadata)	Make a contour map showing several models.

esmvaltool.diag_scripts.ocean.diagnostic_maps.main(cfg)[source]#

Load the config file, and send it to the plot makers.

Parameters:: cfg (dict) – the opened global config dictionary, passed by ESMValTool.

esmvaltool.diag_scripts.ocean.diagnostic_maps.make_map_contour(cfg, metadata, filename)[source]#

Make a simple contour map plot for an individual model.

Parameters:

cfg (dict) – the opened global config dictionary, passed by ESMValTool.
metadata (dict) – the metadata dictionary
filename (str) – the preprocessed model file.

esmvaltool.diag_scripts.ocean.diagnostic_maps.make_map_plots(cfg, metadata, filename)[source]#

Make a simple map plot for an individual model.

Parameters:

cfg (dict) – the opened global config dictionary, passed by ESMValTool.
metadata (dict) – the metadata dictionary
filename (str) – the preprocessed model file.

esmvaltool.diag_scripts.ocean.diagnostic_maps.multi_model_contours(cfg, metadata)[source]#

Make a contour map showing several models.

Parameters:

cfg (dict) – the opened global config dictionary, passed by ESMValTool.
metadata (dict) – the metadata dictionary.

Model 1 vs Model 2 vs Observations diagnostics.#

Diagnostic to produce an image showing four maps, based on a comparison of two different models results against an observational dataset. This process is often used to compare a new iteration of a model under development against a previous version of the same model. The four map plots are:

Top left: model 1
Top right: model 1 minus model 2
Bottom left: model 2 minus obs
Bottom right: model 1 minus obs

All four plots show latitude vs longitude and the cube value is used as the colour scale.

This diagnostic also requires the exper_model, control_model and observational_dataset keys in the recipe.

This tool is part of the ocean diagnostic tools package in the ESMValTool, and was based on the plots produced by the Ocean Assess/Marine Assess toolkit.

Original script: Author: Lee de Mora (PML): ledm@pml.ac.uk

Refactored script: (Alphabetical order) Author: Sophie Hall (Met Office): sophie.hall@metoffice.gov.uk Author: Emma Hogan (Met Office): emma.hogan@metoffice.gov.uk Author: Dave Storkey (Met Office): dave.storkey@metoffice.gov.uk

Functions:

`create_plotting_data`(control, experiment, ...)	Calculate the diff between the ctr, exp & obs to prepare data for plots.
`create_quadmap`(exp_single_level, ...)	Add all subplots to a main plot, positions of subplots are pre-set.
`load_data`(config)	Load all necessary data to output experiment, control, observation.
`main`(config)	Load the config file and running through the order of operation.
`plot_global_single_level`(axis, cube, ...)	Create each individual plot before being added to create_quadmap.
`save_cube`(cube, field_name, config, ancestors)	Produces a provenance record and saves data for each cube.

esmvaltool.diag_scripts.ocean.diagnostic_maps_quad.create_plotting_data(control, experiment, observation)[source]#

Calculate the diff between the ctr, exp & obs to prepare data for plots.

Parameters:

control (iris cube) – Data as defined as control_model from the recipe.
experiment (iris cube) – Data as defined as exper_model from the recipe.
observation (iris cube) – Data as defined as observational_dataset from the recipe.

Returns:

exp (iris cube) – Untouched experimental input.
exp_minus_ctr (iris cube) – Experiment model minus control model.
ctr_minus_obs (iris cube) – Control model minus observational dataset.
exp_minus_obs (iris cube) – Experimental model minus observational dataset.

esmvaltool.diag_scripts.ocean.diagnostic_maps_quad.create_quadmap(exp_single_level, exp_minus_ctr_single_level, ctr_minus_obs_single_level, exp_minus_obs_single_level, config)[source]#

Add all subplots to a main plot, positions of subplots are pre-set.

Parameters:

exp_single_level (iris cube) – Extracted single level of experiment cube.
exp_minus_ctr_single_level (iris cube) – Extracted single level of exp_minus_ctr cube.
ctr_minus_obs_single_level (iris cube) – Extracted single level of ctr_minus_obs cube.
exp_minus_obs_single_level (iris cube) – Extracted single level of exp_minus_obs cube.
config (dictionary) – configuration dictionary that contains all the necessary information for the function to run. It includes details about the models, observational datasets, file paths, and other settings.

Returns:

Make the four pane model vs model vs obs comparison plot

Return type:

quadmap

esmvaltool.diag_scripts.ocean.diagnostic_maps_quad.load_data(config)[source]#

Load all necessary data to output experiment, control, observation.

Parameters:

config (dictionary) – configuration dictionary that contains all the necessary information for the function to run. It includes details about the models, observational datasets, file paths, and other settings.

Returns:

experiment (iris cube) – Data as defined as exper_model from the recipe.
control (iris cube) – Data as defined as control_model from the recipe.
observation (iris cube) – Data as defined as observational_dataset from the recipe.

esmvaltool.diag_scripts.ocean.diagnostic_maps_quad.main(config)[source]#

Load the config file and running through the order of operation.

Parameters:: config (dictionary) – configuration dictionary that contains all the necessary information for the function to run. It includes details about the models, observational datasets, file paths, and other settings.

esmvaltool.diag_scripts.ocean.diagnostic_maps_quad.plot_global_single_level(axis, cube, contour_levels, title)[source]#

Create each individual plot before being added to create_quadmap.

Parameters:

axis (matplotlib 'ax') – Represents one (sub-)plot in a figure. It contains the plotted data, axis ticks, labels, title, legend, etc.
cube (iris cube) – This is a data structure that contains the climate data to be plotted. Including information like temperature values, latitude, longitude, and depth.
contour_levels (numpy.array) – Used to set the ticks on the colour bar and used to define levels for the contour plot.
title (str) – This is a string that will be used as the title of the subplot.

esmvaltool.diag_scripts.ocean.diagnostic_maps_quad.save_cube(cube, field_name, config, ancestors)[source]#

Produces a provenance record and saves data for each cube.

Parameters:

cube (iris cube) – This is a data structure that contains the climate data to be plotted. Including information like temperature values, latitude, longitude, and depth.
field_name (str) – A string that contains the cube name with the corresponding extracted depth level.
config (dictionary) – configuration dictionary that contains all the necessary information for the function to run. It includes details about the models, observational datasets, file paths, and other settings.
ancestors (list) – A list of keys from the input_files dictionary, representing the provenance of the data. This list helps track the origin and transformation history of the data used in the cube

Model vs Observations maps Diagnostic.#

Diagnostic to produce comparison of model and data. The first kind of image shows four maps and the other shows a scatter plot.

The four pane image is a latitude vs longitude figures showing:

Top left: model
Top right: observations
Bottom left: model minus observations
Bottom right: model over observations

The scatter plots plot the matched model coordinate on the x axis, and the observational dataset on the y coordinate, then performs a linear regression of those data and plots the line of best fit on the plot. The parameters of the fit are also shown on the figure.

An appropriate preprocessor for a 3D + time field would be:

preprocessors:
  prep_map:
    extract_levels:
      levels:  [100., ]
      scheme: linear_extrap
    climate_statistics:
      operator: mean
    regrid:
      target_grid: 1x1
      scheme: linear

This tool is part of the ocean diagnostic tools package in the ESMValTool, and was based on the plots produced by the Ocean Assess/Marine Assess toolkit.

Author: Lee de Mora (PML): ledm@pml.ac.uk

Functions:

`add_linear_regression`(plot_axes, arr_x, arr_y)	Add a straight line fit to an axis.
`add_map_subplot`(subplot, cube, nspace[, ...])	Add a map subplot to the current pyplot figure.
`main`(cfg)	Load the config file, and send it to the plot maker.
`make_model_vs_obs_plots`(cfg, metadata, ...)	Make a figure showing four maps and the other shows a scatter plot.
`make_scatter`(cfg, metadata, model_filename, ...)	Makes Scatter plots of model vs observational data.
`rounds_sig`(value[, sig])	Round a float to sig significant digits & return it as a string.

esmvaltool.diag_scripts.ocean.diagnostic_model_vs_obs.add_linear_regression(plot_axes, arr_x, arr_y, showtext=True, add_diagonal=False, extent=None)[source]#

Add a straight line fit to an axis.

Parameters:

plot_axes (matplotlib.pyplot.axes) – The matplotlib axes on which to plot the linear regression.
arr_x (numpy.array) – The data for the x coordinate.
arr_y (numpy array) – The data for the y coordinate.
showtext (bool) – A flag to turn on or off the result of the fit on the plot.
add_diagonal (bool) – A flag to also add the 1:1 diagonal line to the figure
extent (list of floats) – The extent of the plot axes.

esmvaltool.diag_scripts.ocean.diagnostic_model_vs_obs.add_map_subplot(subplot, cube, nspace, title='', cmap='', extend='neither', log=False)[source]#

Add a map subplot to the current pyplot figure.

Parameters:

subplot (int) – The matplotlib.pyplot subplot number. (ie 221)
cube (iris.cube.Cube) – the iris cube to be plotted.
nspace (numpy.array) – An array of the ticks of the colour part.
title (str) – A string to set as the subplot title.
cmap (str) – A string to describe the matplotlib colour map.
extend (str) – Contourf-coloring of values outside the levels range
log (bool) – Flag to plot the colour scale linearly (False) or logarithmically (True)

esmvaltool.diag_scripts.ocean.diagnostic_model_vs_obs.main(cfg)[source]#

Load the config file, and send it to the plot maker.

Parameters:: cfg (dict) – the opened global config dictionairy, passed by ESMValTool.

esmvaltool.diag_scripts.ocean.diagnostic_model_vs_obs.make_model_vs_obs_plots(cfg, metadata, model_filename, obs_filename)[source]#

Make a figure showing four maps and the other shows a scatter plot.

The four pane image is a latitude vs longitude figures showing:

Top left: model
Top right: observations
Bottom left: model minus observations
Bottom right: model over observations

Parameters:

cfg (dict) – the opened global config dictionairy, passed by ESMValTool.
metadata (dict) – the input files dictionairy
model_filename (str) – the preprocessed model file.
obs_filename (str) – the preprocessed observations file.

esmvaltool.diag_scripts.ocean.diagnostic_model_vs_obs.make_scatter(cfg, metadata, model_filename, obs_filename)[source]#

Makes Scatter plots of model vs observational data.

Make scatter plot showing the matched model and observational data with the model data as the x-axis coordinate and the observational data as the y-axis coordinate. A linear regression is also applied to the matched data and the result of the fit is shown on the figure.

Parameters:

cfg (dict) – the opened global config dictionairy, passed by ESMValTool.
metadata (dict) – the input files dictionairy
model_filename (str) – the preprocessed model file.
obs_filename (str) – the preprocessed observations file.

esmvaltool.diag_scripts.ocean.diagnostic_model_vs_obs.rounds_sig(value, sig=3)[source]#

Round a float to sig significant digits & return it as a string.

Parameters:

value (float) – The float that is to be rounded.
sig (int) – The number of significant figures.

Returns:

The rounded output string.

Return type:

str

Profile diagnostics.#

Diagnostic to produce figure of the profile over time from a cube. These plost show cube value (ie temperature) on the x-axis, and depth/height on the y axis. The colour scale is the time series.

Note that this diagnostic assumes that the preprocessors do the bulk of the hard work, and that the cube received by this diagnostic (via the settings.yml and metadata.yml files) has a time component, and depth component, but no latitude or longitude coordinates.

An approproate preprocessor for a 3D+time field would be:

preprocessors:
  prep_profile:
    extract_volume:
      long1: 0.
      long2:  20.
      lat1:  -30.
      lat2:  30.
      z_min: 0.
      z_max: 3000.
    area_statistics:
      operator: mean

In order to add an observational dataset to the profile plot, the following arguments are needed in the diagnostic script:

diagnostics:
  diagnostic_name:
    variables:
      ...
    additional_datasets:
    - {observational dataset description}
    scripts:
      script_name:
        script: ocean/diagnostic_profiles.py
        observational_dataset: {observational dataset description}

This tool is part of the ocean diagnostic tools package in the ESMValTool.

Author: Lee de Mora (PML): ledm@pml.ac.uk

Functions:

`determine_profiles_str`(cube)	Determine a string from the cube, to describe the profile.
`main`(cfg)	Run the diagnostics profile tool.
`make_profiles_plots`(cfg, metadata, filename)	Make a profile plot for an individual model.

esmvaltool.diag_scripts.ocean.diagnostic_profiles.determine_profiles_str(cube)[source]#

Determine a string from the cube, to describe the profile.

Parameters:: cube (iris.cube.Cube) – the opened dataset as a cube.
Returns:: Returns a string which describes the profile.
Return type:: str

esmvaltool.diag_scripts.ocean.diagnostic_profiles.main(cfg)[source]#

Run the diagnostics profile tool.

Load the config file, find an observational dataset filename, pass loaded into the plot making tool.

Parameters:: cfg (dict) – the opened global config dictionairy, passed by ESMValTool.

esmvaltool.diag_scripts.ocean.diagnostic_profiles.make_profiles_plots(cfg, metadata, filename, obs_metadata=None, obs_filename='')[source]#

Make a profile plot for an individual model.

The optional observational dataset can also be added.

Parameters:

cfg (dict) – the opened global config dictionairy, passed by ESMValTool.
metadata (dict) – The metadata dictionairy for a specific model.
filename (str) – The preprocessed model file.
obs_metadata (dict) – The metadata dictionairy for the observational dataset.
obs_filename (str) – The preprocessed observational dataset file.

Time series diagnostics#

Diagnostic to produce figures of the time development of a field from cubes. These plost show time on the x-axis and cube value (ie temperature) on the y-axis.

Two types of plots are produced: individual model timeseries plots and multi model time series plots. The inidivual plots show the results from a single cube, even if this is a mutli-model mean made by the _multimodel.py preproccessor. The multi model time series plots show several models on the same axes, where each model is represented by a different line colour.

Note that this diagnostic assumes that the preprocessors do the bulk of the hard work, and that the cube received by this diagnostic (via the settings.yml and metadata.yml files) has a time component, no depth component, and no latitude or longitude coordinates.

An approproate preprocessor for a 3D+time field would be:

preprocessors:
  prep_timeseries_1:# For Global Volume Averaged
    volume_statistics:
      operator: mean

An approproate preprocessor for a 3D+time field at the surface would be:

prep_timeseries_2: # For Global surface Averaged
  extract_levels:
    levels:  [0., ]
    scheme: linear_extrap
  area_statistics:
    operator: mean

An approproate preprocessor for a 2D+time field would be:

prep_timeseries_2: # For Global surface Averaged
  area_statistics:
    operator: mean

This tool is part of the ocean diagnostic tools package in the ESMValTool.

Author: Lee de Mora (PML): ledm@pml.ac.uk

Functions:

`main`(cfg)	Load the config file and some metadata, then pass them the plot making tools.
`make_time_series_plots`(cfg, metadata, filename)	Make a simple time series plot for an indivudual model 1D cube.
`moving_average`(cube, window)	Calculate a moving average.
`multi_model_time_series`(cfg, metadata)	Make a time series plot showing several preprocesssed datasets.
`timeplot`(cube, **kwargs)	Create a time series plot from the cube.

esmvaltool.diag_scripts.ocean.diagnostic_timeseries.main(cfg)[source]#

Load the config file and some metadata, then pass them the plot making tools.

Parameters:: cfg (dict) – the opened global config dictionairy, passed by ESMValTool.

esmvaltool.diag_scripts.ocean.diagnostic_timeseries.make_time_series_plots(cfg, metadata, filename)[source]#

Make a simple time series plot for an indivudual model 1D cube.

This tool loads the cube from the file, checks that the units are sensible BGC units, checks for layers, adjusts the titles accordingly, determines the ultimate file name and format, then saves the image.

Parameters:

cfg (dict) – the opened global config dictionairy, passed by ESMValTool.
metadata (dict) – The metadata dictionairy for a specific model.
filename (str) – The preprocessed model file.

esmvaltool.diag_scripts.ocean.diagnostic_timeseries.moving_average(cube, window)[source]#

Calculate a moving average.

The window is a string which is a number and a measuremet of time. For instance, the following are acceptable window strings:

5 days
12 years
1 month
5 yr

Also note the the value used is the total width of the window. For instance, if the window provided was ‘10 years’, the the moving average returned would be the average of all values within 5 years of the central value.

In the case of edge conditions, at the start an end of the data, they only include the average of the data available. Ie the first value in the moving average of a 10 year window will only include the average of the five subsequent years.

Parameters:

cube (iris.cube.Cube) – Input cube
window (str) – A description of the window to use for the

Returns:

A cube with the movinage average set as the data points.

Return type:

iris.cube.Cube

esmvaltool.diag_scripts.ocean.diagnostic_timeseries.multi_model_time_series(cfg, metadata)[source]#

Make a time series plot showing several preprocesssed datasets.

This tool loads several cubes from the files, checks that the units are sensible BGC units, checks for layers, adjusts the titles accordingly, determines the ultimate file name and format, then saves the image.

Parameters:

cfg (dict) – the opened global config dictionairy, passed by ESMValTool.
metadata (dict) – The metadata dictionairy for a specific model.

esmvaltool.diag_scripts.ocean.diagnostic_timeseries.timeplot(cube, **kwargs)[source]#

Create a time series plot from the cube.

Note that this function simple does the plotting, it does not save the image or do any of the complex work. This function also takes and of the key word arguments accepted by the matplotlib.pyplot.plot function. These arguments are typically, color, linewidth, linestyle, etc…

If there’s only one datapoint in the cube, it is plotted as a horizontal line.

Parameters:: cube (iris.cube.Cube) – Input cube

Transects diagnostics#

Diagnostic to produce images of a transect. These plost show either latitude or longitude against depth, and the cube value is used as the colour scale.

Note that this diagnostic assumes that the preprocessors do the bulk of the hard work, and that the cube received by this diagnostic (via the settings.yml and metadata.yml files) has no time component, and one of the latitude or longitude coordinates has been reduced to a single value.

An approproate preprocessor for a 3D+time field would be:

preprocessors:
  prep_transect:
    climate_statistics:
      operator: mean
    extract_transect: # Atlantic Meridional Transect
      latitude: [-50.,50.]
      longitude: 332.

This tool is part of the ocean diagnostic tools package in the ESMValTool.

Author: Lee de Mora (PML): ledm@pml.ac.uk

Functions:

`add_sea_floor`(cube)	Add a simple sea floor line from the cube mask.
`determine_set_y_logscale`(cfg, metadata)	Determine whether to use a log scale y axis.
`determine_transect_str`(cube[, region])	Determine the Transect String.
`main`(cfg)	Load the config file and some metadata, then pass them the plot making tools.
`make_cube_region_dict`(cube)	Take a cube and return a dictionairy region: cube.
`make_depth_safe`(cube)	Make the depth coordinate safe.
`make_transect_contours`(cfg, metadata, filename)	Make a contour plot of the transect for an indivudual model.
`make_transects_plots`(cfg, metadata, filename)	Make a simple plot of the transect for an indivudual model.
`multi_model_contours`(cfg, metadatas)	Make a multi model comparison plot showing several transect contour plots.
`titlify`(title)	Check whether a title is too long then add it to current figure.

esmvaltool.diag_scripts.ocean.diagnostic_transects.add_sea_floor(cube)[source]#

Add a simple sea floor line from the cube mask.

Parameters:: cube (iris.cube.Cube) – Input cube to use to produce the sea floor.

esmvaltool.diag_scripts.ocean.diagnostic_transects.determine_set_y_logscale(cfg, metadata)[source]#

Determine whether to use a log scale y axis.

Parameters:

cfg (dict) – the opened global config dictionairy, passed by ESMValTool.
metadata (dict) – The metadata dictionairy for a specific model.

Returns:

Boolean to flag whether to plot as a log scale.

Return type:

bool

esmvaltool.diag_scripts.ocean.diagnostic_transects.determine_transect_str(cube, region='')[source]#

Determine the Transect String.

Takes a guess at a string to describe the transect.

Parameters:: cube (iris.cube.Cube) – Input cube to use to determine the transect name.

esmvaltool.diag_scripts.ocean.diagnostic_transects.main(cfg)[source]#

Load the config file and some metadata, then pass them the plot making tools.

Parameters:: cfg (dict) – the opened global config dictionairy, passed by ESMValTool.

esmvaltool.diag_scripts.ocean.diagnostic_transects.make_cube_region_dict(cube)[source]#

Take a cube and return a dictionairy region: cube.

Each item in the dict is a layer with a separate cube for each layer. ie: cubes[region] = cube from specific region

Cubes with no region component are returns as: cubes[‘’] = cube with no region component.

This is based on the method diagnostics_tools.make_cube_layer_dict, however, it wouldn’t make sense to look for depth layers here.

Parameters:: cube (iris.cube.Cube) – the opened dataset as a cube.
Returns:: A dictionairy of layer name : layer cube.
Return type:: dict

esmvaltool.diag_scripts.ocean.diagnostic_transects.make_depth_safe(cube)[source]#

Make the depth coordinate safe.

If the depth coordinate has a value of zero or above, we replace the zero with the average point of the first depth layer.

Parameters:: cube (iris.cube.Cube) – Input cube to make the depth coordinate safe
Returns:: Output cube with a safe depth coordinate
Return type:: iris.cube.Cube

esmvaltool.diag_scripts.ocean.diagnostic_transects.make_transect_contours(cfg, metadata, filename)[source]#

Make a contour plot of the transect for an indivudual model.

Parameters:

cfg (dict) – the opened global config dictionairy, passed by ESMValTool.
metadata (dict) – The metadata dictionairy for a specific model.
filename (str) – The preprocessed model file.

esmvaltool.diag_scripts.ocean.diagnostic_transects.make_transects_plots(cfg, metadata, filename)[source]#

Make a simple plot of the transect for an indivudual model.

Parameters:

cfg (dict) – the opened global config dictionairy, passed by ESMValTool.
metadata (dict) – The metadata dictionairy for a specific model.
filename (str) – The preprocessed model file.

esmvaltool.diag_scripts.ocean.diagnostic_transects.multi_model_contours(cfg, metadatas)[source]#

Make a multi model comparison plot showing several transect contour plots.

Parameters:

cfg (dict) – the opened global config dictionairy, passed by ESMValTool.
metadatas (dict) – The metadatas dictionairy for a specific model.

esmvaltool.diag_scripts.ocean.diagnostic_transects.titlify(title)[source]#

Check whether a title is too long then add it to current figure.

Parameters:: title (str) – The title for the figure.

Sea Ice Diagnostics.#

Diagnostic to produce a series of images which are useful for evaluating the behaviour of the a sea ice model.

There are three kinds of plots shown here. 1. Sea ice Extent maps plots with a stereoscoic projection. 2. Maps plots of individual models ice fracrtion. 3. Time series plots for the total ice extent.

All three kinds of plots are made for both Summer and Winter in both the North and Southern hemisphere.

This diagnostic takes data from either North or South hemisphere, and from either December-January-February or June-July-August. This diagnostic requires the data to be 2D+time, and typically expects the data field to be the sea ice cover. An approproate preprocessor would be:

preprocessors:
  timeseries_NHW_ice_extent: # North Hemisphere Winter ice_extent
    custom_order: true
    extract_time:
        start_year: 1960
        start_month: 12
        start_day: 1
        end_year: 2005
        end_month: 9
        end_day: 31
    extract_season:
      season: DJF
    extract_region:
      start_longitude: -180.
      end_longitude: 180.
      start_latitude: 0.
      end_latitude: 90.

https://www.naturalearthdata.com/downloads/

Here, cartopy uses the 1:10, physical coastlines and land files:

110m_coastline.dbf  110m_coastline.shp  110m_coastline.shx
110m_land.dbf  110m_land.shp  110m_land.shx

This tool is part of the ocean diagnostic tools package in the ESMValTool.

Author: Lee de Mora (PML): ledm@pml.ac.uk

Functions:

`agregate_by_season`(cube)	Aggregate the cube into seasonal means.
`calculate_area_time_series`(cube, plot_type, ...)	Calculate the area of unmasked cube cells.
`create_ice_cmap`([threshold])	Create colour map with ocean blue below a threshold and white above.
`get_pole`(cube)	Figure out the hemisphere and returns it as a string (North or South).
`get_season`(cube)	Return a climatological season time string.
`get_time_string`(cube)	Return a climatological season string in the format: "year season".
`get_year`(cube)	Return the cube year as a string.
`main`(cfg)	Load the config file and metadata, then pass them the plot making tools.
`make_map_extent_plots`(cfg, metadata, filename)	Make an extent map plot showing several times for an individual model.
`make_map_plots`(cfg, metadata, filename)	Make a simple map plot for an individual model.
`make_polar_map`(cube[, pole, cmap])	Make a polar stereoscopic map plot.
`make_ts_plots`(cfg, metadata, filename)	Make a ice extent and ice area time series plot for an individual model.

esmvaltool.diag_scripts.ocean.diagnostic_seaice.agregate_by_season(cube)[source]#

Aggregate the cube into seasonal means.

Note that it is not currently possible to do this in the preprocessor, as the seasonal mean changes the cube units.

Parameters:: cube (iris.cube.Cube) – Data Cube
Returns:: Data Cube with the seasonal means
Return type:: iris.cube.Cube

esmvaltool.diag_scripts.ocean.diagnostic_seaice.calculate_area_time_series(cube, plot_type, threshold)[source]#

Calculate the area of unmasked cube cells.

Requires a cube with two spacial dimensions. (no depth coordinate).

Parameters:

cube (iris.cube.Cube) – Data Cube
plot_type (str) – The type of plot: ice extent or ice area
threshold (float) – The threshold for ice fraction (typically 15%)

Returns:

numpy array – An numpy array containing the time points.
numpy.array – An numpy array containing the total ice extent or total ice area.

esmvaltool.diag_scripts.ocean.diagnostic_seaice.create_ice_cmap(threshold=0.15)[source]#

Create colour map with ocean blue below a threshold and white above.

Parameters:: threshold (float) – The threshold for the line between blue and white.
Returns:: The resulting colour map.
Return type:: matplotlib.colors.LinearSegmentedColormap

esmvaltool.diag_scripts.ocean.diagnostic_seaice.get_pole(cube)[source]#

Figure out the hemisphere and returns it as a string (North or South).

Parameters:: cube (iris.cube.Cube) – Data Cube
Returns:: The hemisphere (North or South)
Return type:: str

esmvaltool.diag_scripts.ocean.diagnostic_seaice.get_season(cube)[source]#

Return a climatological season time string.

Parameters:: cube (iris.cube.Cube) – Data Cube
Returns:: The climatological season as a string
Return type:: str

esmvaltool.diag_scripts.ocean.diagnostic_seaice.get_time_string(cube)[source]#

Return a climatological season string in the format: “year season”.

Parameters:: cube (iris.cube.Cube) – Data Cube
Returns:: The climatological season as a string
Return type:: str

esmvaltool.diag_scripts.ocean.diagnostic_seaice.get_year(cube)[source]#

Return the cube year as a string.

Parameters:: cube (iris.cube.Cube) – Data Cube
Returns:: The year as a string
Return type:: str

esmvaltool.diag_scripts.ocean.diagnostic_seaice.main(cfg)[source]#

Load the config file and metadata, then pass them the plot making tools.

Parameters:: cfg (dict) – the opened global config dictionairy, passed by ESMValTool.

esmvaltool.diag_scripts.ocean.diagnostic_seaice.make_map_extent_plots(cfg, metadata, filename)[source]#

Make an extent map plot showing several times for an individual model.

Parameters:

cfg (dict) – the opened global config dictionairy, passed by ESMValTool.
metadata (dict) – The metadata dictionairy for a specific model.
filename (str) – The preprocessed model file.

esmvaltool.diag_scripts.ocean.diagnostic_seaice.make_map_plots(cfg, metadata, filename)[source]#

Make a simple map plot for an individual model.

Parameters:

cfg (dict) – the opened global config dictionairy, passed by ESMValTool.
metadata (dict) – The metadata dictionairy for a specific model.
filename (str) – The preprocessed model file.

esmvaltool.diag_scripts.ocean.diagnostic_seaice.make_polar_map(cube, pole='North', cmap='Blues_r')[source]#

Make a polar stereoscopic map plot.

The cube is the opened cube (two dimensional), pole is the polar region (North/South) cmap is the colourmap,

Parameters:

cube (iris.cube.Cube) – Data Cube
pole (str) – The hemisphere
cmap (str) – The string describing the matplotlib colourmap.

Returns:

matplotlib.pyplot.figure – The matplotlib figure where the map was drawn.
matplotlib.pyplot.axes – The matplotlib axes where the map was drawn.

esmvaltool.diag_scripts.ocean.diagnostic_seaice.make_ts_plots(cfg, metadata, filename)[source]#

Make a ice extent and ice area time series plot for an individual model.

Parameters:

cfg (dict) – the opened global config dictionairy, passed by ESMValTool.
metadata (dict) – The metadata dictionairy for a specific model.
filename (str) – The preprocessed model file.

Diagnostic tools#

This module contains several python tools used elsewhere by the ocean diagnostics package.

This tool is part of the ocean diagnostic tools package in the ESMValTool.

Author: Lee de Mora (PML): ledm@pml.ac.uk

Functions:

`add_legend_outside_right`(plot_details, ax1)	Add a legend outside the plot, to the right.
`bgc_units`(cube, name)	Convert the cubes into some friendlier units.
`cube_time_to_float`(cube)	Convert from time coordinate into decimal time.
`decadal_average`(cube)	Calculate the decadal_average.
`folder`(name)	Make a directory out of a string or list or strings.
`get_array_range`(arrays)	Determinue the minimum and maximum values of a list of arrays..
`get_colour_from_cmap`(number, total[, cmap])	Get a colour number of total from a cmap.
`get_cube_range`(cubes)	Determinue the minimum and maximum values of a list of cubes.
`get_cube_range_diff`(cubes)	Determinue the largest deviation from zero in an list of cubes.
`get_decade`(coord, value)	Determine the decade.
`get_image_format`(cfg[, default])	Load the image format from the global config file.
`get_image_path`(cfg, metadata[, prefix, ...])	Produce a path to the final location of the image.
`get_input_files`(cfg[, index])	Load input configuration file as a Dictionairy.
`get_obs_projects`()	Return a list of strings with the names of observations projects.
`guess_calendar_datetime`(cube)	Guess the cftime.datetime form to create datetimes.
`load_thresholds`(cfg, metadata)	Load the thresholds for contour plots from the config files.
`make_cube_layer_dict`(cube)	Take a cube and return a dictionary layer:cube
`match_model_to_key`(model_type, cfg_dict, ...)	Match up model or observations dataset dictionairies from config file.
`prepare_provenance_record`(cfg, ...)	Prepare informations to feed provenance

esmvaltool.diag_scripts.ocean.diagnostic_tools.add_legend_outside_right(plot_details, ax1, column_width=0.1, loc='right')[source]#

Add a legend outside the plot, to the right.

plot_details is a 2 level dict, where the first level is some key (which is hidden) and the 2nd level contains the keys: ‘c’: color ‘lw’: line width ‘label’: label for the legend. ax1 is the axis where the plot was drawn.

Parameters:

plot_details (dict) – A dictionary of the plot details (color, linestyle, linewidth, label)
ax1 (matplotlib.pyplot.axes) – The pyplot axes to add the
column_width (float) – The width of the legend column. This is used to adjust for longer words in the legends
loc (string) – Location of the legend. Options are “right” and “below”.

Returns:

A datetime creator function from cftime, based on the cube’s calendar.

Return type:

cftime.datetime

esmvaltool.diag_scripts.ocean.diagnostic_tools.bgc_units(cube, name)[source]#

Convert the cubes into some friendlier units.

This is because many CMIP standard units are not the standard units used by the BGC community (ie, Celsius is prefered over Kelvin, etc.)

Parameters:

cube (iris.cube.Cube) – the opened dataset as a cube.
name (str) – The string describing the data field.

Returns:

the cube with the new units.

Return type:

iris.cube.Cube

esmvaltool.diag_scripts.ocean.diagnostic_tools.cube_time_to_float(cube)[source]#

Convert from time coordinate into decimal time.

Takes an iris time coordinate and returns a list of floats. :param cube: the opened dataset as a cube. :type cube: iris.cube.Cube

Returns:: List of floats showing the time coordinate in decimal time.
Return type:: list

esmvaltool.diag_scripts.ocean.diagnostic_tools.decadal_average(cube)[source]#

Calculate the decadal_average.

Parameters:: cube (iris.cube.Cube) – The input cube
Return type:: iris.cube

esmvaltool.diag_scripts.ocean.diagnostic_tools.folder(name)[source]#

Make a directory out of a string or list or strings.

Take a string or a list of strings, convert it to a directory style, then make the folder and the string. Returns folder string and final character is always os.sep. (‘/’)

Parameters:: name (list or string) – A list of nested directories, or a path to a directory.
Returns:: Returns a string of a full (potentially new) path of the directory.
Return type:: str

esmvaltool.diag_scripts.ocean.diagnostic_tools.get_array_range(arrays)[source]#

Determinue the minimum and maximum values of a list of arrays..

Parameters:: arrays (list of numpy.array) – A list of numpy.array.
Returns:: A list of two values, the overall minumum and maximum values of the list of cubes.
Return type:: list

esmvaltool.diag_scripts.ocean.diagnostic_tools.get_colour_from_cmap(number, total, cmap='jet')[source]#

Get a colour number of total from a cmap.

This function is used when several lines are created evenly along a colour map.

Parameters:

number (int, float) – The
total (int)
cmap (string, plt.cm) – A colour map, either by name (string) or from matplotlib

esmvaltool.diag_scripts.ocean.diagnostic_tools.get_cube_range(cubes)[source]#

Determinue the minimum and maximum values of a list of cubes.

Parameters:: cubes (list of iris.cube.Cube) – A list of cubes.
Returns:: A list of two values: the overall minumum and maximum values of the list of cubes.
Return type:: list

esmvaltool.diag_scripts.ocean.diagnostic_tools.get_cube_range_diff(cubes)[source]#

Determinue the largest deviation from zero in an list of cubes.

Parameters:: cubes (list of iris.cube.Cube) – A list of cubes.
Returns:: A list of two values: the maximum deviation from zero and its opposite.
Return type:: list

esmvaltool.diag_scripts.ocean.diagnostic_tools.get_decade(coord, value)[source]#

Determine the decade.

Called by iris.coord_categorisation.add_categorised_coord.

esmvaltool.diag_scripts.ocean.diagnostic_tools.get_image_format(cfg, default='png')[source]#

Load the image format from the global config file.

Current tested options are svg, png.

The cfg is the opened global config. The default format is used if no specific format is requested. The default is set in the user config.yml Individual diagnostics can set their own format which will supercede the main config.yml.

Parameters:: cfg (dict) – the opened global config dictionary, passed by ESMValTool.
Returns:: The image format extention.
Return type:: str

esmvaltool.diag_scripts.ocean.diagnostic_tools.get_image_path(cfg, metadata, prefix='diag', suffix='image', metadata_id_list='default')[source]#

Produce a path to the final location of the image.

The cfg is the opened global config, metadata is the metadata dictionary (for the individual dataset file)

Parameters:

cfg (dict) – the opened global config dictionary, passed by ESMValTool.
metadata (dict) – The metadata dictionary for a specific model.
prefix (str) – A string to prepend to the image basename.
suffix (str) – A string to append to the image basename
metadata_id_list (list) – A list of strings to add to the file path. It loads these from the cfg.

Returns:

The ultimate image path

Return type:

str

esmvaltool.diag_scripts.ocean.diagnostic_tools.get_input_files(cfg, index='')[source]#

Load input configuration file as a Dictionairy.

Get a dictionary with input files from the metadata.yml files. This is a wrappper for the _get_input_data_files function from diag_scripts.shared._base.

Parameters:

cfg (dict) – the opened global config dictionary, passed by ESMValTool.
index (int) – the index of the file in the cfg file.

Returns:

A dictionary of the input files and their linked details.

Return type:

dict

esmvaltool.diag_scripts.ocean.diagnostic_tools.get_obs_projects()[source]#

Return a list of strings with the names of observations projects.

Please keep this list up to date, or replace it with something more sensible.

Returns:: Returns a list of strings of the various types of observational data.
Return type:: list

esmvaltool.diag_scripts.ocean.diagnostic_tools.guess_calendar_datetime(cube)[source]#

Guess the cftime.datetime form to create datetimes.

Parameters:: cube (iris.cube.Cube) – the opened dataset as a cube.
Returns:: A datetime creator function from cftime, based on the cube’s calendar.
Return type:: cftime.datetime

esmvaltool.diag_scripts.ocean.diagnostic_tools.load_thresholds(cfg, metadata)[source]#

Load the thresholds for contour plots from the config files.

Parameters:

cfg (dict) – the opened global config dictionary, passed by ESMValTool.
metadata (dict) – the metadata dictionary

Returns:

List of thresholds

Return type:

list

esmvaltool.diag_scripts.ocean.diagnostic_tools.make_cube_layer_dict(cube)[source]#

Take a cube and return a dictionary layer:cube

Each item in the dict is a layer with a separate cube for each layer. ie: cubes[depth] = cube from specific layer

Cubes with no depth component are returned as dict, where the dict key is a blank empty string, and the value is the cube.

Parameters:: cube (iris.cube.Cube) – the opened dataset as a cube.
Returns:: A dictionary of layer name : layer cube.
Return type:: dict

esmvaltool.diag_scripts.ocean.diagnostic_tools.match_model_to_key(model_type, cfg_dict, input_files_dict)[source]#

Match up model or observations dataset dictionairies from config file.

This function checks that the control_model, exper_model and observational_dataset dictionairies from the recipe are matched with the input file dictionary in the cfg metadata.

Parameters:

model_type (str) – The string model_type to match (only used in debugging).
cfg_dict (dict) – the config dictionary item for this model type, parsed directly from the diagnostics/ scripts, part of the recipe.
input_files_dict (dict) –

The input file dictionary, loaded directly from the get_input_files()
function, in diagnostics_tools.py.

Returns:

A dictionary of the input files and their linked details.

Return type:

dict

esmvaltool.diag_scripts.ocean.diagnostic_tools.prepare_provenance_record(cfg, **provenance_record)[source]#

Prepare informations to feed provenance

Parameters:

cfg (dict) – the opened global config dictionary, passed by ESMValTool.
provenance_record (dict) – dictionary for a specific diagnostic provenance details.

Ocean diagnostics toolkit#

Maps diagnostics#

Model 1 vs Model 2 vs Observations diagnostics.#

Model vs Observations maps Diagnostic.#

Profile diagnostics.#

Time series diagnostics#

Transects diagnostics#

Sea Ice Diagnostics.#

Diagnostic tools#

This Page