.. _ocean_drift: Ocean Drift Diagnostic ====================== Description ----------- The **OceanDrift** diagnostic is a set of tools for the analysis and visualization of temporal evolution and drift in ocean model outputs. It provides methods to assess model drift over time by analyzing Hovmöller diagrams and timeseries of ocean variables. The diagnostic supports analysis of full values, anomalies (relative to initial time or time mean), and standardized anomalies. OceanDrift provides tools to: - Compute anomalies and standardized anomalies relative to the initial time (t0) or the time mean - Produce timeseries plots at specific depth levels - Generate Hovmöller diagrams showing the temporal evolution of ocean variables as a function of depth - Perform spatial averaging over predefined ocean regions (e.g., Atlantic Ocean, Pacific Ocean, Global Ocean) Classes ------- There are two main classes for analysis and plotting: * **Hovmoller**: retrieves ocean data (typically temperature and salinity) and processes it for drift analysis. It handles spatial averaging over specified regions and computation of anomalies and standardized anomalies. The diagnostic supports different reference types for anomaly computation: - ``t0`` : Anomalies computed relative to the first time step (initial state) - ``tmean`` : Anomalies computed relative to the time mean of the entire period - ``None`` : No anomaly computation (full values only) * **PlotHovmoller**: provides methods for plotting Hovmöller diagrams and timeseries. It generates multi-panel plots showing different anomaly types and variables. File structure -------------- * The diagnostic is located in the ``aqua/diagnostics/ocean_drift`` directory, which contains both the source code and the command line interface (CLI) script. * A template configuration file is available at ``aqua/diagnostics/templates/diagnostics/config-ocean_drift.yaml`` * Notebooks are available in the ``notebooks/diagnostics/ocean_drift`` directory and contain examples of how to use the diagnostic. * Regions definitions are available in ``aqua/diagnostics/config/tools/ocean3d/definitions/regions.yaml`` Input variables and datasets ---------------------------- The diagnostic works with 3D ocean model outputs and can be applied to any ocean variable. The primary variables typically used in this diagnostic are: * ``thetao`` (sea water potential temperature) * ``so`` (sea water salinity) 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. A higher resolution is not necessary for this diagnostic. Basic usage ----------- The basic usage of this diagnostic is explained with a working example in the notebook. The basic structure of the analysis is the following: .. code-block:: python from aqua.diagnostics import Hovmoller, PlotHovmoller hov = Hovmoller( catalog='climatedt-phase1', model='IFS-NEMO', exp='historical-1990', source='lra-r100-monthly', startdate='01-01-1991', enddate='31-05-1991', loglevel='INFO' ) hov.run( region='io', dim_mean=['lat', 'lon'], anomaly_ref='t0' ) hov_plot = PlotHovmoller(data=hov.processed_data_list) hov_plot.plot_hovmoller() hov_plot.plot_timeseries() .. note:: The diagnostic automatically processes data to generate all transformation types (full values, anomalies and standardized anomalies). Spatial averaging is performed over the specified dimensions before computing temporal transformations. 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/ocean_drift python cli_ocean_drift.py --config 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, 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 ocean drift diagnostic. * ``ocean_drift``: a block (nested in the ``diagnostics`` block) containing options for the Ocean Drift diagnostic. * ``hovmoller``: sub-block containing specific parameters for Hovmöller analysis. * ``run``: enable/disable the diagnostic. * ``diagnostic_name``: name of the diagnostic. ``ocean3d`` by default. * ``vert_coord``: vertical coordinate for the analysis (e.g., ``level``). * ``var``: list of variables to analyse (typically ``['thetao', 'so']``). * ``regions``: list of ocean regions to analyse (e.g., ``['go', 'io', 'ao', 'so', 'arc_o', 'po']``). * ``dim_mean``: dimensions over which to compute spatial averages (typically ``['lat', 'lon']``). .. code-block:: yaml diagnostics: ocean_drift: hovmoller: diagnostic_name: 'ocean3d' vert_coord: level run: true var: ['thetao', 'so'] regions: ['io', 'sss'] dim_mean: ['lat', 'lon'] The diagnostic supports analysis over predefined ocean regions. Common regions include: * ``io`` - Indian Ocean * ``ao`` - Atlantic Ocean * ``po`` - Pacific Ocean * ``arc_o`` - Arctic Ocean * ``go`` - Global Ocean * ``ss`` - Sargasso Sea Additional regions can be defined in ``aqua/diagnostics/config/tools/ocean3d/definitions/regions.yaml``. Output ------ The diagnostic produces two types of plots: * Hovmöller diagrams showing the temporal evolution of ocean variables as a function of depth, with separate panels for each transformation type (full values, anomalies, standardized anomalies) * Timeseries plots showing the temporal evolution at specific depth levels, with multiple lines representing different depths If not specified otherwise, plots will be saved both in PNG and PDF format. Data outputs (containing the computed anomalies over the specified regions) are saved as NetCDF files for further analysis. Example Plots ------------- All plots can be reproduced using the notebooks in the ``notebooks`` directory on LUMI HPC. .. figure:: figures/oceandrift.hovmoller.climatedt-phase1.IFS-NEMO.historical-1990.r1.indian_ocean.png :align: center :width: 18cm Hovmöller diagrams showing ocean temperature drift in the Indian Ocean. Full values, anomalies relative to initial time and standardized anomalies are shown. .. figure:: figures/oceandrift.timeseries.climatedt-phase1.IFS-NEMO.historical-1990.r1.indian_ocean.png :align: center :width: 20cm Timeseries of ocean temperature at multiple depth levels in the Indian Ocean, showing drift patterns from full values, anomalies relative to t0, and standardized anomalies. Available demo notebooks ------------------------ Notebooks are stored in ``notebooks/diagnostics/ocean_drift``: - `hovmoller.ipynb `_ Authors and contributors ------------------------ This diagnostic is maintained by Supriyo Gosh (`@ghossh `_, `supriyo.ghosh@bsc.es `_). 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 ``Ocean_drift`` diagnostic, produced from the diagnostic function docstrings. .. automodule:: aqua.diagnostics.ocean_drift :members: :undoc-members: :show-inheritance: