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)
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)
Functions
|
Load the config file, and send it to the plot makers. |
|
Make a simple contour map plot for an individual model. |
|
Make a simple map plot for an individual model. |
|
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.
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.
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
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)
Functions
|
Add a map subplot to the current pyplot figure. |
|
Load the config file, and send it to the plot maker. |
|
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.
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.
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
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)
Functions
|
Add a straight line fit to an axis. |
|
Add a map subplot to the current pyplot figure. |
|
Load the config file, and send it to the plot maker. |
|
Make a figure showing four maps and the other shows a scatter plot. |
|
Makes Scatter plots of model vs observational data. |
|
Round a float to a specific number of sig. |
-
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
-
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.
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)
Functions
|
Determine a string from the cube, to describe the profile. |
|
Run the diagnostics profile tool. |
|
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
-
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)
Functions
|
Load the config file and some metadata, then pass them the plot making tools. |
|
Make a simple time series plot for an indivudual model 1D cube. |
|
Calculate a moving average. |
|
Make a time series plot showing several preprocesssed datasets. |
|
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.
-
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
-
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.
-
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)
Functions
|
Add a simple sea floor line from the cube mask. |
|
Determine whether to use a log scale y axis. |
|
Determine the Transect String. |
|
Load the config file and some metadata, then pass them the plot making tools. |
|
Take a cube and return a dictionairy region: cube. |
|
Make the depth coordinate safe. |
|
Make a contour plot of the transect for an indivudual model. |
|
Make a simple plot of the transect for an indivudual model. |
|
Make a multi model comparison plot showing several transect contour plots. |
|
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.
-
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
-
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
-
esmvaltool.diag_scripts.ocean.diagnostic_transects.
make_transect_contours
(cfg, metadata, filename)[source]¶ Make a contour plot of the transect for an indivudual model.
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.
-
esmvaltool.diag_scripts.ocean.diagnostic_transects.
make_transects_plots
(cfg, metadata, filename)[source]¶ Make a simple plot of the transect for an indivudual model.
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.
-
esmvaltool.diag_scripts.ocean.diagnostic_transects.
multi_model_contours
(cfg, metadatas)[source]¶ Make a multi model comparison plot showing several transect contour plots.
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.
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.
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.
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.
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)
Functions
|
Aggregate the cube into seasonal means. |
|
Calculate the area of unmasked cube cells. |
|
Create colour map with ocean blue below a threshold and white above. |
|
Figure out the hemisphere and returns it as a string (North or South). |
|
Return a climatological season time string. |
|
Return a climatological season string in the format: “year season”. |
|
Return the cube year as a string. |
|
Load the config file and metadata, then pass them the plot making tools. |
|
Make an extent map plot showing several times for an individual model. |
|
Make a simple map plot for an individual model. |
|
Make a polar stereoscopic map plot. |
|
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
-
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
-
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
-
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
-
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
-
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
-
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.
-
esmvaltool.diag_scripts.ocean.diagnostic_seaice.
make_map_plots
(cfg, metadata, filename)[source]¶ Make a simple map plot for an individual model.
-
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.
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)
Functions
|
Add a legend outside the plot, to the right. |
|
Convert the cubes into some friendlier units. |
|
Convert from time coordinate into decimal time. |
|
Calculate the decadal_average. |
|
Make a directory out of a string or list or strings. |
|
Determinue the minimum and maximum values of a list of arrays.. |
|
Get a colour number of total from a cmap. |
|
Determinue the minimum and maximum values of a list of cubes. |
|
Determinue the largest deviation from zero in an list of cubes. |
|
Determine the decade. |
|
Load the image format from the global config file. |
|
Produce a path to the final location of the image. |
|
Load input configuration file as a Dictionairy. |
Return a list of strings with the names of observations projects. |
|
|
Guess the cftime.datetime form to create datetimes. |
|
Load the thresholds for contour plots from the config files. |
|
Take a cube and return a dictionairy layer:cube |
|
Match up model or observations dataset dictionairies from config file. |
-
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
-
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
-
esmvaltool.diag_scripts.ocean.diagnostic_tools.
decadal_average
(cube)[source]¶ Calculate the decadal_average.
- Parameters
cube (iris.cube.Cube) – The input cube
- Returns
- 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. (‘/’)
-
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
-
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.
-
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
-
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
-
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.
-
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 dictionairy (for the individual dataset file)
- Parameters
cfg (dict) – the opened global config dictionairy, passed by ESMValTool.
metadata (dict) – The metadata dictionairy 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
-
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.
-
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
-
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.
-
esmvaltool.diag_scripts.ocean.diagnostic_tools.
make_cube_layer_dict
(cube)[source]¶ Take a cube and return a dictionairy 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 dictionairy of layer name : layer cube.
- Return type
-
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 dictionairy in the cfg metadata.
- Parameters
model_type (str) – The string model_type to match (only used in debugging).
cfg_dict (dict) – the config dictionairy item for this model type, parsed directly from the diagnostics/ scripts, part of the recipe.
input_files_dict (dict) –
- The input file dictionairy, loaded directly from the get_input_files()
function, in diagnostics_tools.py.
- Returns
A dictionairy of the input files and their linked details.
- Return type