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 51 methods.

Detection engines. cpt_detect() dispatches to the methods in cpt_methods(), across ten 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).

• Epidemic changes and anomalies: collective and point anomalies against a baseline, for one series or many (anomaly's CAPA).

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:

• What to fit: cpt_families() (Poisson, binomial, exponential and other costs), a formula for a regression break (cpt_detect(y ~ x, data)), and cpt_segment_models() and predict() for a model per regime.

• How big, when, and whether at all: cpt_effect(), cpt_test_at() (a date fixed in advance), cpt_attribute_event(), cpt_test_null(), cpt_null_power().

• Should I believe it: cpt_assumptions(), cpt_gof(), cpt_robustness(), cpt_verify().

• Inference: cpt_confint() (five provenances, one contract, including distribution-free conformal sets) and cpt_confint_coverage(), cpt_test(), cpt_regions(), cpt_attribute() (which coordinates changed), cpt_screen() (which of many series changed).

• What would have happened, and how: cpt_counterfactual(), cpt_abruptness().

• Choosing K: cpt_select() (BIC, Zhang-Siegmund mBIC, AIC, CROPS elbow, cross-validation, stability), cpt_k_weights(), 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() (e-detector, CUSUM and EWMA control charts, cpm, ocd), 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.

• Leaving R: as_json(), cpt_export(), cpt_import().

• Measurements: cpt_runtimes, cpt_invariances, cpt_noise_benchmark, cpt_data_types, cpt_null_sizes, cpt_calibration.

Every condition the package raises is classed; see ggchangepoint-conditions.

Author(s)

Maintainer: Youzhi Yu yuyouzhi666@icloud.com

See Also

The entry points, by group:

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

• After detection: cpt_effect(), cpt_test_at(), cpt_assumptions(), cpt_robustness().

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

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

• What if: cpt_counterfactual(), cpt_abruptness().

• 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(), as_json(), cpt_annotations(), cpt_export(), cpt_verify(), ggchangepoint-conditions, 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(), as_json(), cpt_annotations(), cpt_export(), cpt_verify(), ggchangepoint-conditions, 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(), as_json(), cpt_annotations(), cpt_export(), cpt_verify(), ggchangepoint-conditions, 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)

Convert a result to JSON

Description

The whole result as JSON, under a documented and versioned schema, for software that consumes changepoint results rather than a person reading them.

Usage

as_json(x, ...)

## S3 method for class 'ggcpt'
as_json(x, pretty = TRUE, data = TRUE, assumptions = TRUE, digits = NA, ...)

## Default S3 method:
as_json(x, ...)

Arguments

Value

A single string of class "json".

Schema 1.0.0

One object with these fields. Every field is always present; one that does not apply is null, so a reader never has to test for a key.

schema, schema_version

"ggchangepoint.ggcpt" and the version, "1.0.0".

method, engine, engine_version, ggchangepoint_version, r_version, created

what produced the result, and when (ISO 8601).

change_in, family

what was detected, and the distribution family if one was asked for.

penalty

{"type", "value"}.

cp_convention

"left": a changepoint is the last observation of its segment.

n

the series length.

index

{"class", "label", "tz"} of the time index, or null. Dates are written as ISO 8601 strings and timestamps with their offset; tz is a timestamp index's time zone (null otherwise).

changepoints

an array of objects, one per changepoint: cp (position) and cp_value, with cp_index when there is an index, and every engine-specific column (ci_lower, ci_upper, posterior_prob, ...).

segments

seg_id, start, end, n, param_estimate.

regions, coefficients, constraints

the optional slots, as arrays of objects (or an object), or null.

diagnostics

residual_dependence (Ljung-Box p_value, lag, acf1), na_omitted and expected_false_positives where recorded.

assumptions

the cpt_assumptions() rows, or null.

call

the call that made the result, as text.

data

{"index", "value", "fitted", "coordinates"} arrays, or null. coordinates is an object with one array per coordinate of a multivariate result (null for a single series), whose first is value.

See Also

cpt_export() to write a file, cpt_import() to read one back, cpt_report(format = "json").

Other result class: annotate_segments(), as_cpt_series(), as_ggcpt(), cpt_annotations(), cpt_export(), cpt_verify(), ggchangepoint-conditions, is_ggcpt(), new_ggcpt(), print.ggcpt()

Examples

set.seed(1)
fit <- cpt_detect(c(rnorm(50), rnorm(50, 3)), method = "pelt")
cat(as_json(fit, data = FALSE))

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. Each coordinate also gets its own .fitted_<name> and .resid_<name> (its segment means and residuals), 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, bocpd, beast, decafs, segmented, envcpt, mcp and bfast; a formula fit carries its piecewise regression's fitted values the same way.

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.

Examples

set.seed(2026)
fit <- cpt_detect(c(rnorm(60), rnorm(60, 3)), method = "pelt")
head(augment(fit))

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", "diagnostics", "counterfactual",
    "attribution"),
  ...
)

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.

Examples

set.seed(2026)
fit <- cpt_detect(c(rnorm(60), rnorm(60, 3), rnorm(60)), method = "pelt")
ggplot2::autoplot(fit)
ggplot2::autoplot(fit, type = "diagnostics")

# a dated series draws its dates
dated <- cpt_detect(Nile, method = "pelt", change_in = "meanvar")
ggplot2::autoplot(dated)

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

CAPA wrapper: collective and point anomalies (epidemic changepoints)

Description

Wraps anomaly::capa() (Fisch, Eckley and Fearnhead 2022): finds stretches of the series that depart from a persistent baseline and return to it (collective anomalies: an outbreak that subsides, a fault that is repaired, a campaign that ends) and single outlying observations (point anomalies), for one series or many. For a multivariate series it also reports which coordinates each anomaly affects.

Usage

capa_wrapper(
  x,
  change_in = c("mean", "meanvar"),
  robust = FALSE,
  beta = NULL,
  beta_tilde = NULL,
  min_seg_len = 10,
  max_seg_len = Inf,
  max_lag = 0,
  standardise = TRUE,
  ...
)

