diagnostic_list.rst

Diagnostic list
===============

In this section you have a list of the available diagnostics, with a small description of each one and a link to
the full documentation. To see what options are available for each diagnostic, see generate_jobs documentation.

Remember that diagnostics are specified separated by spaces while options are given separated by commas:

.. code-block:: ini

    DIAGS = diag1 diag2,option1,option2 diag3


General
-------

The diagnostics from this section are of general use and can be used with any variable you may have. Most of them are
meant to help you to solve usual issues that you may have with the data: incorrect metadata, scaled up or down variables,
links missing. This section also contains the diagnostic used to calculate the monthly means.

att
~~~~

Writes a global attributte to all the netCDF files for a given variable.
See :class:`~earthdiagnostics.general.attribute.Attribute`

Options:
********

1. Variable:
    Variable name

2. Domain:
    Variable domain

3. Attributte name:
    Attributte to write

4. Attribute value:
    Atrribute's new value. Replace ',' with '&;' and  ' ' with '&.' to avoid parsing errors when processing the diags

5. Grid = '':
    Variable grid. Only required in case that you want to use interpolated data.

monmean
~~~~~~~
Calculates the monthly mean for a given variable. See :class:`~earthdiagnostics.general.monthlymean.MonthlyMean`

.. warning::

    This diagnostic does not use the frequency configuration from the config file. You must specify the original
    frequency when calling it. Otherwise, it will always try to use daily data.

Options:
********

1. Variable:
    Variable name

2. Domain:
    Variable domain

3. Original frequency = daily:
    Original frequency to use

4. Grid = '':
    Variable grid. Only required in case that you want to use interpolated data.

relink
~~~~~~

Regenerates the links created in the monthly_mean, daily_mean, etc folders for a given varible.
See :class:`~earthdiagnostics.general.relink.Relink`

Options:
********

1. Variable:
    Variable name

2. Domain:
    Variable domain

3. Move old =
    True: If True, any data founded in the target directory will be moved to another folder
    (called FOLDER_NAME_old) instead of deleted.

4. Grid = '':
    Variable grid. Only required in case that you want to use interpolated data.


relinkall
~~~~~~~~~

Regenerates the links created in the monthly_mean, daily_mean, etc folders for all variables
See :class:`~earthdiagnostics.general.relinkall.RelinkAll`

Options:
********

This diagnostic has no options

rewrite:
~~~~~~~~

Just rewrites the CMOR output of a given variable. Useful to correct metadata or variable units.
See :class:`~earthdiagnostics.general.rewrite.Rewrite`

Options:
********

1. Variable:
    Variable name

2. Domain:
    Variable domain

3. Grid = '':
    Variable grid. Only required in case that you want to use interpolated data.


scale
~~~~~

Scales a given variable using a given scale factor and offset (NEW_VALUE = OLD_VALUE * scale + offset). Useful to
correct errors on the data.
    See :class:`~earthdiagnostics.general.scale.Scale`

Options:
********

1. Variable:
    Variable name

2. Domain:
    Variable domain

3. Scale value:
    Scale factor for the variable

4. Offset value:
    Value to add to the original value after scaling

5. Grid = '':
    Variable grid. Only required in case that you want to use interpolated data.

6. Min limit = NaN:
    Values below this will not be changed

7. Max limit = NaN:
    Values over this will not be changed

Ocean
-----

The diagnostics from this section are meant to be used with NEMO variables. Some of them will compute new variables
while others just calculate means or sections for variables in the ORCA grid. The interpolation diagnostics are also
included here as they are usually used with variables in the ORCA grid.

areamoc
~~~~~~~

Compute an Atlantic MOC index by averaging the meridional overturning
in a latitude band between 1km and 2km or any other index averaging the meridional overturning in
a given basin and a given domain. See :class:`~earthdiagnostics.ocean.areamoc.AreaMoc`

.. warning::
    The MOC for the given basin must be calculated previously. Usually, it will suffice to call the 'moc' diagnostic
    earlier in the DIAGS list.

Options:
********

1. Min latitude:
    Minimum latitude to compute

2. Max latitude:
    Maximum latitude to compute

3. Min depth:
    Minimum depth (in levels)

4. Max depth:
    Maximum depth (in levels)

