Package: CSIndicators 1.1.2

CSIndicators

Sectoral Indicators for Climate Services Based on Sub-Seasonal to Decadal Climate Predictions

Set of generalised tools for the flexible computation of climate related indicators defined by the user. Each method represents a specific mathematical approach which is combined with the possibility to select an arbitrary time period to define the indicator. This enables a wide range of possibilities to tailor the most suitable indicator for each particular climate service application (agriculture, food security, energy, water management…). This package is intended for sub-seasonal, seasonal and decadal climate predictions, but its methods are also applicable to other time-scales, provided the dimensional structure of the input is maintained. Additionally, the outputs of the functions in this package are compatible with CSTools.

How to cite

Pérez-Zanón, N., Ho, A. Chou, C., Lledó, L., Marcos-Matamoros, R., Rifà, E. and González-Reviriego, N. (2023). CSIndicators: Get tailored climate indicators for applications in your sector. Climate Services. https://doi.org/10.1016/j.cliser.2023.100393

For details in the methodologies see:

Pérez-Zanón, N., Caron, L.-P., Terzago, S., Van Schaeybroeck, B., Lledó, L., Manubens, N., Roulin, E., Alvarez-Castro, M. C., Batté, L., Bretonnière, P.-A., Corti, S., Delgado-Torres, C., Domínguez, M., Fabiano, F., Giuntoli, I., von Hardenberg, J., Sánchez-García, E., Torralba, V., and Verfaillie, D.: Climate Services Toolbox (CSTools) v4.0: from climate forecasts to climate forecast information, Geosci. Model Dev., 15, 6115–6142, https://doi.org/10.5194/gmd-15-6115-2022, 2022.
Chou, C., R. Marcos-Matamoros, L. Palma Garcia, N. Pérez-Zanón, M. Teixeira, S. Silva, N. Fontes, A. Graça, A. Dell'Aquila, S. Calmanti and N. González-Reviriego (2023). Advanced seasonal predictions for vine management based on bioclimatic indicators tailored to the wine sector. Climate Services, 30, 100343, https://doi.org/10.1016/j.cliser.2023.100343.
Lledó, Ll., V. Torralba, A. Soret, J. Ramon and F.J. Doblas-Reyes (2019). Seasonal forecasts of wind power generation. Renewable Energy, 143, 91-100, https://doi.org/10.1016/j.renene.2019.04.135.

Installation

You can then install the public released version of CSIndicators from CRAN:

install.packages("CSIndicators")

Or the development version from the GitLab repository:

# install.packages("devtools")
devtools::install_git("https://earth.bsc.es/gitlab/es/csindicators.git")

Overview

To learn how to use the package see:

• Agricultural Indicators
• Wind Energy Indicators

Functions documentation can be found here.

Function	CST version	Indicators
PeriodMean	CST_PeriodMean	GST, SprTX, DTR, BIO1, BIO2
PeriodMax	CST_PeriodMax	BIO5, BIO13
PeriodMin	PeriodMin	BIO6, BIO14
PeriodVariance	CST_PeriodVariance	BIO4, BIO15
PeriodAccumulation	CST_PeriodAccumulation	SprR, HarR, PRCPTOT, BIO16, ...
PeriodPET	CST_PeriodPET	PET, SPEI
PeriodStandardization	CST_PeriodStandardization	SPEI, SPI
AccumulationExceedingThreshold	CST_AccumulationExceedingThreshold	GDD, R95pTOT, R99pTOT
TotalTimeExceedingThreshold	CST_TotalTimeExceedingThreshold	SU35, SU, FD, ID, TR, R10mm, Rnmm
TotalSpellTimeExceedingThreshold	CST_TotalSpellTimeExceedingThreshold	WSDI, CSDI
WindCapacityFactor	CST_WindCapacityFactor	Wind Capacity Factor
WindPowerDensity	CST_WindPowerDensity	Wind Power Density

Auxiliar function	CST version
AbsToProbs	CST_AbsToProbs
QThreshold	CST_QThreshold
Threshold	CST_Threshold
MergeRefToExp	CST_MergeRefToExp
SelectPeriodOnData	CST_SelectPeriodOnData
SelectPeriodOnDates

Find the current status of each function in this link.

Note I: the CST version uses 's2dv_cube' objects as inputs and outputs while the former version uses multidimensional arrays with named dimensions as inputs and outputs.

Note II: All functions computing indicators allows to subset a time period if required, although this temporal subsetting can also be done with functions SelectPeriodOnData in a separated step.

Object class s2dv_cube

This package is designed to be compatible with other R packages such as CSTools through a common object: the s2dv_cube, used in functions with the prefix CST.

An s2dv_cube is an object to store ordered multidimensional array with named dimensions, specific coordinates and stored metadata. As an example, this is how it looks like (see CSTools::lonlat_temp_st$exp):

's2dv_cube'
Data          [ 279.99, 280.34, 279.45, 281.99, 280.92,  ... ] 
Dimensions    ( dataset = 1, var = 1, member = 15, sdate = 6, ftime = 3, lat = 22, lon = 53 ) 
Coordinates  
 * dataset : dat1 
 * var : tas 
   member : 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 
 * sdate : 20001101, 20011101, 20021101, 20031101, 20041101, 20051101 
   ftime : 1, 2, 3 
 * lat : 48, 47, 46, 45, 44, 43, 42, 41, 40, 39, 38, 37, 36, 35, 34, ...
 * lon : 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, ...
Attributes   
   Dates  : 2000-11-01 2001-11-01 2002-11-01 2003-11-01 2004-11-01 ... 
   varName  : tas 
   metadata :  
      lat 
        units : degrees_north 
        long name : latitude 
      lon 
        units : degrees_east 
        long name : longitude 
      ftime 
        units : hours since 2000-11-01 00:00:00 
      tas 
        units : K 
        long name : 2 metre temperature 
   Datasets  : dat1 
   when  : 2023-10-02 10:11:06 
   source_files  : "/ecmwf/system5c3s/monthly_mean/tas_f6h/tas_20001101.nc" ... 
   load_parameters  : 
       ( dat1 )  : dataset = dat1, var = tas, sdate = 20001101 ... 

Note: The current s2dv_cube object (CSIndicators > 0.0.2 and CSTools > 4.1.1) differs from the original object used in the previous versions of the packages. More information about the s2dv_cube object class can be found here: description of the s2dv_cube object structure document.

Contribute

1. Open an issue to ask for help or describe a function to be integrated
2. Agree with maintainers (@ngonzal2, @rmarcos, @nperez and @erifarov) on the requirements
3. Create a new branch from master with a meaningful name
4. Once the development is finished, open a merge request to merge the branch on master

Note: Remember to work with multidimensionals arrays with named dimensions when possible and use multiApply.

Add a function

To add a new function in this R package, follow this considerations:

1. Each function exposed to the users should be in separate files in the R folder
2. The name of the function should match the name of the file (e.g.: Function() included in file Function.R)
3. The documentation should be in roxygen2 format as a header of the function
4. Once, the function and the documentation is finished, run the command devtools::document() in your R terminal to automatically generate the Function.Rd file
5. Remember to use R 4.1.2 when doing the development
6. Code format: include spaces between operators (e.g. +, -, &), before and after ','. The maximum length of lines is of 100 characters (hard limit 80 characters). Number of indentation spaces is 2.
7. Functions computing Climate indicators should include a temporal subsetting option. Use the already existing functions to adapt your code.