FeedbackTS (version 1.5)

feedback.stats: Computation of feedback and change-in-feedback statistics

Description

Computation of temporal averages of after-before differences around key days calculated from a time series and computation of the difference in the temporal averages around a turning point in time.

Usage

feedback.stats(object, operator, turning.year = NULL,
    trend.correction = list( apply = FALSE , object2 = NULL ))

Arguments

object

either a KDD object or a KDD.yearly.average object.

operator

a character string specifying the transformation of the raw values, must be one of "dmv", "dmpiv" or "dmgiv".

turning.year

an optional numeric vector of years used to specify turning points in the data series.

trend.correction

an optional list of two items: the apply item, which is a logical indicating whether the trend correction should be applied or not (default to FALSE); the object2 item, which is a KDD object typically built like object except that the keyday threshold is fixed at zero (see example section below).

Value

If turning.year = NULL, a numeric equal to the temporal average of after-before differences around key days calculated from the whole time series.

If turning.year is a numeric vector, a numeric vector providing:

--

the temporal average of after-before differences around key days calculated from the whole time series;

--

for each value \(t\) in turning.year,

--

the temporal average \(\bar D_{<t}\) of after-before differences around key days calculated from the time series right-truncated at time \(t\);

--

the temporal average \(\bar D_{\ge t}\) of after-before differences around key days calculated from the time series left-truncated at time \(t\);

--

the difference \(\bar D_{\ge t}-\bar D_{<t}\).

Details

The function computes the following temporal averages of after-before differences around key days calculated from a time series: $$\bar D(I)=\frac{1}{n(I)}\sum_{i\in I} D_i$$ where \(I\) is a set of key days, \(n(I)\) is the number of key days in \(I\), and \(D_i\) is an after-before difference computed for each key day \(i\) (see below and in after.minus.before function).

If operator = "dmv" (difference of mean values), the raw values \(y_{i-K},\ldots,y_{i+K}\) of the time series are used to compute the difference: $$ D_i=\left(\frac{1}{K}\sum_{k=1}^K y_{i+k}\right) - \left(\frac{1}{K}\sum_{k=1}^K y_{i-k}\right)=\frac{1}{K}\sum_{k=1}^K (y_{i+k}-y_{i-k}), $$ where \(i\) is the date of the key day, \(K\) is the number of days considered around the key day (specified when data is provided).

If operator = "dmpiv" (difference of means of positive indicator values), the raw values \(y_{i-K},\ldots,y_{i+K}\) are used to compute the difference: $$ D_i=\left(\frac{1}{K}\sum_{k=1}^K 1(y_{i+k}>0)\right) - \left(\frac{1}{K}\sum_{k=1}^K 1(y_{i-k}>0)\right)=\frac{1}{K}\sum_{k=1}^K \{1(y_{i+k}>0)-1(y_{i-k}>0)\}, $$ where \(1(\cdot)\) is the indicator function.

If operator = "dmgiv" (difference of means of greater indicator values), the raw values \(y_{i-K},\ldots,y_{i+K}\) are used to compute the difference: $$ D_i=\left(\frac{1}{K}\sum_{k=1}^K 1(y_{i+k}>y_{i-k})\right) - \left(\frac{1}{K}\sum_{k=1}^K 1(y_{i-k}>y_{i+k})\right). $$

If turning.year = NULL, the function computes \(\bar D(I)\) where \(I\) is the set of all key days in the whole time series.

If turning.year is a numeric vector, for each value \(t\) in turning.year the function computes \(\bar D(I)\) with \(I\) equal to the set of key days in the whole time series, in the time series before \(t\) and in the time series after \(t\). The function also computes, for each value \(t\), the difference between the temporal averages of after-before differences after \(t\) and before \(t\).

If trend.correction$apply = TRUE, a trend correction is applied to take into account, for example, seasonal effect in the time series (see Morris et al., 2016).

References

Morris, C.E., Soubeyrand, S.; Bigg, E.K., Creamean, J.M., Sands, D.C. (2016). Rainfall feedback maps: a tool to depict the geography of precipitation's sensitivity to aerosols. INRA Research Report.

Soubeyrand, S., Morris, C. E. and Bigg, E. K. (2014). Analysis of fragmented time directionality in time series to elucidate feedbacks in climate data. Environmental Modelling and Software 61: 78-86.

See Also

KDD, KDD.yearly.average, kdd.from.raw.data, after.minus.before, rain.site.6008, rain.feedback.stats

Examples

# NOT RUN {
#### load data for site 6008 (Callagiddy station)
data(rain.site.6008)

#### build KDD objects from raw data (site 6008: Callagiddy station)
## using a threshold value equal to 25
KDD=kdd.from.raw.data(raw.data=rain.site.6008, keyday.threshold=25, nb.days=20,
   col.series=5, col.date=c(2,3,4), na.rm=TRUE, filter=NULL)
	
#### main feedback statistic
feedback.stats(KDD, "dmv")

#### main and auxiliary feedback statistics
feedback.stats(KDD, "dmv", turning.year=c(1960,1980))

#### apply a trend correction
## define the KDD object used for trend correction (it is defined as
## KDD above except that the threshold value is equal to 0)
KDD2=kdd.from.raw.data(raw.data=rain.site.6008, keyday.threshold=0, nb.days=20,
   col.series=5, col.date=c(2,3,4), na.rm=TRUE, filter=NULL)
## compute the statistic
feedback.stats(KDD, "dmv", trend.correction=list(apply=TRUE, object2=KDD2))
# }