Arguments

Value

A ggcpt object whose changepoints are the anomaly boundaries and whose regions slot lists the anomalies, plus a baseline element holding the centre and scale used to standardise each coordinate.

How the result reads

The baseline is everything that is not anomalous, and it is one regime, which is what separates this model from an ordinary segmentation. Each collective anomaly from s to e contributes two changepoints, s - 1 (the last baseline observation before it) and e (its last observation), so the segments alternate between the baseline and the anomalies and every tool built on changepoints works unchanged. The anomalies themselves are in the regions slot, read with cpt_regions(): one row per anomaly with start, end, type ("collective" or "point"), coordinates (the affected coordinates, comma separated), mean_change (the engine's squared standardised mean change for a collective anomaly) and strength (the engine's strength for a point anomaly). Point anomalies are outliers, not changes, so they add no changepoint. autoplot() shades the collective anomalies and rings the point ones, and cpt_attribute() can certify, with error control, which coordinates changed at each boundary.

A series whose two halves differ, with no baseline to return to, is not what CAPA models: the median of such a series lies between the two levels, so both halves look anomalous. Use an ordinary detector for a step.

References

Fisch ATM, Eckley IA, Fearnhead P (2022). “A linear time method for the detection of collective and point anomalies.” Statistical Analysis and Data Mining, 15(4), 494–508. doi:10.1002/sam.11586.

Fisch ATM, Eckley IA, Fearnhead P (2022). “Subset multivariate collective and point anomaly detection.” Journal of Computational and Graphical Statistics, 31(2), 574–585. doi:10.1080/10618600.2021.1987257.

See Also

cpt_regions(), cpt_attribute().

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(), 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 <- c(rnorm(150), rnorm(40, 3), rnorm(150))
x[60] <- 9
fit <- capa_wrapper(x)
cpt_regions(fit)
ggplot2::autoplot(fit)

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 = NULL, 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(), capa_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(), capa_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)

Was the change abrupt? A step against a ramp, at every changepoint

Description

For each changepoint of a change in mean, fits the window around it (between the neighbouring changepoints) twice: as a step, which is what every detector assumes, and as a linear ramp from the old level to the new one, with its centre and width estimated. When the ramp fits clearly better, the change took time, and the reported location is the middle of a transition rather than a moment.

Usage

cpt_abruptness(fit, level = 0.95, max_width = NULL)

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

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

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

Arguments

Value

