Batch changepoint detection over many series — cpt

Runs one detector over every series in a collection — the panel-data loop that methodological and applied work both need constantly. Accepts a matrix/data frame (one column per series) or a named list of numeric vectors. Honours future::plan() for parallel execution when the future.apply package is available, with parallel-safe RNG.

Usage

cpt_batch(
  x,
  method = "pelt",
  change_in = "mean",
  index = NULL,
  seed = NULL,
  keep_fit = TRUE,
  ...
)

# S3 method for class 'ggcpt_batch'
print(x, ...)

# S3 method for class 'ggcpt_batch'
tidy(x, ...)

# S3 method for class 'ggcpt_batch'
autoplot(object, ...)

Arguments

x: For cpt_batch(), a numeric matrix or data frame (columns are series) or a list of numeric vectors; for the print() and tidy() methods, a ggcpt_batch object.
method: Detection method, passed to cpt_detect().
change_in: What to detect change in, passed to cpt_detect().
index: Optional time index shared by every series in the panel (a vector of dates, say), or a named list of one index per series. Carried onto each result and used by tidy() and autoplot(), so a faceted plot of fifty series shows dates rather than positions.
seed: Optional seed for reproducible parallel execution (passed to future.apply::future_lapply() as future.seed; applied via set.seed() when running sequentially).
keep_fit: Keep each engine's raw fit in result[[i]]$fit? Defaults to TRUE, which is what makes a batch result as inspectable as a single one. Set it to FALSE for a large panel: a few engines return fits far bigger than the data they were given — strucchange keeps a triangular $O(n^2)$ RSS matrix, so a single 2000-point series costs about 135 MB, and bfast and bocpd are in the tens of MB — and a panel multiplies that by the number of series. Everything else on the object, including tidy() and autoplot(), is unaffected; only accessors that read $fit (cpt_statistic(), ggcpt_posterior(), cpt_confint(engine = \"native\")) need it.
...: Additional arguments passed to every cpt_detect() call.
object: A ggcpt_batch object (for autoplot()).

Value

A ggcpt_batch object: a tibble with one row per series and columns series, n_changepoints, changepoints (a list-column of tidy tibbles), and result (a list-column of ggcpt objects). Methods: print(), tidy() (one row per changepoint across all series), and autoplot() (faceted small-multiples with each series' changepoints).

Examples

set.seed(2026)
X <- cbind(a = c(rnorm(60), rnorm(60, 4)), b = rnorm(120))
batch <- cpt_batch(X, method = "pelt")
batch
#> ggcpt_batch (2 series, method: pelt)
#> 
#> # A tibble: 2 × 2
#>   series n_changepoints
#>   <chr>           <int>
#> 1 a                   1
#> 2 b                   0
tidy(batch)
#> # A tibble: 1 × 3
#>   series    cp cp_value
#>   <chr>  <int>    <dbl>
#> 1 a         60   -0.999
ggplot2::autoplot(batch)