5. Basin = 'Global':
    Basin to calculate the diagnostic on.


averagesection
~~~~~~~~~~~~~~

Compute an average of a given zone. The variable MUST be in a regular grid
See :class:`~earthdiagnostics.ocean.averagesection.AverageSection`

Options:
********

1. Variable:
    Variable to average

2. Min longitude:
    Minimum longitude to compute

3. Max longitude:
    Maximum longitude to compute

4. Min latitude:
    Minimum latitude to compute

5. Max latitude:
    Maximum latitude to compute

6. Domain = ocean:
    Variable domain

convectionsites
~~~~~~~~~~~~~~~

Compute the intensity of convection in the four main convection sites.
See :class:`~earthdiagnostics.ocean.convectionsites.ConvectionSites`

Options:
********

This diagnostic has no options

cutsection
~~~~~~~~~~

Cuts a meridional or zonal section. See :class:`~earthdiagnostics.ocean.cutsection.CutSection`

Options:
********

1. Variable:
    Variable to cut the section on

2. Zonal:
    If True, calculates a zonal section. If False, it will be a meridional one

3. Value:
    Reference value for the section

4. Domain = ocean:
    Variable's domain


gyres
~~~~~

Compute the intensity of the subtropical and subpolar gyres. See :class:`~earthdiagnostics.ocean.gyres.Gyres`

Options:
********

This diagnostic has no options

heatcontent
~~~~~~~~~~~

Compute the total and mean ocean heat content. See :class:`~earthdiagnostics.ocean.heatcontent.HeatContent`

Options:
********

1. Basin
    Basin to calculate the heat content one

2. Mixed layer:
    If 1, reduces the compuation to the mixed layer. If -1, excludes the mixed layer from the computations.
    If 0, no effect.

3. Min depth:
    Minimum depth for the calculation in levels. If 0, whole depth is used

4. Max depth:
    Maximum depth for the calculation in levels

heatcontentlayer
~~~~~~~~~~~~~~~~

Point-wise Ocean Heat Content in a specified ocean thickness.
See :class:`~earthdiagnostics.ocean.heatcontentlayer.HeatContentLayer`

Options:
********

3. Min depth:
    Minimum depth for the calculation in meteres

4. Max depth:
    Maximum depth for the calculation in meters

5. Basin = 'Global':
    Basin to calculate the heat content on.

        options_available = (DiagnosticIntOption('min_depth'),
                             DiagnosticIntOption('max_depth'),
                             DiagnosticBasinOption('basin', Basins.Global))

interpolate
~~~~~~~~~~~

3-dimensional conservative interpolation to the regular atmospheric grid.
It can also be used for 2D (i,j) variables. See :class:`~earthdiagnostics.ocean.interpolate.Interpolate`

.. warning::
    This interpolation requires the pre-generated weights that can be found in '/esnas/autosubmit/con_files/weights'.
    Make sure that they are available for your configuration.

Options:
********

1. Target grid:
    New grid for the data

2. Variable:
    Variable to interpolate

3. Domain = ocean:
    Variable's domain

4. Invert latitude:
    If True, inverts the latitude in the output file.

interpolateCDO
~~~~~~~~~~~~~~

Bilinear interpolation to a given grid using CDO. See :class:`~earthdiagnostics.ocean.interpolatecdo.InterpolateCDO`

.. warning::
    This interpolation is non-conservative, so treat its output with care. It has the advantage that does not require the
    pre-generated weights so it can be used when the 'interp' diagnostic is not available.

Options:
********

1. Variable:
    variable to interpolate

2. Target grid:
    Variable domain

3. Domain = ocean:
    Variable's domain

4. Mask oceans = True:
    If True, replaces the values in the ocean by NaN. You must only set it to false if, for some reason, you are
    interpolating an atmospheric or land variable that is stored in the NEMO grid (yes, this can happen, i.e. with tas).


maxmoc
~~~~~~

Compute an Atlantic MOC index by finding the maximum of the annual mean meridional overturning in a
latitude / depth region. Output from this diagnostic will be always in yearly frequency.
See :class:`~earthdiagnostics.ocean.maxmoc.MaxMoc`

.. warning::
    The MOC for the given basin must be calculated previously. Usually, it will suffice to call the 'moc' diagnostic
    earlier in the DIAGS list.

