cpt_register_method: Register an external changepoint detector

In ggchangepoint: Combines Changepoint Analysis with 'ggplot2'

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

name	Method name, as it will be passed to cpt_detect(). Must not clash with a built-in method.
fn	A function called as fn(x, ...). It may return either a ggcpt object (built with as_ggcpt(), say) or a bare vector of changepoint indices, which is coerced with as_ggcpt(). A returned ggcpt may carry a $diagnostics list, which is what makes cpt_statistic() and cpt_solution_path() work for the method. Two conventions apply to it. diagnostics$solution_path needs a cp column and may add contrast, start and end; it goes through the same filtering and step-numbering as a built-in path, so out-of-range candidates are dropped and selected is computed rather than trusted. diagnostics$statistic (a numeric vector, or a list with statistic, label and threshold) is padded with NA to the length of the series when it is shorter, and the pad is centred: a moving-window statistic is trimmed at both ends, so a left-aligned pad would shift every value by the bandwidth. Supply a full-length vector if that is not the alignment you want.
change_in	Character vector of change_in values the detector supports. Defaults to "mean".
engine	Name of the package or system supplying the detector, for display in cpt_methods(). Defaults to "user".
citation	Optional citation string returned by cpt_cite(). When NULL, cpt_cite() says plainly that the registration supplied none rather than inventing one.
capabilities	Optional named list of capability flags overriding the defaults (all FALSE): multivariate, online, ci, fitted, posterior, statistic, path, scale_space.
cp_convention	"left" (the changepoint is the last index of the left segment, this package's convention) or "right". Used when fn returns bare indices.
overwrite	Replace an existing registration of the same name? Defaults to FALSE.

Value

Invisibly, the method name.

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

Registered methods are labelled, not endorsed

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

See Also

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

Examples

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

ggchangepoint documentation built on Nov. 5, 2026, 9:06 a.m.