TSS.RESTREND: Time Series Segmented RESidual TREND

Description

The TSS-RESTREND package is designed used via the TSS-RESTREND function which calls all the other functions in the correct order to perform a complete TSS-RESTREND analysis. The individual functions have been made callable to allow for greater user control. The version in active development, as well as additional documentation, data and example scripts, see https://github.com/ArdenB/TSSRESTREND.

Details

Version 0.3.0

Note

This code is a demostration of the method and not the code used in Burrell et. al., (2017). The original code uses both python and R and was designed for batch proccessing. For the pixels tested using the TSS.RESTREND package it produces identical results.

Author(s)

Maintainer: Arden Burrell arden.burrell@gmail.com

Antecedental Rainfall (and temperature) Accumulation calculator for the VI Complete Time Series

Description

Takes the Complete Time Series Vegetation Index and a table of every possible accumulation period and offset period for precipitation and temperature(optional). A OLS is calculated lm for every combination of VI ~ rainfall (and temperature if that is included). if only the VPR is being calculated, this Function preferences those results where slope>0 (increase in rainfall causes an increase in vegetation),returning the rainfall accumulation that has the highest R-squared and a positive slope. If no combination produces a positive slope then the one with the highest R-squared is returned.

Usage

ACP.calculator(
  CTSR.VI,
  ACP.table,
  ACT.table = NULL,
  allow.negative = FALSE,
  allowneg.retest = FALSE
)

Arguments

Value

A list containing:

summary a Matrix containing "slope", "intercept", "p.value", "R^2.Value", "Break.Height", "Slope.Change" of the lm between Antecedental Rainfall Accumulation (CTSR.RF) and the CTSR.VI

CTSR.precip see CTSR.RF in TSSRESTREND for description

CTSR.osp The offest period for the complete time series rainfall

CTSR.acp The accumulation period for the complete time series rainfall

CTSR.tmp The optimally accumulated CTS temperature

CTSR.tosp The offest period for the complete time series temperature

CTSR.tacp The accumulation period for the complete time series temperature

Examples

#Find the data
vi.path <- system.file("extdata", "rabbitVI.csv", package = "TSS.RESTREND", mustWork = TRUE)
in.VI <- read.csv(vi.path)
CTSR.VI <- ts(in.VI, start=c(1982, 1), end=c(2013,12), frequency = 12)
data(rabbitACPtable)
ACPres <- ACP.calculator(CTSR.VI, rabbitACPtable)
print(ACPres$summary)

Annual max VI Calculator

Description

Takes the montly time series of the VI and calculates the growing season max VI. In series where the peak occurs in November or December, an interannual growing season is assessed.

Usage

AnMaxVI(CTSR.VI)

Arguments

Value

Max(anu.VI) The annual (Growing season) max VI. See TSSRESTREND

Max.Month The month number where max values were observed (1 for January). if month > 12, the peak was detected in Nov, Dec, Jan. In this case the peak seasonal value and position is used.

index(VI.index) the index of the CTSR.VI ts that the anu.VI values occur at. See TSSRESTREND. Note.R indexs from 1 rather than 0.

Author(s)

Arden Burrell, arden.burrell@unsw.edu.au

Examples

anmax <- AnMaxVI(stdRESTRENDCTSR$cts.NDVI)
print(anmax)

Antecedental accumulation calculator for the annual max VI time series

Description

Takes the Annual Max VI Time Series, the VI.index and tables of every possible accumulation period and offset period for preciptation and Temperature (optional). A OLS is calculated lm for every combination of VI ~ rainfall. If temperature is provided The formula is (VI ~ rainfall + temperature). By defualt, this function preferences those results where slope>0 (increase in rainfall causes an increase in vegetation), returning the rainfall accumulation that has the highest R-squared and a positive slope. If no combinations produce a positive slope then the one with the highest Rsquared is returned. TO DO: non peramtric and other variables

Usage

AnnualClim.Cal(
  anu.VI,
  VI.index,
  ACP.table,
  ACT.table = NULL,
  Breakpoint = FALSE,
  allow.negative = FALSE,
  allowneg.retest = FALSE
)

Arguments

Value

summary a Matrix containing "slope", "intercept", "p.value", "R^2.Value", "Break.Height", "Slope.Change" of the lm of VI ~ rainfall. If Breakpoint, summary covers both rf.b4 and rf.af.

