Detection API¶

Core detection functions and result objects.

fastcpd.fastcpd¶

fastcpd.fastcpd.fastcpd(data: ndarray | list, beta: str | float = 'MBIC', cost_adjustment: str = 'MBIC', family: str = 'mean', epsilon: float = 1e-10, segment_count: int = 10, trim: float = 0.02, momentum_coef: float = 0.0, p: int = 0, order: list | None = None, cost: Callable | None = None, cost_gradient: Callable | None = None, cost_hessian: Callable | None = None, cp_only: bool = False, vanilla_percentage: float | str = 0.0, warm_start: bool = True, lower: list | None = None, upper: list | None = None, line_search: list | None = None, variance_estimate: ndarray | None = None, p_response: int = 1, pruning_coef: float = 0.0, multiple_epochs: Callable[[int], int] | None = None, lasso_alpha: float = 1.0, lasso_cv: bool = False, min_segment_length: int | None = None) → FastcpdResult[source]¶

Fast change point detection using sequential gradient descent.

Parameters:

data – Input data array of shape (n, d) where n is number of observations and d is the dimensionality. For univariate data, shape can be (n,).
beta – Penalty for number of change points. Can be “BIC”, “MBIC”, “MDL” or a numeric value. Default is “MBIC” which uses (p + 2) * log(n) / 2.
cost_adjustment – Cost adjustment criterion. Can be “BIC”, “MBIC”, “MDL” or None.
family – Model family. Options: - “mean”: Mean change detection - “variance”: Variance change detection - “meanvariance”: Mean and/or variance change - “ar”: AR(p) model - “arma”: ARMA(p,q) model - “garch”: GARCH(p,q) model - “var”: VAR(p) model - “custom”: Custom cost function
epsilon – Small constant to avoid numerical issues
segment_count – Initial number of segments for warm start
trim – Proportion to trim from boundaries
momentum_coef – Momentum coefficient for gradient descent
p – Number of parameters (for AR models)
order – Order parameters for time series models, e.g., [p, q] for ARMA(p,q)
cost – Custom cost function (for family=”custom”)
cost_gradient – Gradient of custom cost function
cost_hessian – Hessian of custom cost function
cp_only – Whether to return only change points (no parameters)
vanilla_percentage – Fraction of data to process with vanilla PELT (0 to 1)
warm_start – Whether to use warm start initialization
lower – Lower bounds for parameters
upper – Upper bounds for parameters
line_search – Line search coefficients
variance_estimate – Known variance-covariance matrix
p_response – Dimension of response variable
pruning_coef – Pruning coefficient for optimization
multiple_epochs – Function to determine number of epochs

Returns:

Object containing change points and related information

Return type:

FastcpdResult

Examples

>>> import numpy as np
>>> from fastcpd import fastcpd
>>>
>>> # Mean change detection
>>> data = np.concatenate([np.random.normal(0, 1, 300),
...                        np.random.normal(5, 1, 400),
...                        np.random.normal(2, 1, 300)])
>>> result = fastcpd(data, family="mean")
>>> print(result.cp_set)

>>> # Multivariate mean change
>>> data = np.concatenate([
...     np.random.multivariate_normal([0, 0, 0], np.eye(3), 300),
...     np.random.multivariate_normal([5, 5, 5], np.eye(3), 400),
...     np.random.multivariate_normal([2, 2, 2], np.eye(3), 300)
... ])
>>> result = fastcpd(data, family="mean")
>>> result.plot()

FastcpdResult¶

class fastcpd.fastcpd.FastcpdResult(raw_cp_set: ndarray, cp_set: ndarray, cost_values: ndarray, residuals: ndarray, thetas: ndarray, data: ndarray, family: str)[source]¶

Result from fastcpd change point detection.

raw_cp_set¶

Raw change point indices

Type:: numpy.ndarray

cp_set¶

Final change point indices

Type:: numpy.ndarray

cost_values¶

Cost values for each segment

Type:: numpy.ndarray

residuals¶

Residuals from the model

Type:: numpy.ndarray

thetas¶

Parameter estimates for each segment

Type:: numpy.ndarray

data¶

Original data

Type:: numpy.ndarray

family¶

Model family used

Type:: str

raw_cp_set: ndarray¶

cp_set: ndarray¶

cost_values: ndarray¶

residuals: ndarray¶

thetas: ndarray¶

data: ndarray¶

family: str¶

plot()[source]¶: Plot the data with detected change points.

__init__(raw_cp_set: ndarray, cp_set: ndarray, cost_values: ndarray, residuals: ndarray, thetas: ndarray, data: ndarray, family: str) → None¶

fastcpd.segmentation¶

Convenience functions for common detection scenarios.

Parametric Methods¶

fastcpd.segmentation.mean(data: ndarray | list, beta: str | float = 'MBIC', **kwargs) → FastcpdResult[source]¶

Detect mean changes in univariate or multivariate data.

Parameters:

data – Input data of shape (n,) for univariate or (n, d) for multivariate
beta – Penalty for number of change points
**kwargs – Additional arguments passed to fastcpd()

Returns:

Change point detection results

Return type:

FastcpdResult

Examples

>>> import numpy as np
>>> from fastcpd.segmentation import mean
>>>
>>> # Univariate mean change
>>> data = np.concatenate([np.random.normal(0, 1, 300),
...                        np.random.normal(5, 1, 400)])
>>> result = mean(data)
>>> print(result.cp_set)

>>> # Multivariate mean change
>>> data = np.concatenate([
...     np.random.multivariate_normal([0, 0], np.eye(2), 300),
...     np.random.multivariate_normal([5, 5], np.eye(2), 400)
... ])
>>> result = mean(data)

fastcpd.segmentation.variance(data: ndarray | list, beta: str | float = 'MBIC', **kwargs) → FastcpdResult[source]¶

Detect variance changes in data.

Parameters:

data – Input data
beta – Penalty for number of change points
**kwargs – Additional arguments passed to fastcpd()

Returns:

Change point detection results

Return type:

FastcpdResult

fastcpd.segmentation.meanvariance(data: ndarray | list, beta: str | float = 'MBIC', **kwargs) → FastcpdResult[source]¶

Detect mean and/or variance changes in data.

Parameters:

data – Input data
beta – Penalty for number of change points
**kwargs – Additional arguments passed to fastcpd()

Returns:

Change point detection results

Return type:

FastcpdResult

Regression Methods¶

fastcpd.segmentation.linear_regression(data: ndarray | list, beta: str | float = 'MBIC', **kwargs) → FastcpdResult[source]¶

Detect changes in linear regression parameters.

The first column of data is treated as the response variable, and the remaining columns are treated as predictors.

Parameters:

data – Input data of shape (n, d+1) where first column is response
beta – Penalty for number of change points
**kwargs – Additional arguments passed to fastcpd()

Returns:

Change point detection results

Return type:

FastcpdResult

Examples

