Package {ggchangepoint}

ggchangepoint package

Description

Unified tidy changepoint detection with ggplot2 visualisation.

Details

ggchangepoint provides a consistent S3 result class (ggcpt) for changepoint detection results, broom-style methods (tidy(), glance(), augment()), ggplot2 integration via autoplot() and composable geoms (geom_changepoint(), geom_cpt_segment(), geom_cpt_ci(), geom_cpt_region(), geom_cpt_label(), geom_cpt_event(), stat_changepoint()), and a unified dispatcher cpt_detect() that reaches fifty methods.

Detection engines. cpt_detect() dispatches to the methods in cpt_methods(), across nine families:

• Penalised/optimal: PELT, BinSeg, SegNeigh, AMOC (changepoint); FPOP (fpop); fast binary segmentation (binsegRcpp); the CROPS penalty path (cpt_crops()); fastcpd (fastcpd, incl. AR/ARMA/GARCH); change-in-slope via CPOP (cpop).

• Multiscale/search: WBS (wbs), WBS2 and TGUH (breakfast), NOT (not), MOSUM incl. multiscale (mosum), Isolate-Detect (IDetect), SMUCE/HSMUCE with confidence intervals (stepR), WBS for nonstationary series (wbsts).

• Inference: Narrowest Significance Pursuit (nsp), which returns intervals rather than points.

• Nonparametric/kernel: NP (changepoint.np), E-Divisive/E-Agglo (ecp), kernel running statistics (kcpRS), NP-MOJO (CptNonPar), sequential CPM (cpm), self-normalisation (SNSeg), depth ranks (KWCChangepoint).

• Bayesian: Barry-Hartigan posterior (bcp), online BOCPD (ocp), BEAST model averaging (Rbeast), formula-based regression with changepoints (mcp).

• High-dimensional: sparse projection (InspectChangepoint), online ocd (ocd), geometric mapping (changepoint.geo), sparsity-adaptive ESAC and Pilliat (HDCD), and covariance, network, VAR and high-dimensional-regression changes (changepoints).

• Functional and network: functional mean and covariance (fChange), NMF-based network structure (fabisearch).

• Regression, trend and season: Bai-Perron breaks with CIs (strucchange), broken-line regression (segmented), changepoints-vs-autocorrelation model selection (EnvCpt), drift+AR robust detection (DeCAFS), BFAST season-and-trend breaks (bfast).

• Classical single-change tests: Pettitt, Buishand and SNHT (trend), Taylor's analyzer (ChangePointTaylor).

What surrounds the detectors. Every detector returns a ggcpt object with a stable tibble(cp, cp_value) contract, optionally carrying a time index, engine confidence intervals, a fitted signal, significance regions and diagnostics. Around that:

• Inference: cpt_confint() (four provenances, one contract), cpt_test(), cpt_regions().

• Choosing K: cpt_select() (BIC, Zhang-Siegmund mBIC, AIC, CROPS elbow, cross-validation, stability), cpt_crops(), cpt_penalty().

• Diagnostics: cpt_influence(), cpt_leverage(), cpt_sensitivity(), cpt_stability(), cpt_statistic(), cpt_solution_path(), cpt_scale_space().

• Supervised detection: cpt_labels(), cpt_label_error(), cpt_label_error_curve(), cpt_learn_penalty().

• Choosing a method: cpt_recommend(), cpt_consensus(), ggcpt_compare().

• Evaluation: cpt_metrics(), cpt_metrics_annotated(), cpt_benchmark(), cpt_datasets(), cpt_load_tcpd().

• Streaming: cpt_monitor(), cpt_update(), alarms(), cpt_replay(), cpt_delay().

• Study design: cpt_simulate(), cpt_power(), cpt_min_detectable(), cpt_scenarios().

• Communication: cpt_annotate_events(), cpt_report(), cpt_gt(), ggcpt_interactive(), cpt_cite().

• Extension: as_ggcpt() and cpt_register_method() bring detectors this package does not and cannot depend on into the same grammar.

Author(s)

Maintainer: Youzhi Yu yuyouzhi666@icloud.com

See Also

The entry points, by group:

• Detect: cpt_detect(), cpt_methods(), cpt_register_method().

• Visualise: autoplot.ggcpt(), ggcptplot(), ggcpt_compare().

• Inference and selection: cpt_confint(), cpt_test(), cpt_select().

• Choosing and combining methods: cpt_consensus(), cpt_recommend(), cpt_benchmark().

• Evaluation: cpt_metrics().

• Streaming: cpt_monitor().

• Study design: cpt_simulate(), cpt_power().

• Communication: cpt_report().

Useful links:

• https://pursuitofdatascience.github.io/ggchangepoint/

• Report bugs at https://github.com/PursuitOfDataScience/ggchangepoint/issues

The alarm log of a monitor

Description

Every observation at which a sequential monitor crossed its threshold, in the order they fired. A monitor that never fired returns a zero-row tibble rather than NULL, so the result is always safe to rbind() or plot.

Usage

alarms(x, ...)

## S3 method for class 'ggcpt_monitor'
alarms(x, ...)

Arguments

Value

A tibble with one row per alarm: time (the observation at which it fired, counted from the first one fed to the monitor), statistic and threshold.

See Also

cpt_monitor(), cpt_delay().

Examples

set.seed(2026)
mon <- cpt_monitor("edetector", baseline = rnorm(100))
mon <- cpt_update(mon, c(rnorm(50), rnorm(50, 3)))
alarms(mon)

Annotate segments with alternating shading

Description

Adds alternating shaded rectangles to highlight segments between changepoints.

Usage

annotate_segments(cp, n, fill = c("grey90", "white"), alpha = 0.5, ...)

Arguments

Value

A list of ggplot annotations.

See Also

Other result class: as_cpt_series(), as_ggcpt(), cpt_annotations(), is_ggcpt(), new_ggcpt(), print.ggcpt()

Examples

library(ggplot2)
set.seed(2026)
fit <- cpt_detect(c(rnorm(50), rnorm(50, 4)), method = "pelt")
ggplot(fit$data, aes(index, value)) +
  annotate_segments(fit$changepoints$cp, n = nrow(fit$data)) +
  geom_line()

Coerce annotations to changepoint labels

Description

Turns a plain ground-truth changepoint set (the kind cpt_metrics() takes) into labelled regions, so one annotation can drive both the metric and the supervised machinery. Each true changepoint becomes a "one_change" region of width 2 * margin + 1, and the stretches between them become "no_change" regions.

Usage

as_cpt_labels(truth, n, margin = 5, negatives = TRUE, series = NA_character_)

Arguments

Value

A cpt_labels tibble.

Examples

as_cpt_labels(c(50, 120), n = 200)

Coerce a time series object to values plus a time index

Description

Detection itself runs on positions (every wrapped engine assumes an equally spaced sequence), but real series carry dates, and reporting a changepoint as "index 147" when the data are monthly rainfall is an unnecessary translation step for the user. as_cpt_series() is the one place that separates the two: it pulls the numeric values out of a ts, xts, zoo, tsibble or data frame and returns the time index alongside them, so cpt_detect() can detect on positions and report on dates.

Usage

as_cpt_series(x, index = NULL, check_regular = TRUE)

Arguments

Value

A list with components values (a numeric vector, or a matrix for multivariate input), index (the time index, or NULL when there is none), index_label (a name for the x axis) and frequency (the seasonal frequency a ts carried, or NULL; cpt_detect() hands this to the engines that need one, such as bfast_wrapper()).

See Also

Other result class: annotate_segments(), as_ggcpt(), cpt_annotations(), is_ggcpt(), new_ggcpt(), print.ggcpt()

Examples

as_cpt_series(1:10)$index
s <- as_cpt_series(1:10, index = as.Date("2020-01-01") + 0:9)
s$index

Turn external changepoints into a ggcpt result

Description

Wraps a set of changepoint locations (from a detector this package does not wrap, a Python tool called through reticulate, a neural detector, a published paper's reported breaks, or an analyst's own annotations) into a first-class ggcpt object. Everything built on the ggcpt contract then applies: autoplot(), the composable geoms, tidy()/glance()/augment(), cpt_metrics(), cpt_consensus(), cpt_report().

Usage

as_ggcpt(
  cp,
  x,
  fitted = NULL,
  method = "custom",
  change_in = "mean",
  ci = NULL,
  regions = NULL,
  penalty = NULL,
  cp_convention = c("left", "right"),
  index = NULL,
  fit = NULL,
  extra = NULL
)

Arguments

Value

A ggcpt object, with the same components as any detector in the package returns (see new_ggcpt() for the full list, and cpt_detect() for the summary).

See Also

cpt_register_method() to make cpt_detect() dispatch to an external detector by name.

Other result class: annotate_segments(), as_cpt_series(), cpt_annotations(), is_ggcpt(), new_ggcpt(), print.ggcpt()

Examples

set.seed(2026)
x <- c(rnorm(60), rnorm(60, 4))
fit <- as_ggcpt(c(60), x, method = "my_detector")
fit
tidy(fit)

Augment a ggcpt object

Description

Returns the original data with added columns: seg_id, .fitted, .resid, and is_changepoint.

Usage

## S3 method for class 'ggcpt'
augment(x, ...)

Arguments

Details

For a multivariate result every coordinate is returned, but the changepoints are shared across them, so seg_id and is_changepoint apply to the whole row while .fitted and .resid describe the univariate series the result carries: $data$value, the same series $segments$param_estimate summarises, so .resid is always value - .fitted. For most multivariate engines that series is the first coordinate; fmean, fcov, kwc and fabisearch store the cross-sectional mean rowMeans() instead, and for those .fitted/.resid describe that mean rather than any one column. Either way the two columns agree with each other, which is what makes .resid a residual. When an engine supplies its own fitted signal that signal is used for .fitted in place of the segment means, and rides along in a fitted column of its own, so for those engines the two columns agree. The engines that do this are exactly the ones cpt_methods() marks in its fitted column: smuce, hsmuce, cpop, bcp, beast, decafs, segmented, mcp and bfast.

Value

