Package 'FeedbackTS'

Analysis of Feedback in Time Series

Description

Analysis of fragmented time directionality to investigate feedbacks in time series. Tools provided by the package allow the analysis of feedback for a single time series and the analysis of feedback for a set of time series collected across a spatial domain.

Details

Package:	FeedbackTS
Type:	Package
Version:	1.5
Date:	2020-01-22
License:	GPL (>=2.0)
Depends:	methods, maps, mapdata, proj4, sp, gstat, automap, date

To analyze feedback in a single time series create a KDD object (Key Day Dataset) with the construction function kdd.from.raw.data and test fragmented time directionality with the function feedback.test.

To analyze the spatial pattern of feedback from a set of time series collected across a spatial domain, create indices of feedback with the function feedback.stats, map the index with map.statistic, krige the index with krige and test spatial variation in feedback with krige.test.

Author(s)

Samuel Soubeyrand, Cindy E. Morris, E. Keith Bigg

Maintainer: Samuel Soubeyrand [email protected]

References

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.

Examples

#### load library
## Not run: library(FeedbackTS)

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

#### load data of feedback and change-in-feedback indices in 88 sites across Australia
data(rain.feedback.stats)

#### spatial coordinates of the 88 sites
coord=rain.feedback.stats[,3:4]


########  ANALYSIS OF FEEDBACK WITH A SINGLE TIME SERIES

#### 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)

#### test feedback and change in feedback with a single data series
## using the thresholded data series
## using difference of means of positive indicator values (i.e. rainfall occurrence)
## computer intensive stage
## Not run: 
par(mfrow=c(1,2), mar=c(5.1,4.1,4.1,2.1))
feedback.test(object=KDD, test="feedback", operator="dmpiv", nb.rand=10^3, plots=TRUE)
## End(Not run)

########  ANALYSIS OF FEEDBACK WITH A SET OF TIME SERIES COLLECTED ACROSS SPACE

#### map of feedback index computed from the whole data series
par(mfrow=c(1,1), mar=c(0,0,0,0))
stat1=rain.feedback.stats[["Feedback.whole.period"]]
map.statistic(coord,stat1,cex.circles=c(3,0.2),
   region=list(border="Australia",xlim=c(110,155)),
   legend=list(x=c(rep(114,3),rep(123,2)),y=-c(37,39.5,42,37,39.5),
      xtext=c(rep(114,3),rep(123,2))+1,ytext=-c(37,39.5,42,37,39.5),digits=2),
  main="Feedback")

#### variogram analysis and kriging of feedback index
## computer intensive stage
## Not run: 
par(mfrow=c(2,2), mar=c(5.1,4.1,4.1,2.1))
kr1=krige(coordinates=coord, statistic=stat1,
   grid=list(x=seq(110,155,0.25),y=seq(-45,-11,0.25),border="Australia", 
      proj="+proj=lcc +lat_1=-18 +lat_2=-36 +lat0=-25 +lon_0=140",degrees=TRUE),
   plots=TRUE)

## End(Not run)

#### test spatial variation in feedback index and plot test output
## computer intensive stage
## Not run: 
kt1=krige.test(krige.output=kr1,subregion=list(x=c(138,152,152,138),y=-c(40,40,33,33)),
  alternative="greater", nb.rand=2000)
par(mfrow=c(1,2), mar=c(5.1,4.1,4.1,2.1))	
plot(kt1,digits=list(predict=3,pvalue=3),breaks=12)

## End(Not run)

---

Computation of after-before differences around key days

Description

Computation of after-before differences around key days using using data $K$ days before and after each key day.

Usage

after.minus.before(data, operator)

Arguments

data	either a KDD object, a KDD.yearly.average object, or a matrix with an odd number of rows corresponding built as the before.after slot of 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".

Details

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 after and before 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).$

Value

A numeric vector providing for each key day the value of the after-before difference.

Author(s)

Samuel Soubeyrand [email protected], Cindy E. Morris, E. Keith Bigg.

References

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, rain.site.6008

Examples

#### 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)

#### compute and plot after-before differences of KDD 
par(mfrow=c(2,2), mar=c(5.1,4.1,4.1,4.1))

## using option dmpiv (difference of means of positive indicator values)
amb1=after.minus.before(KDD,"dmpiv")
plot(KDD["day"],amb1,type="l",xlab="Day",ylab="After-Before")
abline(h=0,lty="dashed",col="grey")
plot(KDD["day"],cumsum(amb1),type="l",xlab="Day",ylab="Cumul After-Before")
abline(h=0,lty="dashed",col="grey")

