<a id="api-shared"></a>

# Shared diagnostic script code

Code that is shared between multiple diagnostic scripts.

**Classes:**

| [`Datasets`](#esmvaltool.diag_scripts.shared.Datasets)(cfg)                            | Class to easily access a recipe's datasets in a diagnostic script.   |
|-------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
| [`ProvenanceLogger`](#esmvaltool.diag_scripts.shared.ProvenanceLogger)(cfg)                    | Open the provenance logger.                                          |
| [`Variable`](#esmvaltool.diag_scripts.shared.Variable)(short_name, standard_name, ...) | Variable class containing all relevant information.                  |
| [`Variables`](#esmvaltool.diag_scripts.shared.Variables)([cfg])                         | Class to easily access a recipe's variables in a diagnostic.         |

**Functions:**

| [`apply_supermeans`](#esmvaltool.diag_scripts.shared.apply_supermeans)(ctrl, exper, obs_list)         | Apply supermeans on data components ie MEAN on time.              |
|--------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| [`extract_variables`](#esmvaltool.diag_scripts.shared.extract_variables)(cfg[, as_iris])               | Extract basic variable information from configuration dictionary. |
| [`get_cfg`](#esmvaltool.diag_scripts.shared.get_cfg)([filename])                             | Read diagnostic script configuration from settings.yml.           |
| [`get_control_exper_obs`](#esmvaltool.diag_scripts.shared.get_control_exper_obs)(short_name, ...[, ...])   | Get control, exper and obs datasets.                              |
| [`get_diagnostic_filename`](#esmvaltool.diag_scripts.shared.get_diagnostic_filename)(basename, cfg[, ...])   | Get a valid path for saving a diagnostic data file.               |
| [`get_plot_filename`](#esmvaltool.diag_scripts.shared.get_plot_filename)(basename, cfg)                | Get a valid path for saving a diagnostic plot.                    |
| [`group_metadata`](#esmvaltool.diag_scripts.shared.group_metadata)(metadata, attribute[, sort])     | Group metadata describing preprocessed data by attribute.         |
| [`run_diagnostic`](#esmvaltool.diag_scripts.shared.run_diagnostic)()                                | Run a Python diagnostic.                                          |
| [`save_data`](#esmvaltool.diag_scripts.shared.save_data)(basename, provenance, cfg, cube, ...) | Save the data used to create a plot to file.                      |
| [`save_figure`](#esmvaltool.diag_scripts.shared.save_figure)(basename, provenance, cfg[, ...])   | Save a figure to file.                                            |
| [`select_metadata`](#esmvaltool.diag_scripts.shared.select_metadata)(metadata, \*\*attributes)       | Select specific metadata describing preprocessed data.            |
| [`sorted_group_metadata`](#esmvaltool.diag_scripts.shared.sorted_group_metadata)(metadata_groups, sort)    | Sort grouped metadata.                                            |
| [`sorted_metadata`](#esmvaltool.diag_scripts.shared.sorted_metadata)(metadata, sort)                 | Sort a list of metadata describing preprocessed data.             |
| [`variables_available`](#esmvaltool.diag_scripts.shared.variables_available)(cfg, short_names)           | Check if data from certain variables is available.                |

### *class* esmvaltool.diag_scripts.shared.Datasets(cfg)

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

Class to easily access a recipe’s datasets in a diagnostic script.

#### NOTE
This class has been deprecated in version 2.2 and will be removed two minor
releases later in version 2.4.

### Examples

Get all variables of a recipe configuration cfg:

```default
datasets = Datasets(cfg)
```

Access data of a dataset with path dataset_path:

```default
datasets.get_data(path=dataset_path)
```

Access dataset information of the dataset:

```default
datasets.get_dataset_info(path=dataset_path)
```

Access the data of all datasets with exp=piControl:

```default
datasets.get_data_list(exp=piControl)
```

**Methods:**

| [`add_dataset`](#esmvaltool.diag_scripts.shared.Datasets.add_dataset)(path[, data])               | Add dataset to class.                   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| [`add_to_data`](#esmvaltool.diag_scripts.shared.Datasets.add_to_data)(data[, path])               | Add element to a dataset's data.        |
| [`get_data`](#esmvaltool.diag_scripts.shared.Datasets.get_data)([path])                        | Access a dataset's data.                |
| [`get_data_list`](#esmvaltool.diag_scripts.shared.Datasets.get_data_list)(\*\*dataset_info)         | Access the datasets' data in a list.    |
| [`get_dataset_info`](#esmvaltool.diag_scripts.shared.Datasets.get_dataset_info)([path])                | Access a dataset's information.         |
| [`get_dataset_info_list`](#esmvaltool.diag_scripts.shared.Datasets.get_dataset_info_list)(\*\*dataset_info) | Access dataset's information in a list. |
| [`get_info`](#esmvaltool.diag_scripts.shared.Datasets.get_info)(key[, path])                   | Access a 'dataset_info\`'s key.         |
| [`get_info_list`](#esmvaltool.diag_scripts.shared.Datasets.get_info_list)(key, \*\*dataset_info)    | Access dataset_info's key values.       |
| [`get_path`](#esmvaltool.diag_scripts.shared.Datasets.get_path)(\*\*dataset_info)              | Access a dataset's path.                |
| [`get_path_list`](#esmvaltool.diag_scripts.shared.Datasets.get_path_list)(\*\*dataset_info)         | Access dataset's paths in a list.       |
| [`set_data`](#esmvaltool.diag_scripts.shared.Datasets.set_data)(data[, path])                  | Set element as a dataset's data.        |

#### add_dataset(path, data=None, \*\*dataset_info)

Add dataset to class.

* **Parameters:**
  * **path** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – (Unique) path to the dataset.
  * **data** (*optional*) – Arbitrary object to be saved as data for the dataset.
  * **\*\*dataset_info** (*optional*) – Keyword arguments describing the dataset, e.g. dataset=CanESM2,
    exp=piControl or short_name=tas.

#### add_to_data(data, path=None, \*\*dataset_info)

Add element to a dataset’s data.

### Notes

Either path or a unique dataset_info description have to be given.
Fails when given information is ambiguous.

* **Parameters:**
  * **data** – Element to be added to the dataset’s data.
  * **path** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* *optional*) – Path to the dataset
  * **\*\*dataset_info** (*optional*) – Keyword arguments describing the dataset, e.g. dataset=CanESM2,
    exp=piControl or short_name=tas.
* **Raises:**
  [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) – If data given by dataset_info is ambiguous.

#### get_data(path=None, \*\*dataset_info)

Access a dataset’s data.

### Notes

Either path or a unique dataset_info description have to be
given. Fails when given information is ambiguous.

* **Parameters:**
  * **path** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* *optional*) – Path to the dataset
  * **\*\*dataset_info** (*optional*) – Keyword arguments describing the dataset, e.g. dataset=CanESM2,
    exp=piControl or short_name=tas.
* **Returns:**
  Data of the selected dataset.
* **Return type:**
  data_object
* **Raises:**
  [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) – If data given by dataset_info is ambiguous.

#### get_data_list(\*\*dataset_info)

Access the datasets’ data in a list.

### Notes

The returned data is sorted alphabetically respective to the paths.

* **Parameters:**
  **\*\*dataset_info** (*optional*) – Keyword arguments describing the dataset, e.g. dataset=CanESM2,
  exp=piControl or short_name=tas.
* **Returns:**
  Data of the selected datasets.
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list)

#### get_dataset_info(path=None, \*\*dataset_info)

Access a dataset’s information.

### Notes

Either path or a unique dataset_info description have to be
given. Fails when given information is ambiguous.

* **Parameters:**
  * **path** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* *optional*) – Path to the dataset.
  * **\*\*dataset_info** (*optional*) – Keyword arguments describing the dataset, e.g. dataset=CanESM2,
    exp=piControl or short_name=tas.
* **Returns:**
  All dataset information.
* **Return type:**
  [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)
* **Raises:**
  [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) – If data given by dataset_info is ambiguous.

#### get_dataset_info_list(\*\*dataset_info)

Access dataset’s information in a list.

### Notes

The returned data is sorted alphabetically respective to the paths.

* **Parameters:**
  **\*\*dataset_info** (*optional*) – Keyword arguments describing the dataset, e.g. dataset=CanESM2,
  exp=piControl or short_name=tas.
* **Returns:**
  Information dictionaries of the selected datasets.
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list)

#### get_info(key, path=None, \*\*dataset_info)

Access a ‘dataset_info\`’s key.

### Notes

Either path or a unique dataset_info description have to be
given. Fails when given information is ambiguous. If the dataset_info
does not contain the key, returns None.

* **Parameters:**
  * **key** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – Desired dictionary key.
  * **path** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – Path to the dataset.
  * **\*\*dataset_info** (*optional*) – Keyword arguments describing the dataset, e.g. dataset=CanESM2,
    exp=piControl or short_name=tas.
* **Returns:**
  key information of the given dataset.
* **Return type:**
  [str](https://docs.python.org/3/builtins/stdtypes.html#str)
* **Raises:**
  [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) – If data given by dataset_info is ambiguous.

#### get_info_list(key, \*\*dataset_info)

Access dataset_info’s key values.

### Notes

The returned data is sorted alphabetically respective to the paths.

* **Parameters:**
  * **key** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – Desired dictionary key.
  * **\*\*dataset_info** (*optional*) – Keyword arguments describing the dataset, e.g. dataset=CanESM2,
    exp=piControl or short_name=tas.
* **Returns:**
  key information of the selected datasets.
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list)

#### get_path(\*\*dataset_info)

Access a dataset’s path.

### Notes

A unique dataset_info description has to be given. Fails when given
information is ambiguous.

* **Parameters:**
  **\*\*dataset_info** (*optional*) – Keyword arguments describing the dataset, e.g. dataset=CanESM2,
  exp=piControl or short_name=tas.
* **Returns:**
  Path of the selected dataset.
* **Return type:**
  [str](https://docs.python.org/3/builtins/stdtypes.html#str)
* **Raises:**
  [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) – If data given by dataset_info is ambiguous.

#### get_path_list(\*\*dataset_info)

Access dataset’s paths in a list.

### Notes

The returned data is sorted alphabetically respective to the paths.

* **Parameters:**
  **\*\*dataset_info** (*optional*) – Keyword arguments describing the dataset, e.g. dataset=CanESM2,
  exp=piControl or short_name=tas.
* **Returns:**
  Paths of the selected datasets.
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list)

#### set_data(data, path=None, \*\*dataset_info)

Set element as a dataset’s data.

### Notes

Either path or a unique dataset_info description have to be
given. Fails when if given information is ambiguous.

* **Parameters:**
  * **data** – Element to be set as the dataset’s data.
  * **path** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* *optional*) – Path to the dataset.
  * **\*\*dataset_info** (*optional*) – Keyword arguments describing the dataset, e.g. dataset=CanESM2,
    exp=piControl or short_name=tas.
* **Raises:**
  [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) – If data given by dataset_info is ambiguous.

### *class* esmvaltool.diag_scripts.shared.ProvenanceLogger(cfg)

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

Open the provenance logger.

* **Parameters:**
  **cfg** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – Dictionary with diagnostic configuration.

### Example

Use as a context manager:

```default
record = {
    'caption': "This is a nice plot.",
    'statistics': ['mean'],
    'domain': ['global'],
    'plot_type': ['zonal'],
    'authors': [
        'first_author',
        'second_author',
    ],
    'references': [
        'author20journal',
    ],
    'ancestors': [
        '/path/to/input_file_1.nc',
        '/path/to/input_file_2.nc',
    ],
}
output_file = '/path/to/result.nc'

with ProvenanceLogger(cfg) as provenance_logger:
    provenance_logger.log(output_file, record)
```

**Methods:**

| [`log`](#esmvaltool.diag_scripts.shared.ProvenanceLogger.log)(filename, record)   | Record provenance.   |
|--------------------------------------------------------------------------|----------------------|

#### log(filename, record)

Record provenance.

* **Parameters:**
  * **filename** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – Name of the file containing the diagnostic data.
  * **record** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – 

    Dictionary with the provenance information to be logged.

    Typical keys are:
    : - ancestors
      - authors
      - caption
      - domain
      - plot_type
      - references
      - statistics

#### NOTE
See the provenance [documentation](https://docs.esmvaltool.org/en/latest/community/diagnostic.html#recording-provenance) for more information.

### *class* esmvaltool.diag_scripts.shared.Variable(short_name, standard_name, long_name, units)

Bases: [`Variable`](#esmvaltool.diag_scripts.shared.Variable)

Variable class containing all relevant information.

#### NOTE
This class has been deprecated in version 2.2 and will be removed two minor
releases later in version 2.4.

**Methods:**

| [`count`](#esmvaltool.diag_scripts.shared.Variable.count)(value, /)             | Return number of occurrences of value.   |
|------------------------------------------------------------------------------|------------------------------------------|
| [`index`](#esmvaltool.diag_scripts.shared.Variable.index)(value[, start, stop]) | Return first index of value.             |

**Attributes:**

| [`long_name`](#esmvaltool.diag_scripts.shared.Variable.long_name)     | Alias for field number 2   |
|----------------------------------------------------------------|----------------------------|
| [`short_name`](#esmvaltool.diag_scripts.shared.Variable.short_name)    | Alias for field number 0   |
| [`standard_name`](#esmvaltool.diag_scripts.shared.Variable.standard_name) | Alias for field number 1   |
| [`units`](#esmvaltool.diag_scripts.shared.Variable.units)         | Alias for field number 3   |

#### count(value,)

Return number of occurrences of value.

#### index(value, start=0, stop=9223372036854775807,)

Return first index of value.

Raises ValueError if the value is not present.

#### long_name

Alias for field number 2

#### short_name

Alias for field number 0

#### standard_name

Alias for field number 1

#### units

Alias for field number 3

### *class* esmvaltool.diag_scripts.shared.Variables(cfg=None, \*\*names)

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

Class to easily access a recipe’s variables in a diagnostic.

#### NOTE
This class has been deprecated in version 2.2 and will be removed two minor
releases later in version 2.4.

### Examples

Get all variables of a recipe configuration cfg:

```default
variables = Variables(cfg)
```

Access information of a variable tas:

```default
variables.short_name('tas')
variables.standard_name('tas')
variables.long_name('tas')
variables.units('tas')
```

Access [`iris`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.html#module-iris)-suitable dictionary of a variable tas:

```default
variables.iris_dict('tas')
```

Check if variables tas and pr are available:

```default
variables.vars_available('tas', 'pr')
```

**Methods:**

| [`add_vars`](#esmvaltool.diag_scripts.shared.Variables.add_vars)(\*\*names)        | Add custom variables to the class.                                                                                              |
|-----------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| [`iris_dict`](#esmvaltool.diag_scripts.shared.Variables.iris_dict)(var)             | Access [`iris`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.html#module-iris) dictionary of the variable. |
| [`long_name`](#esmvaltool.diag_scripts.shared.Variables.long_name)(var)             | Access long name.                                                                                                               |
| [`modify_var`](#esmvaltool.diag_scripts.shared.Variables.modify_var)(var, \*\*names) | Modify an already existing  variable of the class.                                                                              |
| [`short_name`](#esmvaltool.diag_scripts.shared.Variables.short_name)(var)            | Access short name.                                                                                                              |
| [`short_names`](#esmvaltool.diag_scripts.shared.Variables.short_names)()              | Get list of all short_names.                                                                                                    |
| [`standard_name`](#esmvaltool.diag_scripts.shared.Variables.standard_name)(var)         | Access standard name.                                                                                                           |
| [`standard_names`](#esmvaltool.diag_scripts.shared.Variables.standard_names)()           | Get list of all standard_names.                                                                                                 |
| [`units`](#esmvaltool.diag_scripts.shared.Variables.units)(var)                 | Access units.                                                                                                                   |
| [`var_name`](#esmvaltool.diag_scripts.shared.Variables.var_name)(var)              | Access var name.                                                                                                                |
| [`vars_available`](#esmvaltool.diag_scripts.shared.Variables.vars_available)(\*args)     | Check if given variables are available.                                                                                         |

#### add_vars(\*\*names)

Add custom variables to the class.

* **Parameters:**
  **\*\*names** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict) *or* [*Variable*](#esmvaltool.diag_scripts.shared.Variable) *,* *optional*) – Keyword arguments of the form short_name=Variable_object where
  Variable_object can be given as [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) or [`Variable`](#esmvaltool.diag_scripts.shared.Variable).

#### iris_dict(var)

Access [`iris`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.html#module-iris) dictionary of the variable.

* **Parameters:**
  **var** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – (Short) name of the variable.
* **Returns:**
  Dictionary containing all attributes of the variable which can be
  used directly in [`iris`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.html#module-iris) (short_name replaced by var_name).
* **Return type:**
  [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)

#### long_name(var)

Access long name.

* **Parameters:**
  **var** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – (Short) name of the variable.
* **Returns:**
  Long name of the variable.
* **Return type:**
  [str](https://docs.python.org/3/builtins/stdtypes.html#str)

#### modify_var(var, \*\*names)

Modify an already existing  variable of the class.

* **Parameters:**
  * **var** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – (Short) name of the existing variable.
  * **\*\*names** – Keyword arguments of the form short_name=tas.
* **Raises:**
  * [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If var is not an existing variable.
  * [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – If a non-valid keyword argument is given.

#### short_name(var)

Access short name.

* **Parameters:**
  **var** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – (Short) name of the variable.
* **Returns:**
  Short name of the variable.
* **Return type:**
  [str](https://docs.python.org/3/builtins/stdtypes.html#str)

#### short_names()

Get list of all short_names.

* **Returns:**
  List of all short_names.
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list)

#### standard_name(var)

Access standard name.

* **Parameters:**
  **var** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – (Short) name of the variable.
* **Returns:**
  Standard name of the variable.
* **Return type:**
  [str](https://docs.python.org/3/builtins/stdtypes.html#str)

#### standard_names()

Get list of all standard_names.

* **Returns:**
  List of all standard_names.
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list)

#### units(var)

Access units.

* **Parameters:**
  **var** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – (Short) name of the variable.
* **Returns:**
  Units of the variable.
* **Return type:**
  [str](https://docs.python.org/3/builtins/stdtypes.html#str)

#### var_name(var)

Access var name.

* **Parameters:**
  **var** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – (Short) name of the variable.
* **Returns:**
  Var name (=short name) of the variable.
* **Return type:**
  [str](https://docs.python.org/3/builtins/stdtypes.html#str)

#### vars_available(\*args)

Check if given variables are available.

* **Parameters:**
  **\*args** – Short names of the variables to be tested.
* **Returns:**
  True if variables are available, False if not.
* **Return type:**
  [bool](https://docs.python.org/3/builtins/functions.html#bool)

### esmvaltool.diag_scripts.shared.apply_supermeans(ctrl, exper, obs_list)

Apply supermeans on data components ie MEAN on time.

This function is an extension of climate_statistics() meant to ease the
time-meaning procedure when dealing with CONTROL, EXPERIMENT and OBS
(if any) datasets.
ctrl: dictionary of CONTROL dataset
exper: dictionary of EXPERIMENT dataset
obs_lis: list of dicts for OBS datasets (0, 1 or many)

Returns: control and experiment cubes and list of obs cubes

### esmvaltool.diag_scripts.shared.extract_variables(cfg, as_iris=False)

Extract basic variable information from configuration dictionary.

Returns short_name, standard_name, long_name and units keys for
each variable.

* **Parameters:**
  * **cfg** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – Diagnostic script configuration.
  * **as_iris** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* *optional*) – Replace short_name by var_name, this can be used directly in
    [`iris`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.html#module-iris) classes.
* **Returns:**
  Variable information in `dict`s (values) for each `short_name`
  (key).
* **Return type:**
  [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)

### esmvaltool.diag_scripts.shared.get_cfg(filename=None)

Read diagnostic script configuration from settings.yml.

### esmvaltool.diag_scripts.shared.get_control_exper_obs(short_name, input_data, cfg, cmip_type=None)

Get control, exper and obs datasets.

This function is used when running recipes that need
a clear distinction between a control dataset, an experiment
dataset and have optional obs (OBS, obs4MIPs etc) datasets;
such recipes include recipe_validation, and all the autoassess
ones;
short_name: variable short name
input_data: dict containing the input data info
cfg: config file as used in this module
cmip_type: optional, CMIP project type (CMIP5 or CMIP6)

### esmvaltool.diag_scripts.shared.get_diagnostic_filename(basename, cfg, extension='nc')

Get a valid path for saving a diagnostic data file.

* **Parameters:**
  * **basename** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – The basename of the file.
  * **cfg** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – Dictionary with diagnostic configuration.
  * **extension** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – File name extension.
* **Returns:**
  A valid path for saving a diagnostic data file.
* **Return type:**
  [str](https://docs.python.org/3/builtins/stdtypes.html#str)

### esmvaltool.diag_scripts.shared.get_plot_filename(basename, cfg)

Get a valid path for saving a diagnostic plot.

* **Parameters:**
  * **basename** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – The basename of the file.
  * **cfg** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – Dictionary with diagnostic configuration.
* **Returns:**
  A valid path for saving a diagnostic plot.
* **Return type:**
  [str](https://docs.python.org/3/builtins/stdtypes.html#str)

### esmvaltool.diag_scripts.shared.group_metadata(metadata, attribute, sort=None)

Group metadata describing preprocessed data by attribute.

* **Parameters:**
  * **metadata** ([`list`](https://docs.python.org/3/builtins/stdtypes.html#list) of [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)) – A list of metadata describing preprocessed data.
  * **attribute** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – The attribute name that the metadata should be grouped by.
  * **sort** – See sorted_group_metadata.
* **Returns:**
  A dictionary containing the requested groups.
* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) of [`list`](https://docs.python.org/3/builtins/stdtypes.html#list) of [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### esmvaltool.diag_scripts.shared.run_diagnostic()

Run a Python diagnostic.

This context manager is the main entry point for most Python diagnostics.

### Example

See esmvaltool/diag_scripts/examples/diagnostic.py for an extensive
example of how to start your diagnostic.

Basic usage is as follows, add these lines at the bottom of your script:

```default
def main(cfg):
    # Your diagnostic code goes here.
    print(cfg)

if __name__ == '__main__':
    with run_diagnostic() as cfg:
        main(cfg)
```

To prevent the diagnostic script from using the Dask Distributed scheduler,
set `no_distributed: true` in the diagnostic script definition in the
recipe or in the resulting settings.yml file.

The cfg dict passed to main contains the script configuration that
can be used with the other functions in this module.

### esmvaltool.diag_scripts.shared.save_data(basename, provenance, cfg, cube, \*\*kwargs)

Save the data used to create a plot to file.

* **Parameters:**
  * **basename** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – The basename of the file.
  * **provenance** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – The provenance record for the data.
  * **cfg** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – Dictionary with diagnostic configuration.
  * **cube** ([*iris.cube.Cube*](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.cube.html#iris.cube.Cube)) – Data cube to save.
  * **\*\*kwargs** – Extra keyword arguments to pass to [`iris.save`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.html#iris.save).

#### SEE ALSO
[`ProvenanceLogger`](#esmvaltool.diag_scripts.shared.ProvenanceLogger)
: For an example provenance record that can be used with this function.

### esmvaltool.diag_scripts.shared.save_figure(basename, provenance, cfg, figure=None, close=True, \*\*kwargs)

Save a figure to file.

* **Parameters:**
  * **basename** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – The basename of the file.
  * **provenance** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – The provenance record for the figure.
  * **cfg** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – Dictionary with diagnostic configuration.
  * **figure** ([*matplotlib.figure.Figure*](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html#matplotlib.figure.Figure)) – Figure to save.
  * **close** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Close the figure after saving.
  * **\*\*kwargs** – Keyword arguments to pass to [`matplotlib.figure.Figure.savefig`](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.savefig.html#matplotlib.figure.Figure.savefig).

#### SEE ALSO
[`ProvenanceLogger`](#esmvaltool.diag_scripts.shared.ProvenanceLogger)
: For an example provenance record that can be used with this function.

### esmvaltool.diag_scripts.shared.select_metadata(metadata, \*\*attributes)

Select specific metadata describing preprocessed data.

* **Parameters:**
  * **metadata** ([`list`](https://docs.python.org/3/builtins/stdtypes.html#list) of [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)) – A list of metadata describing preprocessed data.
  * **\*\*attributes** – Keyword arguments specifying the required variable attributes and
    their values.
    Use the value ‘\*’ to select any variable that has the attribute.
* **Returns:**
  A list of matching metadata.
* **Return type:**
  [`list`](https://docs.python.org/3/builtins/stdtypes.html#list) of [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### esmvaltool.diag_scripts.shared.sorted_group_metadata(metadata_groups, sort)

Sort grouped metadata.

Sorting is done on strings and is not case sensitive.

* **Parameters:**
  * **metadata_groups** ([`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) of [`list`](https://docs.python.org/3/builtins/stdtypes.html#list) of [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)) – Dictionary containing the groups of metadata.
  * **sort** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool) or [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) or [`list`](https://docs.python.org/3/builtins/stdtypes.html#list) of [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – One or more attributes to sort by or True to just sort the groups but
    not the lists.
* **Returns:**
  A dictionary containing the requested groups.
* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) of [`list`](https://docs.python.org/3/builtins/stdtypes.html#list) of [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### esmvaltool.diag_scripts.shared.sorted_metadata(metadata, sort)

Sort a list of metadata describing preprocessed data.

Sorting is done on strings and is not case sensitive.

* **Parameters:**
  * **metadata** ([`list`](https://docs.python.org/3/builtins/stdtypes.html#list) of [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)) – A list of metadata describing preprocessed data.
  * **sort** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str) or [`list`](https://docs.python.org/3/builtins/stdtypes.html#list) of [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – One or more attributes to sort by.
* **Returns:**
  The sorted list of variable metadata.
* **Return type:**
  [`list`](https://docs.python.org/3/builtins/stdtypes.html#list) of [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### esmvaltool.diag_scripts.shared.variables_available(cfg, short_names)

Check if data from certain variables is available.

* **Parameters:**
  * **cfg** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – Diagnostic script configuration.
  * **short_names** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list) *of* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – Variable short_names which should be checked.
* **Returns:**
  True if all variables available, False if not.
* **Return type:**
  [bool](https://docs.python.org/3/builtins/functions.html#bool)

## Iris helper functions

Convenience functions for [`iris`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.html#module-iris) objects.

**Functions:**

| [`check_coordinate`](#esmvaltool.diag_scripts.shared.iris_helpers.check_coordinate)(cubes, coord_name)           | Compare coordinate of cubes and raise error if not identical.                                                                                             |
|------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`convert_to_iris`](#esmvaltool.diag_scripts.shared.iris_helpers.convert_to_iris)(dict_)                        | Change all appearances of `short_name` to `var_name`.                                                                                                     |
| [`get_mean_cube`](#esmvaltool.diag_scripts.shared.iris_helpers.get_mean_cube)(datasets)                       | Get mean cube of a list of datasets.                                                                                                                      |
| [`intersect_dataset_coordinates`](#esmvaltool.diag_scripts.shared.iris_helpers.intersect_dataset_coordinates)(cubes)          | Compare dataset coordinates of cubes and match them if necessary.                                                                                         |
| [`iris_project_constraint`](#esmvaltool.diag_scripts.shared.iris_helpers.iris_project_constraint)(projects, input_data) | Create [`iris.Constraint`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.html#iris.Constraint) to select specific projects from data. |
| [`prepare_cube_for_merging`](#esmvaltool.diag_scripts.shared.iris_helpers.prepare_cube_for_merging)(cube, cube_label)    | Prepare single [`iris.cube.Cube`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.cube.html#iris.cube.Cube) in order to merge it later. |
| [`unify_1d_cubes`](#esmvaltool.diag_scripts.shared.iris_helpers.unify_1d_cubes)(cubes, coord_name)             | Unify 1D cubes by transforming them to identical coordinates.                                                                                             |
| [`unify_time_coord`](#esmvaltool.diag_scripts.shared.iris_helpers.unify_time_coord)(cube[, target_units])        | Unify time coordinate of cube in-place.                                                                                                                   |

### esmvaltool.diag_scripts.shared.iris_helpers.check_coordinate(cubes, coord_name)

Compare coordinate of cubes and raise error if not identical.

* **Parameters:**
  * **cubes** ([*iris.cube.CubeList*](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.cube.html#iris.cube.CubeList)) – Cubes to be compared.
  * **coord_name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – Name of the coordinate.
* **Returns:**
  Points of the coordinate.
* **Return type:**
  numpy.array
* **Raises:**
  * [**iris.exceptions.CoordinateNotFoundError**](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.exceptions.html#iris.exceptions.CoordinateNotFoundError) – Coordinate `coord_name` is not a coordinate of one of the cubes.
  * [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – Given coordinate differs for the input cubes.

### esmvaltool.diag_scripts.shared.iris_helpers.convert_to_iris(dict_)

Change all appearances of `short_name` to `var_name`.

* **Parameters:**
  **dict** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – Dictionary to convert.
* **Returns:**
  Converted dictionary.
* **Return type:**
  [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)
* **Raises:**
  [**KeyError**](https://docs.python.org/3/builtins/exceptions.html#KeyError) – [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) contains keys\`\`’short_name’\`\` **and** `'var_name'`.

### esmvaltool.diag_scripts.shared.iris_helpers.get_mean_cube(datasets)

Get mean cube of a list of datasets.

* **Parameters:**
  **datasets** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list) *of* [*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – List of datasets (given as metadata [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)).
* **Returns:**
  Mean cube.
* **Return type:**
  [iris.cube.Cube](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.cube.html#iris.cube.Cube)

### esmvaltool.diag_scripts.shared.iris_helpers.intersect_dataset_coordinates(cubes)

Compare dataset coordinates of cubes and match them if necessary.

Use intersection of coordinate ‘dataset’ of all given cubes and remove
elements which are not given in all cubes.

* **Parameters:**
  **cubes** ([*iris.cube.CubeList*](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.cube.html#iris.cube.CubeList)) – Cubes to be compared.
* **Returns:**
  Transformed cubes.
* **Return type:**
  [iris.cube.CubeList](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.cube.html#iris.cube.CubeList)
* **Raises:**
  * [**iris.exceptions.CoordinateNotFoundError**](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.exceptions.html#iris.exceptions.CoordinateNotFoundError) – Coordinate `dataset` is not a coordinate of one of the cubes.
  * [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – At least one of the cubes contains a `dataset` coordinate with
        duplicate elements or the cubes do not share common elements.

### esmvaltool.diag_scripts.shared.iris_helpers.iris_project_constraint(projects, input_data, negate=False)

Create [`iris.Constraint`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.html#iris.Constraint) to select specific projects from data.

* **Parameters:**
  * **projects** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list) *of* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – Projects to be selected.
  * **input_data** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list) *of* [*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – List of dataset metadata used to extract all relevant datasets
    belonging to given `projects`.
  * **negate** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* *optional* *(**default: False* *)*) – Negate constraint (`False`: select all elements that fit
    `projects`, True\`: select all elements that do **not** fit
    `projects`).
* **Returns:**
  constraint for coordinate `dataset`.
* **Return type:**
  [iris.Constraint](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.html#iris.Constraint)

### esmvaltool.diag_scripts.shared.iris_helpers.prepare_cube_for_merging(cube, cube_label)

Prepare single [`iris.cube.Cube`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.cube.html#iris.cube.Cube) in order to merge it later.

* **Parameters:**
  * **cube** ([*iris.cube.Cube*](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.cube.html#iris.cube.Cube)) – Cube to be pre-processed.
  * **cube_label** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – Label for the new scalar coordinate `cube_label`.

### esmvaltool.diag_scripts.shared.iris_helpers.unify_1d_cubes(cubes, coord_name)

Unify 1D cubes by transforming them to identical coordinates.

Use union of all coordinates as reference and transform other cubes to it
by adding missing values.

* **Parameters:**
  * **cubes** ([*iris.cube.CubeList*](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.cube.html#iris.cube.CubeList)) – Cubes to be processed.
  * **coord_name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – Name of the coordinate.
* **Returns:**
  Transformed cubes.
* **Return type:**
  [iris.cube.CubeList](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.cube.html#iris.cube.CubeList)
* **Raises:**
  [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – Cubes are not 1D, coordinate name differs or not all cube coordinates
      are subsets of longest coordinate.

### esmvaltool.diag_scripts.shared.iris_helpers.unify_time_coord(cube, target_units='days since 1850-01-01 00:00:00')

Unify time coordinate of cube in-place.

* **Parameters:**
  * **cube** ([*iris.cube.Cube*](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.cube.html#iris.cube.Cube)) – Cube whose time coordinate is transformed in-place.
  * **target_units** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *or* [*cf_units.Unit*](https://cf-units.readthedocs.io/en/latest/unit.html#cf_units.Unit) *,* *optional*) – Target time units.
* **Raises:**
  [**iris.exceptions.CoordinateNotFoundError**](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.exceptions.html#iris.exceptions.CoordinateNotFoundError) – Cube does not contain coordinate `time`.

## Plotting

Module that provides common plot functions.

**Functions:**

| [`get_dataset_style`](#esmvaltool.diag_scripts.shared.plot.get_dataset_style)(dataset[, style_file])          | Retrieve the style information for the given dataset.   |
|----------------------------------------------------------------------------------------------------|---------------------------------------------------------|
| [`get_path_to_mpl_style`](#esmvaltool.diag_scripts.shared.plot.get_path_to_mpl_style)([style_file])               | Get path to matplotlib style file.                      |
| [`global_contourf`](#esmvaltool.diag_scripts.shared.plot.global_contourf)(cube[, cbar_center, ...])         | Plot global filled contour plot.                        |
| [`global_pcolormesh`](#esmvaltool.diag_scripts.shared.plot.global_pcolormesh)(cube[, cbar_center, ...])       | Plot global color mesh.                                 |
| [`multi_dataset_scatterplot`](#esmvaltool.diag_scripts.shared.plot.multi_dataset_scatterplot)(x_data, y_data, ...)    | Plot a multi dataset scatterplot.                       |
| [`quickplot`](#esmvaltool.diag_scripts.shared.plot.quickplot)(cube, plot_type[, filename])            | Plot a cube using one of the iris.quickplot functions.  |
| [`scatterplot`](#esmvaltool.diag_scripts.shared.plot.scatterplot)(x_data, y_data, filepath, \*\*kwargs) | Plot a scatterplot.                                     |

### esmvaltool.diag_scripts.shared.plot.get_dataset_style(dataset, style_file=None)

Retrieve the style information for the given dataset.

### esmvaltool.diag_scripts.shared.plot.get_path_to_mpl_style(style_file=None)

Get path to matplotlib style file.

### esmvaltool.diag_scripts.shared.plot.global_contourf(cube, cbar_center=None, cbar_label=None, cbar_range=None, cbar_ticks=None, \*\*kwargs)

Plot global filled contour plot.

#### NOTE
This is only possible if the cube is 2D with dimensional coordinates
latitude and longitude.

* **Parameters:**
  * **cube** ([*iris.cube.Cube*](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.cube.html#iris.cube.Cube)) – Cube to plot.
  * **cbar_center** ([*float*](https://docs.python.org/3/builtins/functions.html#float) *,* *optional*) – Central value for the colormap, useful for diverging colormaps. Can
    only be used if `cbar_range` is given.
  * **cbar_label** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* *optional*) – Label for the colorbar.
  * **cbar_range** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list) *of* [*float*](https://docs.python.org/3/builtins/functions.html#float) *,* *optional*) – Range of the colorbar (first and second list element) and number of
    distinct colors (third element). See `numpy.linspace`.
  * **cbar_ticks** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list) *,* *optional*) – Ticks for the colorbar.
  * **\*\*kwargs** – Keyword argument for [`iris.plot.contourf()`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.plot.html#iris.plot.contourf).
* **Returns:**
  Plot object.
* **Return type:**
  [matplotlib.contour.QuadContourSet](https://matplotlib.org/stable/api/contour_api.html#matplotlib.contour.QuadContourSet)
* **Raises:**
  * [**iris.exceptions.CoordinateNotFoundError**](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.exceptions.html#iris.exceptions.CoordinateNotFoundError) – Input [`iris.cube.Cube`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.cube.html#iris.cube.Cube) does not contain the necessary
        dimensional coordinates `'latitude'` and `'longitude'`.
  * [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – Input [`iris.cube.Cube`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.cube.html#iris.cube.Cube) is not 2D.

### esmvaltool.diag_scripts.shared.plot.global_pcolormesh(cube, cbar_center=None, cbar_label=None, cbar_ticks=None, \*\*kwargs)

Plot global color mesh.

#### NOTE
This is only possible if the cube is 2D with dimensional coordinates
latitude and longitude.

* **Parameters:**
  * **cube** ([*iris.cube.Cube*](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.cube.html#iris.cube.Cube)) – Cube to plot.
  * **cbar_center** ([*float*](https://docs.python.org/3/builtins/functions.html#float) *,* *optional*) – Central value for the colormap, useful for diverging colormaps. Can
    only be used if `vmin` and `vmax` are given.
  * **cbar_label** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* *optional*) – Label for the colorbar.
  * **cbar_ticks** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list) *,* *optional*) – Ticks for the colorbar.
  * **\*\*kwargs** – Keyword argument for [`iris.plot.pcolormesh()`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.plot.html#iris.plot.pcolormesh).
* **Returns:**
  Plot object.
* **Return type:**
  [matplotlib.contour.QuadContourSet](https://matplotlib.org/stable/api/contour_api.html#matplotlib.contour.QuadContourSet)
* **Raises:**
  * [**iris.exceptions.CoordinateNotFoundError**](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.exceptions.html#iris.exceptions.CoordinateNotFoundError) – Input [`iris.cube.Cube`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.cube.html#iris.cube.Cube) does not contain the necessary
        dimensional coordinates `'latitude'` and `'longitude'`.
  * [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – Input [`iris.cube.Cube`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.cube.html#iris.cube.Cube) is not 2D.

### esmvaltool.diag_scripts.shared.plot.multi_dataset_scatterplot(x_data, y_data, datasets, filepath, \*\*kwargs)

Plot a multi dataset scatterplot.

### Notes

Allowed keyword arguments:

* mpl_style_file ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)):  Path to the matplotlib style file.
* dataset_style_file ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)): Path to the dataset style file.
* plot_kwargs (array-like): Keyword arguments for the plot (e.g.
  label, makersize, etc.).
* save_kwargs ([`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)): Keyword arguments for saving the plot.
* axes_functions ([`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)): Arbitrary functions for axes, i.e.
  axes.set_title(‘title’).

* **Parameters:**
  * **x_data** (*array-like*) – x data of each dataset.
  * **y_data** (*array-like*) – y data of each dataset.
  * **datasets** (*array-like*) – Names of the datasets.
  * **filepath** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – Path to which plot is written.
  * **\*\*kwargs** – Keyword arguments.
* **Raises:**
  * [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – A non-valid keyword argument is given or x_data, y_data, datasets
        or (if given) plot_kwargs is not array-like.
  * [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – x_data, y_data, datasets or plot_kwargs do not have the same
         size.

### esmvaltool.diag_scripts.shared.plot.quickplot(cube, plot_type, filename=None, \*\*kwargs)

Plot a cube using one of the iris.quickplot functions.

### esmvaltool.diag_scripts.shared.plot.scatterplot(x_data, y_data, filepath, \*\*kwargs)

Plot a scatterplot.

### Notes

Allowed keyword arguments:

* mpl_style_file ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)):  Path to the matplotlib style file.
* plot_kwargs (array-like): Keyword arguments for the plot (e.g.
  label, makersize, etc.).
* save_kwargs ([`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)): Keyword arguments for saving the plot.
* axes_functions ([`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)): Arbitrary functions for axes, i.e.
  axes.set_title(‘title’).

* **Parameters:**
  * **x_data** (*array-like*) – x data of each dataset.
  * **y_data** (*array-like*) – y data of each dataset.
  * **filepath** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – Path to which plot is written.
  * **\*\*kwargs** – Keyword arguments.
* **Raises:**
  * [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – A non-valid keyword argument is given or x_data, y_data or (if
        given) plot_kwargs is not array-like.
  * [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – x_data, y_data or plot_kwargs do not have the same size.