A ggcpt_abruptness tibble with one row per changepoint: cp, window_start, window_end, width (the best ramp width, in observations), width_lower and width_upper (its interval), centre (the ramp's centre), statistic (the likelihood-ratio statistic against the step), p_value and verdict ("abrupt" when the step is not rejected, "gradual" when it is). autoplot() draws each window with the step and the ramp; print() and tidy() work as usual.

How it decides

For a ramp of width w centred at c, the level is a before c - w/2, b after c + w/2, and linear between, so for fixed (c, w) the fit is ordinary least squares in (a, b). The residual sum of squares is profiled over the centre for each width on a grid (every width up to 8, then geometric), and the step is the width-0 member of the family. The statistic m \log(RSS_{step} / RSS_{ramp}) over the window's m observations is compared with a chi-squared distribution on one degree of freedom. The step sits on the boundary of the family, which makes that reference conservative, and the search over widths and centres, which makes it liberal; measured on true steps (jumps of 1 to 8 noise standard deviations, n of 300 and 1,000, Gaussian and t_3 noise, 400 replicates each, detected with pelt), the step was rejected in 1.0 to 5.2 per cent of fits at level = 0.95. A ramp of 2 standard deviations over 30 observations was called gradual in 53 per cent of fits at n = 300, over 60 observations in 70 per cent. The width interval collects every width whose profile statistic is within the chi-squared quantile of the best.

A ramp also fits a step plus a few outliers near it, and a window that holds a second, undetected change; read "gradual" as "a step is not an adequate description", and look at autoplot().

See Also

cpt_simulate() with transition, to measure how a detector places a gradual change; cpt_gof().

Other inference: cpt_assumptions(), cpt_attribute(), cpt_attribute_event(), cpt_confint_coverage(), cpt_effect(), cpt_gof(), cpt_k_weights(), cpt_null_power(), cpt_robustness(), cpt_screen(), cpt_test_at(), cpt_test_null()

Examples

set.seed(2026)
ramp <- c(rep(0, 100), seq(0, 4, length.out = 30), rep(4, 100))
fit <- cpt_detect(ramp + rnorm(230, 0, 0.5), method = "pelt")
cpt_abruptness(fit)
step <- cpt_detect(c(rnorm(100), rnorm(100, 4)), method = "pelt")
cpt_abruptness(step)

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(), as_json(), cpt_export(), cpt_verify(), ggchangepoint-conditions, is_ggcpt(), new_ggcpt(), print.ggcpt()

Examples

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

Check the assumptions behind a segmentation

Description

A short report on whether the result's assumptions look violated for this series, what that does to the answer, and what would model it. It reports and does not act: every automatic correction measured trades true changepoints for false ones, and which side of that trade matters is the analyst's decision.

Usage

cpt_assumptions(fit, lag = NULL)

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

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

Arguments

Value

A ggcpt_assumptions tibble with one row per check: component, value, flag (TRUE when the check raises a concern), detail and advice. The components:

residual_dependence

Ljung-Box p-value on the within-segment residuals (and their lag-1 autocorrelation in detail). Flagged below 0.05. Autocorrelated noise is the commonest reason for spurious changepoints.

scale_sensitivity

the noise standard deviation, flagged when the engine's answer depends on the data's units (measured) and the noise is far from unit scale.

expected_false_positives

how many changepoints the engine is expected to report on this much pure noise: n / arl0 for cpm, and the measured null-size table otherwise. Flagged above one.

count_plausibility

reported changepoints per hundred observations, flagged above one: more than n / 100 is more often misconfiguration than a finding.

data_type

what the series looks like (continuous, counts, binary, proportions), flagged when a Gaussian cost is fitted to non-Gaussian data.

See Also

cpt_report(), which prints this; cpt_robustness() for the answer under other noise models.

Other inference: cpt_abruptness(), cpt_attribute(), cpt_attribute_event(), cpt_confint_coverage(), cpt_effect(), cpt_gof(), cpt_k_weights(), cpt_null_power(), cpt_robustness(), cpt_screen(), cpt_test_at(), cpt_test_null()

Examples

set.seed(1)
ar <- as.numeric(arima.sim(list(ar = 0.7), 300))
cpt_assumptions(cpt_detect(ar, method = "pelt"))

Which coordinates changed? Certified attribution for a multivariate fit

Description

For each changepoint of a multivariate result, tests every coordinate for a change in its window and returns the set certified to have changed, with family-wise error or false discovery rate control and a location or scale label for each certified coordinate. This is ARM, attribution by rank maxima (Peng et al. 2026). It accepts the changepoints of any detector, including a registered one or a result built with as_ggcpt(), and its guarantee does not depend on how, or how well, they were located.

Usage

cpt_attribute(
  object,
  alpha = 0.05,
  control = c("fwer", "holm", "fdr"),
  B = 999,
  margin = NULL,
  seed = NULL
)

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

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

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

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

Arguments

Value

A ggcpt_attribution tibble with one row per changepoint and coordinate: cp, cp_index (when the result has a time index), coordinate, statistic (the coordinate's maximum over splits and channels), statistic_location, statistic_scale, p_value (the per-coordinate permutation p-value), p_adjusted (adjusted for control), changed (TRUE when certified at alpha), type ("location" or "scale" for a certified coordinate, NA otherwise), window_start, window_end, n_window (rows used, after dropping any with a missing value) and source ("arm"). print(), autoplot() (a coordinate-by-changepoint map with the certified cells outlined), tidy() and glance() work on it.

What is certified, and what is not

Each changepoint is examined in its own window: the stretch of the series between its neighbouring changepoints (the whole series for a single changepoint). Coordinate j is tested for the null hypothesis that its values in the window are identically distributed, that is, that it did not change there. For every split t of the window the location evidence is the standardised Wilcoxon rank sum and the scale evidence the standardised Mood statistic (squared centred ranks), each computed from that coordinate's own ranks; the coordinate's statistic is the largest of the two over every split. That maximum is what makes the result independent of the detector: no estimate of the location can make a coordinate that did not change look more changed than the maximum already allows for.

The guarantees are per changepoint. With K changepoints the chance of any false attribution anywhere is at most K times alpha under "fwer" and "holm". They also take the window as given: the neighbouring changepoints were located from the same data, so for a fit with several changepoints the guarantee holds conditionally on those windows, and exactly for a single changepoint. Rows of the window are assumed independent (permutation is exchangeable only then), so serially dependent data need care, as everywhere else.

The type label is descriptive and carries no error control of its own: "scale" when the scale evidence is the larger, "location" otherwise.

References

Peng C, Wu M, Yan Q, Chen D, Shen Z (2026). “ARM: Detector-Agnostic Changepoint Attribution with Finite-Sample Error Control.” arXiv preprint arXiv:2608.01691.

See Also

cpt_confint() for where a changepoint is; cpt_attribute_event() for attributing a change to a named event rather than to a coordinate.

Other inference: cpt_abruptness(), cpt_assumptions(), cpt_attribute_event(), cpt_confint_coverage(), cpt_effect(), cpt_gof(), cpt_k_weights(), cpt_null_power(), cpt_robustness(), cpt_screen(), cpt_test_at(), cpt_test_null()

Examples

set.seed(2026)
n <- 120
X <- matrix(rnorm(n * 6), n, 6,
            dimnames = list(NULL, paste0("sensor", 1:6)))
X[61:n, 2] <- X[61:n, 2] + 2   # a shift in sensor2
X[61:n, 5] <- X[61:n, 5] * 3   # a scale change in sensor5
fit <- cpt_detect(X, method = "ecp")
att <- cpt_attribute(fit, B = 199, seed = 1)
att
ggplot2::autoplot(att)

Was a detected change the event you have in mind?

Description

The mirror of cpt_test_at(). A detector found a change on 14 March and something is known to have happened on 1 March: is that the same event? The detection's confidence interval answers it: an event inside the interval is consistent with being the change, one outside is not.

Usage

cpt_attribute_event(fit, event, level = 0.95, ...)

Arguments

Value

A tibble with one row per event: event, event_position, the nearest changepoint cp (and cp_index), its interval ci_lower/ci_upper, distance (positions from the changepoint to the event), inside and a plain-language verdict.

See Also

Other inference: cpt_abruptness(), cpt_assumptions(), cpt_attribute(), cpt_confint_coverage(), cpt_effect(), cpt_gof(), cpt_k_weights(), cpt_null_power(), cpt_robustness(), cpt_screen(), cpt_test_at(), cpt_test_null()

Examples

set.seed(1)
dates <- as.Date("2026-01-01") + 0:119
fit <- cpt_detect(c(rnorm(60), rnorm(60, 3)), method = "strucchange",
                  index = dates)
cpt_attribute_event(fit, as.Date(c("2026-02-28", "2026-04-10")))

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). A method that fails on one dataset (its engine errors, is not installed, or cannot take that series: see ggchangepoint-conditions) records the message and the grid continues. Invalid data or arguments, which every method would reject, stop the benchmark instead, naming the dataset and method, so a mistake in the call is not reported as a finding about an engine.

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)

What the package promises, against what it delivers

Description

The calibration suite: every guarantee the documentation states that a simulation can check, with the realised value and its Monte Carlo standard error. Location intervals and sets are scored for coverage (conditional on a changepoint landing within 20 positions of the truth), tests for their size at 5% on data with no change, monitors for their in-control run length, and the panel screen for its false discovery rate. The row for cpt_test() at a location the data chose is there to show what selection_adjusted = FALSE means: its nominal 5% is not what it delivers.

Usage

cpt_calibration

Format

