Teleconnections

Description

The teleconnections diagnostic is a set of tool to compute the most relevant teleconnections. NAO (North Atlantic Oscillation), ENSO (El Niño Southern Oscillation) and MJO (Madden-Julian Oscillation) are the teleconnections currently implemented. The diagnostic is build to evaluate the teleconnections indices and to compute regression and correlation maps with respect to the teleconnection index.

Note

MJO is currently missing a command line interface and it is not operational yet.

Classes

There are three classes to compute the netCDF files:

• NAO: a class that computes the NAO index based on the mean sea level pressure (msl) variable with the station based method, and computes the regression and correlation maps with respect to the NAO index.

• ENSO: a class that computes the ENSO index based on the sea surface temperature (tos) variable with the Nino3.4 region and computes the regression and correlation maps with respect to the ENSO index.

• MJO: a class that allows to compute the MJO Hovmoeller plots based on the top net thermal radiation flux (tnlwrf) variable.

There are three other classes to produce the plots:

• PlotNAO: a class that ingests xarrays and produces the NAO index time series and the regression and correlation maps.

• PlotENSO: a class that ingests xarrays and produces the ENSO index time series and the regression and correlation maps.

• PlotMJO: a class that ingests xarrays and produces the MJO Hovmoeller plots.

File structure

• The diagnostic is located in the src/aqua_diagnostics/teleconnections directory, which contains the source code and the command line interface (CLI) script.

• The configuration files are located in the config/diagnostics/teleconnections directory and contain the default configuration for the diagnostic.

• Notebooks are available in the notebooks/diagnostics/teleconnections directory and contain examples of how to use the diagnostic.

• Interface files to specify custom regions or other variable names for the index evaluation are available in the config/diagnostics/teleconnections/interface directory.

Note

A command line to evaluate with the bootstrap method the concordance maps of regression and correlation is available in the cli_bootstrap.py file. This is not included in any automatic run of the diagnostic because it is a time-consuming process.

Input variables and datasets

By default, the diagnostics compare against the ERA5 dataset, with the index evaluated over the entire available period (1940 to present).

The necessary variables for the default evaluation are: - NAO: Sea level pressure (msl). - ENSO: Sea surface temperature (tos). - MJO: Top net thermal radiation flux (tnlwrf).

Other variables can be used for the regression and correlation maps.

CLI usage

The diagnostic can be run from the command line interface (CLI) by running the following command:

cd $AQUA/src/aqua_diagnostics/teleconnections
python cli_teleconnections.py --config <path_to_config_file>

Three configuration files are provided and run when executing the aqua-analysis (see AQUA analysis wrapper). Two configuration files are for atmospheric and oceanic teleconnections.

Additionally the CLI can be run with the following optional arguments:

• --config, -c: Path to the configuration file.

• --nworkers, -n: Number of workers to use for parallel processing.

• --cluster: Cluster to use for parallel processing. By default a local cluster is used.

• --loglevel, -l: Logging level. Default is WARNING.

• --catalog: Catalog to use for the analysis. It can be defined in the config file.

• --model: Model to analyse. It can be defined in the config file.

• --exp: Experiment to analyse. It can be defined in the config file.

• --source: Source to analyse. It can be defined in the config file.

• --outputdir: Output directory for the plots.

Config file structure

The configuration file is a YAML file that contains the following information:

• datasets: a list of models to analyse (defined by the catalog, model, exp, source arguments)

datasets:
  - catalog: climatedt-phase1
    model: IFS-NEMO
    exp: historical-1990
    source: lra-r100-monthly
    regrid: null
  - catalog: climatedt-phase1
    model: ICON
    exp: historical-1990
    source: lra-r100-monthly
    regrid: null

• references: a list of reference datasets to use for the analysis.

references:
  - catalog: obs
    model: ERA5
    exp: era5
    source: monthly
    regrid: null

• output: a block describing the details of the output. Is contains:

  • outputdir: the output directory for the plots.

  • rebuild: a boolean that enables the rebuilding of the plots.

  • save_pdf: a boolean that enables the saving of the plots in pdf format.

  • save_png: a boolean that enables the saving of the plots in png format.

  • dpi: the resolution of the plots.

