seasonality {berryFunctions}

Seasonality analysis

Description

Examine time series for seasonality of high (low) values

Usage

seasonality(
  dates,
  values,
  data,
  drange = NA,
  vrange = NA,
  shift = 0,
  janline = TRUE,
  hlines = FALSE,
  nmax = 0,
  maxargs = NULL,
  plot = 1,
  add = FALSE,
  nmin = 100,
  probs = c(0, 25, 50, 75, 95, 99.9)/100,
  width = 3,
  text = TRUE,
  texti = seq(200, 20, length.out = length(probs)),
  textargs = NULL,
  months = substr(month.abb, 1, 1),
  slab = "Month",
  tlab = "Year",
  vlab = NA,
  xlim = NA,
  ylim = NA,
  xaxs = NA,
  yaxs = NA,
  main = "Seasonality",
  adj = 0.2,
  mar = c(3, 3, 4, 1),
  mgp = c(1.7, 0.7, 0),
  keeppar = TRUE,
  legend = TRUE,
  legargs = NULL,
  returnall = FALSE,
  quiet = FALSE,
  ...
)

Arguments

dates

Dates in ascending order. Can be character strings or strptime results, as accepted (and coerced) by as.Date

values

Values to be mapped in color with colPoints

data

Optional: data.frame with the column names as given by dates and values

drange

Optional date range (analogous to xlim), can be a vector like dates. Can also be numerical years, in which case "-01-01" is appended. DEFAULT: NA (computed from dates internally)

vrange

Optional value range (analogous to ylim), can be a vector like values. DEFAULT: NA (computed from values internally)

shift

Number of days to move the year-break to. E.g. shift=61 for German hydrological year (Nov to Oct). DEFAULT: 0

janline

Logical: Should horizontal line be plotted at January 1st if shift!=0? DEFAULT: TRUE

hlines

Draw horizontal background lines in plot 1? Either FALSE (the default), TRUE to draw gray background lines at each month start, or a list of arguments passed to abline with owa. DEFAULT: FALSE

nmax

Number of annual maxima to be marked, plotted and returned. Currently, only 0 and 1 are implemented. DEFAULT: 0

maxargs

List of arguments passed to lines for annual maxima, e.g. maxargs=list(type="l", col="red", lty=3). DEFAULT: NULL (several internal defaults are used, but can be overridden)

plot

Integer specifying the type of plot. Can be a vector to produce several plots.
0: none, only return the data.frame with annual maxima.
1: color coded doy (day of the year) over year (the default).
2: Color coded spiral graph with spiralDate.
3: Spaghetti line plot with discharge over doy, one line per year.
4: probs quantileMean over doy, with optional aggregation window (width) around each doy.
5: Annmax over time for crude trend analysis.
DEFAULT: 1

add

Logical. Add to existing plot? DEFAULT: FALSE

nmin

Minimum number of values that must be present per (hydrological) year to be plotted in plot type 5. DEFAULT: 100

probs

Probabilities passed to quantileMean for plot=4. DEFAULT: c(0,25,50,75,95,99)/100

width

Numeric: window width for plot=4. Used as sd in gaussian weighting. Support (number of values around a DOY passed to quantile function at least once) is ca 4.9*width. The value at doy itself is used 10 times. Larger values of width require more computing time. DEFAULT: 3

text

Logical. Call textField if plot=4? DEFAULT: TRUE

texti

Numerical (vector): indices at which to label the lines. DEFAULT: seq(200,20,length.out=length(probs))

textargs

List of arguments passed to textField for plot=4. DEFAULT: NULL

months

Labels for the months. DEFAULT: J,F,M,A,M,J,J,A,S,O,N,D

slab, tlab, vlab

Labels for the season, time (year) and values used on the axes and title of colPointsLegend. DEFAULT: "Month", "Year", substitute(values)

xlim, ylim

Limits of x and y axis. DEFAULT: NA (specified internally per plot type)

xaxs, yaxs

x and y Axis style, see par. Use "r" for regular 4% expansion, "i" for in range only. DEFAULT: NA (specified internally per plot type)