A tibble with one row per guarantee and setting:

guarantee

what is promised, and by which function.

call

the call that was measured.

setting

the data and the options it was measured on.

kind

"coverage", "size" (for cpt_attribute(), the family-wise error over the coordinates that did not change), "run_length" or "false_discovery_rate".

nominal

the promised value: a confidence level, a test's level or an average run length (for the e-detector, a lower bound).

realised

the measured value.

mcse

its Monte Carlo standard error.

reps

replicates that counted (for coverage, those that detected the change).

Source

data-raw/calibration.R.

See Also

The calibration article on the package website, https://pursuitofdatascience.github.io/ggchangepoint/articles/calibration.html.

Other measurement tables: cpt_data_types, cpt_invariances, cpt_noise_benchmark, cpt_null_sizes, cpt_runtimes

Examples

cpt_calibration[, c("call", "nominal", "realised", "mcse")]

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 five 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", "conformal"),
  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), and set_size for method = "conformal" (how many locations the confidence set holds; an empty set has NA bounds and warns, because no single change between exchangeable segments fits that window). 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.

The conformal route was measured with cpt_confint_coverage() on the same design (300 replicates per cell, pelt, level 0.95). For a jump of three standard deviations it covered 0.960 at a mean width of 0.5 (the bootstrap: 0.973 at 2.0); for a jump of one standard deviation 0.970 at 18.6, where the bootstrap fell short of the level at 0.926 (width 25.8); under t_3 noise with a jump of two, 0.963 at 3.5 (bootstrap 0.943 at 4.4). Its guarantee assumes exchangeable observations within each segment, and under AR(1) noise with \rho = 0.3 it covered 0.920 (bootstrap 0.887): dependent noise shortens every interval here, and cpt_assumptions() checks for it.

References

Hore R, Ramdas A (2026). “Conformal changepoint localization.” arXiv preprint arXiv:2602.06267.

See Also

cpt_confint_coverage(), which measures how often each route covers; 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 = "conformal", B = 50, seed = 1)
cpt_confint(fit, method = "bootstrap", B = 25, seed = 1)

How often do the confidence intervals cover? A Monte Carlo check

Description

Simulates series with one changepoint of known location, detects with method, computes cpt_confint() by each route in routes, and reports how often the interval contains the true location and how wide it was. This is the measurement behind the coverage statements in ?cpt_confint, and the way to check them for your own series length, jump size and noise before relying on an interval.

Usage

cpt_confint_coverage(
  method = "pelt",
  routes = c("conformal", "bootstrap"),
  n = 200,
  jump = 2,
  noise = c("gauss", "t", "ar1"),
  n_sim = 100,
  level = 0.95,
  B = 100,
  seed = NULL,
  ...
)

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

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

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

Arguments

Details

The changepoint sits at floor(n / 2). Coverage is computed over the replicates in which the detector reported at least one changepoint, taking the one nearest the truth, so it is coverage given a detection; n_detected says how many replicates that is. A route that fails on a replicate (an engine that supplies no native interval, say) is counted in n_failed rather than as a miss.

Value

A ggcpt_coverage tibble with one row per route: method, route, n_sim, n_detected, n_failed, coverage, coverage_se (its Monte Carlo standard error), mean_width, level. print(), autoplot() (coverage with a two-standard-error bar against the nominal level) and tidy() work on it.

See Also

cpt_confint(), cpt_calibration.

Other inference: cpt_abruptness(), cpt_assumptions(), cpt_attribute(), cpt_attribute_event(), cpt_effect(), cpt_gof(), cpt_k_weights(), cpt_null_power(), cpt_robustness(), cpt_screen(), cpt_test_at(), cpt_test_null()

Examples

cov <- cpt_confint_coverage(n_sim = 6, n = 80, B = 20, seed = 1)
cov
ggplot2::autoplot(cov)

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 = "majority",
  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 does not remove shared false positives

Voting removes the idiosyncrasies of individual algorithms. It does not remove a false positive that every algorithm makes for the same reason, and a violated assumption is exactly such a reason: measured under AR(1) noise, every one of pelt's spurious changepoints was reproduced by wbs within five observations, and the 2-of-3 consensus of pelt, binseg and wbs had more false positives (1.40) than two of its own members. The useful signal in a panel is its disagreement: the disagreement value in the consensus attribute is the share of the locations any member found that not every member found, and a high value says the members' shared assumption may be what is wrong (see cpt_assumptions() and cpt_robustness()).

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)

What would have happened without the change? Observed against counterfactual

Description

For each changepoint, carries the segment before it forward over the segment after it, using that segment's own model, and sets the prediction beside what was observed. The gap is the effect of the change, observation by observation, in the units of the data: the interrupted-time-series exhibit.

Usage

cpt_counterfactual(
  fit,
  model = NULL,
  data = NULL,
  engine = stats::lm,
  level = 0.95,
  ...
)

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

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

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

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

Arguments

Value

A ggcpt_counterfactual tibble with one row per observation after each changepoint, up to the next: cp (the change it belongs to), position, index (the time index, or the position when there is none), observed, counterfactual, lower and upper (the prediction interval, NA when the model supplies none) and effect (observed - counterfactual). autoplot() draws the series with each counterfactual and its band; glance() gives one row per change with the mean and cumulative effect; print() and tidy() work as usual.

Reading it

The counterfactual is a prediction from the pre-change segment alone, so its interval widens the further it is carried: a level is carried at constant width, a line fans out. The interval describes the pre-change model's uncertainty, not the location's: the changepoint is taken as given, and cpt_confint() is the place to ask how sure that location is. Where the detector chose the location from the same data, the effect is the naive one, and cpt_effect() measures it on held-out observations instead.

See Also

cpt_effect(), cpt_segment_models(), predict.ggcpt().

Other segment models: cpt_segment_models(), predict.ggcpt()

Examples

set.seed(2026)
x <- c(rnorm(80, 10), rnorm(60, 13))
fit <- cpt_detect(x, method = "pelt", change_in = "meanvar")
cf <- cpt_counterfactual(fit)
glance(cf)
ggplot2::autoplot(cf)

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")

