### Finalize development setup

Source: https://docs.esmvaltool.org/en/latest/quickstart/installation.html

Activates the development environment and installs pre-commit hooks for code formatting.

```bash
pixi shell -e esmvalcore-dev
```

```bash
pre-commit install
```

--------------------------------

### Command Line Example

Source: https://docs.esmvaltool.org/en/latest/tutorials/template.html

A basic example of a command line instruction.

```bash
my command
```

--------------------------------

### List installed recipes

Source: https://docs.esmvaltool.org/en/latest/_sources/quickstart/running.rst.txt

Prints a complete list of all installed recipes to the console.

```bash
esmvaltool recipes list
```

--------------------------------

### Example Preprocessor Configuration

Source: https://docs.esmvaltool.org/en/latest/_modules/esmvaltool/diag_scripts/ocean/diagnostic_model_vs_obs.html

An example configuration for a preprocessor suitable for 3D + time fields before passing them to the diagnostic.

```yaml
preprocessors:
    prep_map:
      extract_levels:
        levels:  [100., ]
        scheme: linear_extrap
      climate_statistics:
        operator: mean
      regrid:
        target_grid: 1x1
        scheme: linear
```

--------------------------------

### Example Preprocessor Configuration

Source: https://docs.esmvaltool.org/en/latest/_modules/esmvaltool/diag_scripts/ocean/diagnostic_seaice.html

An example configuration for an ESMValTool preprocessor to prepare data for the sea ice diagnostic.

```yaml
  preprocessors:
    timeseries_NHW_ice_extent: # North Hemisphere Winter ice_extent
      custom_order: true
      extract_time:
          start_year: 1960
          start_month: 12
          start_day: 1
          end_year: 2005
          end_month: 9
          end_day: 31
      extract_season:
        season: DJF
      extract_region:
        start_longitude: -180.
        end_longitude: 180.
        start_latitude: 0.
        end_latitude: 90.
```

--------------------------------

### Initialize Datasets

Source: https://docs.esmvaltool.org/en/latest/_modules/esmvaltool/diag_scripts/shared/_diag.html

Get all variables of a recipe configuration `cfg`.

```python
datasets = Datasets(cfg)
```

--------------------------------

### Example Preprocessor Configuration

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.ocean.html

An example configuration for a preprocessor to extract North Hemisphere Winter ice extent data.

```default
preprocessors:
  timeseries_NHW_ice_extent: # North Hemisphere Winter ice_extent
    custom_order: true
    extract_time:
        start_year: 1960
        start_month: 12
        start_day: 1
        end_year: 2005
        end_month: 9
        end_day: 31
    extract_season:
      season: DJF
    extract_region:
      start_longitude: -180.
      end_longitude: 180.
      start_latitude: 0.
      end_latitude: 90.
```

--------------------------------

### Install Language-Specific Subpackages

Source: https://docs.esmvaltool.org/en/latest/_sources/quickstart/installation.rst.txt

Command to install support for Python and NCL diagnostics into an existing environment.

```bash
mamba install esmvaltool-python esmvaltool-ncl
```

--------------------------------

### Execute Miniforge installation script

Source: https://docs.esmvaltool.org/en/latest/_sources/quickstart/installation.rst.txt

Run the downloaded shell script to install the Mamba package manager on Linux.

```bash
bash Miniforge3-Linux-x86_64.sh
```

--------------------------------

### Verify Git installation

Source: https://docs.esmvaltool.org/en/latest/_sources/community/repository.rst.txt

Run this command to confirm that Git is installed and to check the current version.

```bash
git --version
```

--------------------------------

### Example recipe log output

Source: https://docs.esmvaltool.org/en/latest/_sources/utils/RTW/add_a_recipe.rst.txt

The actual duration and memory usage can be found in the main_log.txt file.

```text
YYYY-MM-DD HH:MM:SS:sss UTC [12345] INFO    Time for running the recipe was: 0:02:13.334742
YYYY-MM-DD HH:MM:SS:sss UTC [12345] INFO    Maximum memory used (estimate): 2.4 GB
[...]
YYYY-MM-DD HH:MM:SS:sss UTC [12345] INFO    Run was successful
```

--------------------------------

### Configure autoassess_landsurf_surfrad in YAML

Source: https://docs.esmvaltool.org/en/latest/_sources/recipes/recipe_autoassess_landsurface_surfrad.rst.txt

Example configuration for the autoassess_landsurf_surfrad diagnostic, showing the required start and end date format for the Surfrad metric.

```yaml
scripts:
  autoassess_landsurf_surfrad: &autoassess_landsurf_surfrad_settings
    script: autoassess/autoassess_area_base.py
    title: "Autoassess Land-Surface Diagnostic Surfrad Metric"
    area: land_surface_surfrad
    control_model: UKESM1-0-LL
    exp_model: UKESM1-0-LL
    obs_models: [CERES-EBAF]
    obs_type: obs4MIPs
    start: 1997/12/01
    end: 2002/12/01
```

--------------------------------

### Example preprocessor configuration for transects

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.ocean.html

An example of a preprocessor configuration for a 3D+time field, including climate statistics and transect extraction.

```default
preprocessors:
  prep_transect:
    climate_statistics:
      operator: mean
    extract_transect: # Atlantic Meridional Transect
      latitude: [-50.,50.]
      longitude: 332.
```

--------------------------------

### Install with Pip

Source: https://docs.esmvaltool.org/en/latest/_sources/quickstart/installation.rst.txt

Install ESMValTool via pip after manually satisfying non-PyPI dependencies.

```bash
pip install esmvaltool
```

--------------------------------

### Verify ESMValTool installation

Source: https://docs.esmvaltool.org/en/latest/_sources/quickstart/installation.rst.txt

Run the tool with the help flag to confirm that the installation is working correctly.

```bash
esmvaltool --help
```

--------------------------------

### Example log_provenance call in NCL

Source: https://docs.esmvaltool.org/en/latest/community/diagnostic.html

A concrete example of calling log_provenance with specific arguments.

```console
log_provenance(ncdf_outfile, \
               map@outfile, \
               "Mean of variable: " + var0, \
               "mean", \
               "global", \
               "geo", \
               (/"righi_mattia", "gottschaldt_klaus-dirk"/), \
               (/"acknow_author"/), \
               metadata_att_as_array(info0, "filename"))
```

--------------------------------

### Install diagnostic-specific dependencies

Source: https://docs.esmvaltool.org/en/latest/_sources/quickstart/installation.rst.txt

Use these commands to install dependencies for specific diagnostic types like NCL or R.

```bash
pixi shell -e esmvaltool-dev
```

--------------------------------

### Install imagehash dependency

Source: https://docs.esmvaltool.org/en/latest/_sources/community/release_strategy/detailed_release_procedure.rst.txt

Prerequisite command to install the imagehash library required for comparison.

```bash
pip install imagehash
```

--------------------------------

### Imports and Logger Setup

Source: https://docs.esmvaltool.org/en/latest/_modules/esmvaltool/diag_scripts/ocean/diagnostic_maps_quad.html

Initializes the necessary libraries for data processing, plotting, and logging for the diagnostic script.

```python
import logging
import os
import sys

import cartopy.crs as ccrs
import iris
import iris.analysis.cartography
import iris.plot as iplt
import matplotlib.pyplot as plt
import numpy as np
from cartopy.mpl.gridliner import LATITUDE_FORMATTER, LONGITUDE_FORMATTER

from esmvaltool.diag_scripts.ocean import diagnostic_tools as diagtools
from esmvaltool.diag_scripts.shared import (
    run_diagnostic,
    save_data,
    save_figure,
)

# Create a logger object.
logger = logging.getLogger(os.path.basename(__file__))
logging.getLogger().addHandler(logging.StreamHandler(sys.stdout))
```

--------------------------------

### Copy Miniconda installer to VM with scp

Source: https://docs.esmvaltool.org/en/latest/_sources/community/release_strategy/detailed_release_procedure.rst.txt

Copies a Miniconda installer from Levante $HOME to the VM. Replace the filename and target directory as needed. Conda environments should be created under /mnt/esmvaltool_disk2/work/<username>.

```bash
scp Miniconda3-py39_4.12.0-Linux-x86_64.sh user@esmvaltool.dkrz.de:/mnt/esmvaltool_disk2/work/<username>
```

--------------------------------

### Install default configuration

Source: https://docs.esmvaltool.org/en/latest/_sources/quickstart/configuration.rst.txt

Run this command to copy the default configuration file to the default location. The resulting file must be customized to point to your local data before running recipes.

```bash
esmvaltool config copy defaults/config-user.yml
```

--------------------------------

### Bash output example

Source: https://docs.esmvaltool.org/en/latest/_sources/tutorials/template.rst.txt

Displays command output within an expandable dropdown component.

```bash
.. dropdown:: Output
   :color: secondary
   :icon: eye

   .. code-block:: bash
      :caption: Bash

      my output
```

--------------------------------

### Command Output Example

Source: https://docs.esmvaltool.org/en/latest/tutorials/template.html

The expected output from a command execution.

```bash
my output
```

--------------------------------

### Install OpenMP on MacOS

Source: https://docs.esmvaltool.org/en/latest/_sources/quickstart/installation.rst.txt

Command to install the OpenMP library using Homebrew, which is required for some recipes on MacOS.

```bash
brew install libomp
```

--------------------------------

### Verify Mamba installation

Source: https://docs.esmvaltool.org/en/latest/_sources/quickstart/installation.rst.txt

Check that the mamba executable is correctly installed and accessible in your path.

```bash
which mamba
```

--------------------------------

### Bash command example

Source: https://docs.esmvaltool.org/en/latest/_sources/tutorials/template.rst.txt

A basic bash command snippet.

```bash
.. code-block:: bash
   :caption: Bash

   my command
```

--------------------------------

### Run RTW in production mode

Source: https://docs.esmvaltool.org/en/latest/_sources/utils/RTW/user_guide/dkrz_production.rst.txt

Navigate to the workflow directory and execute the workflow with the DKRZ and production options, installing it into a specific directory.

```bash
cd ESMValTool/esmvaltool/utils/recipe_test_workflow
cylc vip -O dkrz -O production -n recipe_test_workflow_production
```

--------------------------------

### Example settings.yml file

Source: https://docs.esmvaltool.org/en/latest/_sources/quickstart/output.rst.txt

This file is automatically generated by ESMValCore for each diagnostic to pass global keys, paths, and configuration flags to diagnostic scripts.

```yaml
input_files:[[...]recipe_ocean_bgc_20190118_134855/preproc/diag_timeseries_scalars/mfo/metadata.yml]
log_level: debug
output_file_type: png
plot_dir: [...]recipe_ocean_bgc_20190118_134855/plots/diag_timeseries_scalars/Scalar_timeseries
profile_diagnostic: false
recipe: recipe_ocean_bgc.yml
run_dir: [...]recipe_ocean_bgc_20190118_134855/run/diag_timeseries_scalars/Scalar_timeseries
script: Scalar_timeseries
version: 2.0a1
work_dir: [...]recipe_ocean_bgc_20190118_134855/work/diag_timeseries_scalars/Scalar_timeseries
write_netcdf: true
write_plots: true
```

--------------------------------

### Configure proxy for Pip

Source: https://docs.esmvaltool.org/en/latest/_sources/quickstart/installation.rst.txt

Install from source behind a proxy by specifying trusted hosts.

```bash
pip install --trusted-host=pypi.python.org --trusted-host=pypi.org --trusted-host=files.pythonhosted.org --no-deps -e .[develop]
```

--------------------------------

### Install ESMValTool on MacOS

Source: https://docs.esmvaltool.org/en/latest/_sources/quickstart/installation.rst.txt

Commands to create a new environment with Python diagnostic support, activate it, and verify the installation.

```bash
mamba create --name esmvaltool esmvaltool-python
```

```bash
conda activate esmvaltool
```

```bash
esmvaltool --help
```

--------------------------------

### Example Preprocessor Configuration for Map Diagnostics

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.ocean.html

An example preprocessor configuration for a 3D+time field, ensuring the cube has no time component and specific depth levels before map plotting.

```default
preprocessors:
  prep_map:
    extract_levels:
      levels:  [100., ]
       scheme: linear_extrap
    climate_statistics:
      operator: mean
```

--------------------------------

### Documenting mamba version

Source: https://docs.esmvaltool.org/en/latest/_sources/community/release_strategy/detailed_release_procedure.rst.txt

Check the installed version of mamba for reproducibility.

```bash
mamba --version
```

--------------------------------

### Get dataset information

Source: https://docs.esmvaltool.org/en/latest/_sources/input.rst.txt

Retrieves downloading instructions for a specific dataset.

```bash
esmvaltool data info [DATASET]
```

--------------------------------

### Recipe Configuration for sea_surface_temperature

Source: https://docs.esmvaltool.org/en/latest/_sources/recipes/recipe_oceans.rst.txt

Example YAML configuration for a recipe defining variables, datasets, and script parameters for ocean surface temperature analysis.

```yaml
sea_surface_temperature:
    description: Global surface quad plots tos
    variables:
      tos:  # Temperature ocean surface
        preprocessor: prep_quad_map
        mip: Omon
    additional_datasets:
      - {dataset: WOA, project: obs4MIPs, level: L3,
         start_year: 2000, end_year: 2000, tier: 2}
    scripts:
      Global_Ocean_map:  &Global_Ocean_map
        script: ocean/diagnostic_maps_quad.py
        control_model: {dataset: HadGEM3-GC31-LL, project: CMIP6, mip: Omon,
                        exp: historical, ensemble: r1i1p1f3}
        exper_model: {dataset: UKESM1-0-LL, project: CMIP6, mip: Omon,
                      exp: historical, ensemble: r1i1p1f2}
        observational_dataset: {dataset: WOA, project: obs4MIPs}
```

--------------------------------

### Install ncdf4.helpers manually in R

Source: https://docs.esmvaltool.org/en/latest/_sources/recipes/recipe_hyint.rst.txt

Commands to manually download, install, and clean up the ncdf4.helpers package from the CRAN archive, required for the extreme_events diagnostic.

```R
url <- "https://cran.r-project.org/src/contrib/Archive/ncdf4.helpers/ncdf4.helpers_0.3-3.tar.gz"
pkgFile <- "ncdf4.helpers_0.3-3.tar.gz"
download.file(url = url, destfile = pkgFile)
install.packages(pkgs=pkgFile, type="source", repos=NULL)
unlink(pkgFile)
```

--------------------------------

### Symbolic link to latest output directory

Source: https://docs.esmvaltool.org/en/latest/_sources/faq.rst.txt

Example of directory structure showing the latest output link and the command to create it.

```bash
recipe_example_20190905_163431
recipe_example_20190905_163519
recipe_example_latest -> recipe_example_20190905_163519
```

```bash
esmvaltool run recipe_example.yml; \
ln -sfT $(ls -1d ~/esmvaltool_output/recipe_example_* | tail -1) ~/esmvaltool_output/recipe_example_latest
```

--------------------------------

### Configure preprocessor for profile diagnostics

Source: https://docs.esmvaltool.org/en/latest/_modules/esmvaltool/diag_scripts/ocean/diagnostic_profiles.html

Example configuration for a preprocessor to extract a volume and calculate area statistics before generating profiles.

```yaml
preprocessors:
    prep_profile:
      extract_volume:
        long1: 0.
        long2:  20.
        lat1:  -30.
        lat2:  30.
        z_min: 0.
        z_max: 3000.
      area_statistics:
        operator: mean
```

--------------------------------

### Activate Environment and Verify Installation

Source: https://docs.esmvaltool.org/en/latest/_sources/quickstart/installation.rst.txt

Commands to activate the esmvaltool conda environment and verify the installation by displaying the help message.

```bash
conda activate esmvaltool
```

```bash
esmvaltool --help
```

--------------------------------

### Get help for specific esmvaltool data commands

Source: https://docs.esmvaltool.org/en/latest/_sources/input.rst.txt

Displays help information for the download subcommand.

```bash
esmvaltool data download --help
```

--------------------------------

### Enter the ESMValTool directory and activate the environment

Source: https://docs.esmvaltool.org/en/latest/quickstart/installation.html

Navigate to the source directory and use pixi to create and activate the development environment.

```bash
cd ESMValTool
```

```bash
pixi shell --frozen
```

--------------------------------

### get_input_files(cfg[, patterns, ignore_patterns])

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.emergent_constraints/init.html

Get input files.

```APIDOC
## get_input_files(cfg[, patterns, ignore_patterns])

### Description
Get input files.

### Parameters
- **cfg** (dict) - Required - Configuration dictionary.
- **patterns** (list, optional) - Optional - File patterns.
- **ignore_patterns** (list, optional) - Optional - Patterns to ignore.

### Returns
- **files** (list) - List of input files.
```

--------------------------------

### Diagnostic script imports and logging setup

Source: https://docs.esmvaltool.org/en/latest/_modules/esmvaltool/diag_scripts/ocean/diagnostic_maps.html

Standard imports and logging configuration for the diagnostic script.

```python
import itertools
import logging
import os
import sys

import cartopy
import iris
import iris.quickplot as qplt
import matplotlib.pyplot as plt

from esmvaltool.diag_scripts.ocean import diagnostic_tools as diagtools
from esmvaltool.diag_scripts.shared import ProvenanceLogger, run_diagnostic

# This part sends debug statements to stdout
logger = logging.getLogger(os.path.basename(__file__))
logging.getLogger().addHandler(logging.StreamHandler(sys.stdout))
```

--------------------------------

### Get details for a ruff rule

Source: https://docs.esmvaltool.org/en/latest/_sources/community/code_documentation.rst.txt

Shows a detailed explanation of a specific ruff rule, using RET504 as an example rule code.

```bash
ruff rule RET504
```

--------------------------------

### Install pre-commit hooks

Source: https://docs.esmvaltool.org/en/latest/_sources/community/code_documentation.rst.txt

Run this command once after cloning the ESMValTool repository to enable pre-commit checks that run automatically on every commit.

```bash
pre-commit install
```

--------------------------------

### Configure autoassess_area_base.py in recipe

Source: https://docs.esmvaltool.org/en/latest/recipes/recipe_autoassess_stratosphere.html

Example configuration for the stratosphere diagnostic metric using the autoassess_area_base.py wrapper. Note the use of YYYY/MM/DD format for start and end dates to accommodate native Autoassess time gating requirements.

```yaml
scripts:
  autoassess_strato_test_1: &autoassess_strato_test_1_settings
    script: autoassess/autoassess_area_base.py  # the base wrapper
    title: "Autoassess Stratosphere Diagnostic Metric"  # title
    area: stratosphere  # assesment area
    control_model: UKESM1-0-LL-hist  # control dataset name
    exp_model: UKESM1-0-LL-piCont  # experiment dataset name
    obs_models: [ERA-Interim]  # list to hold models that are NOT for metrics but for obs operations
    additional_metrics: [ERA-Interim]  # list to hold additional datasets for metrics
    start: 2004/12/01  # start date in native Autoassess format
    end: 2014/12/01  # end date in native Autoassess format
```

--------------------------------

### Preprocessor Configuration for 2D+time Field

Source: https://docs.esmvaltool.org/en/latest/_modules/esmvaltool/diag_scripts/ocean/diagnostic_timeseries.html

Example configuration for a 2D+time field using area statistics.

```yaml
prep_timeseries_2: # For Global surface Averaged
      area_statistics:
        operator: mean
```

--------------------------------

### Get image format from configuration

Source: https://docs.esmvaltool.org/en/latest/_modules/esmvaltool/diag_scripts/ocean/diagnostic_tools.html

Retrieves the desired image format from the global configuration dictionary, falling back to a default if not specified.

```python
def get_image_format(cfg, default="png"):
    """
    Load the image format from the global config file.

    Current tested options are svg, png.

    The cfg is the opened global config.
    The default format is used if no specific format is requested.
    The default is set in the user config.yml
    Individual diagnostics can set their own format which will
    supercede the main config.yml.

    Arguments
    ---------
    cfg: dict
        the opened global config dictionary, passed by ESMValTool.

    Returns
    -------
    str
        The image format extention.
    """
    image_extention = default

    # Load format from config.yml and set it as default
    if "output_file_type" in cfg:
        image_extention = cfg["output_file_type"]

    # Load format from config.yml and set it as default
    if "image_format" in cfg:
        image_extention = cfg["image_format"]

    matplotlib_image_formats = plt.gcf().canvas.get_supported_filetypes()
    if image_extention not in matplotlib_image_formats:
        logger.warning(
            " ".join(
                [
                    "Image format ",
                    image_extention,
                    "not in matplot:",
                    ", ".join(matplotlib_image_formats),
                ],
            ),
        )

    image_extention = "." + image_extention
    image_extention = image_extention.replace("..", ".")
    return image_extention
```

--------------------------------

### Preprocessor Configuration for Global Volume Averaged Data

Source: https://docs.esmvaltool.org/en/latest/_modules/esmvaltool/diag_scripts/ocean/diagnostic_timeseries.html

Example configuration for a 3D+time field using volume statistics.

```yaml
preprocessors:
    prep_timeseries_1:# For Global Volume Averaged
      volume_statistics:
        operator: mean
```

--------------------------------

### Build documentation using pixi

Source: https://docs.esmvaltool.org/en/latest/_sources/community/code_documentation.rst.txt

Alternative command to build documentation using the pixi task runner.

```bash
pixi run doc
```

--------------------------------

### Access Recipe Variables

Source: https://docs.esmvaltool.org/en/latest/_modules/esmvaltool/diag_scripts/shared/_diag.html

Examples for retrieving variable information and checking availability using the Variables class.

```python
variables = Variables(cfg)

variables.short_name('tas')
variables.standard_name('tas')
variables.long_name('tas')
variables.units('tas')

variables.iris_dict('tas')

variables.vars_available('tas', 'pr')
```

--------------------------------

### Preprocessor configuration for Global surface Averaged 2D+time fields

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.ocean.html

Example configuration for a 2D+time field using area statistics.

```default
prep_timeseries_2: # For Global surface Averaged
  area_statistics:
    operator: mean
```

--------------------------------

### Build documentation from scratch

Source: https://docs.esmvaltool.org/en/latest/_sources/community/code_documentation.rst.txt

Command to build documentation from scratch by ignoring cached files.

```bash
sphinx-build -Ea doc/sphinx/source/ doc/sphinx/build/
```

--------------------------------

### Preprocessors for diagnostic_timeseries.py

Source: https://docs.esmvaltool.org/en/latest/recipes/recipe_oceans.html

Configuration examples for global area-weighted average 2D fields, global volume-weighted average 3D fields, and global area-weighted surface of a 3D field.

```yaml
area_statistics:
  operator: mean
```

```yaml
volume_statistics:
  operator: mean
```

```yaml
extract_levels:
  levels: [0., ]
  scheme: linear_horizontal_extrapolate_vertical
area_statistics:
  operator: mean
```

--------------------------------

### Build documentation with sphinx-build

Source: https://docs.esmvaltool.org/en/latest/_sources/community/code_documentation.rst.txt

Standard command to build documentation from the source directory to the build directory.

```bash
sphinx-build doc/sphinx/source/ doc/sphinx/build/
```

--------------------------------

### Build documentation with sphinx-build

Source: https://docs.esmvaltool.org/en/latest/community/code_documentation.html

Run this command from the repository root to build the documentation into doc/sphinx/build/. The second variant with -Ea forces a full rebuild from scratch.

```default
sphinx-build doc/sphinx/source/ doc/sphinx/build/
```

```default
sphinx-build -Ea doc/sphinx/source/ doc/sphinx/build/
```

--------------------------------

### Get a local copy of a recipe

Source: https://docs.esmvaltool.org/en/latest/_sources/quickstart/running.rst.txt

