Class ARCostFunction

Namespace

SignalSharp.CostFunctions.Cost

Assembly

SignalSharp.dll

Represents a cost function based on fitting an Autoregressive (AR) model for the PELT method.

public class ARCostFunction : CostFunctionBase, ILikelihoodCostFunction, IPELTCostFunction

Inheritance

object

CostFunctionBase

ARCostFunction

Implements

ILikelihoodCostFunction

IPELTCostFunction

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This cost function evaluates the goodness-of-fit of an Autoregressive (AR) model of a specified order p to a segment of the time series data. The cost is defined as the Residual Sum of Squares (RSS) after fitting the model using Ordinary Least Squares (OLS).

The AR(p) model predicts the current value based on the p preceding values: signal[t] = c + a1*signal[t-1] + a2*signal[t-2] + ... + ap*signal[t-p] + error[t] where c is an optional intercept term and a1, ..., ap are the AR coefficients.

This cost function is useful for detecting changes in the underlying dynamics or autocorrelation structure of a time series. A lower RSS indicates a better fit of the AR model to the segment.

Important Notes:

• Minimum Segment Length: The segment must be long enough to both form the AR equations and solve the resulting linear system. The minimum required length is max(order + 1, 2*order + k), where k is 1 if includeIntercept is true, and 0 otherwise. Shorter segments will cause a SegmentLengthException.
• Constant Data Segments: Fitting an AR model with an intercept to a perfectly constant segment (e.g., [5, 5, 5]) leads to a singular linear system (collinearity between the intercept and lagged variables). This function handles this by returning double.PositiveInfinity cost for such segments. Fitting without an intercept may result in a near-zero cost if the constant value is non-zero.
• This implementation currently only supports univariate (single-dimensional) time series.
• When used with information criteria (BIC/AIC), this function estimates the residual variance and uses it to calculate the likelihood metric. The number of parameters includes AR coefficients, intercept (if used), and residual variance.

Constructors

ARCostFunction(int, bool)

Initializes a new instance of the ARCostFunction class.

public ARCostFunction(int order, bool includeIntercept = true)

Parameters

order int

The order p of the Autoregressive model (must be >= 1).

includeIntercept bool

Whether to include an intercept term (constant) in the AR model. Default is true.

Exceptions

ArgumentOutOfRangeException

Thrown if order is less than 1.

Properties

SupportsInformationCriteria

Indicates that this cost function provides likelihood metrics suitable for BIC/AIC.

public bool SupportsInformationCriteria { get; }

Property Value

bool

Methods

ComputeCost(int?, int?)

Computes the cost (Residual Sum of Squares) for a segment by fitting an AR(p) model.

public override double ComputeCost(int? start = null, int? end = null)

Parameters

start int?

The start index of the segment (inclusive). If null, defaults to 0.

end int?

The end index of the segment (exclusive). If null, defaults to the length of the signal.

Returns

double

The computed RSS cost for the segment, or double.PositiveInfinity if the model cannot be fit.

Exceptions

UninitializedDataException

Thrown when Fit method has not been called before ComputeCost.

ArgumentOutOfRangeException

Thrown when the segment indices are out of bounds.

SegmentLengthException

Thrown when the segment length is less than the minimum required length.

CostFunctionException

Thrown if an unexpected error occurs during fitting.

ComputeLikelihoodMetric(int, int)

Computes the Gaussian negative log-likelihood metric -2 * logL for the segment, assuming errors are Gaussian. Metric = n_eff * log(variance_mle), where variance_mle = RSS / n_eff and n_eff = segmentLength - order.

public double ComputeLikelihoodMetric(int start, int end)

Parameters

start int

The start index of the segment (inclusive).

end int

The end index of the segment (exclusive).

Returns

double

The computed likelihood metric, or double.PositiveInfinity if the model cannot be fit or variance is near zero.

Exceptions

UninitializedDataException

Thrown when Fit method has not been called.

ArgumentOutOfRangeException

Thrown when the segment indices are out of bounds.

SegmentLengthException

Thrown when the segment length is invalid.

CostFunctionException

Thrown if an unexpected error occurs during calculation.

Fit(double[,])

Fits the cost function to the provided multi-dimensional time series data. Note: ARCostFunction currently only supports univariate (1D) signals.

public override IPELTCostFunction Fit(double[,] signalMatrix)

Parameters

signalMatrix double[,]

The multi-dimensional time series data. Must have exactly one row.

Returns

IPELTCostFunction

The fitted ARCostFunction instance.

Exceptions

ArgumentNullException

Thrown if the signal matrix is null.

NotSupportedException

Thrown if the signal matrix has more than one dimension (row).

ArgumentException

Thrown if the signal length is less than order + 1.

Fit(double[])

Fits the cost function to the provided one-dimensional time series data.

public IPELTCostFunction Fit(double[] signal)

Parameters

signal double[]

The one-dimensional time series data to fit.

Returns

IPELTCostFunction

The fitted ARCostFunction instance.

Exceptions

ArgumentNullException

Thrown if the signal is null.

ArgumentException

Thrown if the signal length is less than order + 1.

GetSegmentParameterCount(int)

Gets the number of parameters estimated for an AR(p) model segment. Includes AR coefficients, intercept (if applicable), and residual variance.

public int GetSegmentParameterCount(int segmentLength)

Parameters

segmentLength int

The length of the segment (unused in this implementation as parameter count depends only on order and intercept).

Returns

int

Number of parameters: p (coeffs) + 1 (variance) [+ 1 (intercept)].