Learn R Programming

berryFunctions (version 1.22.5)

seasonality: 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,
  ...
)

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.

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.

Author

Berry Boessenkool, berry-b@gmx.de, Jul-Oct 2016

See Also

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

Examples

Run this code
# 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

Run the code above in your browser using DataLab