Retrieves a local copy of a recipe for customization. Replace recipe_name.yml with the desired recipe name.

```bash
esmvaltool recipes get recipe_name.yml
```

--------------------------------

### Monitor configuration file maps definition

Source: https://docs.esmvaltool.org/en/latest/_sources/recipes/recipe_monitor.rst.txt

Example of defining map projections, ticks, and layout options in the monitor configuration YAML file.

```yaml
maps:
   global: # Map name, choose a meaningful one
      projection: PlateCarree # Cartopy projection to use
      projection_kwargs: # Dictionary with Cartopy's projection keyword arguments.
         central_longitude: 285
      smooth: true # If true, interpolate values to get smoother maps. If not, all points in a cells will get the exact same color
      lon: [-120, -60, 0, 60, 120, 180] # Set longitude ticks
      lat: [-90, -60, -30, 0, 30, 60, 90] # Set latitude ticks
      colorbar_location: bottom
      extent: null # If defined, restrict the projection to a region. Format [lon1, lon2, lat1, lat2]
      suptitle_pos: 0.87 # Title position in the figure.
```

--------------------------------

### Install pygithub dependency

Source: https://docs.esmvaltool.org/en/latest/_sources/utils/utils.rst.txt

Install the pygithub package required for the release notes drafting script.

```bash
pip install pygithub
```

--------------------------------

### Python code example with highlighting

Source: https://docs.esmvaltool.org/en/latest/_sources/tutorials/template.rst.txt

A python code snippet featuring line numbers and highlighted lines.

```python
.. code-block:: python
   :caption: Python
   :linenos:
   :emphasize-lines: 2

   with line numbers
   and code highlighting
```

--------------------------------

### Verify ESMValTool version

Source: https://docs.esmvaltool.org/en/latest/_sources/quickstart/installation.rst.txt

Run this command to confirm that the development version of ESMValCore is correctly installed.

```bash
esmvaltool version
```

--------------------------------

### Preprocessor Configuration for Global Surface Averaged Data

Source: https://docs.esmvaltool.org/en/latest/_modules/esmvaltool/diag_scripts/ocean/diagnostic_timeseries.html

Example configuration for a 3D+time field at the surface using linear extrapolation.

```yaml
prep_timeseries_2: # For Global surface Averaged
      extract_levels:
        levels:  [0., ]
        scheme: linear_extrap
      area_statistics:
        operator: mean
```

--------------------------------

### Configure autoassess_area_base.py diagnostic settings

Source: https://docs.esmvaltool.org/en/latest/_sources/recipes/recipe_autoassess_landsurface_permafrost.rst.txt

Example of standard inputs for the autoassess_area_base.py wrapper as defined in a recipe script section.

```yaml
scripts:
  plot_landsurf_permafrost: &plot_landsurf_permafrost_settings
    <<: *autoassess_landsurf_permafrost_settings
    control_model: MPI-ESM-LR
    exp_model: MPI-ESM-MR
    script: autoassess/plot_autoassess_metrics.py
    ancestors: ['*/autoassess_landsurf_permafrost']
    title: "Plot Land-Surface Permafrost Metrics"
    plot_name: "Permafrost_Metrics"
    diag_tag: aa_landsurf_permafrost
    diag_name: autoassess_landsurf_permafrost
```

--------------------------------

### Generate overview webpages for recipe runs

Source: https://docs.esmvaltool.org/en/latest/_sources/utils/utils.rst.txt

Run this script to generate index.html and debug.html files summarizing recipe runs in the specified output directory.

```python
python esmvaltool/utils/testing/regression/summarize.py ~/esmvaltool_output/
```

--------------------------------

### Module Initialization and Logging

Source: https://docs.esmvaltool.org/en/latest/_modules/esmvaltool/diag_scripts/ocean/diagnostic_tools.html

Sets up logging to stdout for the diagnostic tools module.

```python
import logging
import os
import sys
from pathlib import Path

import cftime
import iris
import matplotlib.pyplot as plt
import numpy as np
import yaml

from esmvaltool.diag_scripts.shared._base import _get_input_data_files

# This part sends debug statements to stdout
logger = logging.getLogger(os.path.basename(__file__))
logging.getLogger().addHandler(logging.StreamHandler(sys.stdout))
```

--------------------------------

### Monitor configuration file variables definition

Source: https://docs.esmvaltool.org/en/latest/_sources/recipes/recipe_monitor.rst.txt

Example of defining variable-specific options, including color maps and bounds, using YAML anchors for defaults.

```yaml
variables:
   # Define default. Variable definitions completely override the default
   # not just the values defined. If you want to override only the defined
   # values, use yaml anchors as shown
   default: &default
      colors: RdYlBu_r # Matplotlib colormap to use for the colorbar
      N: 20 # Number of map intervals to plot
      bad: [0.9, 0.9, 0.9] # Color to use when no data
   pr:
      <<: *default
      colors: gist_earth_r
      # Define bounds of the colorbar, as a list of
      bounds: 0-10.5,0.5 # Set colorbar bounds, as a list or in the format min-max,interval
      extend: max # Set extend parameter of mpl colorbar. See https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.colorbar.html
   sos:
      # If default is defined, entries are treated as map specific option.
      # Missing values in map definitionas are taken from variable's default
      # definition
      default:
         <<: *default
         bounds: 25-41,1
         extend: both
      arctic:
         bounds: 25-40,1
      antarctic:
         bounds: 30-40,0.5
   nao: &nao
      <<: *default
      extend: both
      # Variable definitions can override map parameters. Use with caution.
      bounds: [-0.03, -0.025, -0.02, -0.015, -0.01, -0.005, 0., 0.005, 0.01, 0.015, 0.02, 0.025, 0.03]
      projection: PlateCarree
      smooth: true
      lon: [-90, -60, -30, 0, 30]
      lat: [20, 40, 60, 80]
      colorbar_location: bottom
      suptitle_pos: 0.87
   sam:
      <<: *nao
      lat: [-90, -80, -70, -60, -50]
      projection: SouthPolarStereo
      projection_kwargs:
         central_longitude: 270
      smooth: true
      lon: [-120, -60, 0, 60, 120, 180]
```

