get_statistics: Compute current changepoint statistics

In focus: Online Changepoint Detection in Univariate and Multivariate Data Streams

Compute current changepoint statistics

Description

Computes the current changepoint test statistic and detection result based on all observations processed so far.

Usage

get_statistics(info_ptr, family, theta0 = NULL, shape = NULL)

Arguments

info_ptr	External pointer to detector created by detector_create().
family	Character string specifying the distribution family: "gaussian": Gaussian (normal) distribution "poisson": Poisson distribution "bernoulli": Bernoulli (binary) distribution "gamma": Gamma distribution (requires shape parameter) "npfocus": Nonparametric detection (see details) "arp": AutoRegressive Process detection (requires detector created with type = "arp")
theta0	Numeric vector specifying the null hypothesis parameter. For univariate detectors: scalar (length-1 vector). For multivariate detectors: vector matching the number of dimensions. Default is NULL.
shape	Numeric scalar. Shape parameter for gamma distribution. Required and must be positive when family = "gamma". Default is NULL.

Details

The function computes a log-likelihood ratio test statistic comparing the null hypothesis (no change) against the alternative (a change at the optimal location). The statistic is typically compared against a threshold to determine if a changepoint should be declared.

Gamma family: When family = "gamma" a positive shape parameter must be provided; otherwise an error is raised. Passing shape for a non-gamma family will be ignored (and in some interfaces will trigger a warning).

NPFOCuS: For non-parametric detection one needs to set detector(type = "npfocus") and the cost can be computed as get_statistics(family = "npfocus"). The quantiles vector argument is required. NPFOCuS returns two statistics (sum and max over quantiles) as a vector; in the offline interface stat will be a matrix with two columns.

AutoRegressive Process (ARP): For ARP detection, use family = "arp" with a detector created via detector_create(type = "arp", rho = ...). The AR coefficients (rho) are already built into the detector at creation time. The optional theta0 parameter specifies the pre-change mean (if known) and is used for pruning logic; if not provided (NULL), pruning operates without this information. Returns a scalar test statistic optimized for detecting changepoints in AR processes.

Value

A list with components:

stopping_time	Integer. Current time index (number of observations processed).
changepoint	Integer or NULL. Detected changepoint location (1-based index), or NULL if no changepoint detected.
stat	Numeric scalar or vector. Test statistic(s). For univariate detectors, a scalar. For multivariate detectors, a vector of statistics for each projection.

Examples

## Online (sequential) example
# Generate data with a changepoint
set.seed(123)
Y <- c(rnorm(500, mean = 0), rnorm(500, mean = 1))
det <- detector_create(type = "univariate")
stat_trace <- numeric(length(Y))
threshold <- 20
for (i in seq_along(Y)) {
  detector_update(det, Y[i])
  r <- get_statistics(det, family = "gaussian")
  stat_trace[i] <- r$stat
  if (!is.null(r$stat) && r$stat > threshold) {
    cat("Online detection at", i, "estimate tau =", r$changepoint, "\n")
    plot(stat_trace[1:i], type = "l", ylab = "Test Statistic", xlab = "Time")
    break
  }
}

## Note that multiple models can be tested simultaneously on the same detector
# as the statistics is independent of the detector state.
# For example, testing both Gaussian and Poisson costs
set.seed(2024)
# Generate Poisson count data with a rate change
Y_counts <- c(rpois(500, lambda = 10), rpois(500, lambda = 15))
# Compute full trajectories for comparison
det2 <- detector_create(type = "univariate")
stat_gaussian <- numeric(length(Y_counts))
stat_poisson <- numeric(length(Y_counts))

for (i in seq_along(Y_counts)) {
  detector_update(det2, Y_counts[i])
  stat_gaussian[i] <- get_statistics(det2, family = "gaussian")$stat
  stat_poisson[i] <- get_statistics(det2, family = "poisson", theta0 = 10)$stat
}

# Plot comparison
oldpar <- par(mfrow = c(1, 2))
plot(stat_gaussian, type = "l", main = "Gaussian Statistic on Poisson Data",
     xlab = "Time", ylab = "Statistic", lwd = 2, col = "blue")
abline(v = 500, col = "green", lty = 3, lwd = 2)

plot(stat_poisson, type = "l", main = "Poisson Statistic on Poisson Data",
     xlab = "Time", ylab = "Statistic", lwd = 2, col = "red")
abline(v = 500, col = "green", lty = 3, lwd = 2)
par(oldpar)

focus documentation built on March 30, 2026, 5:08 p.m.