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

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

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

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

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

diagnostics:
   diag_name:
     ...
     scripts:
       Global_Ocean_map:
         script: ocean/diagnostic_maps_quad.py
         exper_model:  {Model 1 dataset details}
         control_model: {Model 2 dataset details}
         observational_dataset: {Observational dataset details}

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_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.
`multi_model_maps`(cfg, input_files)	Make the four pane model vs model vs obs comparison plot.

esmvaltool.diag_scripts.ocean.diagnostic_maps_quad.add_map_subplot(subplot, cube, nspace, title='', cmap='')[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.

esmvaltool.diag_scripts.ocean.diagnostic_maps_quad.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_maps_quad.multi_model_maps(cfg, input_files)[source]#

Make the four pane model vs model vs obs comparison plot.

Parameters:

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

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={}, 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.