A tibble with one row per observation: the data as the result carries it, plus four added columns. The data half depends on the result: index and value for a univariate one, index plus one column per coordinate (named as the input's columns were) for a multivariate one, and an extra fitted column for the engines that supply their own fitted signal. The added four are always the same:

seg_id

which segment the observation falls in, counting from 1.

.fitted

the segment's param_estimate: the segment mean, for every method in the package, or the engine's own fitted signal where there is one. See the details below for the multivariate case.

.resid

value - .fitted, against the univariate series the result carries.

is_changepoint

TRUE at each detected location, under the result's cp_convention.

Measured on a pelt fit the columns are index, value, seg_id, .fitted, .resid, is_changepoint.

Autoplot a ggcpt object

Description

Renders a changepoint detection result as a ggplot. The raw series is drawn as a line (with optional points), changepoints are shown as vertical lines, and (optionally) fitted segment levels, the engine's fitted signal, and changepoint-location confidence intervals are overlaid. Multivariate results (from ecp, inspect, geomcp, ...) are drawn as faceted small-multiples with shared changepoint rules.

Usage

## S3 method for class 'ggcpt'
autoplot(
  object,
  show_segments = FALSE,
  show_ci = FALSE,
  show_fit = FALSE,
  show_regions = NULL,
  cptline_alpha = 1,
  cptline_color = "blue",
  cptline_type = "solid",
  cptline_linewidth = 0.5,
  show_points = NULL,
  show_line = TRUE,
  index = NULL,
  labels = NULL,
  type = c("series", "statistic", "path", "scale_space"),
  ...
)

Arguments

Value

A ggplot object.

See Also

ggcpt_plot_methods for the base plot() methods that delegate here, and theme_ggcpt() and geom_changepoint() for restyling and re-assembling the layers by hand.

Bayesian changepoint wrapper (Barry-Hartigan product partition model)

Description

Wraps bcp::bcp(), the MCMC implementation (Erdman and Emerson, 2007) of the Barry and Hartigan (1993) product partition model. The engine returns a posterior probability of a changepoint at every location; locations whose posterior probability reaches prob_threshold are reported as changepoints, and the full probability profile is kept so that ggcpt_posterior() can draw the classic two-panel posterior plot.

Usage

bcp_wrapper(x, prob_threshold = 0.5, burnin = 50, mcmc = 500, seed = NULL, ...)

Arguments

Value

A ggcpt object. The changepoints tibble carries a posterior_prob column, and the data tibble carries the posterior mean in its fitted column.

References

Barry D, Hartigan JA (1993). “A Bayesian analysis for change point problems.” Journal of the American Statistical Association, 88(421), 309–319.

Erdman C, Emerson JW (2007). “bcp: An R package for performing a Bayesian analysis of change point problems.” Journal of Statistical Software, 23(3), 1–13.

See Also

Other changepoint engines: beast_wrapper(), bfast_wrapper(), binsegrcpp_wrapper(), bocpd_wrapper(), cpm_wrapper(), cpop_wrapper(), cpt_wrapper(), decafs_wrapper(), ecp_wrapper(), envcpt_wrapper(), esac_wrapper(), fabisearch_wrapper(), fastcpd_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

res <- bcp_wrapper(c(rnorm(60), rnorm(60, 4)), seed = 2026)
res$changepoints
ggcpt_posterior(res)

BEAST wrapper: Bayesian estimation of abrupt change, seasonality, and trend

Description

Wraps Rbeast::beast() (Zhao et al., 2019), a Bayesian model-averaging ensemble that estimates the number and location of trend changepoints together with their posterior occurrence probabilities. Locations whose posterior probability reaches prob_threshold are reported; the probability profile renders via ggcpt_posterior().

Usage

beast_wrapper(x, prob_threshold = 0.5, seed = NULL, ...)

Arguments

Value

A ggcpt object. The changepoints tibble carries posterior_prob, and the data tibble carries the posterior mean trend in its fitted column.

References

Zhao K, Wulder MA, Hu T, Bright R, Wu Q, Qin H, Li Y, Toman E, Mallick B, Zhang X, Brown M (2019). “Detecting change-point, trend, and seasonality in satellite time series data to track abrupt changes and nonlinear dynamics: A Bayesian ensemble algorithm.” Remote Sensing of Environment, 232, 111181.

See Also

Other changepoint engines: bcp_wrapper(), bfast_wrapper(), binsegrcpp_wrapper(), bocpd_wrapper(), cpm_wrapper(), cpop_wrapper(), cpt_wrapper(), decafs_wrapper(), ecp_wrapper(), envcpt_wrapper(), esac_wrapper(), fabisearch_wrapper(), fastcpd_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

# try(): Rbeast intermittently returns an all-NaN fit and the condition
# can persist for a session, so a check must not fail on it -- the
# wrapper reports it by name when it happens.
res <- try(beast_wrapper(c(rnorm(60), rnorm(60, 4)), seed = 2026),
           silent = TRUE)
if (!inherits(res, "try-error")) res$changepoints

BFAST wrapper: breaks for additive season and trend

Description

Wraps the bfast family (Verbesselt et al.), the standard tool in remote sensing and land-cover monitoring. BFAST decomposes a seasonal series into trend and seasonal components and detects breaks in each separately, which is the right question for satellite time series where a shift in phenology and a shift in level mean different things.

Usage

bfast_wrapper(
  x,
  frequency = 12,
  change_in = c("mean", "slope", "seasonality"),
  h = 0.15,
  season = c("harmonic", "dummy", "none"),
  max_iter = 5,
  ...
)

Arguments

Value

A ggcpt object whose fitted column holds the estimated trend component (so autoplot(show_fit = TRUE) draws it) and whose changepoints carry ci_lower/ci_upper from strucchange's break-date intervals when available.

References

Verbesselt J, Hyndman R, Newnham G, Culvenor D (2010). “Detecting trend and seasonal changes in satellite image time series.” Remote Sensing of Environment, 114(1), 106–115. doi:10.1016/j.rse.2009.08.014.

See Also

Other changepoint engines: bcp_wrapper(), beast_wrapper(), binsegrcpp_wrapper(), bocpd_wrapper(), cpm_wrapper(), cpop_wrapper(), cpt_wrapper(), decafs_wrapper(), ecp_wrapper(), envcpt_wrapper(), esac_wrapper(), fabisearch_wrapper(), fastcpd_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)
season <- rep(sin(seq(0, 2 * pi, length.out = 12)), 10)
y <- stats::ts(c(rnorm(60, 1), rnorm(60, 5)) + season,
               frequency = 12, start = c(2000, 1))
bfast_wrapper(y)

Fast binary segmentation across loss functions

Description

Wraps binsegRcpp::binseg() (Hocking): a C++ binary segmentation that runs in O(n \log n) for the best case and supports several loss functions, including ones no other engine here offers (Poisson, \ell_1). It is the package's performance path for binary segmentation on long series, and it returns the whole nested family of segmentations, so it also feeds cpt_solution_path().

Usage

binsegrcpp_wrapper(
  x,
  change_in = c("mean", "meanvar"),
  distribution = NULL,
  max_segments = NULL,
  n_segments = NULL,
  min_segment_length = NULL
)

Arguments

Value

A ggcpt object.

References

Hocking TD (2024). “Finite sample complexity analysis of binary segmentation.” arXiv preprint arXiv:2410.08654. doi:10.48550/arXiv.2410.08654.

See Also

Other changepoint engines: bcp_wrapper(), beast_wrapper(), bfast_wrapper(), bocpd_wrapper(), cpm_wrapper(), cpop_wrapper(), cpt_wrapper(), decafs_wrapper(), ecp_wrapper(), envcpt_wrapper(), esac_wrapper(), fabisearch_wrapper(), fastcpd_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)
binsegrcpp_wrapper(c(rnorm(100), rnorm(100, 3)))

Bayesian online changepoint detection wrapper (BOCPD)

Description

Wraps ocp::onlineCPD(), an implementation of Bayesian Online Changepoint Detection (Adams and MacKay, 2007). BOCPD recursively updates a posterior over the current run length (time since the last change); the maximum a posteriori set of changepoints is reported, and the full run-length posterior is kept so that ggcpt_runlength() can draw the signature run-length heatmap.

Usage

bocpd_wrapper(x, hazard = 100, ...)

Arguments

Value

A ggcpt object with the MAP changepoint set. The full ocp fit (including the run-length posterior) is kept in $fit.

References

Adams RP, MacKay DJ (2007). “Bayesian online changepoint detection.” arXiv preprint arXiv:0710.3742.

See Also

Other changepoint engines: bcp_wrapper(), beast_wrapper(), bfast_wrapper(), binsegrcpp_wrapper(), cpm_wrapper(), cpop_wrapper(), cpt_wrapper(), decafs_wrapper(), ecp_wrapper(), envcpt_wrapper(), esac_wrapper(), fabisearch_wrapper(), fastcpd_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

res <- bocpd_wrapper(c(rnorm(60), rnorm(60, 4)))
res$changepoints
ggcpt_runlength(res)

Sequential change point model wrapper (CPM)

Description

Wraps cpm::processStream() (Ross, 2015) for distribution-free sequential changepoint detection via repeated two-sample tests (Mann-Whitney for location, Mood for scale, Lepage, Kolmogorov-Smirnov and Cramer-von-Mises for general changes, and parametric Student/Bartlett/GLR variants). Although the engine is designed for streams, it is run here over the full series in one pass, mimicking online monitoring with average run length arl0.

Usage

cpm_wrapper(x, cpm_type = "Mann-Whitney", arl0 = 500, startup = 20, ...)

Arguments

Value

A ggcpt object. The changepoints tibble carries a detection_time column: the index at which the sequential test flagged each change (always later than the estimated location).

References

Ross GJ (2015). “Parametric and nonparametric sequential change detection in R: The cpm package.” Journal of Statistical Software, 66(3), 1–20.

See Also

Other changepoint engines: bcp_wrapper(), beast_wrapper(), bfast_wrapper(), binsegrcpp_wrapper(), bocpd_wrapper(), cpop_wrapper(), cpt_wrapper(), decafs_wrapper(), ecp_wrapper(), envcpt_wrapper(), esac_wrapper(), fabisearch_wrapper(), fastcpd_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

res <- cpm_wrapper(c(rnorm(100), rnorm(100, 3)))
res$changepoints

CPOP wrapper: optimal change-in-slope detection

Description

Wraps cpop::cpop() (Fearnhead, Maidstone and Letchford, 2019; Fearnhead and Grose, 2024): exact penalised estimation of a continuous piecewise-linear mean via dynamic programming with functional pruning. This is the engine behind cpt_detect(change_in = "slope"). The fitted broken line is stored in the fitted column and renders via autoplot(show_fit = TRUE).

Usage

cpop_wrapper(x, penalty = NULL, sd = NULL, ...)

Arguments

Value

A ggcpt object with change_in = "slope". For a continuous fit the reported location is the kink point itself.

References

Fearnhead P, Maidstone R, Letchford A (2019). “Detecting changes in slope with an L0 penalty.” Journal of Computational and Graphical Statistics, 28(2), 265–275.

Fearnhead P, Grose D (2024). “cpop: Detecting changes in piecewise-linear signals.” Journal of Statistical Software, 109(7), 1–30.

See Also

Other changepoint engines: bcp_wrapper(), beast_wrapper(), bfast_wrapper(), binsegrcpp_wrapper(), bocpd_wrapper(), cpm_wrapper(), cpt_wrapper(), decafs_wrapper(), ecp_wrapper(), envcpt_wrapper(), esac_wrapper(), fabisearch_wrapper(), fastcpd_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)
y <- cumsum(c(rep(0.3, 100), rep(-0.4, 100))) + rnorm(200)
res <- cpop_wrapper(y)
res$changepoints
ggplot2::autoplot(res, show_fit = TRUE)

Match detected changepoints to known events

Description

Joins a table of real-world events to a detection result and reports all three outcomes: changepoints an event explains, changepoints no event explains, and events no changepoint found. Matching reuses the same tolerance rule as cpt_metrics() and cpt_consensus(), so the package has one notion of "close enough" throughout.

Usage

cpt_annotate_events(
  object,
  events,
  location = NULL,
  label = NULL,
  tolerance = 5
)

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

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

## S3 method for class 'ggcpt_events'
autoplot(object, repel = NULL, ...)

Arguments

Value

A ggcpt_events object: a list with

matched

one row per matched pair: cp, event, event_value (the event's own location, on the index scale when it was given as one), event_position (that location as a position in the series) and distance.

unexplained

detected changepoints with no event (cp).

undetected

events with no changepoint (event, event_value, event_position).

matched and unexplained carry cp_index, the changepoint on the original scale, when (and only when) the result carries a time index, so "cp_index" %in% names(x) is the test for it.

tidy() flattens those three slots into one table with a status column, and the row count is therefore the number of changepoints plus the number of events, not either one alone. The three values are "matched" (a pair: both cp and event filled, with distance), "unexplained_changepoint" (a changepoint with no event: cp filled, event and distance NA) and "undetected_event" (an event with no changepoint: event and position filled, cp and distance NA).

Filter on status, not on is.na(cp). An "unexplained_changepoint" row has a non-missing cp, so subset(tidy(x), !is.na(cp)) returns the matched pairs and the unexplained changepoints, which is the natural mistake to make, and it silently overstates how many changepoints an event explains. With print(), tidy() and autoplot().

See Also

geom_cpt_event(), cpt_report().

Examples

set.seed(2026)
x <- c(rnorm(60), rnorm(60, 4))
dates <- as.Date("2020-01-01") + 0:119
fit <- cpt_detect(x, method = "pelt", index = dates)
events <- data.frame(when = as.Date(c("2020-03-01", "2020-04-15")),
                     what = c("policy change", "supply shock"))
cpt_annotate_events(fit, events)

Per-annotator ground truth for a benchmark dataset

Description

Returns the annotation sets of a dataset one row per (annotator, changepoint), so the disagreement between human annotators is visible instead of averaged away.

Usage

cpt_annotations(dataset)

Arguments

Value

A tibble with dataset, annotator and cp.

See Also

cpt_metrics_annotated().

Other result class: annotate_segments(), as_cpt_series(), as_ggcpt(), is_ggcpt(), new_ggcpt(), print.ggcpt()

Examples

cpt_annotations(cpt_datasets(n = 200, names = "step"))

Batch changepoint detection over many series

Description

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

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, with columns series, cp and cp_value), 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
tidy(batch)
ggplot2::autoplot(batch)

Benchmark detectors across datasets

Description

Runs a grid of methods over a collection of labelled series and scores every cell with cpt_metrics() (or cpt_metrics_annotated() when a dataset carries several annotators). An engine that errors on one dataset records the message and the grid continues.

Usage

cpt_benchmark(
  datasets,
  methods = c("pelt", "binseg", "wbs"),
  metrics = c("covering", "f1"),
  tolerance = 5,
  change_in = "mean",
  parallel = TRUE,
  progress = TRUE,
  seed = NULL,
  ...
)

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

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

## S3 method for class 'ggcpt_benchmark'
autoplot(
  object,
  plot_type = c("heatmap", "ranks", "critical_difference"),
  metric = NULL,
  alpha = 0.05,
  ...
)

Arguments

Value

A ggcpt_benchmark object: a tibble with one row per (dataset, method): dataset, method, n, n_annotators (how many ground-truth sets the dataset supplied), n_cp, the requested metrics, runtime and error, with print(), tidy() and autoplot() ("heatmap", "ranks", "critical_difference").