--------------------------------

### Preprocessor configuration for Global surface Averaged 3D+time fields

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.ocean.html

Example configuration for a 3D+time field at the surface using level extraction and area statistics.

```default
prep_timeseries_2: # For Global surface Averaged
  extract_levels:
    levels:  [0., ]
    scheme: linear_extrap
  area_statistics:
    operator: mean
```

--------------------------------

### Configure diagnostic with CMIP6 scenario 60

Source: https://docs.esmvaltool.org/en/latest/_sources/recipes/recipe_climate_change_hotspot.rst.txt

Example of updating the diagnostic configuration to use scenario 60 by referencing the cmip6_60 anchor.

```yaml
pr_cmip6_60:
 variables:
  pr:
    mip: Amon
    short_name: pr
    preprocessor: ensemble_members
    additional_datasets: *cmip6_60
 scripts:
  pr_cmip6_60:
    <<: *script_input
```

--------------------------------

### Install ESMValTool on Linux

Source: https://docs.esmvaltool.org/en/latest/_sources/quickstart/installation.rst.txt

Create a new conda environment named 'esmvaltool' and install the ESMValTool package.

```bash
mamba create --name esmvaltool esmvaltool
```

--------------------------------

### Initialize Variables from configuration

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.shared.html

Create a Variables instance using the recipe configuration object cfg.

```python
variables = Variables(cfg)
```

--------------------------------

### Generate .zenodo.json from CITATION.cff

Source: https://docs.esmvaltool.org/en/latest/_sources/community/code_documentation.rst.txt

Install cffconvert and use it to generate the .zenodo.json file from the CITATION.cff file. Note that this process may discard 'communities' and 'grants' entries, which must be restored manually.

```bash
pip install cffconvert
cffconvert --infile CITATION.cff --format zenodo --outfile .zenodo.json
```

--------------------------------

### Diagnostic section configuration for diagnostic_seaice.py

Source: https://docs.esmvaltool.org/en/latest/recipes/recipe_oceans.html

Example diagnostic section configuration for the recipe, specifying the variable and script parameters for sea ice analysis.

```yaml
diag_ice_NHW:
  description: North Hemisphere Winter Sea Ice diagnostics
  variables:
    sic: # surface ice cover
      preprocessor: timeseries_NHW_ice_extent
      field: TO2M
      mip: OImon
  scripts:
    Global_seaice_timeseries:
      script: ocean/diagnostic_seaice.py
      threshold: 15.
```

--------------------------------

### Run automated tests

Source: https://docs.esmvaltool.org/en/latest/_sources/quickstart/installation.rst.txt

Execute the test suite to verify the installation. Use the -n flag to run tests in parallel on multiple threads.

```bash
pytest -m "not installation"
```

```bash
pytest -n 4
```

--------------------------------

### Datasets.__init__(cfg)

Source: https://docs.esmvaltool.org/en/latest/_modules/esmvaltool/diag_scripts/shared/_diag.html

Initializes the Datasets object by loading all datasets from the recipe configuration dictionary. Raises TypeError if the configuration is invalid.

```APIDOC
## Datasets.__init__(cfg)

### Description
Initializes the Datasets object by loading all datasets from the recipe configuration dictionary. Raises TypeError if the configuration is invalid.

### Method
Constructor

### Parameters
- **cfg** (dict, optional) - Configuration dictionary of the recipe.

### Raises
- **TypeError** - If recipe configuration dictionary is not valid.

### Notes
- Deprecated since version 2.2, will be removed in version 2.4.
```

--------------------------------

### main(cfg)

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.ocean.html

Runs the diagnostics profile tool. Loads the config file, finds an observational dataset filename, and passes it into the plot making tool.

```APIDOC
## main(cfg)

### Description
Run the diagnostics profile tool. Load the config file, find an observational dataset filename, pass loaded into the plot making tool.

### Parameters
- **cfg** (dict) - Required - The opened global config dictionairy, passed by ESMValTool.
```

--------------------------------

### Load Mamba environment variables

Source: https://docs.esmvaltool.org/en/latest/_sources/quickstart/installation.rst.txt

Manually source the conda profile script if automatic loading was skipped during installation. Replace <prefix> with your actual installation path.

```bash
source <prefix>/etc/profile.d/conda.sh
```

--------------------------------

### main(cfg)

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.ocean.html

Loads the config file and some metadata, then passes them to the plot making tools.

```APIDOC
## Function: main(cfg)

### Description
Loads the config file and some metadata, then passes them to the plot making tools.

### Parameters
- **cfg** (dict) - Required - The opened global config dictionary, passed by ESMValTool.

### Returns
None
```

--------------------------------

### Preprocessor configuration for map diagnostics

Source: https://docs.esmvaltool.org/en/latest/_modules/esmvaltool/diag_scripts/ocean/diagnostic_maps.html

An example of a preprocessor configuration for a 3D+time field, ensuring the data is ready for map plotting by extracting levels and calculating statistics.

```yaml
preprocessors:
    prep_map:
      extract_levels:
        levels:  [100., ]
         scheme: linear_extrap
      climate_statistics:
        operator: mean
```

--------------------------------

### main(cfg)

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.ocean.html

Loads the config file and metadata, then passes them to the plot making tools.

```APIDOC
## main(cfg)

### Description
Load the config file and some metadata, then pass them the plot making tools.

### Parameters
- **cfg** (dict) - Required - The opened global config dictionairy, passed by ESMValTool.

```

--------------------------------

### Variables.standard_names()

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.shared.html

Gets a list of all standard names.

```APIDOC
## Variables.standard_names()

### Description
Get list of all standard_names.

### Method
standard_names

### Parameters
None

### Returns
- **list** - List of all standard_names.
```

--------------------------------

### Variables.short_names()

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.shared.html

Gets a list of all short names.

```APIDOC
## Variables.short_names()

### Description
Get list of all short_names.

### Method
short_names

### Parameters
None

### Returns
- **list** - List of all short_names.
```

