.. _seaice: Sea Ice Diagnostic ================== Description ----------- The **SeaIce** diagnostic is a set of tools for the analysis and visualization of sea ice metrics from climate model outputs. It supports analysis of sea ice extent, volume, fraction, and thickness. SeaIce provides tools to plot: - Time series of sea ice extent and volume - Seasonal cycles with optional uncertainty bands - 2D climatology maps of sea ice fraction and thickness - Bias maps between models and reference datasets Time series and seasonal cycles can be computed over a specific region of the Northern or Southern Hemisphere. Default regions are the Arctic and the Antarctic regions, but it is possible to select other regions and custom regions can be defined in the configuration file. Two main components are included: - A class that performs the computations and prepares the data (including saving NetCDF files). - Separate classes for producing 1D (time series) and 2D (maps) visualizations. Classes ------- There is one class for the analysis and two for the plotting: * **SeaIce**: performs all core computations for sea ice metrics — ``extent``, ``volume``, ``fraction``, and ``thickness`` metrics — for a single model or reference dataset. It manages data loading, regional masking, spatial integration, and statistical processing. It supports time series analysis and seasonal cycle computation with optional standard deviation calculations. - **Time-series methods** (compute integrated values over user-defined regions): - ``extent``: computes the area of ocean grid cells with a configurable sea-ice concentration ``threshold`` (default: 15%). - ``volume``: computes the integrated sea-ice thickness across each region. - **2D spatial methods** (compute monthly climatological maps): - ``fraction``: returns monthly mean maps of sea-ice concentration (0-1). - ``thickness``: returns monthly mean maps of sea-ice thickness (in meters). * **PlotSeaIce**: generates time-series and seasonal-cycle visualizations. It can receive a ``xarray.DataArray``, a ``xarray.Dataset``, or a list of ``xarray.Dataset`` objects containing sea-ice diagnostics from multiple models and a reference dataset, enabling direct comparisons. * **Plot2DSeaIce**: produces visualizations for 2D spatial climatologies and corresponding biases across all months. It supports the same data formats as PlotSeaIce, allowing side-by-side evaluation of multiple models against observations or a chosen reference. .. note:: The ``extent`` and ``volume`` methods produce time series data, while ``fraction`` and ``thickness`` methods produce 2D spatial maps. File structure -------------- * The diagnostic is located in the ``aqua/diagnostics/seaice`` 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-seaice.yaml`` * Regional definitions are available in ``aqua/diagnostics/config/tools/seaice/definitions/regions.yaml``. * Notebooks are available in the ``notebooks/diagnostics/seaice`` directory and contain examples of how to use the diagnostic. Input variables and datasets ---------------------------- The diagnostic supports the following variables (the ``Fixer`` class of AQUA-core can convert different variable names into the accepted format): * ``siconc`` (sea ice concentration, GRIB parameter id 31) * ``sithick`` (sea ice thickness, GRIB parameter id 32) The default reference dataset for sea ice concentration is OSI-SAF, but custom references can be provided in the configuration file. 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: **Time Series** .. code-block:: python from aqua.diagnostics import SeaIce, PlotSeaIce # Compute sea ice extent (time series calculation) si = SeaIce(model='IFS-NEMO', exp='historical-1990', source='lra-r100-monthly', loglevel="DEBUG") result = si.compute_seaice(method='extent', var='siconc') # Plot time series psi = PlotSeaIce(monthly_models=result, catalog=si.catalog, model='IFS-NEMO', exp='historical-1990', source='lra-r100-monthly', loglevel='DEBUG'loglevel='DEBUG') psi.plot_seaice(plot_type='timeseries', save_format=['png', 'pdf']) **2D Spatial** .. code-block:: python from aqua.diagnostics import SeaIce, Plot2DSeaIce # Compute sea ice fraction (2D maps calculation) si = SeaIce(model='IFS-NEMO', exp='historical-1990', source='lra-r100-monthly', loglevel="DEBUG") result = si.compute_seaice(method='fraction', var='siconc', stat='mean', freq='monthly') # Compute reference data # For Arctic region: si_ref_nh = SeaIce(catalog='obs', model='OSI-SAF', exp='osi-saf-aqua', source='nh-monthly', regrid='r100', regions=['arctic'], loglevel="DEBUG") ref_nh = si_ref_nh.compute_seaice(method='fraction', var='siconc', stat='mean', freq='monthly') # For Antarctic region: si_ref_sh = SeaIce(catalog='obs', model='OSI-SAF', exp='osi-saf-aqua', source='sh-monthly', regrid='r100', regions=['antarctic'], loglevel="DEBUG") ref_sh = si_ref_sh.compute_seaice(method='fraction', var='siconc', stat='mean', freq='monthly') ref = [ref_nh, ref_sh] # or just ref_nh to plot only Arctic region for example # Plot 2D maps psi_2d = Plot2DSeaIce(models=result, ref=ref, loglevel='DEBUG') psi_2d.plot_2d_seaice(plot_type='var', method='fraction', months=[3,9], projkw={'projname': 'orthographic', 'projpars': {'central_longitude': 0.0, 'central_latitude': 'max_lat_signed'} } save_format=['png', 'pdf']) # optional; default is SAVE_FORMAT (['png', 'pdf', 'svg']) .. note:: Start/end dates, reference datasets, and regional subsets may be specified in the configuration. If not specified otherwise, plots will be saved using ``SAVE_FORMAT`` (PNG, PDF, and SVG) 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/seaice python cli_seaice.py --config Additionally, the CLI can be run with the following optional arguments: - ``--config``, ``-c``: Path to the configuration file. Default are ``aqua/diagnostics/config/diagnostics/seaice/config_seaice-osi.yaml`` and ``config_seaice-psc.yaml``. - ``--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. - ``--proj``: Projection type for 2D plots. Choices are 'orthographic' or 'azimuthal_equidistant'. Default is 'orthographic'. - ``--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 sea ice diagnostic. The sea ice configuration file is organized into several main sections: **Dataset Configuration:** .. code-block:: yaml datasets: - catalog: null # mandatory as null model: 'IFS-NEMO' # mandatory exp: 'historical-1990' # mandatory source: 'lra-r100-monthly' # mandatory regrid: null # if the diagnostic supports it **Reference Datasets:** .. code-block:: yaml references: # ---- Extent in NH ---- - &ref_osi_nh catalog: 'obs' # mandatory model: 'OSI-SAF' # mandatory exp: 'osi-saf-aqua' # mandatory source: 'nh-monthly' # mandatory regrid: 'r100' domain: "nh" The reference datasets are defined using YAML anchors (``&ref_osi_nh``) and can be reused across different diagnostic blocks. Each reference dataset specifies: - ``catalog``: Data catalog identifier - ``model``: Reference model name (e.g., OSI-SAF, PSC) - ``exp``: Experiment identifier - ``source``: Data source specification - ``regrid``: Regridding target resolution - ``domain``: Geographic domain (nh=Northern Hemisphere, sh=Southern Hemisphere) **Diagnostic Blocks:** Each diagnostic block in ``config-seaice-osi.yaml``: - ``seaice_timeseries`` - ``seaice_seasonal_cycle`` - ``seaice_2d_bias`` contains the following parameters such as: .. code-block:: yaml seaice_timeseries: run: true methods: ["extent", "volume"] # Methods to compute regions: ['arctic','antarctic'] # Regions to analyze startdate: '1991-01-01' # Analysis start date enddate: '2000-01-01' # Analysis end date calc_ref_std: true # Calculate reference standard deviation ref_std_freq: 'monthly' # Standard deviation frequency varname: # Variable mapping for each method extent: 'siconc' volume: 'sithick' fraction: 'siconc' thickness: 'sithick' **Method-specific variable mapping:** - ``extent`` and ``fraction``: Use ``siconc`` as variable name (sea ice concentration) - ``volume`` and ``thickness``: Use ``sithick`` as variable name (sea ice thickness) **Reference dataset assignment:** Each diagnostic block includes a ``references`` section that assigns specific reference datasets to methods: .. code-block:: yaml references: - <<: *ref_osi_nh use_for_method: "extent" # Use this reference for extent analysis varname: "siconc" - <<: *ref_psc_nh use_for_method: "volume" # Use this reference for volume analysis varname: "sithick" **2D Bias Configuration:** The ``seaice_2d_bias`` block includes additional parameters for spatial analysis: .. code-block:: yaml seaice_2d_bias: months: [3, 9] # Months to plot (March and September) projections: # Map projection options orthographic: projname: "orthographic" projpars: central_longitude: 0.0 central_latitude: "max_lat_signed" extent_regions: # Geographic extent for each region Arctic: [-180, 180, 50, 90] Antarctic: [-180, 180, -50, -90] ``projections`` can be tuned to the user according to the section 'Projections and custom maps' in AQUA graphic tools documentation. Output ------ The diagnostic produces four types of outputs: * Time series plots of sea ice extent and volume for specified regions * Seasonal cycle plots with optional standard deviation bands * 2D climatology maps of sea ice fraction and thickness * Bias maps showing spatial differences between model and reference data Plots are saved in PDF, PNG, and SVG format by default (see ``SAVE_FORMAT``). Data outputs are saved as NetCDF files. Observations ------------ The default reference datasets are: * OSI-SAF for sea ice concentration metrics (``extent``, ``fraction``) * PSC (PIOMAS for Arctic, GIOMAS for Antarctic) for sea ice thickness metrics (``volume``, ``thickness``) Details are available on the `OSI-SAF website `_. An updated OSI-SAF version is available in the AQUA ``obs`` catalog (``exp=osi-saf-aqua``), which concatenates OSI-SAF osi-450-a1 (1979-2021) and OSI-SAF osi-430 (2022-2024) datasets. 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/seaice_ts_volume_Arctic_Antarctic.png :width: 100% Time series of sea ice volume for Arctic and Antarctic regions. .. figure:: figures/seaice_seasonalcycle_extent_Arctic_Antarctic.png :width: 100% Seasonal cycle of sea ice extent for Arctic and Antarctic regions .. figure:: figures/seaice_2d_fraction_Arctic_3-9.png :width: 100% 2D sea ice fraction maps for the Arctic region (March and September). .. figure:: figures/seaice_2d_thickness_Antarctic_3-9.png :width: 100% 2D sea ice thickness maps for the Antarctic region (March and September). Available demo notebooks ------------------------ Notebooks are stored in ``notebooks/diagnostics/seaice``: - `seaice_timeseries.ipynb `_ - `seaice_seasonalcycle.ipynb `_ - `seaice_2d.ipynb `_ References ---------- * Lavergne, T., Sørensen, A. M., Kern, S., Tonboe, R., Notz, D., Aaboe, S., Bell, L., Dybkjær, G., Eastwood, S., Gabarro, C., Heygster, G., Killie, M. A., Brandt Kreiner, M., Lavelle, J., Saldo, R., Sandven, S., & Pedersen, L. T. (2019). Version 2 of the EUMETSAT OSI SAF and ESA CCI sea-ice concentration climate data records. The Cryosphere, 13(1), 49-78. https://doi.org/10.5194/tc-13-49-2019. * Knowles, K., E. G. Njoku, R. Armstrong, and M. J. Brodzik. 2000. Nimbus-7 SMMR Pathfinder Daily EASE-Grid Brightness Temperatures, Version 1. Boulder, Colorado USA. NASA National Snow and Ice Data Center Distributed Active Archive Center. https://doi.org/10.5067/36SLCSCZU7N6. Authors and contributors ------------------------ This diagnostic is maintained by Emanuele Tovazzi (`@tovaz92 `_, `emanueletovazzi@cnr.it `_). Contributions are welcome — please open an issue or a pull request. For questions or suggestions, contact the AQUA team or the maintainers. Detailed API ------------ This section provides a detailed reference for the Application Programming Interface (API) of the ``seaice`` diagnostic, produced from the diagnostic function docstrings. .. automodule:: aqua.diagnostics.seaice :members: :undoc-members: :show-inheritance: