Welcome to ClimDexCalc2’s documentation!#

The ClimDexCalc2 Plugin#

authors:

Lukas Hüneke [1], Andy Richling, Igor Kröner, Jens Grieger, Christopher Kadow
Institut für Meteorologie, Freie Universität Berlin
Version from 2024.07.11

This plugin uses the Climpact software provided by the World Meteorological Organizations’s Expert Team on Sector-Specific Climate Indices (ET-SCI) to calculate a set of climate indices recommended by the ET-SCI. This set is an extension of the indices developed by the joint CCl/WCRP/JCOMM Expert Team on Climate Change Detection and Indices (ETCCDI), adding indices relevant to the health, agriculture, food security, water resources and hydrology sectors. The indices are calculated from daily temperature and precipitation data and optionally linked to Freva for additional calculations. The output has monthly and/or annual temporal resolution, depending on the chosen indices. The plugin can be used for observations, reanalyses, historical and future simulations.

Note

The plugin replaces the former ClimDexCalc with an extended number of climate indices.

As of 2024-07-11 it has changed its name from Climpact-SCI to ClimDexCalc2.

Usage#

A lot of the climate indices Climpact can calculate utilize percentile based thresholds with respect to some base period. In this case the plugin offers two workflows:

  1. The percentiles are calculated during index calculation. In this case the base period has to lie within the time period over which the indices are calculated. The percentiles are not written out.

  2. In a first run of the plugin, only the percentiles are calculated and written out. In a second run, the indices are calculated, using the percentiles from the first run. In this case, the indices can only be calculated over a time period lying outside of the base period. For the calculation of the percentiles, all three input variables (tasmax, tasmin and pr) need to be available.

Data Requirements#

  • Input Variables: Tasmax, tasmin and pr are needed, depending on the chosen indices.

  • Time Resolution: A daily time resolution is expected.

  • Grid: The underlying climdex.pcic only works with regular grids, with no bounds attributes in latitude or longitude variables.

  • Completeness of time series: If one of indices to be calculated requires multiple input variables (or if percentiles are calculated), the input data for these variables must have the same length and number of time steps.

Warning

Depending on the gridtype of the data and chosen percentile_method there might be an automatic bilinear or conservative remapping into regular lonlat grid using cdo, previous to the indices calculation:

gridtype

variable

mapping

gaussian

no

curvilinear

tas, tasmax, tasmin
pr
remapbil
remapcon

However, there is an option to apply your own remapping (overriding the one by default), with the cdo_preproc parameter. This can be useful if you want to map the data to your percentile data.

Configuration#

First, the input data must be selected from the data-browser via the fields project, product, institute, model, experiment, ensemble, and cmor_table.

The data-browser or the dryrun option should be used to check that the variables tasmin, tasmax and/or pr (depending on the desired indices) are available for the chosen input data in daily resolution for the entire time of interest.

In the indices field, a comma separated list of the climate indices, that should be calculated, can be supplied. See the Climpact website for a detailed description of the available indices. Alternatively, the field can be left empty to calculate all available indices. Be aware, that this will take a long time for larger datasets. Finally, writing “percentiles” will cause the plugin to calculate a percentile file instead of climate indices. All three input variables need to be available for this option, as percentiles for all indices will be calculated.

The percentilefile field can be used to point to point to such a file, in order to use it for index calculation in subsequent runs.

Next, the timeperiod of interest has to be given in a comma-separated format: firstyear,lastyear. If a percentile file was given in the previous field, the time period has to lie outside of the base period of the percentile file.

The parameter baseperiod defines the reference period for percentile-based climate indices, if no percentile file is used. In this case, the base period has to be contained within the time period. The format is same as for the time period.

In time_frequency_output the temporal aggregation level of the resulting output can be chosen. Some indices are only available for either “annual” or “monthly” aggregation level.

wsdin_n, csdin_n, hddheatn_n, cddcoldn_n, gddgrown_n, rxnday_n, rnnmm_n, ntxntn_n and ntxbntnb_n can be used to specify custom parameters for the indices wddid, csdid, hddheatn, cddcoldn, gddgrown, rxdday, rnnmm, txdtnd and txbdtnbd. See the Climpact website for details.

In ehf_def the definition of the excess heat factor (ehf) can be changed. It is used for the calculation of the index hw. Use PA13 to follow the definition of Perkins and Alexander [2], or NF13 to follow Nairn and Fawcett [3] instead. More details can be found in the Climpact user guide.

Futhermore, the number of parallel-processing tasks (ntask), the output (outputdir) and cache (cachedir) directories have to be specified.

If dryrun is set to true, the plugin will print out the input data files it could find for the given input parameters and exit without calculating anything.

Finally, options to keep the cache (cacheclear) and to add the resulting data to the data-browser (link2database) may be used. Keep in mind that the cache can be very large, as it contains a copy of the input data.

Output#

The resulting files contain the selected climate indices – one individual file for each index. The files follow the CMOR structure of the system with the index name as the name of the variable.

Missing Values#

Climpact permits a maximum of 3 missing days in any month, and a maximum of 15 missing days in any year. If any of these thresholds is exceeded, the month or year in question is not calculated. Further, if a month is missing then the corresponding year is also removed. Lastly, at least 10% of the base period must have valid values in order for percentile-based indices to be calculated.

Installation#

To install the conda environment with the necessary libraries to run the plugin:

  1. you need to have conda already avaible, for example by loading a Freva module:

$ module load clint xces # or any other Freva instance
  1. then git clone and create the conda environment:

$ git clone https://gitlab.dkrz.de/bm1159/plugins4freva/climdexcalc2.git
$ cd climdexcalc2
$ make all
  1. to activate the environment (including climpact library and R compiler):

$ source $(pwd)/plugin_env/bin/activate
  1. to deactivate it, run:

$ conda deactivate

Updating the Plugin with git:#

  1. cd <PATH2PLUGIN>

  2. git checkout -b <new_branch> (commit changes in a new branch <new_branch>)

  3. git push --set-upstream origin <new_branch> (push changes upstream to <new_branch>)

  4. pull/merge request into main/master branch (at e.g. gitlab), wait for reviews, merge

Contact & References#