acu.RF (aka. annual.precip)The optimal accumulated rainfall for anu.VI. Mut be a object of class 'ts' and of equal length to anu.VI. It is caculated from the ACP.table by finding the acp and osp that has the largest R^2 value. lm(anu.VI ~ rainfall)

acu.TM (aka, annual.temp) The optimal accumulated rainfall for anu.T<. Mut be a object of class 'ts' and of equal length to anu.VI. It is caculated from the ACT.table by finding the tacp and tosp that has the largest R^2 value. lm(anu.VI ~ rainfall+temperature)

rf.b4 The optimal acumulated rainfall before the Breakpoint

rf.af The Optimally accumulated rainfall after the Breakpoint

tm.b4 The optimal acumulated temperature before the Breakpoint

tm.af The Optimally accumulated temperature after the Breakpoint

osp The offest period for the annual max time series rainfall

acp The accumulation period for the annual max time series rainfall

tosp The offest period for the annual max time series temperature

tacp The accumulation period for the annual max time series temperature

Author(s)

Arden Burrell, arden.burrell@unsw.edu.au

Examples

ARC <- AnnualClim.Cal(stdRESTREND$max.NDVI, stdRESTREND$index, stdRESTRENDrfTab)
print(ARC)
## Not run: 

#Test the complete time series for breakpoints
VPRBFdem <- VPR.BFAST(segVPRCTSR$cts.NDVI, segVPRCTSR$cts.precip)
bp<-as.numeric(VPRBFdem$bkps)

#test the significance of the breakpoints
reschow <- CHOW(segVPR$max.NDVI, segVPR$acum.RF, segVPR$index, bp)
brkp <- as.integer(reschow$bp.summary["yr.index"])
ARCseg <-AnnualClim.Cal(segVPR$max.NDVI, segVPR$index, segVPRrfTab, Breakpoint = brkp)
print(ARCseg)

## End(Not run)

Chow test on detected breakpoints

Description

Takes the breakpoints detected by VPR.BFAST, finds the most significant one then tests it in both the residuals and the VPR.

Usage

CHOW(anu.VI, acu.RF, VI.index, breakpoints, acu.TM = NULL, sig = 0.05)

Arguments

Value

n.Method The method that the ts should be tested with. TSSRESTREND internal communication.

bp.summary Summary of the most signifcant breakpoint in the residuals and VPR. see sctest

allbp.index the Annual index of every breakpoint. Used by plot.TSSRESTREND

bpRESID.chow Chow test in the VPR residuals. See sctest

bpVPR.chow Chow test in the VPR. See sctest

Author(s)

Arden Burrell, arden.burrell@unsw.edu.au

Examples

## Not run: 
#Test the complete time series for breakpoints
VPRBFdem <- VPR.BFAST(segVPRCTSR$cts.NDVI, segVPRCTSR$cts.precip)
bp <- as.numeric(VPRBFdem$bkps)
#test the significance of the breakpoints
reschow <- CHOW(segVPR$max.NDVI, segVPR$acum.RF, segVPR$index, bp)
print(reschow)

## End(Not run)

RESTREND (RESidual TREND)

Description

For ts with no significant breakpoints in the residuals or the VPR. Takes annual VI max and it associated optimal accumulated precipitation

Usage

RESTREND(
  anu.VI,
  acu.RF,
  VI.index,
  acu.TM = NULL,
  sig = 0.05,
  retnonsig = FALSE
)

Arguments

Value

a list of class TSSRESTREND. See TSSRESTREND for details. Note. if called seperatly from TSSRESTREND, this list will be incomplete.

Author(s)

Arden Burrell, arden.burrell@unsw.edu.au

Examples

restrend <- RESTREND(stdRESTREND$max.NDVI, stdRESTREND$acc.precip, stdRESTREND$index)
print(restrend)

Time Series Segmentation of Residual Trends (MAIN FUNCTION)

Description

Time Series Segmented Residual Trend (TSS.RESTREND) methodology.Takes in a complete monthly time series of a VI and its corrosponding precipitation (and temperature). It then looks looks for breakpoints using the BFAST function. The significance of the breakpoin in the residuals and the VPR is assessed using a Chow test, then, the total time series change is calculated.

Usage