## using option dmv (difference of means of values)
amb2=after.minus.before(KDD,"dmv")
plot(KDD["day"],amb2,type="l",xlab="Day",ylab="After-Before")
abline(h=0,lty="dashed",col="grey")
plot(KDD["day"],cumsum(amb2),type="l",xlab="Day",ylab="Cumul After-Before")
abline(h=0,lty="dashed",col="grey")

---

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).

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).

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}$.

Author(s)

Samuel Soubeyrand [email protected], Cindy E. Morris, E. Keith Bigg.

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

#### 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))

---

Test of feedback and change-in-feedback for a single time series

Description

Randomization test to investigate the fragmented time directionality in a single time series and the temporal variation in the fragmented time directionality.

Usage

feedback.test(object, test, operator, nb.rand, plots = TRUE, turning.year = NULL)

Arguments

object	either a KDD object or a KDD.yearly.average object.
test	a character string specifying the type of test, must be one of "feedback" or "change.in.feedback".
operator	a character string specifying the transformation of the raw values, must be one of "dmv" or "dmpiv" (see section Details in after.minus.before).
nb.rand	a positive integer specifying the number of randomizations.
plots	a logical indicating if plots characterizing the test are produced (if plots = TRUE) or not (if plots = FALSE), default is TRUE.
turning.year	an optional numeric value specifying a temporal turning point in the data series, must be provided if operator = "change.in.feedback".

Details

If plots = TRUE, two plots are produced. The first plot gives the cumulative after-before difference (CABD; red curve) and for each CABD value the quantiles of order 0.025 (bottom dotted curve), 0.25 (bottom dashed curve), 0.5 (solid black curve), 0.75 (top dashed curve) and 0.975 (top dotted curve) under the null hypothesis that is tested (either no feedback or no change-in-feedback). The second plot gives the number of exits of the CABD function from the confidence intervals (red line) and the distribution of the number of exits under the null hypothesis that is tested (histogram).

Value

A numeric value providing the p-value of the test.

Author(s)

Samuel Soubeyrand [email protected], Cindy E. Morris, E. Keith Bigg.

References

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

Examples

#### 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)

#### test feedback and change in feedback with a single data series
## using the thresholded data series
## using difference of means of positive indicator values (i.e. rainfall occurrence)
par(mfrow=c(1,2), mar=c(5.1,4.1,4.1,2.1))
feedback.test(object=KDD, test="feedback", operator="dmpiv", nb.rand=10^3, plots=TRUE)

---

Build a KDD object from values of slots

Description

Build a KDD (Key Day Dataset) object directly from values of the slots of the KDD class.

Usage

kdd(before.after, date, year, day, keyday.threshold)

Arguments

before.after	a matrix with $2\times K+1$ rows and $n$ columns: Each column gives the raw values $y_{i-K},\ldots,y_{i+K}$ of the time series, where $i$ is the date of the key day, $K$ is the number of days considered after and before the key day, $n$ is the number of key days in the data series (depends on keyday.threshold).
date	a character vector providing the dates of the key days in format yyyy.mm.dd.
year	a numeric vector providing the years during which the key days occurred.
day	a numeric vector providing for each key day the number of days since the beginning of the data series.
keyday.threshold	a numeric value providing the threshold value above which a day is considered as a key day (i.e. if $y_i\ge$ keyday.threshold, then day $i$ is a key day).

Value

an object from the KDD class.

Author(s)

Samuel Soubeyrand [email protected], Cindy E. Morris, E. Keith Bigg.

References

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.from.raw.data, rain.site.6008

Examples

#### 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)
	
#### build a new KDD object by modifying one of the slots of KDD
## (e.g. new starting point of the data series)
KDD2=kdd(before.after=KDD@before.after,date=KDD@date,year=KDD@year,
   day=KDD@day-100,keyday.threshold=KDD@keyday.threshold)

#### simplest alternative
KDD2=KDD
KDD2["day"]=KDD2["day"]-100

---

Class "KDD"

Description

Class KDD (Key Day Dataset) used as argument in FeedbackTS functions for the analysis of fragmented time directionality and feedback.

Objects from the Class

Objects can be created by calls of the form new("KDD", ...), kdd.from.raw.data(...) and kdd(...).

Slots

before.after:

Object of class "matrix" with $2\times K+1$ rows and $n$ columns: Each column gives the raw values $y_{i-K},\ldots,y_{i+K}$ of the time series, where $i$ is the date of the key day, $K$ is the number of days considered after and before the key day, $n$ is the number of key days in the data series (depends on keyday.threshold).

date:

Object of class "character", vector of size $n$ providing the dates of the key days in format yyyy.mm.dd.

year:

Object of class "numeric", vector of size $n$ providing the years during which the key days occurred.

day:

Object of class "numeric", vector of size $n$ providing for each key day the number of days since the beginning of the data series.

keyday.threshold:

Object of class "numeric" providing the threshold value above which a day is considered as a key day (i.e. if $y_i\ge$ keyday.threshold, then day $i$ is a key day).

Methods

[<-

signature(x = "KDD", i = "ANY", j = "ANY", value = "ANY"): Change one of the slots.

[

signature(x = "KDD"): Extract one of the slots.

names

signature(x = "KDD"): Prints slot names.

show

signature(object = "KDD"): Prints all slots of the KDD object.

summary

signature(object = "KDD"): Prints summary characteristics of the KDD object.

Author(s)

Samuel Soubeyrand [email protected], Cindy E. Morris, E. Keith Bigg.

References

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.from.raw.data, KDD.yearly.average, rain.site.6008

Examples

showClass("KDD")

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

#### build a KDD object 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)

## summary of the object
summary(KDD)
## names of the object
names(KDD)
slotNames(KDD)

## show attributes of the object
KDD["before.after"][,1:5]
KDD["date"]
KDD["keyday.threshold"]

## change keyday threshold
KDD["keyday.threshold"]=50

---

Build a KDD object from raw data

Description

Build a KDD (Key Day Dataset) object from a matrix or a data frame containing a time series and other attributes.

Usage

kdd.from.raw.data(raw.data, keyday.threshold, nb.days, col.series, col.date, 
na.rm = TRUE, filter = NULL)

Arguments

raw.data	a data frame or a matrix containing raw data.
keyday.threshold	a numeric providing the threshold value above which a day is considered as a key day (i.e. if the value $y_i$ of the times series is greater than or equal to keyday.threshold at day $i$, then day $i$ is a key day).
nb.days	an integer specifying the number of days considered after and before each key day.
col.series	an integer specifying the number of the column containing the time series.
col.date	an integer vector of size three specifying the numbers of the columns containing the vector of years, the vector of months and the vector of days in numeric format.
na.rm	a logical indicating whether key days $i$ with missing values in the sub-series $y_{i-K},\ldots,y_{i+K}$ have to be discarded. If na.rm = TRUE, these key days are discarded (default is TRUE).
filter	a list of lists specifying the filters to carry out over the time series (default is NULL).

Details

The filter argument is a list of lists, each list having the following arguments:

apply.over:

a character string that must be one of "keyday" or "range", and that indicates whether the filter concerns only the key days or also the range of days considered around the key days ($K$ days before and $K$ days after each key day).

column:

an integer specifying the column of raw.data which the filter is applied to.

value:

a value that must be taken by the variable determined by the argument column.

Let $i$ denote a key day. Let $z_i$ denote the value, at day $i$, of the variable determined by the argument column. If apply.over = "keyday" and $z_i$ = value, then key day $i$ is kept, otherwise it is discarded. If apply.over = "range" and $z_j$ = value for all $j\in\{i-K,\ldots,i+K\}$, then key day $i$ is kept, otherwise it is discarded.

Value

an object from the KDD class.

Author(s)

Samuel Soubeyrand [email protected], Cindy E. Morris, E. Keith Bigg.

References

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, rain.site.6008

Examples

#### 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)
summary(KDD)

#### build KDD objects from raw data (site 6008: Callagiddy station)
## using a threshold value equal to 25
## using filters
rain.site.6008b=cbind(rain.site.6008,rain.site.6008[["Year"]]>=1960)
KDD2=kdd.from.raw.data(raw.data=rain.site.6008b,keyday.threshold=25,nb.days=20,
   col.series=5,col.date=c(2,3,4),na.rm=TRUE,
   filter=list(list(apply.over="range",column=6,value=TRUE)))
summary(KDD2)

---

Build a KDD.yearly.average object from a KDD object

Description

Build a KDD.yearly.average (yearly average of a Key Day Dataset) by averaging on a yearly basis a KDD object

Usage

kdd.yearly.average(object)

Arguments

object

an object from the KDD class.

Value

an object from the KDD.yearly.average class.

Note

The before.after matrix of the KDD object is averaged on a yearly basis: every group of columns corresponding to a single year is averaged into a single column.

Author(s)

Samuel Soubeyrand [email protected], Cindy E. Morris, E. Keith Bigg.

References

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.yearly.average, KDD, kdd.from.raw.data, rain.site.6008

Examples

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

#### build a KDD object 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)

#### build the yearly average of KDD
KDD2=kdd.yearly.average(KDD)

## summary of the object
summary(KDD2)

---

Class "KDD.yearly.average"

Description

Class KDD.yearly.average (yearly average of a Key Day Dataset) used as argument in FeedbackTS functions for the analysis of fragmented time directionality and feedback.

Objects from the Class

Objects can be created by calls of the form new("KDD.yearly.average", ...) and kdd.yearly.average(...).

Slots

before.after:

Object of class "matrix" with $2\times K+1$ rows and $n$ columns: Each column gives the yearly average of the vectors of raw values $(y_{i-K},\ldots,y_{i+K})$ of the time series for key days $i$ occurring during a single year ($K$ is the number of days considered after and before the key day, $n$ is the number of years with key days in the data series and depends on keyday.threshold).

year:

Object of class "numeric", vector of size $n$ providing the years during which the key days occurred.

keyday.threshold:

Object of class "numeric" providing the threshold value above which a day is considered as a key day (i.e. if $y_i\ge$ keyday.threshold, then day $i$ is a key day).

yearly.nb.keydays:

Object of class "numeric", vector of size $n$ providing the number of key days at each year of the slot year.

Methods

[

signature(x = "KDD.yearly.average"): Extract one of the slots.

names

signature(x = "KDD.yearly.average"): Prints slot names.

show

signature(object = "KDD.yearly.average"): Prints all slots of the KDD object.

summary

signature(object = "KDD.yearly.average"): Prints summary characteristics of the KDD object.

Author(s)

Samuel Soubeyrand [email protected], Cindy E. Morris, E. Keith Bigg.

References

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.yearly.average, KDD, kdd.from.raw.data, rain.site.6008

Examples

showClass("KDD.yearly.average")

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

#### build a KDD object 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)

#### build the yearly average of KDD
KDD2=kdd.yearly.average(KDD)

## summary of the object
summary(KDD2)
## names of the object
names(KDD2)
slotNames(KDD2)

## show attributes of the object
KDD2["before.after"][,1:5]
KDD2["year"]
KDD2["keyday.threshold"]

---

Kriging function

Description

Variogram analysis and kriging prediction used to analyze feedback and change-in-feedback across space. This function is grounded on the function autoKrige in the automap package, grounded itself on the gstat package.

Usage

krige(coordinates, statistic, grid, krige.param=NULL, plots=TRUE,
    variog.param=list(npoints=50,nsim=99,plot.numbers=0.04))

Arguments

coordinates	a 2-column matrix with latitudes and longitudes of observation sites.
statistic	a numeric vector specifying the values, at observation sites, of the statistic to be predicted.
grid	a list of arguments defining the grid over which the statistic is predicted: x: a numeric vector of longitudes. y: a numeric vector of latitudes. border: a character string that names the region in the world within which the statistic will be predicted. This is a character string in the database world; see the function map in the maps package. proj: a projection definition; see the function project in the proj4 package. degrees: a logical indicating if the lat/long coordinates are assumed to be in degrees (if degrees = TRUE), or in radians (if degrees = FALSE).
krige.param	a character string equal either to "x+y", "x" or "y" indicating whether the coordinates (and which coordinates) have to be accounted for in the trend in universal kriging; default is NULL, indicating that ordinary kriging without trend is performed.
plots	a logical indicating if plots characterizing the variogram analysis and the kriging prediction are produced (if plots = TRUE) or not (if plots = FALSE), default is TRUE.
variog.param	a list of arguments used to display the variography, : npoints: a numeric value specifying the number of points at which the variogram model is calculated, default is 50. nsim: a numeric value specifying the number of Monte Carlo simulations used to compute the envelope, default is 99. plot.numbers: a numeric value specifyng the relative distance to be used between circles representing the empirical semivariogram and texts providing the number of point pairs used for computing each value of the empirical semivariogram, default is 0.04 (if plot.numbers = 0, these texts are not displayed).

Details

If plots = TRUE, four plots are produced. Plot 1: Estimation of the semivariogram of the statistic (dots: sample semivariogram; solid curve: theoretical semivariogram; dashed curves: Monte-Carlo envelopes. Plot 2: Boxplots of kriging prediction (left) and kriging standard error (right). Plot 3: Kriging prediction. Plot 4: Kriging standard error.

Value

a list of items characterizing the variogram analysis and the kriging prediction:

input	the list of arguments in the call of the krige function except the argument plots.
MAP	a list allowing to draw the border of the study region that can be made of several polygons. This is the output of the function map in the maps package.
grid	a 2-column matrix providing the coordinates (in degrees) of the nodes of the prediction locations.
in.region	a logical vector indicating, for each grid node whose coordinates are given in the 2-column matrix grid, if the node is in the study region or not. The study region is defined by MAP.
krige	a list providing the result the variography and the spatial prediction. This is the output of the function autoKrige in the automap package.

Note

The krige function uses some of the functionalities of the map function in the maps package, and of a few functions in the gstat and automap package. To fully exploit the functionalities of these external functions (in particular autoKrige), the krige function should be extended.

Author(s)

Samuel Soubeyrand [email protected], Cindy E. Morris, E. Keith Bigg.

References

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

rain.feedback.stats, map in the maps package, autoKrige and autofitVariogram in the automap package

Examples

#### load data of feedback and change-in-feedback indices in 88 sites across Australia
data(rain.feedback.stats)

#### spatial coordinates of the 88 sites
coord=rain.feedback.stats[,3:4]

#### feedback index
stat1=rain.feedback.stats[["Feedback.whole.period"]]

#### variogram analysis and kriging of feedback index
## computer intensive stage
## Not run: 
par(mfrow=c(2,2), mar=c(5.1,4.1,4.1,4.1))
kr1=krige(coordinates=coord, statistic=stat1,
   grid=list(x=seq(110,155,0.25),y=seq(-45,-11,0.25),border="Australia", 
      proj="+proj=lcc +lat_1=-18 +lat_2=-36 +lat0=-25 +lon_0=140",degrees=TRUE),
   plots=TRUE)

## the plot style from the \code{automap} package can be obtained as follows:
plot(kr1$krige)

## End(Not run)

---

Test of spatial variation in feedback and change-in-feedback

Description

Randomization test to investigate spatial variation in a kriged index.

Usage

krige.test(krige.output, subregion, alternative, nb.rand, subregion.coverage=0.8)

Arguments

krige.output	a list of items corresponding to the output of the krige function.
subregion	a list of two vectors containing the lat/long coordinates of the vertices of a polygon. The polygon defines a subregion where one supposes variation in the predicted index krige.output$krige$predict. x: longitudes. y: latitudes.
alternative	a character string specifying the alternative hypothesis, must be one of "greater" or "less".
nb.rand	a positive integer specifying the number of randomizations (here, a randomization is a random translation on a torus).
subregion.coverage	a numeric value between zero and one specifying a criterion to accept a random translation (see Details). Default value is 0.8.

Details

The criterion to accept a random translation is a minimum coverage of subregion by the translated grid: the ratio between the number of nodes of the translated grid that are contained in subregion and the number of nodes of the original grid that are contained in subregion must be equal to or greater than subregion.coverage.

Value

an object from the KT.output class

Author(s)

Samuel Soubeyrand [email protected], Cindy E. Morris, E. Keith Bigg.

References

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

krige, KT.output-class, rain.feedback.stats

Examples

#### load data of feedback and change-in-feedback indices in 88 sites across Australia
data(rain.feedback.stats)

#### spatial coordinates of the 88 sites
coord=rain.feedback.stats[,3:4]

#### map of feedback index computed from the whole data series
stat1=rain.feedback.stats[["Feedback.whole.period"]]

#### variogram analysis and kriging of feedback index
## computer intensive stage
## Not run: 
par(mfrow=c(2,2), mar=c(5.1,4.1,4.1,2.1))
kr1=krige(coordinates=coord, statistic=stat1,
   grid=list(x=seq(110,155,0.25),y=seq(-45,-11,0.25),border="Australia", 
      proj="+proj=lcc +lat_1=-18 +lat_2=-36 +lat0=-25 +lon_0=140",degrees=TRUE),
   plots=TRUE)

## End(Not run)
#### test spatial variation in feedback index and plot test output
## computer intensive stage
## Not run: 
kt1=krige.test(krige.output=kr1,subregion=list(x=c(138,152,152,138),y=-c(40,40,33,33)),
   alternative="greater", nb.rand=2000)
par(mfrow=c(1,2), mar=c(5.1,4.1,4.1,2.1))	
plot(kt1,digits=list(predict=3,pvalue=3),breaks=12)

## End(Not run)

---

Class "KT.output"

Description

Output of the krige.test function.

Objects from the Class

Objects are created by calls of the krige.test function.

Slots

krige.output:

Object of class "list", output of the krige function.

subregion:

Object of class "list", two vectors x and y containing the latitudes and the longitudes, respectively, of the vertices of a polygon. The polygon defines a subregion where one supposes variation in the predicted index.

averageKrigingPrediction.rand:

Object of class "numeric" specifying the averages of the kriging predictions in subregion obtained with randomized data (here, a randomization is a random translation on a torus).

averageKrigingPrediction.obs:

Object of class "numeric" specifying the average of the kriging prediction in subregion obtained with observed data.

alternative:

Object of class "character", "greater" or "less".

p.value:

Object of class "numeric", p-value of the test.

Methods

[<-

signature(x = "KT.output", i = "ANY", j = "ANY", value = "ANY")

[

signature(x = "KT.output"): Extract one of the slots.

names

signature(x = "KT.output"): Prints slot names.

show

signature(object = "KT.output"): Prints all slots of the KDD object.

summary

signature(object = "KT.output"): Prints summary characteristics of the KDD object.

plot

signature(x = "KT.output"), i="ANY": Graphically displays contents of the object.

Author(s)

Samuel Soubeyrand [email protected], Cindy E. Morris, E. Keith Bigg.

References

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.

Examples

showClass("KT.output")

#### load data of feedback and change-in-feedback indices in 88 sites across Australia
data(rain.feedback.stats)

#### spatial coordinates of the 88 sites
coord=rain.feedback.stats[,3:4]

#### map of feedback index computed from the whole data series
stat1=rain.feedback.stats[["Feedback.whole.period"]]

#### variogram analysis and kriging of feedback index
## Not run: 
par(mfrow=c(2,2), mar=c(5.1,4.1,4.1,2.1))
kr1=krige(coordinates=coord, statistic=stat1,
    grid=list(x=seq(110,155,0.25),y=seq(-45,-11,0.25),border="Australia",
        proj="+proj=lcc +lat_1=-18 +lat_2=-36 +lat0=-25 +lon_0=140",degrees=TRUE),
    plots=TRUE)

## End(Not run)

#### test spatial variation in feedback index and plot test output
## computer intensive stage
## Not run: 
kt1=krige.test(krige.output=kr1,subregion=list(x=c(138,152,152,138),y=-c(40,40,33,33)),
   alternative="greater", nb.rand=2000)
par(mfrow=c(1,2), mar=c(5.1,4.1,4.1,2.1))	
plot(kt1,digits=list(predict=3,pvalue=3),breaks=12) 
## End(Not run)

---

Mapping of a spatial index

Description

Mapping of a spatial index with circles whose sizes and colors vary with the values of the index

Usage

map.statistic(coordinates, statistic, region, cex.circles = c(3, 0.2), legend, 
	main = NULL, add = FALSE)

Arguments

coordinates	a 2-column matrix with latitudes and longitudes of observation sites.
statistic	a numeric vector specifying the values, at observation sites, of the index to be mapped.
region	a list of arguments defining the region over which the index is mapped: border: a character string that names the region in the world within which the statistic will be predicted. This is a character string in the database world; see the function map in the maps package. xlim: a numeric vector of size 2 specifying the limits in longitude of the plot. May not be provided. ylim: a numeric vector of size 2 specifying the limits in latitude of the plot. May not be provided.
cex.circles	a numeric vector specifying the circle expansion.
legend	a list of arguments defining the location of the legend in the plot: x: a numeric vector specifying the longitudes where the legend circles are drawn. y: a numeric vector specifying the latitudes where the legend circles are drawn. xtext: a numeric vector specifying the longitudes where the values corresponding to the sizes of the legend circles are drawn. ytext: a numeric vector specifying the latitudes where the values corresponding to the sizes of the legend circles are drawn. digits: integer indicating the number of decimal places to be used.
main	a character string providing an overall title for the plot.
add	a logical indicating whteher the plot must be added to a current plot (if add = TRUE) or not (if add = FALSE), default is FALSE.

Value

a plot.

Author(s)

Samuel Soubeyrand [email protected], Cindy E. Morris, E. Keith Bigg.

References

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

map.statistic rain.feedback.stats.

Examples

#### load data of feedback and change-in-feedback indices in 88 sites across Australia
data(rain.feedback.stats)

#### spatial coordinates of the 88 sites and corresponding feedback index 
#### computed from the whole data series
coord=rain.feedback.stats[,3:4]
stat1=rain.feedback.stats[["Feedback.whole.period"]]

#### map of feedback index 
map.statistic(coord,stat1,cex.circles=c(3,0.2),
   region=list(border="Australia",xlim=c(110,155)),
   legend=list(x=c(rep(114,3),rep(123,2)),y=-c(37,39.5,42,37,39.5),
      xtext=c(rep(114,3),rep(123,2))+1,ytext=-c(37,39.5,42,37,39.5),digits=2),
   main="Feedback")

---

Statistics of rain feedback in Australia

Description

Feedback and change-in-feedback statistics based on 88 rainfall data series colllected in 88 sites across Australia.

Usage

data(rain.feedback.stats)

Format

A data frame with 88 observations on the following 8 variables.

Station.number:

a numeric vector providing the identifiers of the meteorological stations.

Keyday.threshold:

a numeric vector providing for each meteorological station the threshold value above which a day is considered as a key day.

Longitude:

a numeric vector with longitudes of the meteorological stations.

Latitude:

a numeric vector with latitudes of the meteorological stations.

Feedback.whole.period:

a numeric vector providing for each meteorological station the temporal average of after-before differences around key days calculated from the whole time series.

Feedback.before.1960:

a numeric vector providing for each meteorological station the temporal average of after-before differences around key days calculated from the time series right-truncated in 1960 (data from year 1960 were excluded).

Feedback.after.or.in.1960:

a numeric vector providing for each meteorological station the temporal average of after-before differences around key days calculated from the time series left-truncated in 1960 (data from year 1960 were kept).

Change.in.feedback:

a numeric vector providing the difference between Feedback.after.or.in.1960 and Feedback.before.1960.

Details

The statistics in this data set were computed using the feedback.stats function.

Source

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.

References

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.

Examples

#### load data of feedback and change-in-feedback indices in 88 sites across Australia
data(rain.feedback.stats)

#### spatial coordinates of the 88 sites and corresponding feedback index 
#### computed from the whole data series
coord=rain.feedback.stats[,3:4]
stat1=rain.feedback.stats[["Feedback.whole.period"]]

#### map of feedback index 
map.statistic(coord,stat1,cex.circles=c(3,0.2),
   region=list(border="Australia",xlim=c(110,155)),
   legend=list(x=c(rep(114,3),rep(123,2)),y=-c(37,39.5,42,37,39.5),
      xtext=c(rep(114,3),rep(123,2))+1,ytext=-c(37,39.5,42,37,39.5),digits=2),
   main="Feedback")

---

Rainfall data at Callagiddy station

Description

Rainfall data at Callagiddy station in Western Australia (meteorological station with identifier 6008).

Usage

data(rain.site.6008)

Format

A data frame with 36615 observations on the following 5 variables.

Station.Number

a numeric vector providing the identifier of the meteorological station.

Year

a numeric vector specifying the year of each observation.

Month

a numeric vector specifying the month in the year of each observation.

Day

a numeric vector specifying the day in the month of each observation.

Precipitation.in.the.24.hours.before.9am..local.time..in.mm

a numeric vector providing the precipitation level in the 24 hours before 9am, local time, in mm.

Source

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.

References

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.

Examples

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

#### build KDD object from raw data (site 6008: Callagiddy station)
## using a threshold value equal to 0 to keep all days
KDDno=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 after-before differences and plot the whole data series
plot(KDDno["day"],KDDno["before.after"][21,],type="l",xlab="Day",ylab="Daily rainfall")
   axis(3,at=c(1,365*30,365*60,365*90),labels=KDDno["year"][1]+c(0,30,60,90))

---