NAG FL Interface
g13nbf (cp_​pelt_​user)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{n}$ – Integer Input

On entry: $n$, the length of the time series.

Constraint: $\mathbf{n}\ge 2$.

2: $\mathbf{beta}$ – Real (Kind=nag_wp) Input

On entry: $\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.

3: $\mathbf{minss}$ – Integer Input

On entry: the minimum distance between two change points, that is ${\tau }_i-{\tau }_{i-1}\ge \mathbf{minss}$.

Constraint: $\mathbf{minss}\ge 2$.

4: $\mathbf{k}$ – Real (Kind=nag_wp) Input

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

5: $\mathbf{costfn}$ – Subroutine, supplied by the user. External Procedure

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

The specification of costfn is:

Fortran Interface

Subroutine costfn ( ts, nr, r, c, y, iuser, ruser, info) Integer, Intent (In) :: ts, nr, r(nr) Integer, Intent (Inout) :: iuser(*), info Real (Kind=nag_wp), Intent (Inout) :: y(*), ruser(*) Real (Kind=nag_wp), Intent (Out) :: c(nr)

C Header Interface

void  costfn_ (const Integer *ts, const Integer *nr, const Integer r[], double c[], double y[], Integer iuser[], double ruser[], Integer *info)

C++ Header Interface

#include <nag.h> extern "C" { void  costfn_ (const Integer &ts, const Integer &nr, const Integer r[], double c[], double y[], Integer iuser[], double ruser[], Integer &info) }

1: $\mathbf{ts}$ – Integer Input

On entry: a reference time point.

2: $\mathbf{nr}$ – Integer Input

On entry: number of segments being considered.

3: $\mathbf{r}\left(\mathbf{nr}\right)$ – Integer array Input

On entry: time points which, along with ts, define the segments being considered, $0\le \mathbf{r}\left(i\right)\le n$ for $i=1,2,\dots \mathbf{nr}$.

4: $\mathbf{c}\left(\mathbf{nr}\right)$ – Real (Kind=nag_wp) array Output

On exit: the cost function, $C$, with

$$\mathbf{c}\left(i\right)=\left\{\begin{array}{ll}C\left(y_{r_i:t}\right)& \text{ if }t>r_i,\\ C\left(y_{t:r_i}\right)& \text{ otherwise.}\end{array}\right.$$

where $t=\mathbf{ts}$ and $r_i=\mathbf{r}\left(i\right)$.

It should be noted that if $t>r_i$ for any value of $i$ then it will be true for all values of $i$. Therefore the inequality need only be tested once per call to costfn.

5: $\mathbf{y}\left(*\right)$ – Real (Kind=nag_wp) array User Data

costfn is called with y as supplied to g13nbf. You are free to use the array y to supply information to costfn.

y is supplied in addition to iuser and ruser for ease of coding as in most cases costfn will require (functions of) the time series, $y$.

6: $\mathbf{iuser}\left(*\right)$ – Integer array User Workspace

7: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array User Workspace

costfn is called with the arguments iuser and ruser as supplied to g13nbf. You should use the arrays iuser and ruser to supply information to costfn.

8: $\mathbf{info}$ – Integer Input/Output

On entry: $\mathbf{info}=0$.

On exit: set info to a nonzero value if you wish g13nbf to terminate with $\mathbf{ifail}=\mathbf{51}$.

costfn must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which g13nbf is called. Arguments denoted as Input must not be changed by this procedure.

Note: costfn should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by g13nbf. If your code inadvertently does return any NaNs or infinities, g13nbf is likely to produce unexpected results.

6: $\mathbf{ntau}$ – Integer Output

On exit: $m$, the number of change points detected.

7: $\mathbf{tau}\left(\mathbf{n}\right)$ – Integer array Output

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

The remainder of tau is used as workspace.

8: $\mathbf{y}\left(*\right)$ – Real (Kind=nag_wp) array User Data

y is not used by g13nbf, but is passed directly to costfn and may be used to pass information to this routine. y will usually be used to pass (functions of) the time series, $y$ of interest.

9: $\mathbf{iuser}\left(*\right)$ – Integer array User Workspace

10: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array User Workspace

iuser and ruser are not used by g13nbf, but are passed directly to costfn and may be used to pass information to this routine.

11: $\mathbf{ifail}$ – Integer Input/Output

On entry: ifail must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this argument you should refer to Section 4 in the Introduction to the NAG Library FL Interface for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, if you are not familiar with this argument, the recommended value is $0$. When the value $-\mathbf{1}\text{ or }\mathbf{1}$ is used it is essential to test the value of ifail on exit.

On exit: $\mathbf{ifail}=\mathbf{0}$ unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

$\mathbf{ifail}=11$

On entry, $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{n}\ge 2$.

$\mathbf{ifail}=31$

On entry, $\mathbf{minss}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{minss}\ge 2$.

$\mathbf{ifail}=51$

User requested termination.

$\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results