focus_offline: Run FOCuS detector in offline batch mode

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

Run FOCuS detector in offline batch mode

Description

Processes all data at once and returns detection results and trajectories. This is the most efficient way to run changepoint detection when all data is available upfront.

Usage

focus_offline(
  Y,
  threshold,
  type = "univariate",
  family = "gaussian",
  theta0 = NULL,
  dim_indexes = NULL,
  quantiles = NULL,
  pruning_mult = 2L,
  pruning_offset = 1L,
  side = "right",
  shape = NULL,
  anomaly_intensity = NULL,
  rho = NULL,
  mu0_arp = NULL
)

Arguments

Y	Numeric vector or matrix. Data array. For univariate detection, a numeric vector. For multivariate detection, a matrix with observations in rows and dimensions in columns.
threshold	Numeric scalar or vector. Detection threshold(s). Can be: A scalar: applied to all test statistics (default behavior for most cost functions) A vector: length must match the number of test statistics (for example, np-focus returns both the sum and max statistics, so threshold should be length 2). Inf: no thresholding (returns all statistics)
type	Character string specifying detector type. See detector_create() for options. Defaults to "univariate".
family	Character string specifying distribution family. See get_statistics() for options. Defaults to "gaussian".
theta0	Numeric vector. Null hypothesis parameter. Default is NULL.
dim_indexes	List of integer vectors. Projection index sets for multivariate detectors. Default is NULL.
quantiles	Numeric vector. Quantiles for nonparametric detectors. Default is NULL.
pruning_mult	Integer. Pruning multiplier parameter. Default is 2.
pruning_offset	Integer. Pruning offset parameter. Default is 1.
side	Character string. For one-sided detectors: "right" or "left". Default is "right".
shape	Numeric scalar. Shape parameter for gamma distribution. Default is NULL.
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). Only used when type = "arp". Default is NULL.

Details

This function runs the complete detection algorithm in C++ for maximum efficiency. It processes observations sequentially and stops at the first detection (when any statistic exceeds its threshold).

For multivariate data, the algorithm computes multiple statistics (one per projection). Detection occurs when ANY statistic exceeds its threshold.

Value

A list with components:

stat	Numeric matrix. Test statistics over time (n_obs × n_stats). Each row corresponds to one time point, each column to one statistic.
changepoint	Integer vector. Detected changepoints at each time point (1-based indices), or NA if no changepoint detected at that time.
detection_time	Integer or NULL. Time of first detection (1-based), or NULL if no detection occurred.
detected_changepoint	Integer or NULL. Changepoint location at detection time (1-based), or NULL if no detection occurred.
candidates	Data frame. Final candidate segments (see detector_candidates()).
threshold	Numeric vector. Threshold(s) used for detection.
n	Integer. Number of observations processed.
type	Character. Detector type used.
family	Character. Distribution family used.
shape	Numeric or NULL. Shape parameter (for gamma family).

Examples

# Univariate Gaussian detection
set.seed(123)
Y <- c(rnorm(100, mean = 0), rnorm(100, mean = 2))
result <- focus_offline(Y, threshold = 10, type = "univariate",
                       family = "gaussian")
cat("Detection at time:", result$detection_time, "\n")
cat("Changepoint at:", result$detected_changepoint, "\n")

# Plot statistics
plot(result$stat, type = "l", ylab = "Test Statistic", xlab = "Time")
abline(h = result$threshold, col = "red", lty = 2)
if (!is.null(result$detection_time)) {
  abline(v = result$detection_time, col = "blue", lty = 2)
}

# Multivariate detection
Y_multi <- matrix(rnorm(200 * 3), ncol = 3)
Y_multi[101:200, ] <- Y_multi[101:200, ] + 1.5  # Add mean shift
result_multi <- focus_offline(Y_multi, threshold = 15,
                              type = "multivariate",
                              family = "gaussian")

# Poisson detection
Y_poisson <- c(rpois(100, lambda = 2), rpois(100, lambda = 5))
result_poisson <- focus_offline(Y_poisson, threshold = 10,
                                type = "univariate",
                                family = "poisson")

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