--------------------------------

### prepare_provenance_record function

Source: https://docs.esmvaltool.org/en/latest/_modules/esmvaltool/diag_scripts/ocean/diagnostic_tools.html

Reads the recipe file from the run directory, extracts documentation metadata, and updates the provenance record with authors, title, description, projects, realms, and themes.

```python
    recipe_path = Path(cfg["run_dir"]).parents[1] / cfg["recipe"]
    with recipe_path.open() as recipe_file:
        recipe = yaml.safe_load(recipe_file)

    doc = recipe["documentation"]
    authors = doc.get("authors", [])
    authors += [
        maintainer
        for maintainer in doc.get("maintainer", [])
        if maintainer not in authors
    ]
    provenance_record["authors"] = authors
    for key in ["title", "description", "projects"]:
        val = doc[key]
        if val:
            provenance_record[key] = val
    for key in ["realms", "themes"]:
        val = cfg.get(key)
        if val:
            provenance_record[key] = val
    return provenance_record
```

--------------------------------

### esmvaltool.diag_scripts.shared.get_control_exper_obs

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.shared.html

Get control, exper and obs datasets.

```APIDOC
## Function: esmvaltool.diag_scripts.shared.get_control_exper_obs

### Description
Get control, exper and obs datasets.

### Signature
`get_control_exper_obs(short_name, ...[, ...])`

### Parameters
- **short_name** - Short name of the variable.
- **...** - Additional parameters.
```

--------------------------------

### get_colors(cfg[, groups])

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.emergent_constraints/init.html

Get color palette.

```APIDOC
## get_colors(cfg[, groups])

### Description
Get color palette.

### Parameters
- **cfg** (dict) - Required - Configuration dictionary.
- **groups** (list, optional) - Optional - List of groups.

### Returns
- **colors** (list) - List of colors.
```

--------------------------------

### main(config)

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.ocean.html

Loads the config file and runs through the order of operations for the diagnostic.

```APIDOC
## main(config)

### Description
Load the config file and running through the order of operation.
```

--------------------------------

### Configure JASMIN environment

Source: https://docs.esmvaltool.org/en/latest/_sources/utils/RTW/user_guide/quick_start.rst.txt

Add the Metomi bin directory to your PATH in ~/.bashrc.

```bash
export PATH=/apps/jasmin/metomi/bin:$PATH
```

--------------------------------

### esmvaltool.diag_scripts.shared.get_plot_filename

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.shared.html

Get a valid path for saving a diagnostic plot.

```APIDOC
## Function: esmvaltool.diag_scripts.shared.get_plot_filename

### Description
Get a valid path for saving a diagnostic plot.

### Signature
`get_plot_filename(basename, cfg)`

### Parameters
- **basename** - Base name for the file.
- **cfg** - Configuration dictionary.
```

--------------------------------

### Run a recipe with Docker

Source: https://docs.esmvaltool.org/en/latest/_sources/quickstart/installation.rst.txt

Command to execute a recipe while mounting host directories and passing environment variables.

```bash
docker run -e HOME -v "$HOME":"$HOME" -v /data:/data esmvalgroup/esmvaltool:stable run examples/recipe_python.yml
```

--------------------------------

### Main entry point for diagnostic

Source: https://docs.esmvaltool.org/en/latest/_modules/esmvaltool/diag_scripts/ocean/diagnostic_maps_quad.html

Runs the diagnostic using run_diagnostic() as a context manager and calls main with the configuration.

```python
if __name__ == "__main__":
    with run_diagnostic() as CONFIG:
        main(CONFIG)
```

--------------------------------

### get_provenance_record(attributes, tags, **kwargs)

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.emergent_constraints/init.html

Get provenance record.

```APIDOC
## get_provenance_record(attributes, tags, **kwargs)

### Description
Get provenance record.

### Parameters
- **attributes** (dict) - Required - Attributes.
- **tags** (dict) - Required - Tags.
- **kwargs** - Additional keyword arguments.

### Returns
- **record** (dict) - Provenance record.
```

--------------------------------

### main(cfg)

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.ocean.html

Loads the config file and metadata, then passes them to the plot making tools. This is the entry point for the diagnostic.

```APIDOC
## main(cfg)

### Description
Load the config file and metadata, then pass them the plot making tools.

### Parameters
- **cfg** (dict) - Required - Configuration dictionary.

### Returns
- None
```

--------------------------------

### Copy recipe output to VM with rsync

Source: https://docs.esmvaltool.org/en/latest/_sources/community/release_strategy/detailed_release_procedure.rst.txt

Copies recipe output from the testing directory to the VM, excluding preproc directories. Use nohup to keep the process running after logout. Replace paths and version as needed.

```bash
nohup rsync --exclude preproc/ -rlt /path_to_testing/esmvaltool_output/* /shared/esmvaltool/v2.x.x/
```

--------------------------------

### main function in _base.py

Source: https://docs.esmvaltool.org/en/latest/_modules/esmvaltool/diag_scripts/shared/_base.html

The main function parses command-line arguments (filename, -f/--force, -i/--ignore-existing, -n/--no-distributed, -l/--log-level), loads configuration, sets up logging, reads input metadata, cleans previous output, creates output directories, and optionally connects to a Dask distributed scheduler. It yields the configuration dictionary as a context manager.

