Package {ggchangepoint}

ggchangepoint package

Description

Combines Changepoint Analysis with 'ggplot2'.

Details

ggchangepoint tries to offer several changepoint R packages in a tidy format and output the ggplot2 plots so that the tidyverse users can gain some familiarity to work with the changepoint analysis. For the moment, I only include three changepoint packages ('changepoint', 'changepoint.np' and 'ecp' ). More changepoint packages will be included as time progresses.

Author(s)

Maintainer: Youzhi Yu yuyouzhi666@icloud.com

See Also

Useful links:

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

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

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.

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

Value

A tibble with the original data plus augment columns.

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 are overlaid.

Usage

## S3 method for class 'ggcpt'
autoplot(
  object,
  show_segments = FALSE,
  show_ci = FALSE,
  cptline_alpha = 1,
  cptline_color = "blue",
  cptline_type = "solid",
  cptline_linewidth = 0.5,
  show_points = NULL,
  show_line = TRUE,
  ...
)

Arguments

Value

A ggplot object.

Unified changepoint detection dispatcher

Description

Runs one or more changepoint detection methods on a sequence and returns a tidy ggcpt result object. This is the recommended entry point for most users.

Usage

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

Arguments

Value

A ggcpt object.

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)

Changepoint accuracy metrics

Description

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

Usage

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

Arguments

Value

A tibble with columns: n, n_pred, n_truth, precision, recall, f1, covering, hausdorff, rand_index, annotation_error, mae_matched, rmse_matched.

Examples

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

Multi-annotator evaluation

Description

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

Usage

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

Arguments

Value

A tibble with averaged metrics.

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)

Arguments

Value

A numeric penalty value.

Examples

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

Generate simulated changepoint data

Description

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

Usage

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

rcpt(...)

Arguments

Value

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

Examples

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

Changepoint wrapper

Description

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

Usage

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

Arguments

Value

A tibble including which point(s) is/are the changepoint along with raw changepoint value corresponding to that changepoint. Changepoint locations follow the convention of the changepoint package: the last index of the left segment.

References

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

Examples

set.seed(2022)
cpt_wrapper(c(rnorm(100,0,1),rnorm(100,0,10)))
cpt_wrapper(c(rnorm(100,0,1),rnorm(100,10,1)))

ecp wrapper

Description

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

Usage

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

Arguments

Value

A tibble includes which point(s) is/are the changepoint along with raw changepoint value corresponding to that changepoint. Changepoint locations follow the ecp package convention: the first index of the right segment. When no changepoint is found, an empty tibble is returned (0 rows).

References

James NA, Matteson DS (2013). “ecp: An R package for nonparametric multiple change point analysis of multivariate data.” arXiv preprint arXiv:1309.3295.

Examples

set.seed(2022)
ecp_wrapper(c(rnorm(100,0,1),rnorm(100,0,10)))
ecp_wrapper(c(rnorm(100,0,1),rnorm(100,10,1)))

FPOP wrapper — Functional Pruning Optimal Partitioning

Description

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

Usage

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

Arguments

Value

A ggcpt object.

Changepoint vertical rules geom

Description

Draws vertical lines at changepoint locations. Mimics geom_vline but designed to work with the tidy changepoint data frames returned by the package. Can be used as a standalone layer: geom_changepoint(data = cp_df, aes(xintercept = cp)).

Usage

geom_changepoint(
  mapping = NULL,
  data = NULL,
  ...,
  na.rm = FALSE,
  show.legend = NA
)

Arguments

Value

A ggplot layer.

Changepoint confidence interval geom

Description

Draws horizontal whiskers for changepoint-location confidence intervals (e.g. from MOSUM, stepR, strucchange, segmented).

Usage

geom_cpt_ci(mapping = NULL, data = NULL, ..., na.rm = FALSE, show.legend = NA)

Arguments

Value

A ggplot layer.

Changepoint segment level geom

Description

Draws horizontal segments representing the estimated level of each segment between changepoints. Typically used with data from augment().

Usage