TSSRESTREND(
  CTSR.VI,
  ACP.table = FALSE,
  ACT.table = NULL,
  CTSR.RF = FALSE,
  CTSR.TM = NULL,
  anu.VI = FALSE,
  acu.RF = FALSE,
  acu.TM = NULL,
  VI.index = FALSE,
  rf.b4 = FALSE,
  rf.af = FALSE,
  sig = 0.05,
  season = "none",
  exclude = 0,
  allow.negative = FALSE,
  allowneg.retest = FALSE,
  h = 0.15,
  retnonsig = FALSE
)

Arguments

Value

An object of class 'TSSRESTREND' is a list with the following elements:

summary

Method

The method used to determine total change. (RESTREND see RESTREND, segmented.RESTREND see seg.RESTREND, segmented.VPR see seg.VPR)

Total.Change

The total significant change. Residual.Change + VPR.HeightChange.

Residual.Change

The change in the VPR Residuals over the time period

VPR.HeightChange

The change in VI at mean rainfall for a "ts" with a significant breakpoint in the VPR

model.p

p value of the regression model fitted to the VPR. See lm

residual.p

p value of the regression model fitted to the VPR Residuals. See lm

VPRbreak.p

the p value associated with the break height. See lm

bp.year

The Year of the most significant breakpoint

ts.data

The Time series used in analysis. See Arguments for description

• CTSR.VI

• CTSR.RF

• anu.VI

• VI.index

• acu.RF

• StdVar.RF see seg.VPR)

ols.summary

chow.summary

summary of the most significant breakpoint.

chow.ind

Summary of every detected breakpoint

OLS.table

A matrix containing the coefficents for the CTS.fit, VPR.fit, RESTREND.fit and segVPR.fit

TSSRmodels

models of class "lm" lm and class "bfast" bfast generated.

Note

if ACP.table = FALSE, CTSR.RF and acu.RF must be provided as well as rf.b4 and rf.af for 'ts' with a breakpoint in the VPR.

Author(s)

Arden Burrell, arden.burrell@unsw.edu.au

See Also

• plot.TSSRESTREND

• print.TSSRESTREND

Examples

## Not run: 
#To get the latest version of the package (Still in development)
install.packages("devtools")
library("devtools")
install_github("ArdenB/TSSRESTREND", subdir="TSS.RESTREND")
library(TSS.RESTREND)
#Find the path of the rabbitRF.csv dataset, read it in and turn it into a time series
rf.path<- system.file("extdata", "rabbitRF.csv", package = "TSS.RESTREND", mustWork = TRUE)
in.RF <- read.csv(rf.path)
rf.data <- ts(in.RF, end=c(2013,12), frequency = 12)

#Find the path of the rabbitVI.csv dataset and read it in
vi.path <- system.file("extdata", "rabbitVI.csv", package = "TSS.RESTREND", mustWork = TRUE)
in.VI <- read.csv(vi.path)
CTSR.VI <- ts(in.VI, start=c(1982, 1), end=c(2013,12), frequency = 12)

#Define the max accumuulation period
max.acp <- 12
#Define the max offset period
max.osp <- 4
#Create a table of every possible precipitation value given the max.acp and max.osp
ACP.table <- climate.accumulator(CTSR.VI, rf.data, max.acp, max.osp)
results <- TSSRESTREND(CTSR.VI, ACP.table)
print(results)
plot(results, verbose=TRUE)

## End(Not run)

Vegetation change attribution using the Time Series Segmentation of Residual Trends (MAIN FUNCTION)

Description

This is a wrapper function around the TSS-RESTREND main function that dows additional attribution. It measues the Observed vegetation change, land use, climate change and climate varibility. Unlike TSSRESTREND function, this requires both temperature and precitation data fo work.

Usage

TSSRattribution(
  CTSR.VI,
  CTSR.RF,
  CTSR.TM,
  max.acp,
  max.osp,
  C4frac = 0,
  sig = 0.05,
  season = "none",
  exclude = 0,
  allow.negative = FALSE,
  allowneg.retest = FALSE,
  h = 0.15,
  returnmodels = FALSE,
  AnnualRes = FALSE,
  SkipError = TRUE,
  retnonsig = TRUE,
  splitclim = TRUE,
  cliwindow = 20,
  CO2 = FALSE,
  refyear = 1980
)

Arguments

Value

tacp The accumulation period for the annual max time series temperature

Author(s)

Arden Burrell, aburrell@whrc.org

BFAST Breakpoint Detector

Description