```python
    # Implemented as context manager so we can support clean up actions later
    parser = argparse.ArgumentParser(description="Diagnostic script")
    parser.add_argument("filename", help="Path to settings.yml")
    parser.add_argument(
        "-f",
        "--force",
        help=(
            "Force emptying the output directories "
            "(useful when re-running the script)"
        ),
        action="store_true",
    )
    parser.add_argument(
        "-i",
        "--ignore-existing",
        help=(
            "Force running the script, even if output files exist "
            "(useful when re-running the script, use at your own risk)."
        ),
        action="store_true",
    )
    parser.add_argument(
        "-n",
        "--no-distributed",
        help=(
            "Do not use the Dask distributed 'scheduler_address' from the "
            "configuration file "
            "(useful when re-running the script and the scheduler is no "
            "longer available)."
        ),
        action="store_true",
    )
    parser.add_argument(
        "-l",
        "--log-level",
        help=("Set the log-level"),
        choices=["debug", "info", "warning", "error"],
    )
    args = parser.parse_args()

    cfg = get_cfg(args.filename)

    # Set up logging
    if args.log_level:
        cfg["log_level"] = args.log_level

    logging.basicConfig(
        format="%(asctime)s [%(process)d] %(levelname)-8s "
        "%(name)s,%(lineno)s\t%(message)s",
    )
    logging.Formatter.converter = time.gmtime
    logging.captureWarnings(True)
    logging.getLogger().setLevel(cfg["log_level"].upper())

    # Read input metadata
    cfg["input_data"] = _get_input_data_files(cfg)

    logger.info(
        "Starting diagnostic script %s with configuration:\n%s",
        cfg["script"],
        yaml.safe_dump(cfg),
    )

    # Clean run_dir and output directories from previous runs
    default_files = {
        "diagnostic_provenance.yml",
        "log.txt",
        "profile.bin",
        "resource_usage.txt",
        "settings.yml",
    }

    output_directories = (cfg["work_dir"], cfg["plot_dir"])
    old_content = [
        p
        for p in output_directories
        if Path(p).exists() and any(Path(p).iterdir())
    ]
    old_content.extend(
        p
        for p in glob.glob(f"{cfg['run_dir']}{os.sep}*")
        if os.path.basename(p) not in default_files
    )

    if old_content:
        if args.force:
            for content in old_content:
                logger.info("Removing %s", content)
                if os.path.isfile(content):
                    os.remove(content)
                else:
                    shutil.rmtree(content)
        elif not args.ignore_existing:
            raise FileExistsError(
                "Script will abort to prevent accidentally overwriting "
                "your data in the following output files or directories:"
                "\n{}\n Use -f or --force to force emptying the output "
                "directories or use -i or --ignore-existing to ignore "
                "existing output directories.".format("\n".join(old_content)),
            )

    # Create output directories
    for output_directory in output_directories:
        if not os.path.isdir(output_directory):
            logger.info("Creating %s", output_directory)
            os.makedirs(output_directory)

    provenance_file = os.path.join(cfg["run_dir"], "diagnostic_provenance.yml")
    if os.path.exists(provenance_file):
        logger.info("Removing %s from previous run.", provenance_file)
        os.remove(provenance_file)

    use_distributed = not (
        args.no_distributed or cfg.get("no_distributed", False)
    )
    if use_distributed and "scheduler_address" in cfg:
        try:
            client = distributed.Client(cfg["scheduler_address"])
        except OSError as exc:
            raise OSError(
                "Unable to connect to the Dask distributed scheduler at "
                f"{cfg['scheduler_address']}. If the scheduler is no longer "
                "available, try re-running the diagnostic script with the "
                "--no-distributed flag.",
            ) from exc
    else:
        client = contextlib.nullcontext()

    with client:
        yield cfg

    logger.info("End of diagnostic script run.")

```

--------------------------------

### esmvaltool.diag_scripts.shared.get_diagnostic_filename

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.shared.html

Get a valid path for saving a diagnostic data file.

```APIDOC
## Function: esmvaltool.diag_scripts.shared.get_diagnostic_filename

### Description
Get a valid path for saving a diagnostic data file.

### Signature
`get_diagnostic_filename(basename, cfg[, ...])`

### Parameters
- **basename** - Base name for the file.
- **cfg** - Configuration dictionary.
- **...** - Additional parameters.
```

--------------------------------

### MonitorBase.get_plot_folder(var_info)

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.monitor/monitor_base.html

Get plot storage folder from variable info.

```APIDOC
## MonitorBase.get_plot_folder(var_info)

### Description
Get plot storage folder from variable info.

### Method
Python method

### Parameters
- **var_info** (dict) - Required - Variable information from ESMValTool

### Returns
Plot storage folder path.
```

--------------------------------

### MonitorBase.get_plot_name(plot_type, var_info, add_ext=True)

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.monitor/monitor_base.html

Get plot filename from variable info.

```APIDOC
## MonitorBase.get_plot_name(plot_type, var_info, add_ext=True)

### Description
Get plot filename from variable info.

### Method
Python method

### Parameters
- **plot_type** (str) - Required - Name of the plot
- **var_info** (dict) - Required - Variable information from ESMValTool
- **add_ext** (bool, optional, default: True) - Add filename extension from configuration file.

### Returns
Plot filename.
```

--------------------------------

### get_constraint_from_df(training_data, ...[, ...])

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.emergent_constraints/init.html

Get constraint on target variable from pandas.DataFrame.

```APIDOC
## get_constraint_from_df(training_data, ...[, ...])

### Description
Get constraint on target variable from pandas.DataFrame.

### Parameters
- **training_data** (pandas.DataFrame) - Required - Training data.
- Additional parameters as needed.

### Returns
- **constraint** (dict) - Constraint information.
```

--------------------------------

### get_constraint(x_data, y_data, obs_mean, obs_std)

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.emergent_constraints/init.html

Get constraint on target variable.

```APIDOC
## get_constraint(x_data, y_data, obs_mean, obs_std)

### Description
Get constraint on target variable.

### Parameters
- **x_data** (array-like) - Required - X data.
- **y_data** (array-like) - Required - Y data.
- **obs_mean** (float) - Required - Observed mean.
- **obs_std** (float) - Required - Observed standard deviation.

### Returns
- **constraint** (dict) - Constraint information.
```

--------------------------------

### main(config)

Source: https://docs.esmvaltool.org/en/latest/api/esmvaltool.diag_scripts.ocean.html

Loads the config file and runs through the order of operations for the diagnostic script.

```APIDOC
## main(config)

### Description
Loads the config file and runs through the order of operations for the diagnostic script.

### Function Signature
`main(config)`

### Parameters
- **config** (dictionary) - Required - Configuration dictionary that contains all the necessary information for the function to run. It includes details about the models, observational datasets, file paths, and other settings.
```