False positives and power by data type

Description

Ten replicates of a 400-point series with one change at 200, at comparable effect sizes across four data types: Gaussian (a shift of 1.4 standard deviations), Bernoulli (probability 0.15 to 0.75), Poisson (rate 2 to 10) and a proportion (binomial of 20, 0.25 to 0.6). Each engine is at its default, as a user who does not set family gets it.

Usage

cpt_data_types

Format

A tibble with one row per engine and data type:

method

the engine.

data_type

"gaussian", "bernoulli", "poisson" or "proportion".

reps

replicates that ran.

hit_rate

share of replicates finding the change within 20 positions.

fp

mean number of other reported changepoints.

Source

data-raw/measure_engines.R (part datatype).

See Also

Other measurement tables: cpt_calibration, cpt_invariances, cpt_noise_benchmark, cpt_null_sizes, cpt_runtimes

Examples

b <- subset(cpt_data_types, data_type == "bernoulli")
b[order(-b$fp), ][1:5, ]

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,
  ...,
  data = NULL,
  family = NULL,
  group = NULL,
  na_action = c("error", "omit", "engine"),
  fixed = NULL,
  within = NULL,
  min_segment = NULL,
  min_effect = NULL,
  keep_fit = TRUE
)

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, 27 at \sigma = 3 and 76 at \sigma = 10. These are means over 20 draws, because a single draw is not stable here: the same settings gave 15/38 at n = 100 and 47/152 at n = 400, so the effect grows with the series as well as with the noise. (0.5.0, before the two-point minimum segment, reported 39 and 141 at n = 200: the floor halves the damage and does not remove it.) A measured scale-sensitive engine given noise far from unit scale warns (class ggchangepoint_scale_sensitive). 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. Five 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; "bocpd"'s default prior is on the data's own scale; and "envcpt" and "var" changed their answer with the units too (var's gamma_set and lambda_set penalise a squared-error loss on an absolute scale). At a thousandth of the units "decafs", "bocpd" and "var" found nothing. Standardising first avoids all five, and cpt_invariances holds the measurement.

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")

# Counts, with a cost written for them.
counts <- c(rpois(100, 2), rpois(100, 6))
cpt_detect(counts, method = "pelt", family = "poisson")

# Missing values, located in the original positions.
gappy <- x
gappy[c(20, 21, 150)] <- NA
cpt_detect(gappy, method = "pelt", na_action = "omit")$changepoints

# A changepoint known in advance, and a window for another.
cpt_detect(x, method = "pelt", fixed = 50)$changepoints

# Breakpoints in a regression.
if (requireNamespace("strucchange", quietly = TRUE)) {
  d <- data.frame(t = 1:200, z = rnorm(200))
  d$y <- ifelse(d$t <= 120, 1 + d$z, 3 - d$z) + rnorm(200, 0, 0.5)
  fit <- cpt_detect(y ~ z, data = d, method = "strucchange")
  tidy(fit, "coefficients")
}

Effect size at each changepoint

Description

The size of every change a fit reports, in the data's own units and standardised: the level before and after, their difference with an interval, the difference in noise standard deviations, the percentage change, and for count and waiting-time data the rate or hazard ratio.

Usage

cpt_effect(fit, level = 0.95, method = c("naive", "split"), seed = NULL, ...)

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

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

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

Arguments

Value

A ggcpt_effect tibble with one row per changepoint (per changepoint and coordinate for a multivariate fit, per changepoint and term for a regression fit): cp (and cp_index), before, after, n_before, n_after, delta, delta_lower, delta_upper (a Welch interval), delta_std (the change in noise standard deviations, the unit cpt_detect(min_effect = ) filters on), pct_change, sd_before, sd_after, sd_ratio, the family-specific ratio where it applies (rate_ratio for Poisson counts, odds_ratio for binary data, hazard_ratio for exponential waiting times, each with an interval), selection_adjusted and method. With print() and autoplot().

The winner's curse

A change measured at a location the same data chose is biased upward: the detector put the boundary where the two sides differ most, so the difference it reports is the largest the noise allowed. The bias is worst for the marginal detections, which are exactly the ones whose size matters. method = "naive" rows carry selection_adjusted = FALSE for that reason, except at a changepoint fixed in advance with cpt_detect(fixed = ), which the data did not locate and which is TRUE. method = "split" is honest about the size (the measuring half never influenced the locations) and less precise about the location (the locating half has half the data), and it assumes the noise is independent from one observation to the next, since the two halves are interleaved.

See Also

cpt_test_at() for a change at a date fixed in advance, cpt_detect()'s min_effect.

Other inference: cpt_abruptness(), cpt_assumptions(), cpt_attribute(), cpt_attribute_event(), cpt_confint_coverage(), cpt_gof(), cpt_k_weights(), cpt_null_power(), cpt_robustness(), cpt_screen(), cpt_test_at(), cpt_test_null()

Examples

set.seed(1)
fit <- cpt_detect(c(rnorm(100, 10), rnorm(100, 12)), method = "pelt")
cpt_effect(fit)

counts <- c(rpois(100, 4), rpois(100, 8))
cpt_effect(cpt_detect(counts, method = "pelt", family = "poisson"))

Write a result to a file, and read it back

Description

cpt_export() writes a result where software in any language can read it; cpt_import() rebuilds a working ggcpt from the file. A saved .rds already reads in any R session without this package (a ggcpt is a plain list of plain data), so these are for leaving R, or for a format a person can open.

Usage

cpt_export(fit, file, format = NULL, ...)

cpt_import(file, format = NULL, method = "imported", change_in = "mean")

Arguments

Value

cpt_export() returns file, invisibly. cpt_import() returns a ggcpt object; the engine's own $fit is not stored in either format, so it is NULL.

See Also

Other result class: annotate_segments(), as_cpt_series(), as_ggcpt(), as_json(), cpt_annotations(), cpt_verify(), ggchangepoint-conditions, is_ggcpt(), new_ggcpt(), print.ggcpt()

Examples

set.seed(1)
fit <- cpt_detect(c(rnorm(50), rnorm(50, 3)), method = "pelt")
path <- tempfile(fileext = ".json")
cpt_export(fit, path)
back <- cpt_import(path)
back$changepoints
unlink(path)

Distribution families, and what each request runs

Description

The family argument of cpt_detect() names the distribution a segment is modelled with, so count data, waiting times and binary series can be segmented with a cost written for them rather than a Gaussian one. cpt_families() is the table behind it: every legal combination of method, change_in and family, and the engine call each becomes.

Usage

cpt_families(method = NULL)

Arguments

Value

A tibble with one row per legal combination: method, change_in, family (NA for a distribution-free method, which takes no family), engine_call (what is run) and data (what the family requires of the series: "counts", "binary", "positive" or NA).

The families

"gaussian"

The default of every parametric method. On "cpm" it also switches from the nonparametric statistics to the Gaussian ones (Student, Bartlett).

"poisson"

Counts: change_in = "mean" is a change in the rate. Needs non-negative whole numbers.

"binomial"

Binary outcomes: a change in the success probability. Needs 0/1 data.

"exponential"

Waiting times: a change in the rate (the hazard), so change_in = "mean". Needs positive data.

"gamma"

Positive data with a known shape (pass shape, default 1): a change in the scale.

"laplace"

Heavy tails: a change in the median and the scale (change_in = "meanvar").

"l1"

The absolute-loss cost: a change in the median, robust to outliers (change_in = "mean").

A single-parameter family has one thing to change, so Poisson, binomial, exponential and gamma requests use change_in = "mean".

Why an argument and not a model grammar

A grammar that marks the changing parameter (poisson(rate = NA), normal(mean = NA, sd = 1)) would unify change_in, family and the formula interface in one expression, and measured against the fifty methods it fits 42 of them cleanly. It is deferred to 1.0, where change_in can be replaced rather than joined by a second idiom, and this table is the first half of it: change_in = "mean", family = "poisson" already means poisson(rate = NA) internally.

See Also

cpt_detect(), cpt_methods() (its families column), cpt_simulate() to generate data from each family.

Examples

cpt_families("pelt")
# every method that can fit a Poisson rate
unique(subset(cpt_families(), family == "poisson")$method)

set.seed(1)
counts <- c(rpois(100, 3), rpois(100, 9))
cpt_detect(counts, method = "pelt", family = "poisson")

Goodness of fit, segment by segment

Description

The checks behind a segmentation, as numbers: for every segment, its length, level and spread, whether its residuals look independent (Ljung-Box) and Gaussian (Shapiro-Wilk), and a flag where the segment is too short for either test to mean anything.

Usage

cpt_gof(fit, lag = NULL)

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

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

Arguments

Value

A ggcpt_gof tibble with one row per segment (per segment and coordinate for a multivariate fit): seg_id, start, end, n, mean, sd, acf1 (lag-1 autocorrelation of the residuals), ljung_box_p, shapiro_p, and too_short (fewer than 12 observations, where the tests are left NA). The whole-series Ljung-Box result is attached as the "overall" attribute, and print() summarises what the columns say.

See Also

autoplot(fit, type = "diagnostics") draws the same checks; cpt_assumptions() reports them with the alternatives.

Other inference: cpt_abruptness(), cpt_assumptions(), cpt_attribute(), cpt_attribute_event(), cpt_confint_coverage(), cpt_effect(), cpt_k_weights(), cpt_null_power(), cpt_robustness(), cpt_screen(), cpt_test_at(), cpt_test_null()

Examples

set.seed(1)
fit <- cpt_detect(c(rnorm(100), rnorm(100, 3, 2)), method = "pelt")
cpt_gof(fit)

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 the two engines CRAN has archived. fpop, archived in September 2026 at its maintainer's request, is installed from R-Forge (https://R-Forge.R-project.org), where it is developed. ocp, archived in October 2026, is installed from the package website (https://pursuitofdatascience.github.io/ggchangepoint/repo/), a CRAN-like repository that serves the last CRAN release of every engine CRAN no longer does.

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)

