get_peak_times: Find times of peaks in periodic time series

Description Usage Arguments Value Bandwidth tuning Missed peaks References Examples

View source: R/get_peak_times.R

Description

get_peak_times() locates peaks in periodic, equally spaced time series with known period. It applies a central moving average to the raw time series, identifies when peaks occur in the resulting smooth time series, and subsets those peaks in phase with the first peak.

Usage

1
get_peak_times(x, period, bw_mavg, bw_peakid)

Arguments

x

Numeric vector. A periodic, equally spaced time series. Time points are taken to be seq_along(x).

period

Numeric scalar. The period of x in units of the observation interval.

bw_mavg

Numeric scalar. Bandwidth for the central moving average applied to x. x_mavg[i] will be the mean of the set of observations x[j] with |ij| ≤ bandwidth.

bw_peakid

Numeric scalar. Bandwidth for peak identification. i will be a peak time if and only if x_mavg[i] > x_mavg[j] for all j with 0 < &vert;ij&vert; ≤ bandwidth.

Value

A list containing:

x_mavg

Numeric vector. The result of applying a 2 * bw_mavg + 1 point central moving average to x.

all

Numeric vector. A subset of seq_along(x) listing the times of all identified peaks.

phase

Numeric vector. A subset of seq_along(x) listing the times of all identified peaks in phase with the first peak.

A list of the arguments of get_peak_times() is included as an attribute.

Bandwidth tuning

The bandwidths bw_mavg and bw_peakid must be iteratively tuned so as to disqualify peaks caused by noise in x (choose bw_mavg large enough) without disqualifying true peaks (choose bw_peakid not too large). Tuning is not done internally.

Missed peaks

get_peak_times() will not detect peaks at the edges of x. Specifically, it will not detect a peak at index i if:

get_peak_times() will miss peaks in other, typically rare situations. For example, a peak at index i will be missed if, by chance, x_mavg[i] = x_mavg[i+1] (i.e., there are two points of equal height at the top of the peak instead of a single highest point). See the definition of bw_peakid.

References

deJonge MS, Jagan M, Krylova O, Earn DJD. Fast estimation of time-varying transmission rates for infectious diseases.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# Simulate 20 years of disease incidence,
# observed weekly
par_list <- make_par_list(dt_weeks = 1)
df <- make_data(
  par_list = par_list,
  n = 20 * 365 / 7, # 20 years is ~1042 weeks
  with_dem_stoch = TRUE,
  seed = 5
)

# Plot incidence time series, and note the
# apparent 1-year period
plot(Z ~ t_years, df,
  type = "l",
  xlab = "Time (years)",
  ylab = "Incidence"
)

# Find peaks in incidence time series
peaks <- get_peak_times(
  x = df$Z,
  period = 365 / 7, # 1 year is ~52 weeks
  bw_mavg = 6,
  bw_peakid = 8
)

# Verify that peaks were identified correctly
abline(v = df$t_years[peaks$all], lty = 2, col = "red")

davidearn/fastbeta documentation built on June 14, 2020, 3:11 p.m.