Author: José Mauricio Gómez Julián
Date: 2026-02-11

# 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

- See `vignette("offline-detection")` for detailed offline analysis
- See `vignette("online-detection")` for real-time monitoring
- See `vignette("bayesian-methods")` for Bayesian approaches
- See `vignette("multivariate")` for multivariate time series