geom_cpt_segment(
  mapping = NULL,
  data = NULL,
  ...,
  na.rm = FALSE,
  show.legend = NA
)

Arguments

Value

A ggplot layer.

Compare multiple changepoint detection methods

Description

Runs several detectors on the same data and returns a faceted or overlaid ggplot comparison. Respects future::plan() for parallel execution if the future.apply package is available.

Usage

ggcpt_compare(
  x,
  methods = c("pelt", "binseg", "amoc"),
  layout = c("facet", "overlay"),
  change_in = "mean",
  seed = NULL,
  ...
)

Arguments

Value

A ggplot object.

Examples

set.seed(2022)
x <- c(rnorm(100, 0, 1), rnorm(100, 10, 1))
ggcpt_compare(x, methods = c("pelt", "binseg"))

Comparison table

Description

Returns a tidy tibble combining the results of multiple detectors on the same series.

Usage

ggcpt_compare_table(
  x,
  methods = c("pelt", "binseg", "amoc"),
  change_in = "mean",
  ...
)

Arguments

Value

A tibble with columns method, cp, cp_value.

Evaluation visualization

Description

Overlays predictions and ground truth on the series with tolerance windows, colouring true positives, false positives, and misses.

Usage

ggcpt_eval(pred, truth, data_vec, margin = 5)

Arguments

Value

A ggplot object.

Plot for the changepoint package

Description

The plot for changepoints detected by the changepoint package is a line plot for the raw data and the vertical lines representing each changepoint. The x-axis is the row number of the raw data in the original data vector. The plot inherits ggplot2, meaning users can add ggplot2 functions on top the changepoint plot for customization.

Usage

ggcptplot(
  data,
  change_in = "mean_var",
  cp_method = "PELT",
  ...,
  cptline_alpha = 1,
  cptline_color = "blue",
  cptline_type = "solid",
  cptline_linewidth = 0.5,
  cptline_size = lifecycle::deprecated(),
  index = NULL,
  show_points = NULL,
  show_line = TRUE
)

Arguments

Value

A line plot with data points along with the vertical lines representing changepoints.

Examples

ggcptplot(c(rnorm(100,0,1),rnorm(100,0,10)))
ggcptplot(c(rnorm(100,0,1),rnorm(100,10,1)))

Plot for the ecp package

Description

The plot for changepoints detected by the ecp package is a line plot for the raw data and the vertical lines representing each changepoint. The x-axis is the row number of the raw data in the original data vector. The plot inherits ggplot2, meaning users can add ggplot2 functions on top the changepoint plot for customization.

Usage

ggecpplot(
  data,
  algorithm = "divisive",
  min_size = 2,
  ...,
  cptline_alpha = 1,
  cptline_color = "blue",
  cptline_type = "solid",
  cptline_linewidth = 0.5,
  cptline_size = lifecycle::deprecated(),
  index = NULL,
  show_points = NULL,
  show_line = TRUE
)

Arguments

Value

A line plot with data points along with the vertical lines representing changepoints.

Examples

ggecpplot(c(rnorm(100,0,1),rnorm(100,0,10)))
ggecpplot(c(rnorm(100,0,1),rnorm(100,10,1)))

Glance at a ggcpt object

Description

Returns a one-row summary of a changepoint detection result.

Usage

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

Arguments

Value

A one-row tibble with columns: n, n_changepoints, method, change_in, penalty_type, penalty_value, cp_convention, total_cost (if available), runtime (NA).

Isolate-Detect wrapper

Description

Wraps the IDetect package. Requires the IDetect package.

Usage

idetect_wrapper(x, seed = NULL, ...)

Arguments

Value

A ggcpt object.

Test if an object is a ggcpt object

Description

Test if an object is a ggcpt object

Usage

is_ggcpt(x)

Arguments

Value

TRUE if x inherits from ggcpt.

MOSUM wrapper — Moving Sum

Description

Wraps the mosum package for moving-sum-based changepoint detection.

Usage

mosum_wrapper(x, G = NULL, multiscale = FALSE, seed = NULL, ...)