output:
  outputdir: "/path/to/output"
  rebuild: true
  save_pdf: true
  save_png: true
  dpi: 300

• teleconnections: a block, nested in the diagnostics block, that contains the details required for the teleconnections.

  It allows to specify which teleconnections to run, the months window for the rolling mean, the seasons to consider, and the color bar range for the plots. It contains the following blocks:

  • NAO: a block, nested in the teleconnections block, that contains the details required for the NAO teleconnection.

  • ENSO: a block, nested in the teleconnections block, that contains the details required for the ENSO teleconnection.

diagnostics:
    teleconnections:
        NAO:
            run: true
            months_window: 3
            seasons: ['DJF']
            cbar_range: [-5, 5]
        ENSO:
            run: true
            months_window: 3
            seasons: ['annual']
            cbar_range: [-2, 2]

Output

The diagnostic produces the following outputs:

• NAO: North Atlantic Oscillation index, regression and correlation maps.

• ENSO: El Niño Southern Oscillation index, regression and correlation maps.

• MJO: Madden-Julian Oscillation Hovmoeller plots of the Mean top net thermal radiation flux variable.

All these outputs can be stored both as images (pdf format) and as netCDF files. If a reference dataset is provided, the automatic maps consist of contour lines for the model regression map and filled contour map for the difference between the model and the reference regression map.

Example Plots

ENSO IFS-NEMO ssp370 regression map (avg_tos) compared to ERA5. The contour lines are the model regression map and the filled contour map is the difference between the model and the reference regression map (ERA5).

Available demo notebooks

• NAO

• ENSO

• statistical_validation

• MJO

Authors and contributors

This diagnostic is maintained by Matteo Nurisso (@mnurisso, m.nurisso@isac.cnr.it). Contributions are welcome, please open an issue or a pull request. If you have any doubt or suggestion, please contact the AQUA team or the maintainers.

Detailed API

This section provides a detailed reference for the Application Programming Interface (API) of the Teleconnections diagnostic, produced from the diagnostic function docstrings.

Teleconnections module

class aqua.diagnostics.teleconnections.ENSO(catalog: str = None, model: str = None, exp: str = None, source: str = None, regrid: str = None, startdate: str = None, enddate: str = None, configdir: str = None, definition: str = 'teleconnections-destine', loglevel: str = 'WARNING')

Bases: BaseMixin

Class for calculating the El Niño Southern Oscillation (ENSO) index. This class is used to calculate the ENSO index from a given dataset. It inherits from the BaseMixin class and implements the necessary methods to calculate the ENSO index.

Initialize the ENSO class.

Parameters:

• catalog (str) – Catalog name.

• model (str) – Model name.

• exp (str) – Experiment name.

• source (str) – Source name.

• regrid (str) – Regrid target. Default is None.

• startdate (str) – Start date for data retrieval. Default is None.

• enddate (str) – End date for data retrieval. Default is None.

• configdir (str) – Configuration directory. Default is None.

• definition (str) – definition filename. Default is ‘teleconnections-destine’. This is used to deduce the variable name and the lat/lon for the index.

• loglevel (str) – Logging level. Default is ‘WARNING’.

compute_index(months_window: int = 3, box_brd: bool = True, rebuild: bool = False)

” Evaluate station based index for a teleconnection. Field data must be monthly gridded data.

Parameters:

• months_window (int, opt) – months for rolling average, default is 3

• box_brd (bool, opt) – choose if coordinates are comprised or not. Default is True

• rebuild (bool, opt) – if True, the index is recalculated, default is False

retrieve()

Retrieve the data for the ENSO index.

class aqua.diagnostics.teleconnections.MJO(catalog: str = None, model: str = None, exp: str = None, source: str = None, regrid: str = None, startdate: str = None, enddate: str = None, configdir: str = None, definition: str = 'teleconnections-destine', loglevel: str = 'WARNING')

Bases: BaseMixin

MJO (Madden-Julian Oscillation) class.

Initialize the MJO class.

Parameters:

• catalog (str) – Catalog name.

