Class PELTAlgorithm

Namespace

SignalSharp.Detection.PELT

Assembly

SignalSharp.dll

Implements the Piecewise Linear Trend Change (PELT) algorithm for segmenting time series data.

public class PELTAlgorithm : IPELTAlgorithm

Inheritance

object

PELTAlgorithm

Implements

IPELTAlgorithm

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

The PELT algorithm is an exact and efficient dynamic programming approach for detecting multiple change points in time series data. It aims to partition the data into segments where the statistical properties are homogeneous within each segment but differ between segments. This implementation uses pruning to achieve near-linear time complexity under certain conditions.

The algorithm minimizes the sum of segment costs plus a penalty term for each changepoint. The cost function measures the fit or homogeneity of segments, and the penalty controls the number of change points, preventing overfitting.

When `Jump` > 1 in `PELTOptions`, the algorithm becomes approximate by only checking potential previous changepoints at intervals defined by `Jump`, significantly increasing speed for some cost functions at the cost of guaranteed optimality. For exact results, use `Jump = 1`.

Constructors

PELTAlgorithm()

Initializes a new instance of the PELTAlgorithm class with default options (L2 Cost, MinSize=2, Jump=5).

public PELTAlgorithm()

PELTAlgorithm(PELTOptions)

Initializes a new instance of the PELTAlgorithm class with specified configuration options.

public PELTAlgorithm(PELTOptions options)

Parameters

options PELTOptions

The configuration options for the PELT algorithm. Must not be null.

Exceptions

ArgumentNullException

Thrown when options are null.

Properties

Options

Gets the options used to configure this PELT algorithm instance.

public PELTOptions Options { get; }

Property Value

PELTOptions

Methods

Detect(double)

Detects the change points in the fitted signal using the specified penalty value.

public virtual int[] Detect(double penalty)

Parameters

penalty double

The penalty value to control the number of change points. Must be non-negative.

Returns

int[]

An array of indices representing the change points in the signal. The indices correspond to the first point after the change.

Remarks

This method executes the core PELT algorithm to find the optimal segmentation based on the fitted data, cost function, and penalty. If Jump > 1 was specified in options, this may return an approximate solution.

var pelt = new PELTAlgorithm().Fit(signal);
int[] changePoints = pelt.Detect(10.0);

Exceptions

UninitializedDataException

Thrown when Fit method has not been called before Detect.

ArgumentOutOfRangeException

Thrown when the penalty is negative.

Fit(double[,])

Fits the PELT algorithm to the provided multi-dimensional time series data.

public virtual IPELTAlgorithm Fit(double[,] signalMatrix)

Parameters

signalMatrix double[,]

The multi-dimensional time series data to fit, where each row represents a dimension and each column a time point.

Returns

IPELTAlgorithm

The fitted PELTAlgorithm instance.

Remarks

Prepares the algorithm by setting the internal signal representation and fitting the chosen cost function.

double[,] signal = { { 1.0, 2.0, 3.0 }, { 10.0, 11.0, 12.0 } };
var pelt = new PELTAlgorithm().Fit(signal);

Exceptions

ArgumentNullException

Thrown when the signal data is null.

Fit(double[])

Fits the PELT algorithm to the provided one-dimensional time series data.

public virtual IPELTAlgorithm Fit(double[] signal)

Parameters

signal double[]

The one-dimensional time series data to fit.

Returns

IPELTAlgorithm

The fitted PELTAlgorithm instance.

Remarks

Prepares the algorithm by setting the internal signal representation and fitting the chosen cost function.

double[] signal = {1.0, 2.0, 3.0, 10.0, 11.0, 12.0};
var pelt = new PELTAlgorithm().Fit(signal);

Exceptions

ArgumentNullException

Thrown when the signal data is null.

FitAndDetect(double[,], double)

Fits the PELT algorithm to the provided multi-dimensional signal data and detects the change points using the specified penalty value.

public virtual int[] FitAndDetect(double[,] signalMatrix, double penalty)

Parameters

signalMatrix double[,]

The multi-dimensional time series data to be segmented, where each row represents a dimension.

penalty double

The penalty value to control the number of change points. Must be non-negative.

Returns

int[]

An array of indices representing the change points in the signal.

Examples

double[,] signal = { { 1, 1, 10, 10 }, { 5, 5, 20, 20 } };
var pelt = new PELTAlgorithm(); // Uses default options
int[] changePoints = pelt.FitAndDetect(signal, 8.0); // Example penalty
// changePoints might be [2]

FitAndDetect(double[], double)

Fits the PELT algorithm to the provided one-dimensional signal data and detects the change points using the specified penalty value.

public virtual int[] FitAndDetect(double[] signal, double penalty)

Parameters

signal double[]

The one-dimensional time series data to be segmented.

penalty double

The penalty value to control the number of change points. Must be non-negative.

Returns

int[]

An array of indices representing the change points in the signal.

Examples

double[] signal = {1, 1, 1, 10, 10, 10, 1, 1, 1};
var pelt = new PELTAlgorithm(); // Uses default options
int[] changePoints = pelt.FitAndDetect(signal, 5.0); // Example penalty
// changePoints might be [3, 6] depending on cost function and penalty