get_statistics: Compute the Current Changepoint Statistics

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

Compute the Current Changepoint Statistics

Description

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

Usage

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

Arguments

det_ptr	A "focus_detector" object 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 raises a warning and the parameter is ignored.

NPFOCuS. For non-parametric detection, the detector must be created with detector_create(type = "npfocus", quantiles = ...). NPFOCuS returns two statistics (sum and maximum over the quantiles) as a vector; in the offline interface, stat is 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 and the (optional) pre-change mean mu0_arp are set at detector creation, so theta0 is ignored (with a warning) for this family.

Value

An object of class "focus_statistics", with a print method (see focus-methods): a list with components

stopping_time	Numeric. Current time index (number of observations processed).
changepoint	Numeric or NULL. Estimated changepoint location, i.e., the index of the last observation before the change, or NULL if no estimate is available.
stat	Numeric scalar or vector, or NULL if no candidate is available yet. The test statistic: a scalar for all families except "npfocus", which returns the sum and the maximum of the statistics over the quantiles.

The family is stored in the attribute "family".

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 Sept. 17, 2026, 1:08 a.m.