detector_create: Create a FOCuS Changepoint Detector

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

Create a FOCuS Changepoint Detector

Description

Creates an online (sequential) changepoint detector object that provides a step-by-step interface to the FOCuS algorithm. Each call to detector_update() adds new data, and get_statistics() computes the current test statistic and detection result.

Usage

detector_create(
  type,
  dim_indexes = NULL,
  quantiles = NULL,
  pruning_mult = 2L,
  pruning_offset = 1L,
  side = "right",
  anomaly_intensity = NULL,
  rho = NULL,
  mu0_arp = NULL
)

Arguments

type	Character string specifying detector type. One of: "univariate": Two-sided univariate detection "univariate_one_sided": One-sided univariate detection "multivariate": Multivariate detection with projections "npfocus": Nonparametric detection (NP-FOCuS). See details. "arp": AutoRegressive Process detection. Requires rho parameter.
dim_indexes	List of integer vectors specifying projection index sets for high-dimensional multivariate detectors (not required for data with at most 5 dimensions). Each element is a vector of 0-based column indices. Default is NULL.
quantiles	Numeric vector of quantiles for nonparametric ("npfocus") detectors. Required when type = "npfocus". Default is NULL.
pruning_mult	Integer. Candidate pruning multiplier parameter. Default is 2.
pruning_offset	Integer. Candidate pruning offset parameter. Default is 1.
side	Character string. For one-sided detectors, either "right" (detects increases) or "left" (detects decreases). Default is "right".
anomaly_intensity	Numeric scalar. Anomaly intensity threshold for pruning candidates. Only candidates with sufficient signal magnitude are retained. Default is NULL (disabled).
rho	Numeric vector. AR coefficients for AutoRegressive Process (ARP) detectors. Required when type = "arp". Default is NULL.
mu0_arp	Numeric scalar. Pre-change mean for ARP detectors (optional). When provided, enables more efficient pruning by filtering candidates based on the known pre-change parameter. Only used when type = "arp". Default is NULL.

Details

The detector maintains sufficient statistics internally and uses pruning to efficiently track candidate changepoints. The pruning_mult and pruning_offset parameters control the pruning strategy.

AutoRegressive Process (ARP). When type = "arp", the rho parameter must be provided as a numeric vector of AR coefficients (lag-1, lag-2, ..., lag-p). The detector then computes statistics optimal for detecting changepoints in AR(p) processes. Use get_statistics(family = "arp") to retrieve the test statistics. The optional mu0_arp parameter specifies the pre-change mean and is tied to the pruning logic: if provided, it enables more efficient pruning by allowing the algorithm to filter candidates based on the known pre-change parameter.

High-dimensional multivariate detectors. For high-dimensional multivariate detection, computing the full convex hull is prohibitive, as the expected number of candidates grows as \log(n)^p, where n is the number of observations and p the number of dimensions. The set of candidate changepoints can then be approximated by computing the hull on lower-dimensional projections: dim_indexes specifies which dimensions to use for each projection. Use generate_projection_indexes() to generate systematic projection sets.

NPFOCuS. For non-parametric detection, create the detector with detector_create(type = "npfocus", quantiles = ...) and compute the statistics with get_statistics(family = "npfocus"). No other family can be used with this detector type.

Value

An object of class "focus_detector": an external pointer to the state of the C++ detector, which is updated in place. It should be passed to the other detector functions, such as detector_update() and get_statistics(). A print method is available, see focus-methods. As external pointers, detectors cannot be saved and restored across R sessions.

Examples

# Univariate detector
det <- detector_create(type = "univariate")
det <- detector_update(det, 0.5)
det <- detector_update(det, 1.2)
det
r <- get_statistics(det, family = "gaussian")
r

## 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
  }
}

# Multivariate detector with projections
dim_indexes <- list(c(0,1), c(1,2), c(0,2))  # 0-based indices
det_mv <- detector_create(type = "multivariate", dim_indexes = dim_indexes)
detector_update(det_mv, c(0.5, 1.2, -0.3))

# Nonparametric detector
quants <- qnorm(c(0.25, 0.5, 0.75))
det_np <- detector_create(type = "npfocus", quantiles = quants)

# One-sided univariate detector
det_one_sided <- detector_create(type = "univariate_one_sided", side = "left")

focus documentation built on Sept. 17, 2026, 1:08 a.m.