main, adj

Graph title and offset to the left (adj passed to title). DEFAULT: "Seasonality", 0.2

mar, mgp

Parameters specifying plot margin size and labels placement. DEFAULT: c(3,3,4,1), c(1.7,0.7,0) (Changed for plot 3:5 if not given)

keeppar

Logical: Keep the margin parameters? If FALSE, they are reset to the previous values. DEFAULT: TRUE

legend

Logical. Should a legend be drawn? DEFAULT: TRUE

legargs

List of arguments passed as legargs to colPoints. DEFAULT: NULL (internally, plots 3 and 5 have density=F as default)

returnall

Logical: return all relevant output as a list instead of only annmax data.frame? DEFAULT: FALSE

quiet

Logical: suppress progress stuff and colPoints messages? DEFAULT: FALSE

...

Further arguments passed to colPoints like pch, main, xaxs, but not Range (use vrange). Passed to spiralDate if plot=2, like add, format, lines.

Value

The output is always invisible, don't forget to assign it. If returnall=FALSE: Data.frame with year, number of nonNA entries, max value + doy of annual maxima. Please note that the column year does not match the calendrical year if shift!=0.
if returnall=TRUE: a list with annmax (df from above) as well as:
data: data.frame(doy, values, year) and optionally:
plot1, plot3, plot4, plot5: outputs from colPoints
plot2: output list from spiralDate
and other elements depending on plot type, like data3, data4, probs4, width4.

Author(s)

Berry Boessenkool, [e-mail], Jul-Oct 2016

See Also

spiralDate, colPoints, https://waterdata.usgs.gov/nwis

Examples

# browseURL("https://nrfa.ceh.ac.uk/data/station/meanflow/39072")
qfile <- system.file("extdata/discharge39072.csv", package="berryFunctions")
Q <- read.table(qfile, skip=19, header=TRUE, sep=",", fill=TRUE)[,1:2]
rm(qfile)
colnames(Q) <- c("date","discharge")
Q$date <- as.Date(Q$date)
Q$discharge[450:581] <- NA
plot(Q, type="l")
seas <- seasonality(date, discharge, data=Q, shift=100, main="NRFA: Thames\nRoyal Windsor Park")
head(seas)
# notice how n for nonmissing values is lower in the first hydrological year,
# which includes parts of two consecutive calendarical years.

# Be careful with your interpretation. This looks normal up to 2007, but then BAM!:
seasonality(date, discharge, data=Q[Q$date<as.Date("2007-07-15"),], plot=3, shift=100, nmax=1)
seasonality(date, discharge, data=Q[Q$date<as.Date("2007-08-15"),], plot=3, shift=100, nmax=1)

# Shift is important. You don't want to have this event included twice:
seasonality(date, discharge, data=Q[850:950,], plot=3, nmax=1, quiet=TRUE, shift=100)

## Not run:  # excluded from CRAN checks because it is slow
seasonality(date, discharge, data=Q, plot=2) # most floods in winter
seasonality(date, discharge, data=Q, plot=5, vlab="Dude, look at annual max Q!")
seasonality(date, discharge, data=Q, plot=5, shift=100)
s <- seasonality(date, discharge, data=Q, plot=4, shift=100, width=3, returnall=TRUE)
str(s, max.lev=1)

seasonality(date, discharge, data=Q, plot=3:4, add=0:1, ylim=lim0(400), shift=117)
seasonality(date, discharge, data=Q, plot=4, add=TRUE, lwd=3, shift=117, width=3)

## End(Not run)

## Not run: 
dev.new(noRStudioGD=TRUE, record=TRUE)     # large graph on 2nd monitor
par(mfrow=c(2,2))
seasonality(date, discharge, data=Q, plot=(1:5)[-4], shift=100)
seasonality(date, discharge, data=Q, plot=(1:5)[-4], lwd=2)
seasonality(date, discharge, data=Q, plot=(1:5)[-4], nmax=1, shift=100)
seasonality(date, discharge, data=Q, plot=(1:5)[-4], col=divPal(100, ryb=TRUE))
dev.off()

## End(Not run)