Invariances of every engine's answer

Description

Five replicates of a 200-point series with changes at 70 and 140 (a 3-coordinate version for the multivariate engines), detected as given and transformed. A correct mean-change detector returns the same changepoints on 10 * x, 0.1 * x and x + 100, and n - cp on the reversed series.

Usage

cpt_invariances

Format

A tibble with one row per engine:

method

the method.

reps

replicates that ran.

k

median changepoints on the series as given.

scale_invariant

the same answer at x, 10 * x and 0.1 * x in at least four of five replicates. FALSE for the Gaussian-cost engines that assume unit noise, which is why cpt_detect() warns when one is handed noise far from unit scale.

shift_invariant

the same answer on x + 100.

reversal_rate

share of replicates whose reversed series gives the mirrored answer.

sequential

the reversal test fails in most replicates: the answer depends on the direction of time.

concat_k

median changepoints on c(x, x) (four expected, one for a single-change design).

dup_k

median changepoints when every observation is repeated twice, which makes the noise strongly autocorrelated: a measure of how badly the engine fails when its independence assumption does.

Source

data-raw/measure_engines.R (part invariance).

See Also

Other measurement tables: cpt_calibration, cpt_data_types, cpt_noise_benchmark, cpt_null_sizes, cpt_runtimes

Examples

subset(cpt_invariances, !scale_invariant)$method

How sure is the number of changepoints? Weights over K

Description

Turns the criterion curve of cpt_select() into weights over the candidate numbers of changepoints, and averages the candidate segmentations under those weights into a probability, at each location, that it is a changepoint.

Usage

cpt_k_weights(sel)

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

## S3 method for class 'ggcpt_k_weights'
tidy(x, what = c("k", "locations"), ...)

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

## S3 method for class 'ggcpt_k_weights'
autoplot(object, what = c("k", "locations"), ...)

Arguments

Value

