Introduction to RegimeChange

José Mauricio Gómez Julián

2026-02-11

Overview

RegimeChange is a comprehensive R package for detecting regime changes (changepoints) in time series data. It provides a unified interface to both frequentist and Bayesian methods, supports both offline and online detection modes, and offers rigorous uncertainty quantification.

Installation

# From CRAN (when available)
install.packages("RegimeChange")

# From GitHub
# devtools::install_github("yourusername/RegimeChange")

Quick Start

library(RegimeChange)

# Generate example data with a changepoint at t=100
set.seed(123)
data <- c(rnorm(100, mean = 0, sd = 1), rnorm(100, mean = 3, sd = 1))

# Detect changepoints using PELT (default)
result <- detect_regimes(data)

# Print results
print(result)
#> 
#> Regime Change Detection Results
#> ================================
#> 
#> Method: pelt 
#> Change type: both 
#> Mode: offline 
#> 
#> Data: n = 200 observations
#> 
#> Changepoints detected: 1 
#> Locations: 100 
#> 
#> 95% Confidence Intervals:
#>   CP 1: 100 [80, 120]
#> 
#> Segments:
#>   Segment 1: [1, 100] (n=100) | mean=0.090, sd=0.913
#>   Segment 2: [101, 200] (n=100) | mean=2.892, sd=0.967

Visualizing Results

# Basic plot
plot(result)


# Segment-colored plot
plot(result, type = "segments")

Available Methods

RegimeChange supports multiple detection algorithms:

Frequentist Methods

# PELT - Pruned Exact Linear Time (default)
result_pelt <- detect_regimes(data, method = "pelt")

# Binary Segmentation
result_binseg <- detect_regimes(data, method = "binseg")

# Wild Binary Segmentation
result_wbs <- detect_regimes(data, method = "wbs")

# CUSUM
result_cusum <- detect_regimes(data, method = "cusum")

Bayesian Methods

# BOCPD - Bayesian Online Changepoint Detection
result_bocpd <- detect_regimes(data, method = "bocpd")

# Shiryaev-Roberts
result_sr <- detect_regimes(data, method = "shiryaev", mu0 = 0, mu1 = 3, sigma = 1)

Types of Changes

Detect different types of statistical changes:

# Mean changes (default)
detect_regimes(data, type = "mean")

# Variance changes
detect_regimes(data, type = "variance")

# Both mean and variance
detect_regimes(data, type = "both")

# Trend changes
detect_regimes(data, type = "trend")

Prior Specification (Bayesian Methods)

# Normal-Gamma prior for unknown mean and variance
prior <- normal_gamma(mu0 = 0, kappa0 = 1, alpha0 = 1, beta0 = 1)
result <- detect_regimes(data, method = "bocpd", prior = prior)

# Geometric hazard prior
hazard <- geometric_hazard(lambda = 0.01)
result <- detect_regimes(data, method = "bocpd", hazard = hazard)

Evaluation

Evaluate detection performance against known changepoints:

# True changepoint is at position 100
evaluation <- evaluate(result, true_changepoints = 100, tolerance = 5)
print(evaluation)
#> 
#> Changepoint Detection Evaluation
#> =================================
#> 
#> Detection Performance:
#>   True changepoints: 1
#>   Detected: 1
#>   Matched: 1
#>   Precision: 1.000
#>   Recall: 1.000
#>   F1 Score: 1.000
#> 
#> Localization Accuracy:
#>   Hausdorff Distance: 0.00
#>   Mean Absolute Error: 0.00
#>   RMSE: 0.00
#> 
#> Segmentation Quality:
#>   Rand Index: 1.000
#>   Adjusted Rand Index: 1.000
#>   Covering Metric: 1.000

Method Comparison

Compare multiple methods:

comparison <- compare_methods(
  data = data,
  methods = c("pelt", "bocpd", "binseg"),
  true_changepoints = 100
)
print(comparison)

Online Detection

For real-time monitoring:

# Create online detector
detector <- regime_detector(method = "bocpd", prior = normal_gamma())

# Process observations one at a time
for (x in data) {
  result <- update(detector, x)
  detector <- result$detector
  
  if (result$alarm) {
    cat("Changepoint detected at observation", length(detector$history), "\n")
  }
}

Uncertainty Quantification

Get confidence intervals for changepoint locations:

result <- detect_regimes(data, uncertainty = TRUE, bootstrap_reps = 100)
print(result$confidence_intervals)

Next Steps