• model (str) – Model name.

• exp (str) – Experiment name.

• source (str) – Source name.

• regrid (str) – Regrid method.

• startdate (str) – Start date for data retrieval.

• enddate (str) – End date for data retrieval.

• configdir (str) – Configuration directory. Default is the installation directory.

• definition (str) – definition filename. Default is ‘teleconnections-destine’.

• loglevel (str) – Logging level. Default is ‘WARNING’.

compute_hovmoller(day_window: int = None)

Compute the Hovmoller plot for the MJO index. This method prepares the data for a Hovmoller plot by selecting the MJO box, evaluating anomalies, and smoothing the data if required.

Parameters:

day_window (int, optional) – Number of days to be used in the smoothing window. If None, no smoothing is performed. Default is None.

retrieve()

Retrieve the data from the model.

Parameters:

var (str) – The variable to be retrieved. If None, all variables will be retrieved.

self.data

The data retrieved from the model. If return_data is True, the data will be returned.

self.catalog

The catalog used to retrieve the data if no catalog was provided.

class aqua.diagnostics.teleconnections.NAO(catalog: str = None, model: str = None, exp: str = None, source: str = None, regrid: str = None, startdate: str = None, enddate: str = None, configdir: str = None, definition: str = 'teleconnections-destine', loglevel: str = 'WARNING')

Bases: BaseMixin

North Atlantic Oscillation (NAO) index calculation class. This class is used to calculate the NAO index from a given dataset. It inherits from the BaseMixin class and implements the necessary methods to calculate the NAO index.

Initialize the NAO class.

Parameters:

• catalog (str) – Catalog name.

• model (str) – Model name.

• exp (str) – Experiment name.

• source (str) – Source name.

• regrid (str) – Regrid method.

• startdate (str) – Start date for data retrieval.

• enddate (str) – End date for data retrieval.

• configdir (str) – Configuration directory. Default is the installation directory.

• definition (str) – definition filename. Default is ‘teleconnections-destine’.

• loglevel (str) – Logging level. Default is ‘WARNING’.

compute_index(months_window: int = 3, rebuild: bool = False)

” Evaluate station based index for a teleconnection. Field data must be monthly gridded data.

Parameters:

• months_window (int, opt) – months for rolling average, default is 3

• rebuild (bool, opt) – if True, the index is recalculated, default is False

retrieve()

Retrieve the data for the NAO index.

class aqua.diagnostics.teleconnections.PlotENSO(indexes=None, ref_indexes=None, outputdir: str = './', rebuild: bool = True, loglevel: str = 'WARNING')

Bases: PlotBaseMixin

Plot the ENSO products.

Parameters:

• indexes (list) – List of indexes to plot.

• ref_indexes (list) – List of reference indexes to plot.

• outputdir (str) – Directory to save the plots. Default is ‘./’.

• rebuild (bool) – If True, rebuild the plots. Default is True.

• loglevel (str) – Log level for the logger. Default is ‘WARNING’.

plot_index(thresh: float = 0.5)

plot_maps(maps=None, ref_maps=None, statistic: str = None, vmin: float = None, vmax: float = None, vmin_diff: float = None, vmax_diff: float = None, **kwargs)

Plot the maps for the ENSO products.

Parameters:

• maps (list) – List of maps to plot.

• ref_maps (list) – List of reference maps to plot.

• statistic (str) – Statistic to plot. Default is None.

• vmin (float) – Minimum value for the color value. Default is None.

• vmax (float) – Maximum value for the color value. Default is None.

• vmin_diff (float) – Minimum value for the color value for the difference. Default is None.

• vmax_diff (float) – Maximum value for the color value for the difference. Default is None.

• **kwargs – Additional arguments for the plotting function.

Returns:

Figure object.

Return type:

fig

set_index_description()

Set the description of the index. This is used to generate the caption of the figure.

Parameters:

index_name (str) – The name of the index. Default is None.

Returns:

The caption of the figure.

Return type:

str

set_map_description(maps=None, ref_maps=None, statistic: str = None)

Set the description for the maps.

Parameters:

• maps (list) – List of maps to plot.

