naginterfaces.library.tsa.cp_​pelt_​user

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

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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/g13/g13nbf.html

Parameters

nint

$n$, the length of the time series.

betafloat

$\beta$, the penalty term.

There are a number of standard ways of setting $\beta$, including:

SIC or BIC

$\beta =p\times \log \left(n\right)$

AIC

$\beta =2p$

Hannan-Quinn

$\beta =2p\times \log \left(\log \left(n\right)\right)$

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

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

If no penalty is required then set $\beta =0$.

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

kfloat

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

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

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

Parameters

tsint

A reference time point.

rint, ndarray, shape $\left(\text{nr}\right)$

Time points which, along with $ts$, define the segments being considered, $0\le r[i-1]\le n$ for $i=1,2,\dots \text{nr}$.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

cfloat, array-like, shape $\left(\text{nr}\right)$

On exit, the cost function, $C$.

minssint, optional

The minimum distance between two change points, that is ${\tau }_i-{\tau }_{i-1}\ge minss$.

dataarbitrary, optional

User-communication data for callback functions.

Returns

ntauint

$m$, the number of change points detected.

tauint, ndarray, shape $\left(ntau\right)$

The first $m$ elements of $tau$ hold the location of the change points. The $i$th segment is defined by $y_{({\tau }_{i-1}+1)}$ to $y_{{\tau }_i}$, where ${\tau }_0=0$ and ${\tau }_i=tau[i-1],1\le i\le m$.

Raises

NagValueError

(errno $11$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 2$.

(errno $31$)

On entry, $minss=⟨value⟩$.

Constraint: $minss\ge 2$.

Warns

NagCallbackTerminateWarning

(errno $51$)

User requested termination.

Notes

Let $y_{1:n}=\{y_j:j=1,2,\dots ,n\}$ denote a series of data and $\tau =\{{\tau }_i:i=1,2,\dots ,m\}$ denote a set of $m$ ordered (strictly monotonic increasing) indices known as change points with $1\le {\tau }_i\le n$ and ${\tau }_m=n$. For ease of notation we also define ${\tau }_0=0$. The $m$ change points, $\tau$, split the data into $m$ segments, with the $i$th segment being of length $n_i$ and containing $y_{{\tau }_{i-1}+1:{\tau }_i}$.

Given a user-supplied cost function, $C\left(y_{{\tau }_{i-1}+1:{\tau }_i}\right)$ cp_pelt_user solves

$${\text{minimize}}_{m,\tau }\sum _{i=1}^m(C\left(y_{{\tau }_{i-1}+1:{\tau }_i}\right)+\beta )$$

where $\beta$ 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 $K$ such that

$$C\left(y_{(u+1):v}\right)+C\left(y_{(v+1):w}\right)+K\le C\left(y_{(u+1):w}\right)$$

for all $u<v<w$

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