Package 'ggchangepoint'

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)

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

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)

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

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)

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

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

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

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)

Description

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

Usage

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

Arguments

Value

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

References

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

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

See Also

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

Examples

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

Description

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

Usage

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

Arguments

Value

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

References

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

See Also

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

Examples

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

Description

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

Usage

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

Arguments

Value

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

References

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

See Also

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

Examples

set.seed(2026)
season <- rep(sin(seq(0, 2 * pi, length.out = 12)), 10)
y <- stats::ts(c(rnorm(60, 1), rnorm(60, 5)) + season,
               frequency = 12, start = c(2000, 1))
bfast_wrapper(y)

Description

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

Usage

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

Arguments

Value

A ggcpt object.

References

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

See Also

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

Examples

set.seed(2026)
binsegrcpp_wrapper(c(rnorm(100), rnorm(100, 3)))

Description

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

Usage

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

Arguments

Value

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

References

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

See Also

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

Examples

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

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

Description

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

Usage

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

Arguments

Value

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

References

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

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

See Also

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

Examples

set.seed(2026)
y <- cumsum(c(rep(0.3, 100), rep(-0.4, 100))) + rnorm(200)
res <- cpop_wrapper(y)
res$changepoints
ggplot2::autoplot(res, show_fit = TRUE)

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)

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

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_attribute_event(), cpt_effect(), cpt_gof(), cpt_null_power(), cpt_robustness(), 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"))

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_assumptions(), cpt_effect(), cpt_gof(), cpt_null_power(), cpt_robustness(), 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")))

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)

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)

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 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, and monitors for their in-control run length. 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" or "run_length".

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

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)

Description

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

Usage

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

Arguments

Value

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

How well these cover

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

See Also

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

Examples

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

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)

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

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, ]

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

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)

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

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_assumptions(), cpt_attribute_event(), cpt_gof(), cpt_null_power(), cpt_robustness(), 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"))

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)

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

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_assumptions(), cpt_attribute_event(), cpt_effect(), cpt_null_power(), cpt_robustness(), 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)

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

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

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)

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

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)

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

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

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)

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)

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)

Description

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

Usage

cpt_methods(capabilities = TRUE)

Arguments

Value

A tibble with columns:

method

Method name as passed to cpt_detect().

change_in

What types of change the method can detect.

engine

The upstream R package that implements the method.

status

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

installed

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

target_release

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

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

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

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

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

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.