takes the Complete VI and optimally accumulated Rainfall (and tmperature if included), calculates a lm between them And then performs a bfast.in the residuals. If BFAST.raw=TRUE, it will perform bfast on the Complete VI ts

Usage

VPR.BFAST(
  CTSR.VI,
  CTSR.RF,
  CTSR.TM = NULL,
  season = "none",
  BFAST.raw = FALSE,
  h = 0.15
)

Arguments

Value

List of objects:

bkps The index of the Breakpoints detected. If no breakpoints are detected, bkps = FASLE

BFAST.obj See bfast

CTS.lm the lm of CTSR.VI and CTSR.RF

BFAST.type the type of BFAST done (VPR residuals or on the VI timeseris itself)

Author(s)

Arden Burrell, arden.burrell@unsw.edu.au

Examples

## Not run: 
VPRBFdem <- VPR.BFAST(segVPRCTSR$cts.NDVI, segVPRCTSR$cts.precip)
print(VPRBFdem)
## End(Not run)

Climate Accumulator

Description

Takes the time series of rainfall and returns a rainfall accumulation table of every possible combination of the max accumulation period and the max offset period.

Usage

climate.accumulator(
  CTSR.VI,
  clim.data,
  max.acp,
  max.osp,
  temperature = FALSE,
  cliwindow = 0
)

Arguments

Value

ACP.table A matrix with ever possible accumuated climate combination

Examples

# Define the max accumuulation period
acp <- 12
#Define the max offset period
osp <- 4
rftable <- climate.accumulator(segRESTRENDCTSR$cts.NDVI, segRESTRENDctRF$precip, acp, osp)

Franks CO2 Vegetation correction

Description

Adjusts a vegetation time series to account for CO2 fertilisation

Usage

franksCO2(CTSR.VI, C4frac, CO2 = FALSE, refyear = 1980)

Arguments

Value

CTSR.VIadj A version of the CTSR.VI data that has been adjusted to account for CO2

Author(s)

Arden Burrell, aburrell@whrc.org

Plot Function for ojects of the TSSRESTREND class

Description

Produces plots for class TSSRESTREND

Usage

## S3 method for class 'TSSRESTREND'
plot(x, plots = "all", sig = 0.05, ...)

Arguments

Print function for class TSSRESTREND

Description

print function for objects of class TSSRESTREND

Usage

## S3 method for class 'TSSRESTREND'
print(x, ...)

Arguments

Rabbit Impacted Vegetation Precipitation Accumulation Table

Description

Rainfall Accumulation Table form a part of the Simpson-sStrzelecki Dunefields bioregion impacted by reduced rabbit predation after the release of RHD.

Usage

rabbitACPtable

Format

A matrix containing the complete time series of every acp and ofp. See climate.accumulator for details

Source

Awap data from http://www.csiro.au/awap/cgi/awap2.pl

Examples

data(rabbitACPtable)

Segmented RESTREND (RESidual TREND)

Description

For ts with a significant breakpoints in the residuals but not in the VPR. Takes annual VI max and it associated optimal accumulated precipitation and regresses it with a dummy variable that is 0 before the breakpoint and 1 after it

Usage

seg.RESTREND(
  anu.VI,
  acu.RF,
  VI.index,
  breakpoint,
  acu.TM = NULL,
  sig = 0.05,
  retnonsig = FALSE
)

Arguments

Value

a list of class TSSRESTREND. See TSSRESTREND for details. Note. if called seperatly from TSSRESTREND, this list will be incomplete.

Author(s)

Arden Burrell, arden.burrell@unsw.edu.au

Examples

# brkp can be determined using VPR.BFAST and CHOW.
brkp <-  as.integer(11)
resu <- seg.RESTREND(segRESTREND$max.NDVI, segRESTREND$acc.precip, segRESTREND$index, brkp)

Segmented Vegetation Climate Relationship

Description

For a ts with a significant breakpoints in the the VPR/VCR. This function takes annual VI max, the optimal accumulated precipitation (& temperature) before and after the breakpoint, then caculates the Standard Variance of the climate cariables.Theen an OLS is performed with a dummy variable to reperesent the breakpoint (0 before the breakpoint and 1 after it)..

Usage

seg.VPR(
  anu.VI,
  acu.RF,
  VI.index,
  breakpoint,
  rf.b4,
  rf.af,
  acu.TM = NULL,
  tm.b4 = NULL,
  tm.af = NULL,
  sig = 0.05,
  retnonsig = FALSE
)