Arguments

Value

A ggcpt object.

Create a ggcpt object

Description

Create a ggcpt object

Usage

new_ggcpt(
  changepoints = tibble::tibble(cp = integer(), cp_value = numeric()),
  segments = tibble::tibble(seg_id = integer(), start = integer(), end = integer(), n =
    integer(), param_estimate = numeric()),
  data = tibble::tibble(index = integer(), value = numeric()),
  method = character(),
  change_in = character(),
  penalty = list(type = NA_character_, value = NA_real_),
  fit = NULL,
  call = NULL,
  cp_convention = "left"
)

Arguments

Value

An object of class ggcpt.

NOT wrapper — Narrowest-Over-Threshold

Description

Wraps the not package for changepoint detection via the Narrowest-Over-Threshold method.

Usage

not_wrapper(x, contrast = "pcwsConstMean", seed = NULL, ...)

Arguments

Value

A ggcpt object.

Print a ggcpt object

Description

Print a ggcpt object

Usage

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

Arguments

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

generics

augment, glance, tidy

ggplot2

autoplot

Blocks test signal

Description

The classic Donoho-Johnstone blocks test signal with known changepoints.

Usage

signal_blocks(n = 2048, seed = NULL)

Arguments

Value

A tibble with columns index and value. The true_changepoints attribute contains the known changepoint locations.

References

Donoho, D. L. and Johnstone, I. M. (1994). Ideal spatial adaptation by wavelet shrinkage. Biometrika, 81(3), 425-455.

FMS (Four-Metric-Segments) test signal

Description

A piecewise-constant test signal from the WBS/NOT literature.

Usage

signal_fms(n = 2000, seed = NULL)

Arguments

Value

A tibble with columns index and value.

Mix test signal

Description

A piecewise-constant/linear signal from the literature.

Usage

signal_mix(n = 2000, seed = NULL)

Arguments

Value

A tibble with columns index and value.

Stairs test signal

Description

A monotonically stepping signal (staircase).

Usage

signal_stairs(n = 2000, seed = NULL)

Arguments

Value

A tibble with columns index and value.

Teeth test signal

Description

A piecewise-constant signal with regularly spaced changepoints.

Usage

signal_teeth(n = 2000, seed = NULL)

Arguments

Value

A tibble with columns index and value.

Changepoint detection stat

Description

Runs changepoint detection inside the ggplot pipeline. Useful for quick exploration: ggplot(df, aes(t, y)) + geom_line() + stat_changepoint(method = "pelt"). Draws vertical lines at detected changepoint locations.

Usage

stat_changepoint(
  mapping = NULL,
  data = NULL,
  geom = "vline",
  position = "identity",
  ...,
  method = "pelt",
  change_in = "mean",
  na.rm = FALSE,
  show.legend = NA
)

Arguments

Value

A ggplot layer.

TGUH wrapper

Description

Wraps the breakfast package for Tail-Greedy Unbalanced-Haar detection.

Usage

tguh_wrapper(x, ...)

Arguments

Value

A ggcpt object.

ggchangepoint theme

Description

A minimal, publication-ready ggplot2 theme for changepoint plots.

Usage

theme_ggcpt(base_size = 11, base_family = "")

Arguments

Value

A ggplot2 theme object.

Examples

library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) + geom_point() + theme_ggcpt()

Tidy a ggcpt object

Description

Returns the changepoints tibble (one row per changepoint).

Usage

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

Arguments

Value

A tibble with columns cp, cp_value, and any method-specific columns.

WBS2 wrapper — Wild Binary Segmentation 2

Description

Wraps the breakfast package. Requires the breakfast package.

Usage

wbs2_wrapper(x, ...)

Arguments

Value

A ggcpt object.

WBS wrapper — Wild Binary Segmentation

Description

Wraps the wbs package for randomised changepoint detection via Wild Binary Segmentation.

Usage

wbs_wrapper(x, n_intervals = 5000, threshold = NULL, seed = NULL, ...)

Arguments

Value

A ggcpt object.