Skip to contents

Turn external changepoints into a ggcpt result

Source: R/as-ggcpt.R
as_ggcpt.Rd

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

cp

Integer vector of changepoint locations. Out-of-range, duplicated and missing values are dropped and the result is sorted, the same contract every built-in wrapper is held to. But unlike a wrapper, which is normalising an engine's output, this function is given yours, so anything it drops it warns about, with the values and the range they had to fall in. A fractional index is included in that: it is truncated rather than rounded, which makes 50.5 into a changepoint at 50.

x

The series the changepoints refer to: a numeric vector, or a matrix/data frame (rows are time points) for a multivariate result. A one-column matrix or data frame is read as a univariate series.

fitted

Optional length-n fitted signal, used by autoplot(show_fit = TRUE) and augment().

method

Method label. Defaults to "custom".

change_in

What the changepoints are changes in. Defaults to "mean".

ci

Optional two-column matrix or data frame of location confidence intervals, one row per changepoint, giving lower and upper bounds as positions in the same cp_convention as cp: with "right" they are converted along with cp, so an interval keeps bracketing its changepoint.

regions

Optional two-column matrix or data frame of significance regions (start, end); see nsp_wrapper() for the interval-valued case this exists to serve. A region with a missing bound is dropped with a warning.

penalty

Optional penalty descriptor: a number, a string, or a list with type and value.

cp_convention

"left" (the changepoint is the last index of the left segment, this package's convention) or "right" (the first index of the right segment, which is converted on the way in).

index

Optional time index, one value per observation.

fit

Optional raw upstream object to carry along.

extra

Optional named list of per-changepoint columns, each of the same length as cp, appended to the changepoints tibble.

Value

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

See also

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

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

Examples

set.seed(2026)
x <- c(rnorm(60), rnorm(60, 4))
fit <- as_ggcpt(c(60), x, method = "my_detector")
fit
#> ggcpt (changepoint detection result)
#>   Method:             my_detector
#>   Change in:          mean
#>   Changepoints found: 1
#>   CP convention:      left
#>   Penalty:            user
#>   Series length:      120
#> 
#> Changepoints:
#> # A tibble: 1 × 2
#>      cp cp_value
#>   <int>    <dbl>
#> 1    60   -0.999
tidy(fit)
#> # A tibble: 1 × 2
#>      cp cp_value
#>   <int>    <dbl>
#> 1    60   -0.999