Arguments

Value

a list of class TSSRESTREND. See TSSRESTREND for details. Note. if called seperatly from TSSRESTREND, this list will be incomplete.

Author(s)

Arden Burrell, arden.burrell@unsw.edu.au

Examples

brkp <- as.integer(24) #calculated using th CHOW (DONTRUN) example
VPRres <- seg.VPR(segVPR$max.NDVI, segVPR$acum.RF, segVPR$index, brkp, segVPR$RFB4, segVPR$RFAF)
print(VPRres)

Data frame containing the annual data for a segRESTREND analysis

Description

contains anu.VI, acu.RF, VI.index, rf.b4, rf.af. Range 1982 - 2013. Breakpoint for this pixel is 24 (2005)

Usage

segRESTREND

Format

R data frame

Source

gimms-package

Data frame containing the Complete Times Series data for a segmented RESTREND analysis

Description

contains CTSR.VI and CTSR.RF. See TSSRESTREND. Starts 1/1982 and extend to 12/2013

Usage

segRESTRENDCTSR

Format

R data frame

Source

a single pixel from monthlyComposite

See Also

stdRESTREND for the annual values for the same pixel

Data frame containing the raw rainfall data set for the segRESTREND data, ending dec 2013 with a frquency of 12

Description

contains raw monthly precipitation

Usage

segRESTRENDctRF

Format

R data frame

Source

Awap data from http://www.csiro.au/awap/cgi/awap2.pl

See Also

stdRESTREND for the annual values for the same pixel

Precipitation Accumulation Table for the segRESTREND demonstration pixel

Description

Rainfall Accumulation Table

Usage

segRESTRENDrfTab

Format

A matrix containing the complete time series of every acp and ofp. See climate.accumulator for details

Source

Awap data from http://www.csiro.au/awap/cgi/awap2.pl

Data frame containing the annual data for a segVPR analysis

Description

contains anu.VI, acu.RF, VI.index, rf.b4, rf.af. Range 1982 - 2013. Breakpoint for this pixel is 24 (2005)

Usage

segVPR

Format

R data frame

Source

gimms-package

Data frame containing the Complete Times Series data for a segmented VPR (VEGETATION PRECIPTATION RELATIONSHIP) analysis

Description

contains CTSR.VI and CTSR.RF. See TSSRESTREND. Starts 1/1982 and extend to 12/2013

Usage

segVPRCTSR

Format

R data frame

Source

a single pixel from monthlyComposite

See Also

stdRESTREND for the annual values for the same pixel

Data frame containing the raw rainfall data set for the segVPR data, ending dec 2013 with a frquency of 12

Description

contains raw monthly precipitation

Usage

segVPRctRF

Format

R data frame

Source

Awap data from http://www.csiro.au/awap/cgi/awap2.pl

See Also

stdRESTREND for the annual values for the same pixel

Precipitation Accumulation Table for the segVPR demonstration pixel

Description

Rainfall Accumulation Table

Usage

segVPRrfTab

Format

A matrix containing the complete time series of every acp and ofp. See climate.accumulator for details

Source

Awap data from http://www.csiro.au/awap/cgi/awap2.pl

Data frame containing the annual data for a standard Restrend analysis

Description

contains anu.VI, acu.RF and VI.index. Range 1982 - 2013

Usage

stdRESTREND

Format

R data frame

Source

gimms-package

Data frame containing the Complete Times Series data for a standard Restrend analysis

Description

contains CTSR.VI and CTSR.RF. See TSSRESTREND. Starts 1/1982 and extend to 12/2013

Usage

stdRESTRENDCTSR

Format

R data frame

Source

a single pixel from monthlyComposite

See Also

stdRESTREND for the annual values for the same pixel

Data frame containing the raw rainfall data set ending dec 2013 with a frquency of 12

Description

contains raw monthly precipitation

Usage

stdRESTRENDctRF

Format

R data frame

See Also

stdRESTREND for the annual values for the same pixel

Precipitation Accumulation Table for the standard RESTREND demonstration pixel

Description

Rainfall Accumulation Table

Usage

stdRESTRENDrfTab

Format

A matrix containing the complete time series of every acp and ofp. See climate.accumulator for details

Source

Awap data from http://www.csiro.au/awap/cgi/awap2.pl