A ggcpt_k_weights tibble with one row per candidate: k, value (the criterion), delta, weight and chosen. tidy(x, what = "locations") returns the model-averaged probability of a changepoint at each location any candidate uses (position, index, probability); autoplot(x) draws the weights and autoplot(x, what = "locations") the probabilities. print() and glance() (the chosen K, its weight, and the smallest set of K holding 95% of the weight) work on it.

The weights

With \Delta_K the criterion of K changepoints minus the smallest, the weight of K is \exp(-\Delta_K / 2) normalised over the candidates. For "aic" these are Akaike weights; for "bic" and "mbic" they approximate posterior probabilities of each K under equal prior weight. They are conditional on the candidate segmentations: each K is represented by the one segmentation the ladder found for it, so the location probabilities reflect uncertainty about how many changes there are, not about where a given one falls (cpt_confint() answers that).

See Also

cpt_select().

Other inference: cpt_abruptness(), cpt_assumptions(), cpt_attribute(), cpt_attribute_event(), cpt_confint_coverage(), cpt_effect(), cpt_gof(), cpt_null_power(), cpt_robustness(), cpt_screen(), cpt_test_at(), cpt_test_null()

Examples

set.seed(2026)
x <- c(rnorm(80), rnorm(80, 1.2), rnorm(80, 0.4))
sel <- cpt_select(x, criterion = "bic", k_max = 6)
w <- cpt_k_weights(sel)
w
tidy(w, what = "locations")
ggplot2::autoplot(w)

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'
tidy(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(), tidy() 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'
tidy(x, ...)

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

Arguments

Value

A ggcpt_penalty_model object with print(), coef(), tidy() (the coefficients as term and estimate) 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 five: "edetector", "cpm", "ocd", "cusum" and "ewma". The two sets overlap without coinciding: bocpd is an online algorithm this table marks but the monitor does not offer, and edetector, cusum and ewma are native to this package rather than wrapped engines, so they have no row here at all.

families, choices, formula, min_segment, na_handling, cp_convention_upstream

The modelling vocabulary (omitted when capabilities = FALSE): the distribution families cpt_detect(family = ) accepts (see cpt_families(); NA for a distribution-free method); the engine's modelling-choice arguments and their legal values, which cpt_detect() validates; whether it takes a formula with covariates; the engine argument min_segment is translated into; what the engine does with a missing value, measured rather than read from its documentation ("native", "compacts", "silent_loss" or "reject"; see cpt_detect(na_action = )); and the engine's own changepoint convention, which the wrapper translates to "left" ("right": it reports the first observation after the change; "continuous": a location it estimates on a continuous scale; "design": rows of a lagged design).

scale_invariant, sequential, max_cp, tier, noise_model_arg, rate_arg, cost, max_n

Measured and recorded properties (omitted when capabilities = FALSE): whether the answer is the same at x, 10 * x and 0.1 * x; whether it depends on the direction of time; how many changepoints the method can return where that is fixed; "general" for the general-purpose workhorses; the argument that selects the noise model and the one that sets the false-alarm rate; the runtime class at n = 10{,}000 ("fast" under a second, "moderate" under ten, "slow"); and the longest series it finished within the measurement's time cap (0 when it did not finish 1,000 observations). The measurements behind them are the cpt_runtimes and cpt_invariances data sets.

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 = NULL, 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. It has a floor: an empty prediction scores about 1/(K+1) for K true changepoints (0.5 for one change in the middle), so covering is not comparable across problems with different K and should not be averaged over them. cpt_benchmark() ranks within each dataset instead for exactly that reason.

covering_floor, covering_scaled

the covering an empty prediction scores on this truth (the sum of the squared true segment shares, 1/(K+1) when the segments are equal), and covering rescaled so that the floor is 0 and a perfect segmentation 1, (covering - floor)/(1 - floor): comparable across problems with different K. NA when K = 0, where the floor is already 1.

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.

precision, recall and f1 are thresholded at margin: a changepoint off by margin counts as found and one off by margin + 1 as missed, so they can move from 1 to 0 on a one-observation change. covering, hausdorff, rand_index and the matched errors are continuous in the location.

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 = NULL, 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'
tidy(x, ...)

## 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 print() and tidy() (one row) methods.

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", "cusum", "ewma"),
  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,
  ...,
  k = 0.5,
  lambda = 0.2,
  limit = NULL
)

## 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", "control_chart"),
  ...
)

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.

Control charts

"cusum" and "ewma" are the two charts statistical process control runs, and they are sequential changepoint detectors under another name. Each standardises the stream by the baseline's mean and standard deviation (Phase I; the baseline should be in control) and then monitors it (Phase II). The CUSUM keeps S_t^+ = \max(0, S_{t-1}^+ + z_t - k) and S_t^- = \max(0, S_{t-1}^- - z_t - k) and alarms when either reaches h; the EWMA keeps z_t = \lambda x_t + (1 - \lambda) z_{t-1} and alarms when it leaves \pm L \sqrt{\lambda / (2 - \lambda)}. The limit is solved for arl0 by the Markov-chain approximation of the run length (Brook and Evans 1972; Lucas and Saccucci 1990), which reproduces the published tables: a CUSUM with k = 0.5 and h = 4 or 5 has in-control run lengths of 168 and 465, and an EWMA with lambda = 0.1 and L = 2.814 one of 500. Measured through this function with a 5,000-observation baseline and arl0 = 100, the first alarm on in-control data came after 99.4 observations on average for the CUSUM and 99.8 for the EWMA (400 runs each, standard errors about 5). The calibration treats the baseline's mean and standard deviation as exact, so a short baseline shortens the in-control run length: a few hundred observations is a reasonable minimum. Rational subgroups, run rules and capability indices are not modelled; for a formal quality-control programme use a dedicated package such as qcc. autoplot(plot_type = "control_chart") draws the chart.

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. Apart from it and the two textbook control charts below, every detector in this package wraps published, separately maintained code; the three native monitors are labelled as such wherever they appear.

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.

Page ES (1954). “Continuous inspection schemes.” Biometrika, 41(1/2), 100–115. doi:10.1093/biomet/41.1-2.100.

