Skip to contents

Block series: annual maxima and other block extremes

Source: R/timeseries.R
ts_block_series.Rd

Reduces a series to one value per time block – the classical first step of a flood-frequency analysis. ts_water_year() and ts_calendar_year() are the two common cases by name.

Usage

ts_block_series(
  ts,
  window = c("water_year", "calendar_year", "custom_year", "quarter", "month"),
  block = c("maximum", "minimum", "average", "sum"),
  smoothing = c("none", "moving_average", "moving_sum", "difference"),
  period = 1,
  start_month = 10,
  end_month = 9
)

ts_water_year(
  ts,
  block = "maximum",
  smoothing = "none",
  period = 1,
  start_month = 10
)

ts_calendar_year(ts, block = "maximum", smoothing = "none", period = 1)

Arguments

ts

a corehydro_ts.

window

"water_year", "calendar_year", "custom_year", "quarter" or "month".

block

the block function: "maximum" (the default), "minimum", "average" or "sum".

smoothing

"none" (the default), "moving_average", "moving_sum" or "difference".

period

the smoothing window (or the difference lag). Default 1, which is a no-op for the two moving windows.

start_month

the month a water year or custom year begins. Default 10 (October).

end_month

the month a custom year ends. Default 9 (September).

Value

a corehydro_ts on the "irregular" interval.

Details

The result is an IRREGULAR series carrying the date of the observation the block function selected: for "minimum" and "maximum" that is the extreme observation's own date, and for "sum" and "average" it is the block's last date.

A block whose values include a missing one is dropped by "sum" and "average" (the missing value propagates) but kept by "minimum" and "maximum" (the comparison is false against a missing value, so it is simply never selected). That is the library's behaviour and it is worth knowing before reading an annual maximum series built from a gappy record.

smoothing applies BEFORE the block function, which is how an n-day average maximum is built: ts_water_year(ts, smoothing = "moving_average", period = 7) is the annual maximum 7-day mean.

See also

ts_peaks_over_threshold() for the partial-duration alternative, fit_mle() for fitting the result.

Examples

dates <- seq(as.Date("2000-01-01"), by = "month", length.out = 36)
ts <- time_series(dates, c(5, 9, 3, 7, 2, 8, 4, 6, 1, 5, 7, 3,
                           6, 2, 8, 4, 9, 3, 7, 5, 2, 8, 4, 6,
                           3, 7, 5, 9, 2, 6, 4, 8, 1, 5, 3, 7))
ts_water_year(ts)
#> <corehydro_ts> 4 ordinates, interval "irregular"
#>   2000-02-01 to 2002-12-01
#>   2000-02-01  9
#>   2001-05-01  9
#>   2002-04-01  9
#>   2002-12-01  7