• ref_maps (list) – List of reference maps to plot.

• statistic (str) – Statistic to plot. Default is None.

Returns:

Description of the maps.

Return type:

str

class aqua.diagnostics.teleconnections.PlotMJO(data, outputdir: str = './', rebuild: bool = True, loglevel: str = 'WARNING')

Bases: object

PlotMJO class for plotting the MJO Hovmoller data. This class is a placeholder for future plotting methods.

Initialize the PlotMJO class.

Parameters:

• data (xarray.DataArray) – Data to be plot.

• outputdir (str) – Directory where the plots will be saved. Default is ‘./’.

• rebuild (bool) – If True, the plots will be rebuilt. Default is True.

• loglevel (str) – Logging level. Default is ‘WARNING’.

plot_hovmoller(invert_axis: bool = True, invert_time: bool = True, nlevels: int = 21, cmap: str = 'PuOr', vmin: float = -90, vmax: float = 90)

Plot the Hovmoller diagram for the MJO data.

Parameters:

• invert_axis (bool) – If True, invert the axis. Default is True.

• invert_time (bool) – If True, invert the time axis. Default is True.

• nlevels (int) – Number of contour levels. Default is 21.

• cmap (str) – Colormap to use for the plot. Default is ‘PuOr’.

• vmin (float) – Minimum value for the colorbar. Default is -90.

• vmax (float) – Maximum value for the colorbar. Default is 90.

Returns:

The Hovmoller plot figure.

Return type:

fig (matplotlib.figure.Figure)

save_plot(fig, diagnostic_product: str = 'hovmoller', extra_keys: dict = None, dpi: int = 300, format: str = 'png', metadata: dict = None)

Save the plot to a file.

Parameters:

• fig (matplotlib.figure.Figure) – The figure to be saved.

• diagnostic_product (str) – The name of the diagnostic product. Default is None.

• extra_keys (dict) – Extra keys to be used for the filename (e.g. season). Default is None.

• dpi (int) – The dpi of the figure. Default is 300.

• format (str) – The format of the figure. Default is ‘png’.

• metadata (dict) – The metadata to be used for the figure. Default is None. They will be complemented with the metadata from the outputsaver. We usually want to add here the description of the figure.

class aqua.diagnostics.teleconnections.PlotNAO(indexes=None, ref_indexes=None, outputdir: str = './', rebuild: bool = True, loglevel: str = 'WARNING')

Bases: PlotBaseMixin

Plot the NAO products.

Parameters:

• indexes (list) – List of indexes to plot.

• ref_indexes (list) – List of reference indexes to plot.

• outputdir (str) – Directory to save the plots. Default is ‘./’.

• rebuild (bool) – If True, rebuild the plots. Default is True.

• loglevel (str) – Log level for the logger. Default is ‘WARNING’.

plot_index(thresh: float = 0.0)

plot_maps(maps=None, ref_maps=None, statistic: str = None, vmin: float = None, vmax: float = None, vmin_diff: float = None, vmax_diff: float = None, **kwargs)

Plot the maps for the ENSO products.

Parameters:

• maps (list) – List of maps to plot.

• ref_maps (list) – List of reference maps to plot.

• statistic (str) – Statistic to plot. Default is None.

• vmin (float) – Minimum value for the color value. Default is None.

• vmax (float) – Maximum value for the color value. Default is None.

• vmin_diff (float) – Minimum value for the color value for the difference. Default is None.

• vmax_diff (float) – Maximum value for the color value for the difference. Default is None.

• **kwargs – Additional arguments for the plotting function.

Returns:

Figure object.

Return type:

fig

set_index_description()

Set the description of the index. This is used to generate the caption of the figure.

Parameters:

index_name (str) – The name of the index. Default is None.

Returns:

The caption of the figure.

Return type:

str

set_map_description(maps=None, ref_maps=None, statistic: str = None)

Set the description for the maps.

Parameters:

• maps (list) – List of maps to plot.

• ref_maps (list) – List of reference maps to plot.

• statistic (str) – Statistic to plot. Default is None.

Returns:

Description of the maps.

Return type:

str