Roberts SW (1959). “Control chart tests based on geometric moving averages.” Technometrics, 1(3), 239–250. doi:10.1080/00401706.1959.10489860.

Brook D, Evans DA (1972). “An approach to the probability distribution of CUSUM run length.” Biometrika, 59(3), 539–549. doi:10.1093/biomet/59.3.539.

Lucas JM, Saccucci MS (1990). “Exponentially weighted moving average control schemes: properties and enhancements.” Technometrics, 32(1), 1–12. doi:10.1080/00401706.1990.10484583.

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)

False positives and power under four noise regimes

Description

Ten replicates of a 300-point series with mean changes of two marginal standard deviations at 100 and 200, under independent Gaussian noise, heavy-tailed noise (t_3, scaled to unit variance), AR(1) noise with \rho = 0.7 and heteroscedastic noise (standard deviations 0.5, 1 and 2.5 by segment), for every univariate engine at its default and at each setting of its noise-model argument. A recommendation is a call, not a name: smuce and smuce with family = "hsmuce" are different detectors.

Usage

cpt_noise_benchmark

Format

A tibble with one row per engine, setting and regime:

method, setting

the engine and the argument setting ("default" or the argument as written).

call

the cpt_detect() call the row measures.

regime

"iid", "heavy", "ar1" or "hetero".

reps

replicates that ran.

hits

mean number of the two real changes found within ten positions.

fp

mean number of reported changepoints more than ten positions from either.

Source

data-raw/measure_engines.R (part noise).

See Also

Other measurement tables: cpt_calibration, cpt_data_types, cpt_invariances, cpt_null_sizes, cpt_runtimes

Examples

ar <- subset(cpt_noise_benchmark, regime == "ar1")
ar[order(ar$fp), c("call", "hits", "fp")]

What an empty answer could have detected

Description

When a detection comes back empty, the useful question is whether a change of the size you care about would have been found. This runs cpt_min_detectable() at the fit's own length, method and penalty, with the noise level estimated from the series, and reports the smallest shift detected with the requested power: changes smaller than that could well be there and missed.

Usage

cpt_null_power(fit, power = 0.8, n_sim = 50, seed = NULL, ...)

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

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

Arguments

Value

A ggcpt_null_power list with n, sigma (the noise level used), jump (the smallest detectable change, in the data's units), jump_sd (the same in noise standard deviations), change_in (the fit's change type, which sets what jump measures: a shift in the mean, a rise in the standard deviation, both, or a trend, as cpt_power() defines them), power, method and constant (TRUE when the series has no variation, in which case nothing is simulated). With print() and tidy() methods. A formula fit is refused: the simulation has no covariates to draw.

See Also

Other inference: cpt_abruptness(), cpt_assumptions(), cpt_attribute(), cpt_attribute_event(), cpt_confint_coverage(), cpt_effect(), cpt_gof(), cpt_k_weights(), cpt_robustness(), cpt_screen(), cpt_test_at(), cpt_test_null()

Examples

set.seed(1)
fit <- cpt_detect(rnorm(100), method = "pelt")
cpt_null_power(fit, n_sim = 20, seed = 1)

False alarms on pure noise at scale

Description

Independent Gaussian noise with no changepoint anywhere, at 1,000 (50 replicates), 10,000 (10) and 100,000 (6) observations, for the engines the runtime table shows finishing that length quickly. Every changepoint reported is a false alarm.

Usage

cpt_null_sizes

Format

A tibble with one row per engine and length:

method

the engine.

n

the series length.

reps

replicates that ran.

size

share of replicates reporting at least one changepoint.

mean_fp

mean number of changepoints reported.

Source

data-raw/measure_engines.R (part null).

See Also

Other measurement tables: cpt_calibration, cpt_data_types, cpt_invariances, cpt_noise_benchmark, cpt_runtimes

Examples

subset(cpt_null_sizes, n == max(n))

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,
  family = "gaussian",
  baseline = NULL,
  ...
)

## 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 and the package's measurements into an answer. Given what the analyst knows about their problem (how many dimensions, what kind of change, what the noise and the data look like, how long the series is, how many changes they expect, whether they need uncertainty or an online alarm), this returns the methods that fit, as calls, with the power and false-alarm rate measured for each in that situation, a reason and the caveats. It is a decision table, not a model: everything it knows is in cpt_methods() and the measurement tables (cpt_noise_benchmark, cpt_data_types, cpt_runtimes), 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,
  n_expected = NULL,
  data_type = c("continuous", "counts", "binary", "proportion"),
  family = NULL,
  fit = NULL,
  jump = NULL
)

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

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

## S3 method for class 'ggcpt_recommendation'
autoplot(object, top = 15, ...)

Arguments

Value

A ggcpt_recommendation tibble ordered by suitability, with columns method, engine, installed, score, tie (candidates with the same score share a number: the recommender cannot tell them apart on what was supplied), call (the cpt_detect() call to run, including the noise-model or family argument the recommendation depends on), hits and false_positives (measured in the stated regime: mean real changes found out of two, and mean spurious ones), power (when jump is given), why and caveat. print() reads as advice and autoplot() shows the scores and the ties.

How the score is built

Where the method was measured in the stated noise regime, the score starts from 3 - E, where E is the expected number of errors per series in that benchmark (real changes missed plus false alarms), taking the method's best setting of its noise-model argument (which is then the one in call). A method not measured there starts at 1. Then: minus 3 for a single-change design unless n_expected = 1; minus the log of one plus its measured false positives on the stated data type, and plus 1.5 if it fits that data type's family; plus 1 for a location interval and 0.5 for a posterior when uncertainty is needed; at n \ge 5000, plus 0.5 for a fast engine and minus 1 for a slow one; and small tie-breakers for the general-purpose methods (0.25) and for an installed engine (0.1). Sort by false_positives instead if a false alarm costs you more than a miss.

See Also

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

Examples

cpt_recommend(noise = "autocorrelated")
cpt_recommend(data_type = "counts", n_expected = 2)
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.