Multi-Bubble SSR/BIC Dating (Harvey, Leybourne & Whitehouse 2020)

dating_hlw(
  data,
  cv = NULL,
  minw = NULL,
  trim = 0.1,
  min_duration = NULL,
  nboot = 199L,
  seed = NULL,
  join = 3L
)

dating_hlw extends dating_hls to series with more than one explosive episode. It first runs the existing detection and dating of PSY (radf and datestamp) to locate a preliminary start and end for each episode. It then splits the sample into disjoint date windows around them and dates each window again with the SSR/BIC fitting of dating_hls, restricted to Models 2 and 4 for every window except the last.

Arguments

data	A univariate or multivariate numeric time series object, a numeric vector or matrix, or a data.frame. A column may have leading or trailing NA values, which describes an unbalanced panel in which series enter or exit the sample at different times. Those periods are filled with NA in badf and bsadf and excluded from the adf, sadf and gsadf of that series. Interior NA values (a gap in the middle of a series) are not supported. When any series is padded in this way, the panel statistics (bsadf_panel and gsadf_panel) are not available, and the function returns NA for them with a warning.
cv	Critical values for the step-1 PSY detection and dating, as accepted by datestamp. The default NULL computes radf_wb_cv internally.
minw	Minimum window size for the step-1 radf call. The default is psy_minw.
trim	Minimum fraction of the (differenced) sample required in every regime (default 0.05, following the choice of Harvey, Leybourne & Sollis in their empirical application. Their simulations use 0.1).
min_duration	Minimum duration (in observations) for a step-1 PSY episode to be counted. The default is psy_ds (the $\ln(T)$ rule of HLW).
nboot, seed	Passed to radf_wb_cv when cv is not supplied.
join	The run-joining rule of HLW for fragmented step-1 detections. Two explosive runs that are separated by at most join non-rejections and are each at least $\ln(T)$ long are treated as one episode. The default is 3, the value in the paper, and 0 disables joining.

Value

An object of class dating_hlw_obj: a list with one element for each series. Each element is a data frame with one row for each detected episode (model, origination, collapse, recovery). A series with no step-1 detected episode gets a data frame with zero rows.

Details

When exactly one episode is detected, the function reduces to dating_hls applied to the whole series, which is a stated property of the paper. The single window then runs over [1, n] and fits all four models.

res <- dating_hlw(sim_data$psy1, trim = 0.1, nboot = 199L, seed = 1)
print(res)
#> 
#> ── dating_hlw (n = 100, trim = 0.1) ────────────────────────────────────────────
#> 
#> series1:
#>  model origination collapse recovery
#>      4          41       55       71

# Plot the breakpoints of every detected episode over the series
autoplot(res)

# A two-bubble series, for which dating_hls() alone would fit only one bubble
res2 <- dating_hlw(sim_psy2(n = 200, seed = 123), trim = 0.1, nboot = 199L, seed = 1)
autoplot(res2)