.. warning::
    This diagnostic can only be computed for full years. It will discard incomplete years and only compute the index in
    those with the full 12 months available.

Options:
********

1. Min latitude:
    Minimum latitude to compute

2. Max latitude:
    Maximum latitude to compute

3. Min depth:
    Minimum depth (in levels)

4. Max depth:
    Maximum depth (in levels)

5. Basin = 'Global':
    Basin to calculate the diagnostic on.

mixedlayerheatcontent
~~~~~~~~~~~~~~~~~~~~~

Compute mixed layer heat content.
See :class:`~earthdiagnostics.ocean.mixedlayerheatcontent.MixedLayerHeatContent`

Options:
********

This diagnostic has no options

mixedlayersaltcontent
~~~~~~~~~~~~~~~~~~~~~

Compute mixed layer salt content. See :class:`~earthdiagnostics.ocean.mixedlayersaltcontent.MixedLayerSaltContent`

Options:
********

This diagnostic has no options

moc
~~~~

Compute the MOC for oceanic basins. Required for 'areamoc' and 'maxmoc' See :class:`~earthdiagnostics.ocean.moc.Moc`

Options:
********

This diagnostic has no options

psi
~~~~

Compute the barotropic stream function. See :class:`~earthdiagnostics.ocean.psi.Psi`

Options:
********

This diagnostic has no options

regionmean
~~~~~~~~~~

Compute an average of a given zone using cdfmean from CDFTOOLS
See :class:`~earthdiagnostics.ocean.regionmean.RegionMean`

Options:
********

1. Domain:
    Variable domain

2. Variable:
    Variable to average

3. Grid:
    Minimum longitude to compute

4. Save 3d = False:
    If True, it also stores the average per level

5. Min depth:
    Minimum depth to compute in levels. If -1, average from the surface

6. Max depth:
    Maximum depth to compute in levels. If -1, average to the bottom

7. Basin = Global:
    Basin to compute

        options_available = (DiagnosticDomainOption('domain'),
                             DiagnosticOption('variable'),
                             DiagnosticOption('grid'),
                             DiagnosticBoolOption('save3D', False),
                             DiagnosticIntOption('min_depth', -1),
                             DiagnosticIntOption('max_depth', -1),
                             DiagnosticBasinOption('basin', Basins.Global))

siasiesiv
~~~~~~~~~

Compute the sea ice extent , area and volume  in both hemispheres or a specified region.
See :class:`~earthdiagnostics.ocean.siasiesiv.Siasiesiv`

Options:
********

1. Basin = 'Global':
    Basin to restrict the computation to.

verticalmean
~~~~~~~~~~~~

Chooses vertical level in ocean, or vertically averages between 2 or more  ocean levels.
See :class:`~earthdiagnostics.ocean.verticalmean.VerticalMean`

Options:
********

1. Variable:
    Variable to average

2. Min depth = -1:
    Minimum level to compute. If -1, average from the surface

3. Max depth:
    Maximum level to compute. If -1, average to the bottom


verticalmeanmeters
~~~~~~~~~~~~~~~~~~

Averages vertically any given variable.
See :class:`~earthdiagnostics.ocean.verticalmeanmeters.VerticalMeanMeters`

Options:
********

1. Variable:
    Variable to average

2. Min depth = -1:
    Minimum depth to compute in meters. If -1, average from the surface

3. Max depth:
    Maximum depth to compute in meters. If -1, average to the bottom


Statistics
----------

climpercent
~~~~~~~~~~~

Calculates the specified climatological percentile of a given variable.
See :class:`~earthdiagnostics.statistics.climatologicalpercentile.ClimatologicalPercentile`

Options:
********

1. Domain:
    Variable's domain

2. Variable:
    Variable to compute diagnostic on

3. Leadtimes:
    Leadtimes to compute

4. Bins:
    Number of bins to use to discretize the variable

monpercent
~~~~~~~~~~

Calculates the specified monthly percentile of a given variable.
See :class:`~earthdiagnostics.statistics.monthlypercentile.MonthlyPercentile`

Options:
********

1. Domain:
    Variable's domain

2. Variable:
    Variable to compute diagnostic on

3. Percentiles:
    List of requested percentiles ('-' separated)