>>> import numpy as np
>>> from fastcpd.segmentation import linear_regression
>>>
>>> # Simulate linear regression with change
>>> n = 500
>>> X = np.random.randn(n, 2)
>>> y1 = 2 * X[:n//2, 0] + 3 * X[:n//2, 1] + np.random.randn(n//2)
>>> y2 = -1 * X[n//2:, 0] + 5 * X[n//2:, 1] + np.random.randn(n//2)
>>> y = np.concatenate([y1, y2])
>>> data = np.column_stack([y, X])
>>> result = linear_regression(data)
>>> print(result.cp_set)

fastcpd.segmentation.logistic_regression(data: ndarray | list, beta: str | float = 'MBIC', **kwargs) → FastcpdResult[source]¶

Detect changes in logistic regression parameters.

Uses scikit-learn’s highly optimized LogisticRegression (Cython/C implementation). The first column of data is the binary response (0/1), remaining columns are predictors.

Parameters:

data – Input data of shape (n, d+1) where first column is binary response
beta – Penalty for number of change points
**kwargs – Additional arguments passed to fastcpd()

Returns:

Change point detection results

Return type:

FastcpdResult

Examples

>>> import numpy as np
>>> from fastcpd.segmentation import logistic_regression
>>>
>>> # Simulate logistic regression with change
>>> n = 500
>>> X = np.random.randn(n, 2)
>>> # First segment: strong positive effect
>>> prob1 = 1 / (1 + np.exp(-(2*X[:n//2, 0] + 3*X[:n//2, 1])))
>>> y1 = (np.random.rand(n//2) < prob1).astype(float)
>>> # Second segment: negative effect
>>> prob2 = 1 / (1 + np.exp(-(-1*X[n//2:, 0] + 2*X[n//2:, 1])))
>>> y2 = (np.random.rand(n//2) < prob2).astype(float)
>>> y = np.concatenate([y1, y2])
>>> data = np.column_stack([y, X])
>>> result = logistic_regression(data)
>>> print(result.cp_set)

fastcpd.segmentation.poisson_regression(data: ndarray | list, beta: str | float = 'MBIC', **kwargs) → FastcpdResult[source]¶

Detect changes in Poisson regression parameters.

Uses scikit-learn’s PoissonRegressor with optimized LBFGS solver. The first column of data is the count response, remaining columns are predictors.

Parameters:

data – Input data of shape (n, d+1) where first column is count response
beta – Penalty for number of change points
**kwargs – Additional arguments passed to fastcpd()

Returns:

Change point detection results

Return type:

FastcpdResult

Examples

>>> import numpy as np
>>> from fastcpd.segmentation import poisson_regression
>>>
>>> # Simulate Poisson regression with change
>>> n = 500
>>> X = np.random.randn(n, 2)
>>> # First segment
>>> lambda1 = np.exp(0.5*X[:n//2, 0] + 0.8*X[:n//2, 1])
>>> y1 = np.random.poisson(lambda1)
>>> # Second segment
>>> lambda2 = np.exp(-0.3*X[n//2:, 0] + 1.2*X[n//2:, 1])
>>> y2 = np.random.poisson(lambda2)
>>> y = np.concatenate([y1, y2])
>>> data = np.column_stack([y, X])
>>> result = poisson_regression(data)
>>> print(result.cp_set)

fastcpd.segmentation.lasso(data: ndarray | list, beta: str | float = 'MBIC', alpha: float = 1.0, cv: bool = False, **kwargs) → FastcpdResult[source]¶

Detect changes in LASSO regression parameters.

Uses scikit-learn’s highly optimized coordinate descent algorithm. The first column of data is the response, remaining columns are predictors.

Parameters:

data – Input data of shape (n, d+1) where first column is response
beta – Penalty for number of change points
alpha – L1 regularization strength (lambda). Ignored if cv=True.
cv – If True, use cross-validation to select alpha (slower but automatic)
**kwargs – Additional arguments passed to fastcpd()

Returns:

Change point detection results

Return type:

FastcpdResult

Examples

>>> import numpy as np
>>> from fastcpd.segmentation import lasso
>>>
>>> # Simulate sparse regression with change
>>> n = 500
>>> p = 20
>>> X = np.random.randn(n, p)
>>> # First segment: only first 3 features matter
>>> y1 = 2*X[:n//2, 0] + 3*X[:n//2, 1] - 1.5*X[:n//2, 2] + np.random.randn(n//2)
>>> # Second segment: different sparse coefficients
>>> y2 = -1*X[n//2:, 5] + 2*X[n//2:, 8] + np.random.randn(n//2)
>>> y = np.concatenate([y1, y2])
>>> data = np.column_stack([y, X])
>>> result = lasso(data, alpha=0.1)
>>> print(result.cp_set)

Time Series Methods¶

fastcpd.segmentation.ar(data: ndarray | list, p: int = 1, beta: str | float = 'MBIC', **kwargs) → FastcpdResult[source]¶

Detect changes in AR(p) model parameters.

Parameters:

data – Input time series data
p – Order of AR model
beta – Penalty for number of change points
**kwargs – Additional arguments passed to fastcpd()

Returns:

Change point detection results

Return type:

FastcpdResult

Examples

>>> import numpy as np
>>> from fastcpd.segmentation import ar
>>>
>>> # Simulate AR(2) data with change
>>> np.random.seed(42)
>>> n = 500
>>> data1 = np.zeros(n // 2)
>>> for i in range(2, n // 2):
...     data1[i] = 0.6 * data1[i-1] - 0.3 * data1[i-2] + np.random.normal()
>>> data2 = np.zeros(n // 2)
>>> for i in range(2, n // 2):
...     data2[i] = -0.4 * data2[i-1] + 0.5 * data2[i-2] + np.random.normal()
>>> data = np.concatenate([data1, data2])
>>> result = ar(data, p=2)
>>> print(result.cp_set)

fastcpd.segmentation.var(data: ndarray | list, p: int = 1, beta: str | float = 'MBIC', **kwargs) → FastcpdResult[source]¶

Detect changes in VAR(p) model parameters.

Parameters:

data – Input multivariate time series data of shape (n, d)
p – Order of VAR model
beta – Penalty for number of change points
**kwargs – Additional arguments passed to fastcpd()

Returns:

Change point detection results

Return type:

FastcpdResult

fastcpd.segmentation.arma(data: ndarray | list, p: int = 1, q: int = 1, beta: str | float = 'MBIC', **kwargs) → FastcpdResult[source]¶

Detect changes in ARMA(p,q) model parameters.

Parameters:

data – Input time series data
p – AR order
q – MA order
beta – Penalty for number of change points
**kwargs – Additional arguments passed to fastcpd()

Returns:

Change point detection results

Return type:

FastcpdResult

fastcpd.segmentation.garch(data: ndarray | list, p: int = 1, q: int = 1, beta: str | float = 'MBIC', **kwargs) → FastcpdResult[source]¶

Detect changes in GARCH(p,q) model parameters.

Parameters:

data – Input time series data
p – GARCH order
q – ARCH order
beta – Penalty for number of change points
**kwargs – Additional arguments passed to fastcpd()

Returns:

Change point detection results

Return type:

FastcpdResult

Nonparametric Methods¶

fastcpd.segmentation.rank(data: ndarray | list, beta: float = 50.0, trim: float = 0.02, min_segment_length: int | None = None) → FastcpdResult[source]¶

Nonparametric rank-based change detection (distribution-free).

Parameters:

data – (n, d) array or list
beta – numeric penalty (required)
trim – boundary trim proportion
min_segment_length – optional minimum segment length after post-process

fastcpd.segmentation.rbf(data: ndarray | list, beta: float = 50.0, trim: float = 0.02, min_segment_length: int | None = None, gamma: float | None = None, feature_dim: int = 256, seed: int = 0) → FastcpdResult[source]¶

Nonparametric Gaussian-kernel (RBF) change detection via RFF.

Parameters:

data – (n, d) array or list
beta – numeric penalty (required)
trim – boundary trim proportion
min_segment_length – optional minimum segment length after post-process
gamma – RBF bandwidth; defaults to 1/median^2 (pairwise)
feature_dim – RFF feature dimension (default 256)
seed – RNG seed for RFF