.. _global_biases: Global Biases Diagnostic ======================== Description ----------- The **GlobalBiases** diagnostic is a set of tools for the analysis and visualization of 2D spatial biases in climate model outputs. It supports comparative analysis between a target dataset (typically a climate model) and a reference dataset, commonly an observational or reanalysis product such as ERA5. Alternatively, it can be used to compare outputs from two different model simulations, for example to assess differences between historical and scenario experiments. GlobalBiases provides tools to plot: - Climatology maps - Bias maps - Seasonal bias maps - Vertical profiles to assess biases across pressure levels Classes ------- There are three classes in the diagnostic: * **GlobalBiases**: retrieves the data and prepares it for plotting (e.g., regridding, pressure level selection, unit conversion). It handles the computation of mean climatologies, including seasonal climatologies if requested. Climatologies are saved as class attributes and as NetCDF files. * **PlotGlobalBiases**: provides methods for plotting the global biases, seasonal biases, and vertical profiles. It generates the plots based on the data prepared by the GlobalBiases class. * **StatGlobalBiases**: statistical class including methods to compute global bias statistics and to assess the statistical significance of the bias. It computes global bias statistics such as mean bias and root mean square error (RMSE) between the model and reference datasets (area-weighted if grid cell areas are provided). It also performs a two-sample t-test at each grid point to determine if the difference between model and reference data is statistically significant. File structure -------------- * The diagnostic is located in the ``aqua/diagnostics/global_biases`` 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-global_biases.yaml`` * Notebooks are available in the ``notebooks/diagnostics/global_biases`` directory and contain examples of how to use the diagnostic. Input variables and datasets ---------------------------- By default, the diagnostic compares against the ERA5 dataset, but it can be configured to use any other dataset as a reference. A list of the variables that are compared automatically when running the full diagnostic is provided in the configuration files available in the ``aqua/diagnostics/config/diagnostics/global_biases`` directory. Some of the variables that are typically used in this diagnostic are: * ``2t`` (2 metre temperature) * ``tprate`` (total precipitation rate) * ``msl`` (mean sea level pressure) * ``u``, ``v`` (zonal and meridional wind) * ``q`` (specific humidity) 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 GlobalBiases, PlotGlobalBiases biases_ifs_nemo = GlobalBiases( model='IFS-NEMO', exp='historical-1990', source='lra-r100-monthly', loglevel="DEBUG" ) biases_era5 = GlobalBiases( model='ERA5', exp='era5', source='monthly', loglevel="DEBUG" ) biases_ifs_nemo.retrieve(var='q') biases_ifs_nemo.compute_climatology(seasonal=True, areas=True) biases_era5.retrieve(var='q') biases_era5.compute_climatology(seasonal=True, areas=True) pg = PlotGlobalBiases(loglevel='DEBUG') pg.plot_bias(data=biases_ifs_nemo.climatology, data_ref=biases_era5.climatology, var='q', plev=18000, area=biases_ifs_nemo.climatology['cell_area'], show_stats=True, # Statistical test options show_significance = True, # Enable significance stippling significance_alpha = 0.05, # 95% confidence level stipple_density = 3, # Stippling density (higher = more sparse) stipple_size = 0.5, # Size of stipple dots invert_stippling = False, # False = stipple where differences ARE significant ) .. 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/global_biases python cli_global_biases.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 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 global biases diagnostic. * ``globalbiases``: a block (nested in the ``diagnostics`` block) containing options for the Global Biases diagnostic. Variable-specific parameters override the defaults. * ``run``: enable/disable the diagnostic. * ``diagnostic_name``: name of the diagnostic. ``globalbiases`` by default, but can be changed when the globalbiases CLI is invoked within another ``recipe`` diagnostic, as is currently done for ``Radiation``. * ``variables``: list of variables to analyse. * ``formulae``: list of formulae to compute new variables from existing ones (e.g., ``tnlwrf+tnswrf``). * ``plev``: pressure levels to analyse for 3D variables. * ``seasons``: enable seasonal analysis. * ``seasons_stat``: statistic to use for seasonal climatology (e.g., "mean"). * ``vertical``: enable vertical profiles. * ``startdate_data`` / ``enddate_data``: time range for the dataset. * ``startdate_ref`` / ``enddate_ref``: time range for the reference dataset. .. code-block:: yaml globalbiases: run: true diagnostic_name: 'globalbiases' variables: ['tprate', '2t', 'msl', 'tnlwrf', 't', 'u', 'v', 'q', 'tos'] formulae: ['tnlwrf+tnswrf'] params: default: plev: [85000, 20000] seasons: true seasons_stat: 'mean' vertical: true startdate_data: null enddate_data: null startdate_ref: "1990-01-01" enddate_ref: "2020-12-31" tnlwrf+tnswrf: short_name: "tnr" long_name: "Top net radiation" * ``plot_params``: defines colorbar palette and limits and projection parameters for each variable. * ``show_stats`` enables the display of global bias statistics (mean bias and RMSE) on the global bias plot. * ``show_significance`` enables the display of stippling to indicate where the bias is statistically significant, based on a two-sample t-test (``significance_alpha`` defines the confidence level for the test, e.g., 0.05 for 95% confidence). The default parameters are used if not specified for a specific variable. Refer to `AQUA/aqua/core/util/projections.py `_ for available projections. .. code-block:: yaml plot_params: default: projection: 'robinson' projection_params: {} show_stats: true show_significance: true # Enable significance stippling significance_alpha: 0.05 # 95% confidence level 2t: cmap: 'RdBu_r' vmin: -15 vmax: 15 msl: vmin: -1000 vmax: 1000 u: vmin_v: -50 vmax_v: 50 Output ------ The diagnostic produces four types of plots: * Global climatology maps * Global bias maps (model vs reference) * Seasonal bias maps * Vertical bias profiles (for 3D variables) Plots are saved in both PDF and PNG format. Data outputs are saved as NetCDF files. Observations ------------ The default reference dataset is ERA5 reanalysis, provided by ECMWF. The diagnostic uses ERA5 monthly averages at 1x1 degree resolution 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/climatology.png :align: center :width: 100% Climatology of q from IFS-NEMO historical-1990. .. figure:: figures/global_bias.png :align: center :width: 100% Global bias of q from IFS-NEMO historical-1990 with respect to ERA5 climatology. .. figure:: figures/seasonal_bias.png :align: center :width: 100% Seasonal bias of q from IFS-NEMO historical-1990 with respect to ERA5 climatology. .. figure:: figures/vertical_bias.png :align: center :width: 100% Vertical bias of q from IFS-NEMO historical-1990 with respect to ERA5 climatology. Available demo notebooks ------------------------ Notebooks are stored in ``notebooks/diagnostics/global_biases``: - `global_biases.ipynb `_ Authors and contributors ------------------------ This diagnostic is maintained by Silvia Caprioli (`@silviacaprioli `_, `silvia.caprioli@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 ``global_biases`` diagnostic, produced from the diagnostic function docstrings. .. automodule:: aqua.diagnostics.global_biases :members: :undoc-members: :show-inheritance: