naginterfaces.library.tsa.cp_​pelt_​user

naginterfaces.library.tsa.cp_pelt_user(n, beta, k, costfn, minss=2, data=None)[source]

cp_pelt_user detects change points in a univariate time series, that is, the time points at which some feature of the data, for example the mean, changes. Change points are detected using the PELT (Pruned Exact Linear Time) algorithm and a user-supplied cost function.

For full information please refer to the NAG Library document for g13nb

https://www.nag.com/numeric/nl/nagdoc_28.6/flhtml/g13/g13nbf.html

Parameters
nint

, the length of the time series.

betafloat

, the penalty term.

There are a number of standard ways of setting , including:

SIC or BIC

AIC

Hannan-Quinn

where is the number of parameters being treated as estimated in each segment.

The value of will depend on the cost function being used.

If no penalty is required then set .

Generally, the smaller the value of the larger the number of suggested change points.

kfloat

, the constant value that satisfies equation [equation]. If exists, it is unlikely to be unique in such cases, it is recommened that the largest value of , that satisfies equation [equation], is chosen. No check is made that is the correct value for the supplied cost function.

costfncallable c = costfn(ts, r, data=None)

The cost function, . must calculate a vector of costs for a number of segments.

Parameters
tsint

A reference time point.

rint, ndarray, shape

Time points which, along with , define the segments being considered, for .

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
cfloat, array-like, shape

On exit, the cost function, .

minssint, optional

The minimum distance between two change points, that is .

dataarbitrary, optional

User-communication data for callback functions.

Returns
ntauint

, the number of change points detected.

tauint, ndarray, shape

The first elements of hold the location of the change points. The th segment is defined by to , where and .

Raises
NagValueError
(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

Warns
NagCallbackTerminateWarning
(errno )

User requested termination.

Notes

Let denote a series of data and denote a set of ordered (strictly monotonic increasing) indices known as change points with and . For ease of notation we also define . The change points, , split the data into segments, with the th segment being of length and containing .

Given a user-supplied cost function, cp_pelt_user solves

where is a penalty term used to control the number of change points. This minimization is performed using the PELT algorithm of Killick et al. (2012). The PELT algorithm is guaranteed to return the optimal solution to [equation] if there exists a constant such that

for all

References

Chen, J and Gupta, A K, 2010, Parametric Statistical Change Point Analysis With Applications to Genetics, Medicine and Finance (Second Edition), Birkhäuser

Killick, R, Fearnhead, P and Eckely, I A, 2012, Optimal detection of changepoints with a linear computational cost, Journal of the American Statistical Association (107:500), 1590–1598