New indicator SPEI

Hi @allabres, @bsolaraj and @nperez,

I open this issue to keep track of the development for the new SPEI indicator. Feel free to edit it if you find some errors in the description or missunderstood things :).

SPEI

The Standardised Precipitation-Evapotranspiration Index (SPEI) is a multiscalar drought index based on climatic data. It can be used for determining the onset, duration and magnitude of drought conditions with respect to normal conditions in a variety of natural and managed systems such as crops, ecosystems, rivers, water resources, etc. The SPI is calculated using monthly (or weekly) precipitation as the input data. The SPEI uses the monthly (or weekly) difference between precipitation and PET. This represents a simple climatic water balance which is calculated at different time scales to obtain the SPEI (https://spei.csic.es/home.html).

Initial code

The code to compute SPEI indicator is created by @bsolaraj. Also, it has been developed with multiple variables (tasmin, tasmax and precip) within the Verification Suite by @allabres.

Functions development

The new function PeriodSPEI will be a wrapper of smaller functions for each step to compute the SPEI indicator. The input arguments will be similar to the other functions of CSIndicators: a multidimensional array with the data and the corresponding Dates array and the same common parameters. Similarly, there will be a three-level function structure: CST_PeriodSPEI (wrapper of PeriodSPEI to work with s2dv_cube), PeriodSPEI (main function) and atomic functions built for being used with multiApply.

Main functions:

• CST_PeriodSPEI: The inputs and outputs of this fuctions are 's2dv_cubes' objects. It calls PeriodSPEI.
• PeriodSPEI: It works with multidimensional arrays and calls all the other internal functions.

Internal functions:

• (CST_)PeriodPET: (before called evapotranspiration). This internal function calls atomic function .evapotranspiration (before called atomic_pet).
  • .pet: Atomic function that computed the pet for the specified pet_method: hargreaves, hargreaves_modified or thornthwaite.
• (CST_)PeriodAccumulation: (before called accumulation). This internal function calls atomic function .accumulation (before called atomic_accum).
  • .rollaccumulation: Atomic function that computes the accumulation of the previous months inidcated with number parameter accum.
• (CST_)PeriodStandardization: (before called spei_standardization). This internal function calls atomic function .standardization (before called atomic_spei).
  • .standardization: Atomic function that computes the standarization. Before internally was calling spX, but now, I have included spX code directly in .standardization in order that there are less nested functions. Now, the function .standardization calls directly .std (before called spX_ftime)
    • .std: Internal function of the atomic function that computes the standardisation (with or without parameters) for every leadtime step.

Other

• Problem with infinite values: if alpha or eta are greater, it returns an infinity. Proposed and developed solution: take the max x value for distr. Add a parameter (inf.rm?) default FALSE: you get infinity. if it is TRUE, remove (to see where is the infinity). The basic code is already built.
• Vignette: Creation of a use case with the example of seasonal, and another for the decadal. Also, an example can be shown for the accumulation, and without it.

Parameters of PeriodSPEI:

• data: A multidimensional array with named dimensions. The input data is monthly data. Units need to be specified in the parameters description.
• dates: A multidimensional array with named dimensions for Dates corresponding to Data array.
• start and end: An optional parameter to defined the final date of the period to select from the data by providing a list of two elements: the final day of the period and the final month of the period. Needed to specify the period of the year. If they are NULL we need length of the period parameter for the accumulation. They can overrule Time accumulation months parameter.
• time accumulation months (length of the period): Specify the months for accumulation. Maybe there are needed values outside the output time steps.
• method: Standarization method distribution
• inf.rm: Whether to remove infinite values or use the maximum value.

Other parameters:

• time_dim
• memb_dim
• dat_dim ?
• na.rm
• ncores

Things to do:

• Provide an example with the code and the atomic function (@bsolaraj, @allabres)
• Develop the function within the package (@erifarov)
  • Add common parameters of the package
  • Add initial checks
  • Develop the functions
  • Write documentation
  • Create unit test
• Review development:
  • Test the functions (also with real data)

Thanks,
Eva