fastcpd wrapper: fast changepoint detection via sequential gradient descent

Wraps the fastcpd package (Li and Zhang, 2024), a modern PELT-family engine that pairs pruning with sequential gradient descent so that exact or near-exact segmentations of many model families run in near-linear time. Every family the engine documents is reachable except its user-supplied custom cost: Gaussian mean, variance and both; the count and binary families ("poisson", "binomial") and waiting times ("exponential"); linear and penalised regression ("lm", "lasso") and generalised linear models ("poisson", "binomial" with covariates); and the time-series models "ar", "arma", "arima", "garch" and, for a multivariate series, "var".

Usage

fastcpd_wrapper(
  x,
  family = c("mean", "variance", "meanvariance", "ar", "arma", "arima", "garch", "var",
    "lm", "lasso", "poisson", "binomial", "exponential"),
  order = NULL,
  covariates = NULL,
  ...
)

Arguments

x: A numeric vector, or (for family "mean", "variance", "meanvariance" and "var") a matrix with one row per time point for multivariate detection.
family: Model family. "mean" (the default), "variance", "meanvariance"; "poisson", "binomial", "exponential" (a change in the rate or probability of a count, binary or waiting-time series, or in a regression on covariates); "lm", "lasso" (regression, which needs covariates); "ar", "arma", "arima", "garch", "var".
order: Model order for "ar" and "var" (a single integer), "arma" and "garch" (length 2) or "arima" (length 3). Defaults to 1 for AR and VAR, c(1, 1) for ARMA and GARCH and c(1, 0, 0) for ARIMA.
covariates: Optional numeric matrix of regressors, one row per observation, for "lm", "lasso", "poisson" and "binomial". Include a column of ones for an intercept. Without it the count and binary families fit an intercept only: a change in the rate or probability. cpt_detect() builds it from a formula.
...: Additional arguments passed to the corresponding fastcpd::fastcpd.*() function (e.g. beta, trim). beta is fastcpd's penalty: a number, or one of its own names ("MBIC", the default, "BIC", "MDL"). It is recorded on the result, so print() and glance() report the penalty the fit actually used. cpt_detect() forwards a numeric penalty here and translates the three names it shares with fastcpd; see the penalty-semantics section of cpt_penalty().

Value

A ggcpt object. The engine's per-segment parameter estimates (thetas) are kept as $coefficients, one row per segment and parameter, for the families where they are coefficients (the regressions and the intercept-only count, binary and waiting-time models).

References

Li X, Zhang X (2024). “fastcpd: Fast change point detection in R.” arXiv preprint arXiv:2404.05933.

Other changepoint engines: bcp_wrapper(), beast_wrapper(), bfast_wrapper(), binsegrcpp_wrapper(), bocpd_wrapper(), cpm_wrapper(), cpop_wrapper(), cpt_wrapper(), decafs_wrapper(), ecp_wrapper(), envcpt_wrapper(), esac_wrapper(), fabisearch_wrapper(), fcov_wrapper(), fmean_wrapper(), fpop_wrapper(), geomcp_wrapper(), hdcov_wrapper(), hdreg_wrapper(), idetect_wrapper(), inspect_wrapper(), kcp_wrapper(), kwc_wrapper(), mcp_wrapper(), mosum_wrapper(), network_wrapper(), not_wrapper(), npmojo_wrapper(), nsp_wrapper(), ocd_wrapper(), pilliat_wrapper(), segmented_wrapper(), smuce_wrapper(), sn_wrapper(), strucchange_wrapper(), taylor_wrapper(), tguh_wrapper(), trend_wrapper(), var_wrapper(), wbs2_wrapper(), wbs_wrapper(), wbsts_wrapper()

Examples

set.seed(2026)
res <- fastcpd_wrapper(c(rnorm(100), rnorm(100, 4)))
res$changepoints
#> # A tibble: 1 × 2
#>      cp cp_value
#>   <int>    <dbl>
#> 1   100    0.369

# A change in a Poisson rate
counts <- fastcpd_wrapper(c(rpois(100, 3), rpois(100, 9)),
                          family = "poisson")
counts$changepoints
#> # A tibble: 1 × 2
#>      cp cp_value
#>   <int>    <dbl>
#> 1   100        5