significantTau: Compute (pre-whitened) Kendall's tau

Description

Apply the Mann-Kendall trend test (Mann, 1945) to a series of observations and return Kendall's tau (Kendall, 1938) based on a predefined significance level. In contrast to other readily available implementations, it is left to the user to decide whether or not to apply pre-whitening as described in the zyp package vignette (Bronaugh and Werner, 2013).

Usage

## S3 method for class 'numeric':
significantTau(x, p = 0.001, prewhitening = TRUE,
  df = FALSE, ...)
## S3 method for class 'RasterStackBrick':
significantTau(x, p = 0.001,
  prewhitening = TRUE, df = FALSE, filename = "", ...)

Arguments

A 'numeric' vector.

Significance level to be tested.

prewhitening

'logical'. If TRUE, pre-whitening is applied prior to the Mann-Kendall trend test.

'logical'. If TRUE, a 'data.frame' holding the value of Kendall's tau and the referring significance level.

...

Further arguments passed on to zyp.trend.vector.

filename

'character'. Optional output filename, see writeRaster. Needs to include an appropriate file format extension, see writeFormats.

Value

If df = FALSE (default) and p was not exceeded, a single 'numeric'; if df = FALSE and p was exceeded, a 'logical' (NA); else a 'data.frame' with Kendall's tau and the corresponding significance level.

References

Kendall, M.G. (1938). A new measure of rank correlation. Biometrika 30(1/2), 81-93, doi: 10.2307/2332226. Available online at http://www.jstor.org/stable/2332226 (accessed 2015-11-06).

Mann, H.B. (1945). Nonparametric tests against trend. Econometrica 13(3), 245-259, doi: 10.2307/1907187. Available online at http://www.jstor.org/stable/1907187 (accessed 2015-11-06).

Zhang, X., Vincent, L.A., Hogg, W.D. and A. Niitsoo (2000). Temperature and Precipitation Trends in Canada during the 20th Century. Atmosphere-Ocean 38(3), 395-429, doi: 10.1080/07055900.2000.9649654. Available online at http://www.tandfonline.com/doi/abs/10.1080/07055900.2000.9649654 (accessed 2015-11-06).

Yue, S., Pilon, P., Phinney, B. and G. Cavadias (2002). The influence of autocorrelation on the ability to detect trend in hydrological series. Hydrological Processes 16, 1807-1829, doi: 10.1002/hyp.1095. Available online at http://onlinelibrary.wiley.com/doi/10.1002/hyp.1095/abstract (accessed 2015-11-06).

Examples

Run this code

## Example taken from ?Kendall::MannKendall
library(Kendall)
data(PrecipGL)
plot(PrecipGL)

## Mann-Kendall trend test without pre-whitening
x <- as.numeric(PrecipGL)
significantTau(x, p = 0.001, prewhitening = FALSE, df = TRUE)

## Mann-Kendall trend test with pre-whitening
significantTau(x, p = 0.001, prewhitening = TRUE, df = TRUE)

#############################################################################
### use case: significant (p < 0.001) mann-kendall trends (2009-13) #########
#############################################################################

## download files from 2009-2013
gimms_files <- downloadGimms(x = as.Date("2009-01-01"),
                             dsn = paste0(getwd(), "/data"))

## convert binary files to 'Raster*' format
gimms_rasters <- rasterizeGimms(gimms_files, filename = gimms_files,
                                format = "GTiff", overwrite = TRUE)

## crop iran
library(rworldmap)
data(countriesLow)
gimms_iran <- crop(gimms_rasters,
                     subset(countriesLow, ADMIN == "Iran"))

## remove seasonal signal via remote::deseason
library(remote)
gimms_deseason <- deseason(gimms_iran, cycle.window = 24, use.cpp = TRUE)

## identify long-term monotonous trends from mann-kendall trend test; all values
## of kendall's tau with p >= 0.001 are set to NA; note that pre-whitening is
## applied prior to the actual trend test
gimms_trends <- significantTau(gimms_deseason, p = 0.001,
                               prewhitening = TRUE)

## create figure
library(RColorBrewer)
library(latticeExtra)
cols <- colorRampPalette(brewer.pal(11, "BrBG"))
spplot(gimms_trends, col.regions = cols(100), scales = list(draw = TRUE),
       at = seq(-.525, .525, .025),
       main = expression("Kendall's" ~ tau ~ "(2009-2013)")) +
  layer(sp.polygons(countriesLow))