Reading the critical-difference diagram

Rank 1 is best. Each method's mean rank is taken over the datasets, in the direction the metric calls for: higher is better for covering, f1, precision, recall and rand_index; lower for hausdorff, annotation_error, mae_matched and rmse_matched. A metric that came back NA takes the worst rank on that dataset rather than being dropped, so a method that failed there is penalised for it instead of quietly scoring on a smaller sample; ties share the average rank.

The bar is the Nemenyi critical distance

CD = q_\alpha \sqrt{k(k + 1) / (6N)}

for k methods over N datasets, where q_\alpha is the Studentised range statistic at \alpha divided by \sqrt 2 (Demsar, 2006; the constants agree with that paper's Table 5 to three decimals for k = 2, \ldots, 10). Two methods whose mean ranks differ by less than CD are not distinguished at that level.

One caveat the diagram cannot show. Nemenyi is a post-hoc procedure, and the convention is to run it only after a Friedman test has rejected the null that all methods rank equally. autoplot() does not run that omnibus test (it draws the diagram it is asked for), so a gap wider than CD on a grid where Friedman would not have rejected is not the significant difference it looks like. With the handful of datasets cpt_datasets() supplies, N is small and CD correspondingly wide; read the diagram as a descriptive summary unless N is large enough to support the test.

References

van den Burg GJJ, Williams CKI (2020). “An evaluation of change point detection algorithms.” arXiv preprint arXiv:2003.06222. doi:10.48550/arXiv.2003.06222.

Demšar J (2006). “Statistical comparisons of classifiers over multiple data sets.” Journal of Machine Learning Research, 7, 1–30.

See Also

cpt_datasets(), cpt_load_tcpd(), cpt_metrics().

Examples

bm <- cpt_benchmark(cpt_datasets(n = 200, seed = 1),
                    methods = c("pelt", "binseg", "amoc"),
                    progress = FALSE)
bm
ggplot2::autoplot(bm)

Cite the method behind a result

Description

Returns the bibliographic reference(s) for the method behind a ggcpt result (or a method name), so an analysis can cite the right methodological paper without leaving R.

Usage

cpt_cite(x)

Arguments

Value

A tibble with columns method and reference, invisibly; the references are also printed.

Examples

cpt_cite("pelt")
res <- cpt_detect(c(rnorm(50), rnorm(50, 5)), method = "pelt")
cpt_cite(res)

Confidence intervals for changepoint locations

Description

Answers "where could this changepoint be?" for any result, and says which of four routes it used. show_ci = TRUE in autoplot() works only for the handful of engines that ship intervals of their own; this generic covers the rest, and (because the four routes mean genuinely different things) reports the provenance in a source column rather than presenting them as interchangeable.

Usage

cpt_confint(
  object,
  level = 0.95,
  method = c("auto", "native", "nsp", "bootstrap", "posterior"),
  B = 200,
  seed = NULL,
  ...
)

Arguments

Value

A tibble with one row per changepoint: cp, ci_lower, ci_upper, level, source, plus cp_index/ci_lower_index/ci_upper_index on the original scale when the result carries a time index, and n_replicates for method = "bootstrap" (how many replicates actually contributed a draw for that changepoint). method = "nsp" returns NA bounds for a changepoint that falls in no region, which is a finding rather than a failure.

How well these cover

Measured over 120 replicates on a 200-point series with one changepoint at 100 and a jump of three standard deviations, at a nominal level of 0.95: "bootstrap" on pelt covered 0.992 of the time with a mean width of 2.2; strucchange's native intervals covered 1.000 at width 4.4; stepR's (smuce) covered 0.992 at width 4.6; and "posterior" on bcp covered 1.000 at width 157. Every route is conservative (none under-covers), and the width is what separates them. The two native routes and the bootstrap are the ones to quote; see the note on "posterior" above for why its interval is so much wider.

See Also

cpt_test(), cpt_stability(), nsp_wrapper().

Examples

set.seed(2026)
x <- c(rnorm(80), rnorm(80, 4))
fit <- cpt_detect(x, method = "pelt")
cpt_confint(fit, method = "bootstrap", B = 25, seed = 1)

Consensus changepoints across several detectors

Description

Runs a set of detectors on one series and reports the locations they agree on. Two detections count as the same changepoint when they fall within tolerance of each other, the same tolerance window cpt_metrics() matches on (van den Burg and Williams, 2020), so the package has one notion of "close enough" and not two. The grouping necessarily differs: cpt_metrics() matches two sets one-to-one, while consensus has to cluster K of them, so detections are swept in order and a new cluster opens as soon as one lies more than tolerance from the cluster's first member. That cap stops a chain of near-neighbours merging into one arbitrarily wide cluster.

Usage

cpt_consensus(
  x,
  methods = c("pelt", "binseg", "amoc"),
  tolerance = 5,
  min_votes = 2,
  change_in = "mean",
  index = NULL,
  seed = NULL,
  ...
)

## S3 method for class 'ggcpt_consensus'
autoplot(object, plot_type = c("series", "agreement"), ...)

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

Arguments

Value

A ggcpt object (so it plots and tidies like any other result) whose changepoints tibble carries votes and methods (a comma-separated list of the methods that found each location), with the per-method detections kept in a consensus attribute and drawn by autoplot(plot_type = "agreement").

Consensus is not inference

Agreement among detectors is not a p-value, and a location found by six of seven methods is not thereby significant at any level: the methods are run on the same data and are strongly correlated, several of them share an engine, and none of the votes is independent. Read the vote count as a robustness display ("this feature does not depend on which detector I picked"), and use nsp_wrapper() or cpt_confint() when you need a guarantee.

References

van den Burg GJJ, Williams CKI (2020). “An evaluation of change point detection algorithms.” arXiv preprint arXiv:2003.06222. doi:10.48550/arXiv.2003.06222.

See Also

ggcpt_compare(), cpt_recommend(), cpt_metrics().

Examples

set.seed(2026)
x <- c(rnorm(80), rnorm(80, 4))
cons <- cpt_consensus(x, methods = c("pelt", "binseg", "amoc"))
tidy(cons)
ggplot2::autoplot(cons)

CROPS: the full penalty path of a penalised changepoint method

Description

Runs PELT once per distinct optimal segmentation as the penalty ranges over [pen_min, pen_max], using the CROPS algorithm of Haynes, Eckley and Fearnhead (2017) as implemented by the changepoint package. Instead of committing to one penalty, the analyst sees every segmentation the data admits along the path, together with its cost, and picks the elbow.

Usage

cpt_crops(
  x,
  change_in = c("mean", "var", "meanvar"),
  pen_min = NULL,
  pen_max = NULL,
  ...
)

## S3 method for class 'ggcpt_path'
autoplot(
  object,
  type = c("elbow", "path", "segmentations"),
  max_facets = 12,
  ...
)

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

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

Arguments

Value

A ggcpt_path object: a list with a solutions tibble (one row per distinct segmentation: penalty, n_cpts, cost, and a cpts list-column), the data, and metadata. penalty is the lower end of the penalty interval on which that segmentation is optimal: CROPS returns the breakpoints of the penalty axis, so K segmentations come with K + 1 boundaries and each row is optimal from its own penalty up to the next row's. Methods: print(), tidy(), and autoplot() (elbow plot by default; type = "path" for penalty vs. number of changepoints; type = "segmentations" for the faceted segmentations).

References

Haynes K, Eckley IA, Fearnhead P (2017). “Computationally efficient changepoint detection for a range of penalties.” Journal of Computational and Graphical Statistics, 26(1), 134–143.

Killick R, Eckley I (2014). “changepoint: An R package for changepoint analysis.” Journal of statistical software, 58(3), 1–19.

Examples

set.seed(2026)
x <- c(rnorm(100), rnorm(100, 3), rnorm(100, -1))
path <- cpt_crops(x)
path
ggplot2::autoplot(path)
ggplot2::autoplot(path, type = "segmentations")

A catalogue of benchmark datasets

Description

Builds a ready-made collection of labelled series for cpt_benchmark(). By default these are the canonical simulated signals this package already ships, which means the benchmark runs offline, deterministically, and inside R CMD check. Pass source = "tcpd" for the Turing Change Point Dataset instead, which is downloaded and cached.

Usage

cpt_datasets(
  source = c("simulated", "tcpd"),
  n = 500,
  seed = 1,
  names = NULL,
  ...
)

Arguments

Value

A named list of list(series, annotations) datasets, ready for cpt_benchmark().

See Also

cpt_load_tcpd(), cpt_benchmark().

Examples

names(cpt_datasets(n = 200))

Detection delay and false-alarm rate

Description

Scores an online result the way the sequential literature does: how long after each true change did the first alarm arrive, and how many alarms were raised with no change behind them. cpt_metrics() is the wrong tool for an online detector: it asks whether the location was recovered, which a sequential procedure never claims. It will not stop you: cpt_metrics() takes bare integer vectors and never sees which detector produced them, so it cannot know. (An earlier version of this sentence said it warns. It does not, and given that signature it could not.)

Usage

cpt_delay(object, truth, max_delay = Inf)

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

## S3 method for class 'ggcpt_delay'
glance(x, ...)

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

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

Arguments

Value

A ggcpt_delay object: a list with per_change (one row per true change: truth, alarm, delay, detected), false_alarms, and the summary statistics mean_delay, median_delay, n_false_alarms and arl: monitored observations per false alarm. The baseline a cpt_replay() monitor trained on is not counted, because no alarm can fire there; n_obs is the length of the stream in series positions, baseline included.

See Also

cpt_monitor(), cpt_replay().

Examples

set.seed(2026)
mon <- cpt_replay(c(rnorm(200), rnorm(200, 3)), method = "edetector")
cpt_delay(mon, truth = 200)

Unified changepoint detection dispatcher

Description

Runs a changepoint detection method on a sequence and returns a tidy ggcpt result object. This is the recommended entry point for most users. See cpt_methods() for the full method table with engines and capabilities.

Usage

cpt_detect(
  x,
  method = "pelt",
  change_in = "mean",
  penalty = "MBIC",
  index = NULL,
  y = NULL,
  ...
)

Arguments

Value

A ggcpt object: a list with changepoints (cp, cp_value), segments (seg_id, start, end, n, param_estimate), data (index, value), the method, change_in, penalty, cp_convention and runtime that produced it, the matched call, and fit, the raw upstream object. Optional slots (data_wide, regions, diagnostics, ...) appear only when an engine supplies them; new_ggcpt() documents all of them, and tidy.ggcpt(), glance.ggcpt() and augment.ggcpt() are the supported way to read one.

Scale sensitivity of the penalised change-in-mean engines

"pelt", "binseg", "segneigh" and "fpop" compare a penalty against a raw segment cost when change_in = "mean": changepoint's Normal cost assumes a noise standard deviation of 1, and fpop's lambda is an absolute penalty on the residual sum of squares. Neither rescales the data, so on a series whose noise is much wider than 1 the penalty is effectively negligible and the segmentation shatters. On 200 observations with one true changepoint in the middle and a jump of five standard deviations, "pelt" returns 1 changepoint at \sigma = 1, 39 at \sigma = 3 and 141 at \sigma = 10. These are means over 20 draws, because a single draw is not stable here: the same three settings gave 21/75 at n = 100 and 57/266 at n = 400, so the effect grows with the series as well as with the noise. Three ways to avoid it, in order of convenience:

• standardise the series first (cpt_detect(scale(x)[, 1], method = "pelt"));

• pass a penalty on the data's own scale, for example penalty = 2 * log(length(x)) * stats::var(diff(x)) / 2;

• use change_in = "meanvar", which estimates a variance per segment and is unaffected.

Most other engines are unaffected: SMUCE, WBS, WBS2, NOT, MOSUM, Isolate-Detect, TGUH, CPOP, "bcp", "beast" and the nonparametric and multivariate methods estimate or cancel the noise scale internally, and returned the same segmentation at a thousandth, one and a thousand times the units. Three did not, on the same series: "geomcp" runs PELT on its mapped distance and angle series and so inherits the sensitivity above; "decafs" floors its noise estimate at about 0.03, so it under-segments a series whose noise is smaller than that; and "bocpd"'s default prior is on the data's own scale. At a thousandth of the units the last two found nothing. Standardising first avoids all three.

See Also

cpt_methods() for what is available and what each method can do. To get the result out: tidy.ggcpt(), glance.ggcpt(), augment.ggcpt(), summary.ggcpt() and print.ggcpt(). To draw it: autoplot.ggcpt(). For the penalty: cpt_penalty().

Examples

set.seed(2022)
x <- c(rnorm(100, 0, 1), rnorm(100, 10, 1))
result <- cpt_detect(x, method = "pelt", change_in = "mean")
result
ggplot2::autoplot(result)

# A date index: detection is unchanged, but the report speaks in dates.
dates <- as.Date("2000-01-01") + 0:199
dated <- cpt_detect(x, method = "pelt", index = dates)
tidy(dated)

# The data-frame interface.
df <- data.frame(day = dates, value = x)
cpt_detect(df, y = value, index = day, method = "pelt")

A publication-ready changepoint table

Description

Renders the changepoints of a result as a gt table, with the time index, location intervals and segment levels formatted for a paper. Falls back to a plain tibble, with a note, when gt is not installed.

Usage

cpt_gt(object, title = NULL, subtitle = NULL, digits = 3)

Arguments

Value

A gt table, or a tibble when gt is unavailable.

See Also

cpt_report().

Examples

set.seed(2026)
cpt_gt(cpt_detect(c(rnorm(60), rnorm(60, 4)), method = "pelt"))

Influence diagnostics for a changepoint segmentation

Description

Perturbs one observation at a time (deleting it, or replacing it with an outlier), re-runs the detector, and reports what changed: the number of changepoints, where they moved to, and how the segment parameters responded. This is the diagnostic family of Wilms, Killick and Matteson (2022), rendered in ggplot2 so it composes with the rest of the package.

Usage

cpt_influence(
  object,
  type = c("delete", "outlier"),
  engine = c("auto", "changepoint.influence", "recompute"),
  subset = NULL,
  outlier_sd = 5,
  seed = NULL,
  ...
)

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

## S3 method for class 'ggcpt_influence'
autoplot(
  object,
  plot_type = c("overview", "location", "parameter", "map"),
  ...
)

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

Arguments

Value

A ggcpt_influence object: a list with

influence

a tibble with one row per perturbed observation: index, n_cp, delta_n_cp (against the unperturbed fit), max_shift (largest movement of a surviving changepoint, in positions), param_shift (largest absolute change in a segment parameter) and cpts (a list-column of the perturbed changepoint sets). A perturbation whose re-fit failed has n_cp = NA, and is warned about;

param

an n \times n matrix of per-observation segment parameters, one row per perturbation: the input to the influence map;

original, type, engine, method

with print() and autoplot() methods.

References

Wilms I, Killick R, Matteson DS (2022). “Graphical influence diagnostics for changepoint models.” Journal of Computational and Graphical Statistics, 31(3), 753–765. doi:10.1080/10618600.2021.2000873.

See Also

cpt_leverage(), cpt_sensitivity(), cpt_stability().

Examples

set.seed(2026)
fit <- cpt_detect(c(rnorm(40), rnorm(40, 4)), method = "pelt")
inf <- cpt_influence(fit)
inf
head(cpt_leverage(inf))

Install the engines behind a family of methods

Description

The package wraps a lot of upstream engines, all of them in Suggests so that installing ggchangepoint does not drag in dozens of packages nobody asked for. The cost of that choice is a discovery problem: cpt_detect(x, method = "smuce") tells you to install stepR, but only one package at a time. This installs a whole family in one call.

Usage

cpt_install_engines(bundle = "core", dry_run = FALSE, ...)

Arguments

Details

Every package comes from the repositories in getOption("repos") except fpop, which was archived from CRAN in 2026 at its maintainer's request and is installed from R-Forge (https://R-Forge.R-project.org), where it is developed.

Value

Invisibly, a tibble with one row per package (package, bundle, installed_before, installed_after).

See Also

cpt_methods() for the per-method installation status.

Examples

cpt_install_engines("bayesian", dry_run = TRUE)

Score a segmentation against labels

Description

Counts label errors: a positive region with no changepoint is a false negative, a negative region with one is a false positive, and a "one_change" region with two or more is a false positive as well. This is the accuracy measure supervised changepoint detection is built on, and, unlike an information criterion, it is defined by what the expert asserted rather than by a model assumption.

Usage

cpt_label_error(object, labels)

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

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

Arguments

Value

A tibble with one row per label: label_id, series (the label set's series identifier, NA for a single unnamed series), start, end, change, n_changes (how many detections fell inside), status ("correct", "false_positive" or "false_negative"), carrying the totals in an errors attribute and printing them. An empty label set gives a zero-row tibble with the same columns.

See Also

cpt_labels(), cpt_label_error_curve(), geom_cpt_label().

Examples

set.seed(2026)
fit <- cpt_detect(c(rnorm(50), rnorm(50, 4)), method = "pelt")
labs <- cpt_labels(c(40, 70), c(60, 95), c("one_change", "no_change"))
cpt_label_error(fit, labs)

Label error as a function of the penalty

Description

Runs one detector across a penalty grid and counts label errors at each setting: the curve penalty learning is fitted to, and the honest way to see whether any penalty can satisfy the labels.

Usage

cpt_label_error_curve(
  x,
  labels,
  method = "pelt",
  penalties = NULL,
  change_in = "mean",
  ...
)

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

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

Arguments

Value

A ggcpt_label_curve object: a tibble with penalty, n_cp, errors, false_positive, false_negative, plus print() and autoplot(). The target attribute holds the interval of log(penalty) achieving the minimum error, which is what cpt_learn_penalty() regresses on.

See Also

cpt_learn_penalty(), cpt_select().

Examples

set.seed(2026)
x <- c(rnorm(60), rnorm(60, 4))
labs <- as_cpt_labels(60, n = 120)
curve <- cpt_label_error_curve(x, labs, penalties = c(2, 8, 32, 128))
curve

Changepoint labels

Description

Builds the tidy label set that the supervised functions consume: one row per labelled region, each asserting how many changepoints that stretch of the series contains.

Usage

cpt_labels(start, end, change = "change", series = NA_character_)

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

Arguments

Value

A cpt_labels tibble with columns label_id, series, start, end, change.

References

Hocking TD, Rigaill G, Vert J, Bach F (2013). “Learning sparse penalties for change-point detection using max margin interval regression.” In Proceedings of the 30th International Conference on Machine Learning, volume 28, 172–180.

See Also

cpt_label_error(), geom_cpt_label(), cpt_learn_penalty(), as_cpt_labels() to convert a plain changepoint set.

Examples

cpt_labels(c(40, 70), c(60, 90), c("change", "no_change"))

Learn a penalty from labelled series

Description

Fits the supervised penalty model of Hocking et al. (2013): each series contributes a target interval of log-penalties (those achieving the fewest label errors), a feature vector is computed from the series, and a linear model is fitted by minimising the squared hinge loss on those intervals, which is max-margin interval regression. The result has a predict() method, and cpt_detect() accepts it directly as penalty, so a learned penalty is used exactly like a number.

Usage

cpt_learn_penalty(
  series,
  labels,
  method = "pelt",
  penalties = NULL,
  engine = c("auto", "penaltyLearning", "native"),
  ...
)

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

## S3 method for class 'ggcpt_penalty_model'
coef(object, ...)

## S3 method for class 'ggcpt_penalty_model'
predict(object, newdata, ...)

Arguments

Value

A ggcpt_penalty_model object with print(), coef() and predict() methods.

The two scales differ and it matters: coef() gives an intercept plus one weight per feature on the log-penalty scale, which is where the interval regression is fitted, while predict() exponentiates and returns a penalty on the natural scale, the scale cpt_penalty() and cpt_detect() consume. So a coefficient of -0.04 on log_n is a multiplicative effect on the penalty, not an additive one.

Reading the coefficients

The signs are often not interpretable, and that is a property of the labels rather than of the fit. A target interval is open above whenever the largest penalty on the grid still achieves the minimum label error, which is the common case, because a large penalty usually keeps the one changepoint the labels ask for. When every series' interval is open above, any sufficiently large prediction is optimal, the problem does not pin the slopes, and the L_2 term settles them near zero with whatever sign the optimiser reached.

Two measurements on four series of very different length and noise, all with one-change labels, differing only in the data drawn. In one, every non-intercept coefficient came out slightly negative, so the predicted penalty decreased with n, the opposite of the \log n growth a reader would expect from BIC, and not evidence of anything. In the other, every feature weight went to zero and the model became a constant: predict() returned the same penalty for all four series. Both fits put every prediction inside its target, which is the property the model is fitted for, and neither outcome says anything about how a penalty should scale.

So do not read a ggcpt_penalty_model as having discovered a relationship, and do not be surprised by a constant one.

If the coefficients need to mean something, the labels have to constrain the penalty from both sides: widen penalties until the largest one starts to over-segment, so the target intervals close above. cpt_label_error_curve() shows whether they do.

References

Hocking TD, Rigaill G, Vert J, Bach F (2013). “Learning sparse penalties for change-point detection using max margin interval regression.” In Proceedings of the 30th International Conference on Machine Learning, volume 28, 172–180.

See Also

cpt_label_error_curve(), cpt_penalty().

Examples

set.seed(2026)
series <- list(a = c(rnorm(60), rnorm(60, 4)),
               b = c(rnorm(80), rnorm(80, 2)))
labels <- list(a = as_cpt_labels(60, n = 120),
               b = as_cpt_labels(80, n = 160))
model <- cpt_learn_penalty(series, labels,
                           penalties = c(2, 8, 32, 128))
model
stats::predict(model, series$a)

Rank observations by influence

Description

Orders the observations of a cpt_influence() result by how much perturbing them disturbs the segmentation, most influential first. The composite leverage score is the sum of three standardised components (the change in the number of changepoints, the largest movement of a changepoint, and the largest change in a segment parameter), so an observation that shifts a location without changing the count is still ranked.

Usage

cpt_leverage(object, ...)

Arguments

Value

A tibble ordered most influential first, with columns index, delta_n_cp, max_shift, param_shift and leverage.

Rows with leverage = NA come first, and they are the most influential of all. max_shift and param_shift are undefined for a perturbation that left the engine with no changepoints at all (there is nothing to match against and no parameters to compare), so the composite score cannot be formed for an observation whose removal destroys the segmentation entirely. The NA is kept rather than filled in with a fabricated number; read the delta_n_cp column on those rows, which says how many changepoints were lost.

An NA here is always that case. If the original fit found no changepoints then max_shift is missing for every observation, the standardisation returns zeros rather than NAs, and every leverage is finite. A perturbation whose re-fit failed is not one of these: it carries delta_n_cp = NA as well and is sorted last, since nothing is known about it.

Examples

set.seed(2026)
fit <- cpt_detect(c(rnorm(40), rnorm(40, 4)), method = "pelt")
head(cpt_leverage(fit), 3)

Download and cache the Turing Change Point Dataset

Description

Fetches the benchmark of van den Burg and Williams (2020), real series from many domains each annotated independently by several human annotators, and caches it under tools::R_user_dir(). The multi-annotator structure is the point: scoring against a single "true" set silently discards the disagreement, and cpt_metrics_annotated() is built to keep it.

Usage

cpt_load_tcpd(name = NULL, cache_dir = NULL, refresh = FALSE, quiet = FALSE)

Arguments

Value

With name = NULL, a tibble catalogue (name, n_annotators, cached), read from the annotations file alone, so listing it downloads no series. Otherwise a named list of list(series, annotations, index, longname) datasets, in the shape cpt_benchmark() takes.

Network access and licences

This function downloads from GitHub, so it needs a working connection and is skipped in every example and test here. The data belong to their original owners under their own licences; this package neither bundles nor redistributes them. A few TCPD series are not in the repository at all (their sources do not permit redistribution) and are reported as unavailable rather than silently omitted.

References

van den Burg GJJ, Williams CKI (2020). “An evaluation of change point detection algorithms.” arXiv preprint arXiv:2003.06222. doi:10.48550/arXiv.2003.06222.

Examples

# Not run by R CMD check: every call downloads from the Turing Change
# Point Dataset's GitHub repository, and an example must not require
# network access.
## Not run: 
cpt_load_tcpd()                       # the catalogue
d <- cpt_load_tcpd("nile")            # one dataset
cpt_benchmark(d, methods = c("pelt", "amoc"))

## End(Not run)

Introspect available changepoint detection methods

Description

Returns a tibble describing every method the package knows about (those that are wired, those a user has registered with cpt_register_method(), and those that are planned), along with their capabilities and installation status. Useful for discovering what can be run, what needs to be installed, and which methods expose the extras the diagnostics need (confidence intervals, a fitted signal, a posterior, a detector statistic, a solution path, a bandwidth to sweep).

Usage

cpt_methods(capabilities = TRUE)

Arguments

Value

A tibble with columns:

method

Method name as passed to cpt_detect().

change_in

What types of change the method can detect.

engine

The upstream R package that implements the method.

status

"available" (wired in this release), "registered" (supplied by the user this session; see cpt_register_method()), or "planned" (future).

installed

TRUE if the engine package is installed, FALSE if it is a Suggests engine that is missing, NA for planned and registered methods.

target_release

What a planned method is waiting on: a release, or "when on CRAN" when the engine package itself is not available from CRAN. NA for methods that are already wired. Asking cpt_detect() for a planned method reports this rather than claiming the name does not exist.

multivariate, univariate, online, ci, fitted, posterior, statistic, path, scale_space

Capability flags (omitted when capabilities = FALSE). ci means the engine supplies changepoint-location confidence intervals; fitted a length-n fitted signal; posterior a per-location posterior probability; statistic and path the internals rendered by ggcpt_statistic() and ggcpt_solution_path(), which error with the list of supporting engines when a result does not carry them.

scale_space is not one of those, despite sitting beside them. Nothing stores a scale space on a result: cpt_scale_space() computes one on demand by sweeping a multiscale detector's bandwidth over the series, so it works on any series and any result, a pelt fit included. What this column marks is the two engines that sweep can be run with, i.e. the domain of that function's own method argument: subset(cpt_methods(), scale_space)$method.

online means the algorithm is sequential (it consumes observations one at a time), and this table reports it because it governs how the method behaves in batch: an online detector's threshold is a rate per observation, so run over a whole series through cpt_detect() it reports roughly n / \mathrm{arl0} changepoints by construction. It does not mean the method can be passed to cpt_monitor(), which takes its own three: "edetector", "cpm" and "ocd". The two sets overlap without coinciding: bocpd is an online algorithm this table marks but the monitor does not offer, and edetector is native to this package rather than a wrapped engine, so it has no row here at all.

See Also

cpt_install_engines() to install a whole family of the engines this table reports on; cpt_detect() to run one; cpt_register_method() to add your own.

Examples

cpt_methods()
# which methods can draw a confidence interval?
subset(cpt_methods(), ci)$method

Changepoint accuracy metrics

Description

Computes standard accuracy metrics comparing predicted changepoints to ground truth, including precision/recall/F1 with margin, covering metric, Hausdorff distance, adjusted Rand index, annotation error, and MAE/RMSE of matched locations.

Usage

cpt_metrics(pred, truth, n, margin = 5)

Arguments

Details

Precision/recall use a one-to-one matching: each truth may be claimed by at most one prediction (predictions are scanned in order and take the earliest unmatched truth within margin, which yields a maximum matching for interval-structured problems). The covering metric follows van den Burg and Williams (2020): the prediction-side partition is always well defined, so an empty pred scores the covering of the trivial single-segment partition rather than 0.

Value

A tibble with one row and the columns below. “Higher” and “lower” mark which direction is better, the same directions cpt_benchmark() ranks by.

n, n_pred, n_truth

the series length and the two changepoint counts, after out-of-range indices are dropped.

precision, recall, f1

higher is better. The fraction of predictions that matched a truth, the fraction of truths that were matched, and their harmonic mean, all under the one-to-one matching within margin, so they score whether a change was found, not how precisely it was located.

covering

higher is better, in [0, 1]. The segmentation covering metric: each true segment's best Jaccard overlap with a predicted segment, averaged weighted by segment length. Unlike F1 it needs no margin and degrades smoothly with location error.

hausdorff

lower is better, in observations. The largest distance from any changepoint on either side to the nearest one on the other: a worst-case location error, so one badly placed changepoint dominates it.

rand_index

higher is better. The adjusted Rand index between the two segment labellings: 1 for identical partitions, 0 for chance agreement, and negative for worse than chance.

annotation_error

lower is better. A count difference only: abs(n_pred - n_truth). It says nothing about location, so a segmentation with the right number of changepoints in entirely the wrong places scores a perfect 0. Read it beside covering or hausdorff, never alone.

mae_matched, rmse_matched

lower is better, in observations. Mean absolute and root-mean-square location error over the matched pairs only, so they describe how well the changepoints that were found are placed and ignore the ones that were missed. NA when nothing matched.

Degenerate cases, and which way each metric resolves them

Three of the twelve columns are ratios with a zero denominator when one side is empty, and the row does not resolve them all the same way, so the conventions are worth stating rather than inferring from a benchmark table:

• Both empty. The segmentation is exactly right: precision, recall, f1, covering and rand_index are all 1 and annotation_error is 0. (A metric that scored this 0 was a 0.4.0 bug.)

• One side empty. precision and recall are 0 rather than NA (finding nothing where there was a change, and finding a change where there was none, both score badly), and so is f1. rand_index is 0 for the same reason.

• Nothing matched. hausdorff, mae_matched and rmse_matched are NA, because they are distances and there is no pair to measure. They are also NA whenever either side is empty. This is the one place the row mixes conventions: an all-wrong answer gives f1 = 0 and mae_matched = NA in the same row. cpt_benchmark() treats an NA as the worst rank rather than dropping it.

An index outside 1..(n - 1) is dropped with a warning: locations follow the "left" convention, and an out-of-range one would corrupt the partition metrics rather than merely miss.

See Also

cpt_metrics_annotated() for scoring against multiple annotators, and cpt_benchmark() to run a method-by-dataset grid on these metrics.

Examples

cpt_metrics(c(100, 200), c(100, 200), n = 300)
cpt_metrics(c(101, 205), c(100, 200), n = 300, margin = 5)

Multi-annotator evaluation

Description

Computes averaged covering and F1 scores against multiple annotation sets, as used in the Turing Change Point Dataset benchmark.

Usage

cpt_metrics_annotated(pred, annotations, n, margin = 5)

Arguments

Value

A tibble with one row: n, n_annotators, n_pred, and the four metrics this averages: precision, recall, f1 and covering. Each is a plain unweighted mean of the per-annotator value from cpt_metrics(), over all n_annotators of them.

This is a narrower table than cpt_metrics() returns, so a call moved from one to the other loses columns: n_truth (there is no single truth), and the location metrics hausdorff, mae_matched, rmse_matched, rand_index and annotation_error.

The three distance metrics are omitted for a reason worth stating, because it is not obvious: they are NA whenever an annotator shares no matched pair with the prediction, so averaging them would quietly divide by fewer annotators than n_annotators reports. Measured on three annotators against one prediction (list(c(100, 200), integer(0), 150) at n = 300), mae_matched was available for one of the three and hausdorff for two, while f1 and covering were finite for all three. Score those per annotator with cpt_metrics() and combine them yourself if you want them, so the divisor is yours to choose.

covering and f1 are the pair the Turing Change Point Dataset benchmark reports, which is why they are the ones averaged here; precision and recall come along as F1's parts.

See Also

cpt_metrics() for the full single-truth table and what each column means.

Examples

# two annotators who disagree slightly about where the change is
cpt_metrics_annotated(c(100, 200),
                      annotations = list(c(98, 200), c(100, 203)),
                      n = 300, margin = 5)

The smallest detectable change

Description

Inverts cpt_power(): searches for the change size at which the detector reaches a target power. The study-design counterpart of a power curve, and the number that belongs in a pre-registration.

Usage

cpt_min_detectable(
  n,
  sigma = 1,
  method = "pelt",
  power = 0.8,
  range = c(0.1, 5),
  n_sim = 100,
  tolerance = 5,
  change_in = "mean",
  location = 0.5,
  noise = "gauss",
  rho = 0,
  df = 3,
  tol = 0.05,
  max_iter = 12,
  seed = NULL,
  ...
)

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

Arguments

Value

A list with jump (the smallest change reaching power), achieved_power, mc_se, and the trace of evaluations, with a print() method.

See Also

cpt_power().

Examples

# n_sim = 10, max_iter = 3: the search is n_sim detector fits per
# iteration, and n_sim = 30 with max_iter = 4 measured 5.4 s against
# CRAN's 5 s example budget. Raise both for a usable answer.
cpt_min_detectable(n = 200, n_sim = 10, max_iter = 3, seed = 1)

A stateful sequential changepoint monitor

Description

Creates a detector that consumes observations as they arrive and raises alarms, rather than segmenting a series that is already complete. Feed it with cpt_update(), read its alarm log with alarms(), and score it with cpt_delay(), because for an online method "did you find the location?" is the wrong question and "how long did you take, and how often do you false-alarm?" is the right one.

Usage

cpt_monitor(
  method = c("edetector", "cpm", "ocd"),
  baseline = NULL,
  alpha = 0.01,
  arl0 = 500,
  cpm_type = "Mann-Whitney",
  patience = 5000,
  deltas = c(0.5, 1, 2),
  reset = TRUE,
  relearn = 20,
  thresh = "MC",
  mc_reps = 100,
  ...
)

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

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

## S3 method for class 'ggcpt_monitor'
autoplot(object, plot_type = c("timeline", "statistic", "runlength"), ...)

Arguments

Value

A ggcpt_monitor object: a list carrying the detector's state between calls, so it is meant to be passed to cpt_update() and re-assigned rather than read field by field. The parts worth reading are

alarms

the tibble alarms() and tidy() return: one row per alarm, with time, statistic and threshold. Empty (zero rows) until something fires.

t

how many observations the monitor has consumed through cpt_update(), not counting the baseline; an alarm's time is on this same clock. A monitor built by cpt_replay() also carries offset, the number of leading observations it trained on, so time + offset is a position in the replayed series (cpt_delay() applies it for you).

data

every monitored observation so far, baseline excluded (the first coordinate, for a multivariate monitor), which is what autoplot() draws.

method, alpha, n_baseline, reset, relearn

the settings this call fixed, kept so a later cpt_update() cannot silently disagree with them.

state

the detector's internal statistics. Engine internals: their shape differs by method and is not part of the interface.

The e-detector, and why it is implemented rather than wrapped

Shin, Ramdas and Rinaldo (2023) give a nonparametric sequential framework with non-asymptotic control of the average run length, and it has no R implementation. The construction used here is the mixture Shiryaev-Roberts e-detector for a sub-Gaussian shift. For each candidate shift \delta the increment is the likelihood ratio e_t^{(\delta)} = \exp(\delta (X_t - \mu_0)/\sigma^2 - \delta^2/(2\sigma^2)), which has unit mean under the null; the running statistic is R_t^{(\delta)} = (1 + R_{t-1}^{(\delta)}) e_t^{(\delta)}; the shifts are combined by averaging, M_t = K^{-1} \sum_\delta R_t^{(\delta)}; and an alarm is raised the first time M_t \ge 1/\alpha.

The averaging is not a detail. Under the null M_t - t is a mean-zero martingale, so optional stopping at the alarm time \tau gives E_\infty[\tau] = E_\infty[M_\tau] \ge 1/\alpha: a finite-sample lower bound on the in-control average run length, with no asymptotics and no calibration run. A convex combination of e-detectors is an e-detector; a maximum of them is not, and taking one silently multiplies the false-alarm rate by roughly the number of shifts mixed over. Every other detector in this package wraps published, separately maintained code; this one does not, and is labelled as such wherever it appears.

References

Shin J, Ramdas A, Rinaldo A (2023). “E-detectors: a nonparametric framework for sequential change detection.” The New England Journal of Statistics in Data Science, 1(2), 229–260. doi:10.51387/23-NEJSDS49.

See Also

cpt_update(), alarms(), cpt_replay(), cpt_delay().

Examples

set.seed(2026)
mon <- cpt_monitor("edetector", baseline = rnorm(100))
mon <- cpt_update(mon, rnorm(50))          # still in control
mon <- cpt_update(mon, rnorm(50, 3))       # a change arrives
alarms(mon)

Construct changepoint penalties

Description

Helper to construct standard penalty values for use with changepoint detection methods. Returns a numeric penalty value.

Usage

cpt_penalty(type, n = NULL, k = 1, value = NULL, alpha = 1.01, series = NULL)

Arguments

Value

A numeric penalty value.

Penalty semantics across engines

The same penalty name may be interpreted differently by different engines:

• changepoint-based methods (PELT, BinSeg, SegNeigh, AMOC): accept character penalties ("MBIC", "BIC", "AIC", "Hannan-Quinn", "None") and pass them to the upstream changepoint package. A numeric penalty is translated to that package's penalty = "Manual" plus pen.value. The one exception is Segment Neighbourhood, for which changepoint does not implement MBIC: cpt_detect(method = "segneigh") and cpt_wrapper(cp_method = "SegNeigh") therefore fall back to "SIC" when the default penalty is left in place, so a segneigh result is not directly penalty-comparable with a PELT one. Pass penalty explicitly to pin it. For a change in mean these engines also read the penalty on the data's own scale rather than a standardised one; see the scale-sensitivity section of cpt_detect.

• Functional-pruning methods (fpop, cpop, decafs): accept numeric penalties only. When a character penalty is supplied via cpt_detect(), it is resolved to a numeric value using cpt_penalty() before dispatch.

• Search-based methods (WBS, WBS2, NOT, MOSUM, IDetect, TGUH): use internal model-selection criteria (e.g., sSIC, threshold) and generally ignore the penalty argument. Specify thresholds via the wrapper's own arguments.

• fastcpd takes its penalty as beta, on its own scale, and defaults to its native "MBIC". cpt_detect() forwards a numeric penalty as beta, and translates the three names the two packages share ("MBIC", "BIC"/"SIC", "MDL"). Any other character penalty ("AIC", "Hannan-Quinn", "sSIC", "None") has no fastcpd equivalent and is left to the engine's default rather than being silently approximated; pass beta yourself to pin it. Whatever is used is recorded on the result, so print() and glance() report the penalty of the fit in hand.

• Inference/Bayesian methods (smuce, bcp, bocpd, beast, cpm, sn): are tuned by a significance level, posterior-probability threshold, hazard, or average run length rather than a penalty; see each wrapper.

• MBIC in cpt_penalty() is a BIC-type penalty that adds a combinatorial term for the number of ways k changepoints can be placed in n observations, 0.5(k+1)\log n + \log{n \choose k}. It is deliberately stronger than "BIC". It is not the modified BIC of Zhang and Siegmund (2007), whose penalty is 1.5 k \log n + 0.5 \sum_i \log(l_i / n) on the log-likelihood scale (equivalently 3 k \log n + \sum_i \log(l_i / n) on the deviance scale, which is how cpt_select() states it and the scale its cost column uses). It depends on the segment lengths l_i and so cannot be expressed by a function of n and k alone. Use the character "MBIC" with changepoint-based methods to get the engine's native MBIC, and cpt_select(criterion = "mbic") for the Zhang-Siegmund one.

Examples

cpt_penalty("BIC", n = 100)
cpt_penalty("AIC", n = 100)
cpt_penalty("Manual", value = 5)

Detection power for a changepoint scenario

Description

Simulates replicate series under a scenario and reports how often the detector finds the change, how accurately it locates it, and how often it reports changes that are not there. This is the calculation that should precede an analysis, and the one applied papers are increasingly asked for.

Usage

cpt_power(
  n,
  jump,
  sigma = 1,
  method = "pelt",
  location = 0.5,
  n_sim = 200,
  tolerance = 5,
  change_in = "mean",
  noise = "gauss",
  rho = 0,
  df = 3,
  seed = NULL,
  parallel = TRUE,
  ...
)

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

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

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

Arguments

Value

A ggcpt_power object: a tibble with one row per scenario, with columns n, jump, sigma, location, power (proportion of replicates detecting the change within tolerance), mc_se (the Monte Carlo standard error of that proportion), mean_abs_error (location error among detections; NaN when no replicate detected a changepoint within tolerance of the true one, because there is no distance to average, and power reads 0 in the same row), false_positives (mean number of extra changepoints per replicate) and n_sim; with print() and autoplot().

Reproducibility under a parallel plan

A seeded call is reproducible for a given future::plan(), and not across plans. Under a parallel plan the replicates' random numbers come from future.apply's parallel-safe L'Ecuyer streams, derived from seed; run sequentially they come from the calling stream that seed set. Both are deterministic, and they are not the same numbers. Measured on cpt_power(n = c(100, 200), jump = 0.5, n_sim = 8, seed = 11): power = 0.25, 0.125 sequentially and 0, 0.375 on two workers. The scenario is named because the numbers depend on it and on the worker count; what does not depend on either is that the two disagree.

So the guarantee is: same seed and same plan, same answer, every time, whichever plan it is. If a power figure needs to be reproducible by someone else, pin the execution as well as the seed: pass parallel = FALSE, or state the plan alongside the seed. Raising n_sim narrows the gap, because it is Monte Carlo error rather than disagreement: both estimates are of the same quantity, and mc_se says how precisely.

This is specific to cpt_power(), which is the one function here whose parallel tasks consume random numbers. The other six that dispatch on future::plan() (cpt_benchmark(), cpt_batch(), cpt_consensus(), cpt_influence(), cpt_sensitivity() and ggcpt_compare()) farm out work that is deterministic given its input, and were measured to return identical results under a sequential and a two-worker plan, stochastic engines included.

See Also

cpt_min_detectable(), cpt_scenarios(), cpt_simulate().

Examples

pw <- cpt_power(n = 200, jump = c(0.5, 1, 2), n_sim = 30, seed = 1)
pw
ggplot2::autoplot(pw)

Recommend a detection method

Description

Turns the capability matrix into an answer. Given what the analyst knows about their problem (how many dimensions, what kind of change, what the noise looks like, how long the series is, whether they need uncertainty or an online alarm), this returns the shortlist of methods that actually fit, with a reason for each and the reference to cite. It is a decision table, not a model: everything it knows is in cpt_methods(), and making that explicit and printable is the point.

Usage

cpt_recommend(
  dimension = c("univariate", "multivariate"),
  change_in = "mean",
  noise = c("iid", "heavy", "autocorrelated", "heteroscedastic"),
  n = NULL,
  need_uncertainty = FALSE,
  online = FALSE,
  installed_only = FALSE
)

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

## S3 method for class 'ggcpt_recommendation'
print(x, top = 5, ...)

Arguments

Value

A tibble of candidate methods ordered by suitability, with columns method, engine, installed, score, why and caveat, and a print() that reads as advice.

See Also

cpt_methods(), cpt_consensus(), cpt_cite().

Examples

cpt_recommend(noise = "autocorrelated")
cpt_recommend(dimension = "multivariate", change_in = "covariance")

Tidy the significance regions of a ggcpt object

Description

The interval-valued methods (currently nsp_wrapper()) return regions rather than points: each is guaranteed to contain at least one changepoint at a prescribed global significance level. A region is a different object from a confidence interval around an estimate, so it lives in its own slot and has its own accessor rather than being folded into tidy().

Usage

cpt_regions(x)

Arguments

Value

A tibble with columns start, end (positions), length, and, when the result carries a time index, start_index/end_index on the original scale. Any further columns the engine supplied are carried through after those: nsp_wrapper() adds value, the region's statistic. A zero-row tibble when the result carries no regions.

See Also

nsp_wrapper(), geom_cpt_region(), cpt_confint().

Examples

set.seed(2026)
fit <- as_ggcpt(50, c(rnorm(50), rnorm(50, 4)),
                regions = data.frame(start = 45, end = 56))
cpt_regions(fit)

Register an external changepoint detector

Description

Teaches cpt_detect() about a detector this package does not (and often cannot) depend on: an engine that is not on CRAN, a Python detector reached through reticulate, a deep-learning model, a proprietary in-house method, or a hand-curated set of changepoints. The registered method then works with everything built on the ggcpt contract: autoplot(), the geoms, tidy()/glance()/ augment(), cpt_metrics(), ggcpt_compare(), cpt_stability(), cpt_consensus(), cpt_benchmark() and cpt_report().

Usage

cpt_register_method(
  name,
  fn,
  change_in = "mean",
  engine = "user",
  citation = NULL,
  capabilities = list(),
  cp_convention = c("left", "right"),
  overwrite = FALSE
)

cpt_unregister_method(name)

cpt_registered_methods()

Arguments

Value

Invisibly, the method name.

cpt_registered_methods() returns a tibble with one row per registered method (columns method, change_in, engine, has_citation), or a zero-row tibble when none are registered.

Registered methods are labelled, not endorsed

A registered method is visibly user-supplied: cpt_methods() gives it status = "registered", print() on its results marks it, and cpt_cite() reports the citation you supplied or states that none was given. The package validates the shape of what your function returns (through as_ggcpt(), which runs the same contract checks as every built-in wrapper); it does not and cannot validate the method.

See Also

as_ggcpt() to turn changepoints into a result object without registering a method; cpt_unregister_method(); cpt_registered_methods().

Examples

# A deliberately trivial detector: split at the largest jump.
cpt_register_method(
  "biggest_jump",
  fn = function(x, ...) which.max(abs(diff(x))),
  change_in = "mean",
  engine = "example",
  citation = "No citation supplied (illustration only)."
)
set.seed(1)
fit <- cpt_detect(c(rnorm(50), rnorm(50, 5)), method = "biggest_jump")
fit
cpt_unregister_method("biggest_jump")

Replay a series through a sequential detector

Description

Runs a whole series through a monitor in one call, so the alarm timeline of an online method can be studied retrospectively without hand-rolling the update loop. This is the honest version of what 0.4.0's cpm, ocd and bocpd wrappers do implicitly: it reports alarms, which arrive after the change, rather than pretending they are estimated changepoint locations.

Usage

cpt_replay(x, method = c("edetector", "cpm", "ocd"), baseline = NULL, ...)

Arguments

Value

A ggcpt_monitor that has already consumed the series: the same object cpt_monitor() returns, described there, with alarms filled in for whatever fired.

See Also

cpt_delay(), cpt_monitor().

Examples

set.seed(2026)
mon <- cpt_replay(c(rnorm(200), rnorm(200, 3)), method = "edetector")
alarms(mon)

A reproducible report of a changepoint analysis

Description

Assembles everything a reader needs to judge a changepoint result into one artifact: the method and its citation, the penalty, the number and locations of the changepoints with intervals where available, the segment table, stability and diagnostics if they were computed, and the session information. Reproducibility and correct attribution in one call.

Usage

cpt_report(
  object,
  format = c("md", "text", "gt"),
  file = NULL,
  stability = NULL,
  events = NULL,
  confint = TRUE,
  session = TRUE
)

Arguments

Value

A character vector of report lines (or a gt table when format = "gt").

See Also

cpt_gt(), cpt_cite().

Examples

set.seed(2026)
fit <- cpt_detect(c(rnorm(60), rnorm(60, 4)), method = "pelt")
cat(cpt_report(fit, session = FALSE), sep = "\n")

Scale space: the statistic across bandwidths

Description

Sweeps a multiscale detector's bandwidth and returns the statistic at every (location, bandwidth) pair. The resulting heatmap answers the question a single-bandwidth fit cannot: at which resolutions does this feature exist? A change that is significant only at a wide bandwidth is a slow shift; one that appears only at a narrow bandwidth is a spike.

Usage

cpt_scale_space(x, bandwidths = NULL, method = c("mosum", "npmojo"), ...)

ggcpt_scale_space(x, bandwidths = NULL, method = c("mosum", "npmojo"), ...)

Arguments

Value

cpt_scale_space() returns a tibble with index, bandwidth, statistic, threshold, significant (the statistic at that location and bandwidth exceeds the threshold) and detected (the engine reported a changepoint there at that bandwidth). The two differ: a location can clear the threshold without surviving the engine's own pruning. ggcpt_scale_space() draws the heatmap with the accepted changepoints overlaid.

See Also

cpt_statistic().

Examples

set.seed(2026)
x <- c(rnorm(300), rnorm(300, 2))
ss <- cpt_scale_space(x, bandwidths = c(20, 40, 80))
head(ss)

A grid of simulation scenarios

Description

Builds the scenario grid a simulation study varies over, as data rather than as nested loops, so it can be inspected, filtered, subsetted and passed straight to cpt_benchmark().

Usage

cpt_scenarios(
  n = 500,
  jump = c(0.5, 1, 2),
  location = 0.5,
  noise = "gauss",
  rho = 0.5,
  change_in = "mean",
  n_rep = 1,
  seed = 1,
  as_datasets = TRUE
)

Arguments

Value

A named list of datasets, or a tibble of scenarios when as_datasets = FALSE.

See Also

cpt_power(), cpt_benchmark().

Examples

scen <- cpt_scenarios(n = 200, jump = c(1, 3), as_datasets = FALSE)
scen

Choose the number of changepoints

Description

Builds a ladder of candidate segmentations with K = 0, 1, \ldots changepoints and scores each one, returning the chosen K, the criterion curve behind the choice, and the fitted result at that K. Five criteria are available, including the consistent sample-splitting cross-validation of Zou, Wang and Li (2020) and the segment-length mBIC of Zhang and Siegmund (2007).

Usage

cpt_select(
  x,
  method = "pelt",
  criterion = c("bic", "mbic", "aic", "crops_elbow", "cv", "stability"),
  k_max = 20,
  folds = 5,
  B = 100,
  change_in = "mean",
  index = NULL,
  seed = NULL,
  ...
)

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

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

## S3 method for class 'ggcpt_selection'
autoplot(
  object,
  plot_type = c("criterion", "segmentation", "ladder"),
  max_facets = 12,
  ...
)

Arguments

Value

A ggcpt_selection object: a list with criterion_table (one row per candidate K: k, value, cost, chosen, and a cpts list-column), k (the chosen number), fit (the ggcpt at that K), criterion and data. Methods: print(), tidy() and autoplot() with plot_type = "criterion", "segmentation" or "ladder".

References

Zou C, Wang G, Li R (2020). “Consistent selection of the number of change-points via sample-splitting.” The Annals of Statistics, 48(1), 413–439. doi:10.1214/19-AOS1814.

Zhang NR, Siegmund DO (2007). “A modified Bayes information criterion with applications to the analysis of comparative genomic hybridization data.” Biometrics, 63(1), 22–32. doi:10.1111/j.1541-0420.2006.00662.x.

Haynes K, Eckley IA, Fearnhead P (2017). “Computationally efficient changepoint detection for a range of penalties.” Journal of Computational and Graphical Statistics, 26(1), 134–143.

See Also

cpt_crops(), cpt_penalty(), cpt_sensitivity().

Examples

set.seed(2026)
x <- c(rnorm(80), rnorm(80, 4), rnorm(80, 1))
sel <- cpt_select(x, criterion = "bic", k_max = 6)
sel
ggplot2::autoplot(sel)
ggplot2::autoplot(sel, plot_type = "ladder")

Sensitivity of a segmentation to its tuning parameters

Description

The parameter analogue of cpt_influence(): instead of asking which observation drives the answer, it asks which setting does. Runs the detector over a grid of tuning values and reports the detected locations for each, which is the direct answer to the commonest reviewer question about a changepoint analysis: "is this robust to the penalty?".

Usage

cpt_sensitivity(x, method = "pelt", over = list(), seed = NULL, ...)

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

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

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

Arguments

Value

A ggcpt_sensitivity object: a list with a grid tibble (one row per setting: the parameter columns, n_cp, and a cpts list-column), the data, and the swept parameter names. Methods: print(), tidy() (one row per detected changepoint) and autoplot() (a location heatmap over the grid).

See Also

cpt_influence(), cpt_select().

Examples

set.seed(2026)
x <- c(rnorm(60), rnorm(60, 3))
s <- cpt_sensitivity(x, method = "pelt",
                     over = list(penalty = c(2, 10, 40)))
s
ggplot2::autoplot(s)

Generate simulated changepoint data

Description

Creates a synthetic time series with known changepoints for testing and benchmarking.

Usage

cpt_simulate(
  n,
  changepoints = integer(),
  change_in = c("mean", "var", "meanvar", "slope"),
  params = NULL,
  noise = c("gauss", "t", "ar1", "rw"),
  sd = 1,
  df = 3,
  rho = 0,
  seasonality = NULL,
  sd_trend = NULL,
  seed = NULL
)

rcpt(...)

Arguments

Value

A tibble with columns index, value, and seg_id. The true changepoints are stored in the true_changepoints attribute.

See Also

Other test signals: signal_blocks(), signal_fms(), signal_mix(), signal_stairs(), signal_teeth()

Examples

dat <- cpt_simulate(200, changepoints = c(100), change_in = "mean",
                    params = c(0, 10), seed = 2022)
attr(dat, "true_changepoints")

# a seasonal series with a level shift, and one with drifting noise
seasonal <- cpt_simulate(240, changepoints = 120, params = c(0, 3),
                         seasonality = list(period = 12, amplitude = 2),
                         seed = 1)
drifting <- cpt_simulate(240, changepoints = 120, params = c(0, 3),
                         sd_trend = c(0.5, 3), seed = 1)

The solution path of a search-based detector

Description

The order in which candidate changepoints entered the model, with the contrast (or split criterion) at each step. Binary segmentation splits recursively, WBS/WBS2/NOT/TGUH rank random intervals; in every case the final answer is a prefix of a path, and seeing the path shows how decisively each changepoint beat the next.

Usage

cpt_solution_path(object)

ggcpt_solution_path(object, max_steps = 40)

Arguments

Value

cpt_solution_path() returns a tibble with step, cp, contrast and, for interval-based searches, start/end of the interval that proposed it, plus a selected flag marking the changepoints in the final model. ggcpt_solution_path() draws it.

contrast is the engine's own ordering criterion, and it is a different quantity per engine: a penalty value for binseg/segneigh (from changepoint::pen.value.full()), |CUSUM| for wbs, |max.contrast| for not, and breakfast's candidate criterion for wbs2/tguh. The values order the candidates within one result; they are not comparable across engines, and the plot legend names the quantity rather than calling all of them "Contrast".

For wbs2 and tguh the path is recomputed with breakfast, because their fit objects do not keep the candidate list. wbs2's search is randomised, so its path is a second search of the same series rather than a record of the first: it can differ between calls, and selected can be FALSE throughout if the recomputed candidates miss the fit's own changepoints. Every other engine's path is read off the fit.

See Also

cpt_statistic(), cpt_crops() for the penalty path of an optimal-partitioning method.

Examples

set.seed(2026)
fit <- cpt_detect(c(rnorm(150), rnorm(150, 3)), method = "binseg")
cpt_solution_path(fit)

Changepoint stability diagnostics via bootstrap

Description

Most engines report a point set of changepoints with no measure of how fragile it is. cpt_stability() fits the detector once, then resamples residuals within the fitted segments (so the estimated regime structure is preserved), re-runs the detector on each replicate, and reports how often each location is re-detected. The resulting detection-frequency profile is a cheap, model-agnostic confidence signal available for every wrapped engine, including the many that ship no confidence intervals.

Usage

cpt_stability(x, method = "pelt", B = 100, margin = 5, seed = NULL, ...)

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

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

Arguments

Value

A ggcpt_stability object: a list with frequency (a tibble of index and freq, the proportion of replicates detecting a changepoint within margin of that index), original (the point-estimate ggcpt), and B. Methods: print() and autoplot() (frequency profile with the original detections marked).

Examples

set.seed(2026)
x <- c(rnorm(60), rnorm(60, 4))
st <- cpt_stability(x, method = "pelt", B = 20)
st
ggplot2::autoplot(st)

The detector's statistic as a function of location

Description

Returns the criterion the engine evaluated at each position, which is what explains why a changepoint landed where it did. Available for the engines that expose it (subset(cpt_methods(), statistic)$method lists them), and an error naming those engines for the ones that do not.

Usage

cpt_statistic(object)

ggcpt_statistic(object)

Arguments

Value

cpt_statistic() returns a tibble with index, statistic, threshold (the engine's rejection threshold, or NA) and label (what the statistic is). ggcpt_statistic() returns a two-panel ggplot: the series above, the statistic below, sharing the x axis.

See Also

cpt_solution_path(), cpt_scale_space().

Examples

set.seed(2026)
fit <- cpt_detect(c(rnorm(200), rnorm(200, 3)), method = "mosum")
head(cpt_statistic(fit))
ggcpt_statistic(fit)

Test detected changepoints

Description

Attaches a test to each detected changepoint (type = "jump") or to each fitted segment (type = "segment"), using the engine's own test where it has one and an explicitly unadjusted two-sample test where it does not.

Usage

cpt_test(object, type = c("jump", "segment"), correction = "none")

Arguments

Value

A tibble with columns cp (or seg_id), estimate, statistic, p_value, method and selection_adjusted, plus cp_index on the original scale when the result carries a time index (as cpt_confint() does), and p_adjusted when correction is not "none". estimate is the change in the segment mean (the breakpoint's slope change for segmented), and NA for a regression-mode strucchange fit, whose change is a vector of coefficients; its Chow test is run on the full regression model. A multivariate result is refused: both routes test one series.

Selection bias

read this before quoting a p-value: Testing a changepoint at a location that was chosen because the data looked like it changed there is circular, and the resulting p-values are anti-conservative, often severely. The selection_adjusted column records, per row, whether the test accounts for that:

• TRUE for segmented's Davies test, which is built for a nuisance parameter present only under the alternative. It is one global test of "is there a breakpoint", not a test per breakpoint, so on a multi-break fit every row carries the same statistic and p-value, and the method string says so.

• FALSE for the generic Welch two-sample fallback, which compares the segments either side of the changepoint as if the location had been fixed in advance. Useful as a descriptive effect size with a scale attached; not a valid significance test for the existence of the change.

• FALSE for strucchange's route as well, which is the Chow F evaluated at each estimated break date. The Chow statistic's reference distribution assumes the date was fixed in advance, so quoting it at a date the Bai-Perron dynamic program chose is exactly the circularity this column exists to flag. Reporting it is conventional in that literature, which does not make it adjusted. The selection-adjusted objects there are the sup-type statistics and the Bai-Perron critical values.

Two further limits worth knowing. type = "segment" is always the unadjusted Welch test: the native routes above apply only to type = "jump", so a segmented fit tested per-segment does not use Davies' test. And the split above is by engine and type, not by engine alone. For a guarantee that survives selection, use nsp_wrapper() (regions with exact global coverage) or cpt_confint() with method = "nsp". The canonical post-detection tests of Jewell, Fearnhead and Witten (2022) are implemented in ChangepointInference, which is not on CRAN; cpt_register_method() is the supported way to bring it in.

See Also

cpt_confint(), nsp_wrapper().

Examples

set.seed(2026)
fit <- cpt_detect(c(rnorm(60), rnorm(60, 4)), method = "pelt")
cpt_test(fit)

Feed observations to a monitor

Description

Pushes new data through a cpt_monitor(), updating its internal state and appending to its alarm log. The monitor is returned, so the idiom is mon <- cpt_update(mon, new_obs).

Usage

cpt_update(monitor, new_obs)

Arguments

Value

The updated ggcpt_monitor: the same structure as the input (see cpt_monitor()), with t advanced by the number of new observations (rows, for a matrix) and any new rows appended to alarms. Re-assign it: the monitor is a value, not a mutable object, so cpt_update(mon, y) without assignment discards the update.

See Also

cpt_monitor(), alarms().

Examples

set.seed(2026)
mon <- cpt_monitor("edetector", baseline = rnorm(100))
mon <- cpt_update(mon, c(rnorm(50), rnorm(50, 3)))
alarms(mon)

Changepoint wrapper

Description

This function wraps a number of cpt functions from the changepoint package and the cpt.np() function from the changepoint.np package. It is handy that users can use this function to get the same changepoint results as these functions output individually. Moreover, it returns a tibble that inherits the tidyverse style. Functions from the changepoint package do require data normality assumption by default, yet changepoint.np is a non-parametric way to detect changepoints and let data speak by itself. If user sets change_in as np (or cpt_np), a seed should be set before using the function for the sake of reproducibility. For more details on the changepoint and changepoint.np packages, please refer to their documentation.

Usage

cpt_wrapper(data, change_in = "mean_var", cp_method = "PELT", ...)

Arguments

Value

A tibble including which point(s) is/are the changepoint along with raw changepoint value corresponding to that changepoint. Changepoint locations follow the convention of the changepoint package: the last index of the left segment. The upstream cpt object is attached as the "ggcpt_fit" attribute, which is what cpt_detect() stores in the result's $fit.

Standardise the data for a change in mean

With change_in = "mean" the upstream Normal cost assumes a noise standard deviation of 1 and the penalty is compared against the raw residual sum of squares, so a series with wider noise is under-penalised and over-segmented: about 39 changepoints instead of 1 at \sigma = 3 on 200 observations (mean over 20 draws). Standardise the series first, or use change_in = "mean_var", which estimates a variance per segment and is unaffected. See the scale-sensitivity section of cpt_detect.

References

Killick R, Eckley I (2014). “changepoint: An R package for changepoint analysis.” Journal of statistical software, 58(3), 1–19.

See Also

Other changepoint engines: bcp_wrapper(), beast_wrapper(), bfast_wrapper(), binsegrcpp_wrapper(), bocpd_wrapper(), cpm_wrapper(), cpop_wrapper(), decafs_wrapper(), ecp_wrapper(), envcpt_wrapper(), esac_wrapper(), fabisearch_wrapper(), fastcpd_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(2022)
cpt_wrapper(c(rnorm(100,0,1),rnorm(100,0,10)))
cpt_wrapper(c(rnorm(100,0,1),rnorm(100,10,1)))

DeCAFS wrapper: changes amid drift and autocorrelated noise

Description

Wraps DeCAFS::DeCAFS() (Romano, Rigaill, Runge and Fearnhead, 2022), which detects abrupt mean changes when the underlying signal also drifts (random-walk fluctuations) and the noise is AR(1)-autocorrelated, the two regimes in which plain change-in-mean methods over-detect. Model parameters are estimated automatically unless supplied.

Usage

decafs_wrapper(x, penalty = NULL, model_param = NULL, ...)

Arguments

Value

A ggcpt object. The data tibble carries the estimated signal in its fitted column.

References

Romano G, Rigaill G, Runge V, Fearnhead P (2022). “Detecting abrupt changes in the presence of local fluctuations and autocorrelated noise.” Journal of the American Statistical Association, 117(540), 2147–2162.

See Also

Other changepoint engines: bcp_wrapper(), beast_wrapper(), bfast_wrapper(), binsegrcpp_wrapper(), bocpd_wrapper(), cpm_wrapper(), cpop_wrapper(), cpt_wrapper(), ecp_wrapper(), envcpt_wrapper(), esac_wrapper(), fabisearch_wrapper(), fastcpd_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 <- decafs_wrapper(c(rnorm(100), rnorm(100, 5)))
res$changepoints

ecp wrapper

Description

The ecp package provides a non-parametric way to detect changepoints. Unlike the changepoint package, it does not assume raw data to have any formal distribution. This wrapper function wraps two functions from the ecp package, i.e., e.divisive() and e.agglo(). Users can use either function by switching the algorithm argument. Before using the wrapper function, seed should be set for the sake of reproducibility.

Usage

ecp_wrapper(data, algorithm = "divisive", min_size = 2, seed = NULL, ...)

Arguments

Value

A tibble includes which point(s) is/are the changepoint along with raw changepoint value corresponding to that changepoint. Changepoint locations follow the ecp package convention: the first index of the right segment. When no changepoint is found, an empty tibble is returned (0 rows). The upstream fit is not retained ($fit is NULL on a ggcpt from cpt_detect(method = "ecp")), because ecp::e.agglo()'s cluster-progression matrix is quadratic in the series length; call the ecp functions directly if you need their full output.

References

James NA, Matteson DS (2014). “ecp: An R package for nonparametric multiple change point analysis of multivariate data.” Journal of Statistical Software, 62(7), 1–25. doi:10.18637/jss.v062.i07.

See Also

Other changepoint engines: bcp_wrapper(), beast_wrapper(), bfast_wrapper(), binsegrcpp_wrapper(), bocpd_wrapper(), cpm_wrapper(), cpop_wrapper(), cpt_wrapper(), decafs_wrapper(), envcpt_wrapper(), esac_wrapper(), fabisearch_wrapper(), fastcpd_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(2022)
ecp_wrapper(c(rnorm(100,0,1),rnorm(100,0,10)))
ecp_wrapper(c(rnorm(100,0,1),rnorm(100,10,1)))

EnvCpt wrapper: changepoints versus trends versus autocorrelation

Description

Wraps EnvCpt::envcpt() (Beaulieu and Killick, 2018), which fits up to twelve competing models (constant mean or linear trend, each with or without changepoints, and with white-noise, AR(1) or AR(2) errors) and lets an information criterion decide whether the series really contains changepoints or merely trend/autocorrelation ("memory"). The changepoints of the winning model (if any) are returned, and the winning model's name is recorded, guarding against the classic false positive of running a mean-shift detector on autocorrelated data.

Usage

envcpt_wrapper(
  x,
  models = c("mean", "meancpt", "meanar1", "meanar2", "meanar1cpt", "meanar2cpt",
    "trend", "trendcpt", "trendar1", "trendar2", "trendar1cpt", "trendar2cpt"),
  criterion = c("AIC", "BIC"),
  minseglen = 5,
  ...
)

Arguments

Value

A ggcpt object. $fit holds the full envcpt output; the selected model name is stored in the penalty descriptor and printed by glance() via penalty_type. Individual model fits that fail are expected (the criterion ignores them), so the engine's own try() output is not passed on; genuine warnings still are, and a series on which no model fits at all raises an error. A constant series has no changepoints and is not handed to the engine, so $fit is NULL there.

References

Beaulieu C, Killick R (2018). “Distinguishing trends and shifts from memory in climate data.” Journal of Climate, 31(23), 9519–9543.

See Also

Other changepoint engines: bcp_wrapper(), beast_wrapper(), bfast_wrapper(), binsegrcpp_wrapper(), bocpd_wrapper(), cpm_wrapper(), cpop_wrapper(), cpt_wrapper(), decafs_wrapper(), ecp_wrapper(), esac_wrapper(), fabisearch_wrapper(), fastcpd_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 <- envcpt_wrapper(c(rnorm(100), rnorm(100, 3)))
res$changepoints

ESAC wrapper: sparsity-adaptive high-dimensional detection

Description

Wraps HDCD::ESAC() (Moen, Glad and Tveten, 2023): Efficient Sparsity Adaptive Changepoint estimation for a change in the mean vector of a high-dimensional series. Where inspect projects onto a single estimated sparse direction, ESAC adapts across the whole sparsity range at once, which is a different regime rather than a refinement of the same one: it is competitive both when a handful of coordinates change and when all of them do.

Usage

esac_wrapper(
  x,
  threshold_d = 1.5,
  threshold_s = 1,
  empirical = FALSE,
  N = 1000,
  seed = NULL,
  ...
)

Arguments

Value

A ggcpt object. The changepoints tibble carries cusum (the ESAC statistic at each detected location) and depth (its level in the recursion).

References

Moen PAJ, Glad IK, Tveten M (2024). “Efficient sparsity adaptive changepoint estimation.” Electronic Journal of Statistics, 18(2), 3975–4038. doi:10.1214/24-EJS2294.

See Also

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(), fabisearch_wrapper(), fastcpd_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)
X <- matrix(rnorm(100 * 20), nrow = 100)
X[51:100, 1:5] <- X[51:100, 1:5] + 3
esac_wrapper(X)

Network-structure changepoints via non-negative matrix factorisation

Description

Wraps fabisearch::detect.cps() (Ondrus, Olds and Cribben, 2024): factorised binary search for changes in the network structure of a high-dimensional series. Each candidate split is scored by how much better a rank-r non-negative matrix factorisation fits the two halves separately than together, and significance is assessed by permutation.

Usage

fabisearch_wrapper(
  x,
  min_dist = 35,
  n_runs = 50,
  n_reps = 100,
  alpha = NULL,
  rank = NULL,
  n_core = 1,
  seed = NULL,
  ...
)

Arguments

Value

A ggcpt object with change_in = "network". Multivariate input is reduced to one series per observation by taking the cross-sectional mean of the columns, and that is the series stored on the result: autoplot() draws it, tidy()'s cp_value reads it, and $segments$param_estimate and augment()'s .fitted/.resid are computed from it. It is not any one column of the input. The full input is kept in $data_wide for autoplot(type = "coordinates").

Non-negativity, cost, and the attached namespace

Three practical notes. (1) NMF is undefined for negative entries, so this wrapper refuses them rather than letting the engine fail deep inside a factorisation; shift or rescale the series first if it has negatives. (2) It is by far the most expensive engine here (n_runs times n_reps factorisations per candidate split), so the defaults are lowered in the examples. The engine's own progress output is suppressed, so a long call is silent until it returns. (3) fabisearch calls NMF's multi-run machinery, which resolves helpers through the search path and fails with "none of the packages are loaded" when NMF is merely loaded; this wrapper therefore attaches NMF for the duration of the call and detaches it again afterwards.

References

Ondrus M, Cribben I (2024). “fabisearch: a package for change point detection in and visualization of the network structure of multivariate high-dimensional time series in R.” Neurocomputing, 578, 127321. doi:10.1016/j.neucom.2024.127321.

See Also

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(), fastcpd_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

# A change in *structure*, not in scale: two latent factors drive
# different halves of the node set before and after the change.
# Deliberately tiny -- this is by far the most expensive engine in the
# package (n_runs x n_reps factorisations per candidate split). Measured
# at 5-6 s across fresh sessions, against 27 s for the 2 x 25 /
# n_reps = 4
# version this replaced -- and this is the floor: `n_reps = 1` fails
# inside fabisearch with "not enough 'x' observations" (the permutation
# test needs two), and smaller matrices are not reliably cheaper because
# the search then evaluates more splits relative to `min_dist` (2 x 10 at
# min_dist = 8 measured 6.6 s). So this one example stays near CRAN's 5 s
# budget by necessity; `cran-comments.md` says so. Use the defaults on
# real data -- the settings here are for the budget, not for detection.
set.seed(2026)
block <- function(n, cols) {
  f <- abs(stats::rnorm(n)) + 0.5
  Y <- matrix(abs(stats::rnorm(n * 5)) * 0.2 + 0.1, n, 5)
  Y[, cols] <- Y[, cols] + f
  Y
}
Y <- rbind(block(12, 1:2), block(12, 3:5))
fabisearch_wrapper(Y, min_dist = 10, n_runs = 1, n_reps = 2,
                   alpha = 0.25, rank = 2)

fastcpd wrapper: fast changepoint detection via sequential gradient descent

Description

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. This wrapper exposes the time-series families most useful alongside the other engines: mean, variance, mean-and-variance, and AR/ARMA/GARCH model changepoints.

Usage

fastcpd_wrapper(
  x,
  family = c("mean", "variance", "meanvariance", "ar", "arma", "garch"),
  order = NULL,
  ...
)

Arguments

Value

A ggcpt object.

References

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

See Also

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

Functional covariance changepoints

Description

Wraps fChange::fchange() for changes in the covariance operator, eigenstructure or trace of a functional time series: the changes that leave the mean curve untouched.

Usage

fcov_wrapper(
  x,
  target = c("covariance", "trace", "eigenjoint", "eigensingle"),
  statistic = c("Tn", "Mn"),
  critical = c("simulation", "resample", "welch"),
  type = c("segmentation", "single"),
  alpha = 0.05,
  ...
)

Arguments

Value

A ggcpt object with change_in = "covariance". Multivariate input is reduced to one series per observation by taking the cross-sectional mean of the columns, and that is the series stored on the result: autoplot() draws it, tidy()'s cp_value reads it, and $segments$param_estimate and augment()'s .fitted/.resid are computed from it. It is not any one column of the input. The full input is kept in $data_wide for autoplot(type = "coordinates").

For a covariance change this matters when reading the plot: a change in the covariance structure need not move the cross-sectional mean at all, so autoplot() can legitimately show changepoint rules on a series with no visible change in it. That is the detector working, not misfiring; use autoplot(type = "coordinates") to see the columns the change is in.

How long this takes

Minutes, not seconds, on a series of a hundred points: by a wide margin the most expensive engine in the package, and slow enough that a first call looks like a hung session. Timed on one Linux x86-64 machine, against fmean_wrapper() on the identical input so the comparison is the same package and the same data:

The cost is roughly linear in the number of time points and it is in the engine's own estimation rather than in this wrapper. It is, however, dominated by target, which the rest of this section used to deny. Measured at n = 60, p = 6, M = 50 on one Linux x86-64 machine:

So the default is some two hundred times the cost of "trace", and the example below uses "trace" for that reason. Read that as a choice of test and not as a free speedup: the trace is a scalar summary of the covariance operator, so it is a weaker instrument that happens to be cheap, and the row above is one series rather than a comparison of power. If a covariance change matters and the full operator test is the one you want, budget for it.

Two practical consequences either way: size the call before starting it, and do not put the default in a loop: a twelve-replicate study at n = 120 is two hours. Another machine will give different absolute numbers; the ratios are the part to plan around. The “Benchmarks” article compares the engines that do scale.

References

Aue A, Rice G, Sönmez O (2020). “Structural break analysis for spectrum and trace of covariance operators.” Environmetrics, 31(1), e2617.

See Also

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(), fastcpd_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)
# See the note in ?fmean_wrapper on why this is 10 curves and M = 50.
X <- matrix(rnorm(60 * 10), nrow = 60)
X[31:60, ] <- X[31:60, ] * 3
fcov_wrapper(X, target = "trace", M = 50)

Functional mean changepoints

Description

Wraps fChange::fchange() for changes in the mean function of a functional time series: each observation is a curve, and the question is when the average curve shape changes. The binary-segmentation ("segmentation") mode finds multiple changes; the "single" mode runs the one-change test and reports its p-value.

Usage

fmean_wrapper(
  x,
  statistic = c("Tn", "Mn"),
  critical = c("simulation", "resample", "welch"),
  type = c("segmentation", "single"),
  alpha = 0.05,
  robust = FALSE,
  ...
)

Arguments

Value

A ggcpt object; the changepoints tibble carries the engine's p_value for each location. Multivariate input is reduced to one series per observation by taking the cross-sectional mean of the columns, and that is the series stored on the result: autoplot() draws it, tidy()'s cp_value reads it, and $segments$param_estimate and augment()'s .fitted/.resid are computed from it. It is not any one column of the input. The full input is kept in $data_wide for autoplot(type = "coordinates").

References

Aue A, Rice G, Sönmez O (2018). “Detecting and dating structural breaks in functional data without dimension reduction.” Journal of the Royal Statistical Society: Series B, 80(3), 509–529. doi:10.1111/rssb.12257.

See Also

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(), fastcpd_wrapper(), fcov_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)
# 10 curves and M = 50, not 20 and 200: the example is a demonstration,
# and the wider version measured 6.7 s against CRAN's 5 s budget.
X <- matrix(rnorm(60 * 10), nrow = 60)
X[31:60, ] <- X[31:60, ] + 2
fmean_wrapper(X, M = 50)

FPOP wrapper: Functional Pruning Optimal Partitioning

Description

Wraps the fpop package for optimal changepoint detection via functional pruning.

Usage

fpop_wrapper(x, penalty = NULL, ...)

Arguments