.. _teleconnections: Teleconnections Diagnostic ========================== Description ----------- The teleconnections diagnostic is a set of tools 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 built 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 for the analysis: * **NAO**: computes the NAO index based on mean sea level pressure (msl) using the station-based method, and computes regression and correlation maps with respect to the NAO index. * **ENSO**: computes the ENSO index based on sea surface temperature (tos) using the Niño3.4 region, and computes regression and correlation maps with respect to the ENSO index. * **MJO**: computes the MJO Hovmoeller plots based on the top net thermal radiation flux (tnlwrf) variable. There are three other classes for the plots: * **PlotNAO**: produces the NAO index time series and the regression and correlation maps. * **PlotENSO**: produces the ENSO index time series and the regression and correlation maps. * **PlotMJO**: produces the MJO Hovmoeller plots. File structure -------------- * The diagnostic is located in the ``aqua/diagnostics/teleconnections`` directory, which contains the source code and the command line interface (CLI) script. * A template configuration file is available at ``aqua/diagnostics/templates/diagnostics/config-teleconnections.yaml`` * 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 ``aqua/diagnostics/config/tools/teleconnections/definitions`` directory. .. note:: A command line to evaluate, using 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. Please note that the bootstrap CLI is **not actively maintained** and has **not yet been tested against recent API changes or imports**. Input variables and datasets ---------------------------- By default, the diagnostic compares against the ERA5 dataset, with the index evaluated over the entire available period (1940 to present). The necessary variables for the default evaluation are: * ``msl`` (mean sea level pressure) for NAO * ``tos`` (sea surface temperature) for ENSO * ``tnlwrf`` (top net thermal radiation flux) for MJO Other variables can be used for the regression and correlation maps. The diagnostic is designed to work with data from the Low Resolution Archive (LRA), generated by the Data Reduction OPerator (DROP) of the AQUA project, which provides monthly data at a 1x1 degree resolution. Basic usage ----------- The basic usage of this diagnostic is explained with working examples in the notebooks. The basic structure of the analysis is the following: .. code-block:: python from aqua.diagnostics import NAO, PlotNAO nao_dataset = NAO( catalog='climatedt-phase1', model='IFS-NEMO', exp='historical-1990', source='lra-r100-monthly', loglevel=loglevel) nao_obs = NAO( catalog='obs', model='ERA5', exp='era5', source='monthly', loglevel=loglevel) nao_dataset.retrieve() nao_obs.retrieve() nao_dataset.compute_index() nao_obs.compute_index() reg_dataset = nao_dataset.compute_regression(season='DJF') reg_obs = nao_obs.compute_regression(season='DJF') plot = PlotNAO(loglevel='INFO', indexes=nao_dataset.index, ref_indexes=nao_obs.index) fig_index, _ = plot.plot_index() .. note:: Start/end dates and reference dataset can be customized. If not specified otherwise, plots will be saved in PNG and PDF format in the current working directory. CLI usage --------- The diagnostic can be run from the command line interface (CLI) by running the following command: .. code-block:: bash cd $AQUA/aqua/diagnostics/teleconnections python cli_teleconnections.py --config Three configuration files are provided and run when executing the aqua-analysis (see :ref:`aqua_analysis`). 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. Can be defined in the config file. - ``--model``: Model to analyse. Can be defined in the config file. - ``--exp``: Experiment to analyse. Can be defined in the config file. - ``--source``: Source to analyse. Can be defined in the config file. - ``--outputdir``: Output directory for the plots. - ``--startdate``: Start date for the analysis. - ``--enddate``: End date for the analysis. Configuration file structure ---------------------------- The configuration file is a YAML file that contains the details on the dataset to analyse or use as reference, the output directory and the diagnostic settings. Most of the settings are common to all the diagnostics (see :ref:`diagnostics-configuration-files`). Here we describe only the specific settings for the teleconnections diagnostic. * ``teleconnections``: a block (nested in the ``diagnostics`` block), containing options 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. .. code-block:: yaml diagnostics: teleconnections: NAO: run: true diagnostic_name: 'nao' months_window: 3 seasons: ['DJF'] cbar_range: [-5, 5] ENSO: run: true diagnostic_name: 'enso' 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. Plots are saved in both PDF and PNG format. Data outputs are saved 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. Observations ------------ The default reference dataset is ERA5 reanalysis, provided by ECMWF. The diagnostic uses ERA5 monthly averages from the AQUA ``obs`` catalog (``model=ERA5``, ``exp=era5``, ``source=monthly``). Custom reference datasets can be configured in the configuration file. Example Plots ------------- All plots can be reproduced using the notebooks in the ``notebooks`` directory on LUMI HPC. .. figure:: figures/teleconnections.png :align: center :width: 100% 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 ------------------------ Notebooks are stored in ``notebooks/diagnostics/teleconnections``: - `NAO `_ - `ENSO `_ - `statistical_validation `_ - `MJO `_ Authors and contributors ------------------------ This diagnostic is maintained by Matteo Nurisso (`@mnurisso `_, `matteo.nurisso@polito.it `_). Contributions are welcome — please open an issue or a pull request. For questions or suggestions, contact the AQUA team or the maintainer. Detailed API ------------ This section provides a detailed reference for the Application Programming Interface (API) of the ``teleconnections`` diagnostic, produced from the diagnostic function docstrings. .. automodule:: aqua.diagnostics.teleconnections :members: :undoc-members: :show-inheritance: