Methods for Changepoint Detection

Description

Implements various mainstream and specialised changepoint methods for finding single and multiple changepoints within data. Many popular non-parametric and frequentist methods are included. Users should start by looking at the documentation for cpt.mean(), cpt.var() and cpt.meanvar().

Details

Author(s)

Rebecca Killick <r.killick@lancs.ac.uk>, with contributions from Kaylea Haynes, Harjit Hullait, Paul Fearnhead, Robin Long and Jamie Lee.

Maintainer: Rebecca Killick <r.killick@lancs.ac.uk>

References

Chen, J. and Gupta, A. K. (2000) Parametric statistical change point analysis, Birkhauser

PELT Algorithm: Killick R, Fearnhead P, Eckley IA (2012) Optimal detection of changepoints with a linear computational cost, JASA 107(500), 1590–1598

Binary Segmentation: Scott, A. J. and Knott, M. (1974) A Cluster Analysis Method for Grouping Means in the Analysis of Variance, Biometrics 30(3), 507–512

Segment Neighbourhoods: Auger, I. E. And Lawrence, C. E. (1989) Algorithms for the Optimal Identification of Segment Neighborhoods, Bulletin of Mathematical Biology 51(1), 39–54

See Also

cpt.mean,cpt.var,cpt.meanvar

Examples

# change in variance
set.seed(1)
x=c(rnorm(100,0,1),rnorm(100,0,10))
ansvar=cpt.var(x)
plot(ansvar)
print(ansvar) # identifies 1 changepoint at 100

# change in mean
y=c(rnorm(100,0,1),rnorm(100,5,1))
ansmean=cpt.mean(y)
plot(ansmean,cpt.col='blue')
print(ansmean)

# change in mean and variance
z=c(rnorm(100,0,1),rnorm(100,2,10))
ansmeanvar=cpt.meanvar(z)
plot(ansmeanvar,cpt.width=3)
print(ansmeanvar)

Binary Segmentation - Only intended for developer use.

Description

Implements the Binary Segmentation method for identifying changepoints in a given set of summary statistics for a specified cost function and penalty.

This function is called by cpt.mean, cpt.var and cpt.meanvar when method="BinSeg". This is not intended for use by regular users of the package. It is exported for developers to call directly for speed increases or to fit alternative cost functions.

WARNING: No checks on arguments are performed!

Usage

BINSEG(sumstat, pen = 0, cost_func = "norm.mean", shape = 1, minseglen = 2,  Q=5)

Arguments

Details

This function is used as a wrapper function to implement the Binary Segmentation algorithm in C. It simply creates the necessary worker vectors, ensures all inputs are the correct type, and passes everything to the C function.

This function is exported for developer use only. It does not perform any checks on inputs (other than type coersion) and is simply a wrapper function for the C code.

Value

A list is returned with elements:

Author(s)

Rebecca Killick

References

Binary Segmentation: Scott, A. J. and Knott, M. (1974) A Cluster Analysis Method for Grouping Means in the Analysis of Variance, Biometrics 30(3), 507–512

See Also

cpt.mean,cpt.meanvar,plot-methods,cpt

Examples

#This function should only be used by developers, see its use in cpt.mean, cpt.var and cpt.meanvar.

G+C Content in Human Chromosome 1

Description

This dataset gives the G+C content in 3kb windows along the Human Chromosome from 10Mb to 33Mb (no missing data).

Usage

HC1

Format

A vector of length 23553.

Source

http://www.ncbi.nlm.nih.gov/mapview/map_search.cgi?taxid=9606&build=previous

Normalized glioblastoma profile for chromosome 13

Description

This dataset is taken from Lai W, Johnson MJ, Kucherlapati R, Park PJ, Bioinformatics , 2005. The paper states that the original source of the data is from Bredel et al. (2005). The data is Chromosome 13 in GBM31.

Usage

Lai2005fig3

Format

A matrix of dimensions 797 x 5. The columns are Spot, CH, POS.start, POS.end, GBM31.

Source

http://compbio.med.harvard.edu/Supplements/Bioinformatics05b/Profiles/Chrom_13_GBM31.xls

Normalized glioblastoma profile for an excerpt of chromosome 7, the EGFR locus.

Description

This dataset is taken from Lai W, Johnson MJ, Kucherlapati R, Park PJ, Bioinformatics , 2005. The paper states that the original source of the data is from Bredel et al. (2005). The data is an excerpt of chromosome 7 in GBM29 from 40 to 65 Mb.

Usage

Lai2005fig4

Format

A matrix of dimensions 193 x 5. The columns are Spot, CH, POS.start, POS.end, GBM31.

Source

http://compbio.med.harvard.edu/Supplements/Bioinformatics05b/Profiles/Chrom_7_from40_to65Mb_GBM29.xls

PELT (Pruned Exact Linear Time) - Only intended for developer use.

Description

Implements the PELT method for identifying changepoints in a given set of summary statistics for a specified cost function and penalty.

This function is called by cpt.mean, cpt.var and cpt.meanvar when method="PELT". This is not intended for use by regular users of the package. It is exported for developers to call directly for speed increases or to fit alternative cost functions.

WARNING: No checks on arguments are performed!

Usage

PELT(sumstat, pen = 0, cost_func = "norm.mean", shape = 1, minseglen = 1)

Arguments

Details

This function is used as a wrapper function to implement the PELT algorithm in C. It simply creates the necessary worker vectors, ensures all inputs are the correct type, and passes everything to the C function.

This function is exported for developer use only. It does not perform any checks on inputs (other than type coersion) and is simply a wrapper function for the C code.

Value

A list is returned with elements:

Author(s)

Rebecca Killick

References

PELT Algorithm: Killick R, Fearnhead P, Eckley IA (2012) Optimal detection of changepoints with a linear computational cost, JASA 107(500), 1590–1598

CROPS: Haynes K, Eckley IA, Fearnhead P (2014) Efficient penalty search for multiple changepoint problems (in submission), arXiv:1412.3617

See Also

cpt.mean,cpt.meanvar,plot-methods,cpt

Examples

#This function should only be used by developers, see its use in cpt.mean, cpt.var and cpt.meanvar.

Input all required arguments into cpt classes - Only intended for developer use.

Description

This function helps to input all the necessary information into the correct format for cpt and cpt.range classes.

This function is called by cpt.mean, cpt.var and cpt.meanvar when class=TRUE. This is not intended for use by regular users of the package. It is exported for developers to call directly for speed and convenience.

WARNING: No checks on arguments are performed!

Usage

class_input(data, cpttype, method, test.stat, penalty, pen.value, minseglen, 
param.estimates, out=list(), Q=NA, shape=NA)

Arguments

Details

This function takes all the input required for the cpt or cpt.range classes and enters it into the object.

This function is exported for developer use only. It does not perform any checks on inputs and is simply a convenience function for converting the output of the worker functions into a nice format for the cpt and cpt.range classes.

Value

An object of class cpt or cpt.range as appropriate filled with the given attributes.

Author(s)

Rebecca Killick

See Also

cpt.var,cpt.mean,plot-methods,cpt

Examples

#This function should only be used by developers, see its use in cpt.mean, cpt.var and cpt.meanvar.

~~ Methods for Function coef ~~

Description

~~ Methods for function coef ~~

Methods

signature(object = "cpt")

Retrieves parameter estimates (i.e. param.est slot) from an object of class cpt

signature(object = "cpt.reg")

Retrieves parameter estimates (i.e. param.est slot) from an object of class cpt.reg

Class "cpt"

Description

A class for changepoint objects.

Objects from the Class

Objects can be created by calls of the form new("cpt", ...).

new("cpt", ...):

creates a new object with class cpt

Slots

data.set:

Object of class "ts", a coerced time series of the original data.

cpttype:

Object of class "character", the type of changepoint that was identified.

method:

Object of class "character", the method that was used to search for changepoints.

test.stat:

Object of class "character", the test statistic for the analysis of the data.

pen.type:

Object of class "character", the penalty type specified in the analysis.

pen.value:

Object of class "numeric", the value of the penalty used in the analysis.

minseglen:

Object of class "numeric", the minimum segment length (no. of observations between changepoints) used in the analysis.

cpts:

Object of class "numeric", vector of changepoints identified.

ncpts.max:

Object of class "numeric", maximum number of changepoint that can be identified.

param.est:

Object of class "list", list where each element is a vector of parameter estimates, if requested.

date:

Object of class "character", date and time the changepoint analysis was run.

version:

Object of class "character", version number of the package used when the analysis was run.

Methods

cpts

signature(object = "cpt"): retrieves cpts slot

cpttype

signature(object = "cpt"): retrieves cpttype slot

data.set

signature(object = "cpt"): retrieves vector version of data.set slot

data.set.ts

signature(object = "cpt"): retrieves time series version of data.set slot

test.stat

signature(object = "cpt"): retrieves test.stat slot

ncpts.max

signature(object = "cpt"): retrieves ncpts.max slot

method

signature(object = "cpt"): retrieves method slot

minseglen

signature(object = "cpt"): retrieves minseglen slot

param.est

signature(object = "cpt"): retrieves param.est slot

pen.type

signature(object = "cpt"): retrieves pen.type slot

pen.value

signature(object = "cpt"): retrieves pen.value slot

cpts<-

signature(object = "cpt"): replaces cpts slot

cpttype<-

signature(object = "cpt"): replaces cpttype slot

data.set<-

signature(object = "cpt"): replaces data.set slot

test.stat<-

signature(object = "cpt"): replaces test.stat slot

ncpts.max<-

signature(object = "cpt"): replaces ncpts.max slot

method<-

signature(object = "cpt"): replaces method slot

minseglen<-

signature(object = "cpt"): replaces minseglen slot

param.est<-

signature(object = "cpt"): replaces param.est slot

pen.type<-

signature(object = "cpt"): replaces pen.type slot

pen.value<-

signature(object = "cpt"): replaces pen.value slot

print

signature(object = "cpt"): prints details of the cpt object including summary

summary

signature(object = "cpt"): prints a summary of the cpt object

plot

signature(object = "cpt"): plots the cpt object with changepoints highlighted

param

signature(object = "cpt"): calculates the parameter estimates for the cpt object

logLik

signature(object = "cpt"): returns the overall log-likelihood of the cpt object

Author(s)

Rebecca Killick

See Also

data.set-methods,cpts-methods,cpt.reg,cpt.mean,cpt.var,cpt.meanvar

Examples

showClass("cpt") # shows the structure of the cpt class

x=new("cpt") # creates a new object with the cpt class defaults
cpts(x) # retrieves the cpts slot from x
cpts(x)<-c(10,50,100) # replaces the cpts slot from x with c(10,50,100)

# Example of a change in variance at 100 in simulated normal data
set.seed(1)
x=c(rnorm(100,0,1),rnorm(100,0,10))
ans=cpt.var(x) 
print(ans) # prints details of the analysis including a summary
summary(ans)
plot(ans) # plots the data with change (vertical line) at 100
logLik(ans) # raw likelihood of the data with changepoints, second value is likelihood + penalty

Identifying Changes in Mean

Description

Calculates the optimal positioning and (potentially) number of changepoints for data using the user specified method.

Usage

cpt.mean(data,penalty="MBIC",pen.value=0,method="PELT",Q=5,test.stat="Normal",class=TRUE,
param.estimates=TRUE,minseglen=1)

Arguments

Details

This function is used to find changes in mean for data using the test statistic specfified in the test.stat parameter. The changes are found using the method supplied which can be single changepoint (AMOC) or multiple changepoints using exact (PELT or SegNeigh) or approximate (BinSeg) methods. A changepoint is denoted as the last observation of the segment / regime.

Value

If class=TRUE then an object of S4 class "cpt" is returned. The slot cpts contains the changepoints that are returned. For class=FALSE the structure is as follows.

If data is a vector (single dataset) then a vector/list is returned depending on the value of method. If data is a matrix (multiple datasets) then a list is returned where each element in the list is either a vector or list depending on the value of method.

If method is AMOC then a vector (one dataset) or matrix (multiple datasets) is returned, the columns are:

If method is PELT then a vector is returned containing the changepoint locations for the penalty supplied. This always ends with n. If the penalty is CROPS then a list is returned with elements:

If method is SegNeigh then a list is returned with elements:

If method is BinSeg then a list is returned with elements:

Author(s)

Rebecca Killick

References

Change in Normal mean: Hinkley, D. V. (1970) Inference About the Change-Point in a Sequence of Random Variables, Biometrika 57, 1–17

CUSUM Test: M. Csorgo, L. Horvath (1997) Limit Theorems in Change-Point Analysis, Wiley

PELT Algorithm: Killick R, Fearnhead P, Eckley IA (2012) Optimal detection of changepoints with a linear computational cost, JASA 107(500), 1590–1598

CROPS: Haynes K, Eckley IA, Fearnhead P (2014) Efficient penalty search for multiple changepoint problems (in submission), arXiv:1412.3617

Binary Segmentation: Scott, A. J. and Knott, M. (1974) A Cluster Analysis Method for Grouping Means in the Analysis of Variance, Biometrics 30(3), 507–512

Segment Neighbourhoods: Auger, I. E. And Lawrence, C. E. (1989) Algorithms for the Optimal Identification of Segment Neighborhoods, Bulletin of Mathematical Biology 51(1), 39–54

MBIC: Zhang, N. R. and Siegmund, D. O. (2007) A Modified Bayes Information Criterion with Applications to the Analysis of Comparative Genomic Hybridization Data. Biometrics 63, 22-32.

See Also

cpt.var,cpt.meanvar,plot-methods,cpt

Examples

# Example of a change in mean at 100 in simulated normal data
set.seed(1)
x=c(rnorm(100,0,1),rnorm(100,10,1))
cpt.mean(x,penalty="SIC",method="AMOC",class=FALSE) # returns 100 to show that the null hypothesis
#was rejected and the change in mean is at 100 and the confidence level is 1.
ans=cpt.mean(x,penalty="Asymptotic",pen.value=0.01,method="AMOC")
cpts(ans)# returns 100 to show that the null hypothesis was rejected, the change in mean is at 100
#and we are 99% confident of this result
cpt.mean(x,penalty="Manual",pen.value=0.8,method="AMOC",test.stat="CUSUM")
# returns 101 as the changepoint location


# Example of multiple changes in mean at 50,100,150 in simulated normal data
set.seed(1)
x=c(rnorm(50,0,1),rnorm(50,5,1),rnorm(50,10,1),rnorm(50,3,1))
cpt.mean(x,penalty="Manual",pen.value="2*log(n)",method="BinSeg",Q=5,class=FALSE)
# returns optimal number of changepoints is 3, locations are 50,100,150.

# Example of using the CROPS penalty in data set above
set.seed(1)
x=c(rnorm(50,0,1),rnorm(50,5,1),rnorm(50,10,1),rnorm(50,3,1))
out=cpt.mean(x, pen.value = c(4,1500),penalty = "CROPS",method = "PELT")
cpts.full(out)  # returns 7 segmentations for penalty values between 4 and 1500.
# We find segmentations with 7, 5, 4, 3, 2, 1 and 0 changepoints.
# Note that the empty final row indicates no changepoints.
pen.value.full(out) # gives associated penalty transition points
# CROPS does not give an optimal set of changepoints thus we may wish to explore further
plot(out,diagnostic=TRUE)
# looks like the segmentation with 3 changepoints, 50,100,150 is the most appropriate
plot(out,ncpts=3)


# Example multiple datasets where the first row has multiple changes in mean and the second row has
#no change in mean
set.seed(1)
x=c(rnorm(50,0,1),rnorm(50,5,1),rnorm(50,10,1),rnorm(50,3,1))
y=rnorm(200,0,1)
z=rbind(x,y)
cpt.mean(z,penalty="Asymptotic",pen.value=0.01,method="SegNeigh",Q=5,class=FALSE) # returns list
#that has two elements, the first has 3 changes in mean and variance at 50,100,150 and the second
#has no changes in variance
ans=cpt.mean(z,penalty="Asymptotic",pen.value=0.01,method="PELT")
cpts(ans[[1]]) # same results as for the SegNeigh method.
cpts(ans[[2]]) # same results as for the SegNeigh method.

Identifying Changes in Mean and Variance

Description

Calculates the optimal positioning and (potentially) number of changepoints for data using the user specified method.

Usage

cpt.meanvar(data,penalty="MBIC",pen.value=0,method="PELT",Q=5,test.stat="Normal",
class=TRUE,param.estimates=TRUE,shape=1,minseglen=2)

Arguments

Details

This function is used to find changes in mean and variance for data using the test statistic specified in the test.stat parameter. The changes are found using the method supplied which can be single changepoint (AMOC) or multiple changepoints using exact (PELT or SegNeigh) or approximate (BinSeg) methods. A changepoint is denoted as the last observation of the segment / regime.

Value

If class=TRUE then an object of S4 class "cpt" is returned. The slot cpts contains the changepoints that are returned. For class=FALSE the structure is as follows.

If data is a vector (single dataset) then a vector/list is returned depending on the value of method. If data is a matrix (multiple datasets) then a list is returned where each element in the list is either a vector or list depending on the value of method.

If method is AMOC then a vector (one dataset) or matrix (multiple datasets) is returned, the columns are:

If method is PELT then a vector is returned containing the changepoint locations for the penalty supplied. This always ends with n. If the penalty is CROPS then a list is returned with elements:

If method is SegNeigh then a list is returned with elements:

If method is BinSeg then a list is returned with elements:

Author(s)

Rebecca Killick

References

Change in Normal mean and variance: Chen, J. and Gupta, A. K. (2000) Parametric statistical change point analysis, Birkhauser

Change in Gamma shape parameter: Chen, J. and Gupta, A. K. (2000) Parametric statistical change point analysis, Birkhauser

Change in Exponential model: Chen, J. and Gupta, A. K. (2000) Parametric statistical change point analysis, Birkhauser

Change in Poisson model: Chen, J. and Gupta, A. K. (2000) Parametric statistical change point analysis, Birkhauser

PELT Algorithm: Killick R, Fearnhead P, Eckley IA (2012) Optimal detection of changepoints with a linear computational cost, JASA 107(500), 1590–1598

CROPS: Haynes K, Eckley IA, Fearnhead P (2014) Efficient penalty search for multiple changepoint problems (in submission), arXiv:1412.3617

Binary Segmentation: Scott, A. J. and Knott, M. (1974) A Cluster Analysis Method for Grouping Means in the Analysis of Variance, Biometrics 30(3), 507–512

Segment Neighbourhoods: Auger, I. E. And Lawrence, C. E. (1989) Algorithms for the Optimal Identification of Segment Neighborhoods, Bulletin of Mathematical Biology 51(1), 39–54

MBIC: Zhang, N. R. and Siegmund, D. O. (2007) A Modified Bayes Information Criterion with Applications to the Analysis of Comparative Genomic Hybridization Data. Biometrics 63, 22-32.

See Also

cpt.var,cpt.mean,plot-methods,cpt

Examples

# Example of a change in scale parameter (mean and variance) at 100 in simulated gamma data
set.seed(1)
x=c(rgamma(100,shape=1,rate=1),rgamma(100,shape=1,rate=5))
cpt.meanvar(x,penalty="SIC",method="AMOC",test.stat="Gamma",class=FALSE,shape=1) # returns 97 to
#show that the null hypothesis was rejected and the change in scale parameter is at 97
ans=cpt.meanvar(x,penalty="AIC",method="AMOC",test.stat="Gamma",shape=1)
cpts(ans)
# returns 97 to show that the null hypothesis was rejected, the change in scale parameter is at 97


# Example of multiple changes in mean and variance at 50,100,150 in simulated normal data
set.seed(1)
x=c(rnorm(50,0,1),rnorm(50,5,3),rnorm(50,10,1),rnorm(50,3,10))
cpt.meanvar(x,penalty="Manual",pen.value="4*log(n)",method="BinSeg",Q=5,class=FALSE)
# returns optimal number of changepoints is 4, locations are 50,100,150,152.

# Example of using the CROPS penalty in the above example
set.seed(1)
x=c(rnorm(50,0,1),rnorm(50,5,3),rnorm(50,10,1),rnorm(50,3,10))
out=cpt.meanvar(x,pen.value=c(2*log(length(x)),100*log(length(x))),penalty="CROPS",method="PELT")
cpts.full(out)
# returns 6 segmentations for penalty values between 2log(n) and 100log(n).
# We find segmentations with 9, 7, 4, 3, 1 and 0 changepoints.
# Note that the empty final row indicates no changepoints.
pen.value.full(out) # gives associated penalty transition points
# CROPS does not give an optimal set of changepoints thus we may wish to explore further
plot(out,diagnostic=TRUE)
# looks like the segmentation with 4 changepoints, 50,100,150,200 is the most appropriate
plot(out,ncpts=3)


# Example multiple datasets where the first row has multiple changes in mean and variance and the
#second row has no change in mean or variance
set.seed(1)
x=c(rnorm(50,0,1),rnorm(50,5,3),rnorm(50,10,1),rnorm(50,3,10))
y=rnorm(200,0,1)
z=rbind(x,y)
cpt.meanvar(z,penalty="Asymptotic",pen.value=0.01,method="SegNeigh",Q=5,class=FALSE) # returns list
#that has two elements, the first has 3 changes in mean and variance at 50,100,150 and the second
#has no changes in mean or variance
ans=cpt.meanvar(z,penalty="Asymptotic",pen.value=0.01,method="PELT")
cpts(ans[[1]]) # same results as for the SegNeigh method.
cpts(ans[[2]]) # same results as for the SegNeigh method.

Class "cpt.range"

Description

A class for changepoint objects that return more than 1 segmentation. Inherits from cpt class.

Objects from the Class

Objects can be created by calls of the form new("cpt.range", ...).

new("cpt.range", ...):

creates a new object with class cpt.range

Slots

cpts.full:

Object of class "matrix", each row of the matrix is a different segmentation of the data (different set of changepoints).

pen.value.full:

Object of class "vector", each element is the penalty used to create the set of changepoints in the corresponding row of cpts.full.

The remaining slots are inherited from the cpt class.

data.set:

Object of class "ts", a coerced time series of the original data. Inherited from cpt class.

cpttype:

Object of class "character", the type of changepoint that was identified. Inherited from cpt class.

method:

Object of class "character", the method that was used to search for changepoints. Inherited from cpt class.

test.stat:

Object of class "character", the test statistic for the analysis of the data. Inherited from cpt class.

pen.type:

Object of class "character", the penalty type specified in the analysis. Inherited from cpt class.

pen.value:

Object of class "numeric", the value of the penalty used in the analysis. Inherited from cpt class.

minseglen:

Object of class "numeric", the minimum segment length (no. of observations between changepoints) used in the analysis. Inherited from cpt class.

cpts:

Object of class "numeric", vector of optimal changepoints identified. Inherited from cpt class.

ncpts.max:

Object of class "numeric", maximum number of changepoint that can be identified. Inherited from cpt class.

param.est:

Object of class "list", list where each element is a vector of parameter estimates, if requested. Inherited from cpt class.

date:

Object of class "character", date and time the changepoint analysis was run. Inherited from cpt class.

version:

Object of class "character", version number of the package used when the analysis was run. Inherited from cpt class.

Methods

cpts.full

signature(object = "cpt.range"): retrieves cpts.full slot

pen.value.full

signature(object = "cpt.range"): retrieves pen.value.full slot

cpts.full<-

signature(object = "cpt.range"): replaces cpts.full slot

param

signature(object="cpt.range",ncpts=NA): creates parameter estimates for the segmentation with ncpts number of changepoints. If ncpts=NA then the optimal set of changepoints according to the set penalty is used.

pen.value.full<-

signature(object = "cpt.range"): replaces pen.value.full slot

plot

signature(object="cpt.range",ncpts=NA,diagnostic=FALSE): by default plots the optimal segmentation as for class="cpt". If ncpts is specified then plots the segmentation for ncpts number of changepoints. If diagnostic=TRUE then produces a diagnostic plot to aide selection of the number of changes.

print

signature(object = "cpt.range"): prints details of the cpt.range object including summary

summary

signature(object = "cpt.range"): prints a summary of the cpt.range object

Author(s)

Rebecca Killick

See Also

cpts.full-methods,cpt,cpt.mean,cpt.var,cpt.meanvar

Examples

showClass("cpt.range") # shows the structure of the cpt.range class

x=new("cpt.range") # creates a new object with the cpt.range class defaults
cpts(x) # retrieves the cpts slot from x
cpts(x)<-c(10,50,100) # replaces the cpts slot from x with c(10,50,100)

# Example of multiple changes in variance at 50,100,150 in simulated normal data
set.seed(1)
x=c(rnorm(50,0,1),rnorm(50,0,10),rnorm(50,0,5),rnorm(50,0,1))
out=cpt.var(x,pen.value=c(log(length(x)),10*log(length(x))),penalty="CROPS",method="PELT")
print(out) # prints details of the analysis including a summary
summary(out)
plot(out,diagnostic=TRUE) # a diagnostic plot to identify number of changepoints
# looks like the segmentation with 3 changepoints, 50,99,150 is the most appropriate
plot(out,ncpts=3) # plots the segmentation for 3 changes
logLik(out,ncpts=3) 
# raw likelihood of the data with changepoints, second value is likelihood + penalty

Identifying Changes in Regression

Description

Calculates the optimal position and (potentially) number of changepoints in regression structure for data using the user specified method.

Usage

  cpt.reg(data, penalty="MBIC", pen.value=0, method="PELT", test.stat="Normal",
    class=TRUE, param.estimates=TRUE, shape=0, minseglen=3, tol=1e-07)

Arguments

Details

This function is used to find change in linear regression structure for data. The changes are found using the method supplied wihich can be single changepoint (AMOC) or multiple changepoints (PELT). A changepoint is denoted as the last observation of the segment / regime.

Value

If class=TRUE then an object of S4 class "cpt.reg" is returned. The slot cpts contains the changepoints that are returned. For class=FALSE the changepoint positions are returned, along with supplementary information about the fit detailed below. (This info is mainly used for bug fixing.)

If data is a matrix, then a vector/list/cpt.reg is returned depending on the of method. If data is a 3D array (multiple data sets, with total number of data sets = dim1 and each data set of the same size) then a list is returned where each element is either a vector/list/cpt.reg corresponding to the fit on each data set in the order they appear in the array.

If method="AMOC" & dist="Normal" then a list is returned with:

cpts: changepoint position.

pen.value: penalty value.

If method="PELT" & dist="Normal" then a list is returned with:

cpts: changepoint positions.

lastchangecpts: index of last changepoint according to optimal sequential fit.

lastchangelike: cost at last changepont according to optimal sequential fit.

ncpts: number of changepoints according to optimal squential fit.

Author(s)

Rebecca Killick, Simon Taylor

References

PELT Algorithm: Killick R, Fearnhead P, Eckley IA (2012) Optimal detection of changepoints with a linear computational cost, JASA 107(500), 1590–1598

MBIC: Zhang, N. R. and Siegmund, D. O. (2007) A Modified Bayes Information Criterion with Applications to the Analysis of Comparative Genomic Hybridization Data. Biometrics 63, 22-32.

See Also

cpt.mean, penalty_decision, plot-methods, cpt, lm.fit

Examples

## Trend change
set.seed(1)
  x <- 1:200
  beta0 <- rep(c(0,100,50,0),each=50)
  beta1 <- rep(c(1,-1,0,0.25),each=50)
  y <- beta0 + beta1*x + rnorm(200)
  data <- cbind(y,1,x)

  out <- cpt.reg(data, method="PELT", minseglen=5, penalty="MBIC", test.stat="Normal")
  cpts(out)      ##changepoints
  param.est(out) ##parameter estimates (rows: beta estimates per segment)
  plot(out)      ##plot of fit



  ## Seasonal change, period 12
  n=100
indicator=rep(1,n)
trend=1:n
seasonal=cos(2*pi*(1:n -6)/12) # yearly, peak in summer
cpt.s = c(rep(0,floor(n/4)), rep(2, floor(n/4)), rep(1, floor(n/4)),rep(0,n-3*floor(n/4)))
##3 Alternating Cpts
y=0.1*cpt.s*1:n+cos(2*pi*(1:n -6)/12)+rnorm(n)
data=cbind(y,indicator,trend,seasonal)
out=cpt.reg(data, minseglen=12)
plot(out,cpt.width=3)
cpts(out)
param.est(out) ## column order of estimates matches the column order of inputs

Class "cpt.reg"

Description

A class for changepoint objects, specifically change in regression.

Objects from the Class

Objects can be created by calls of the form new("cpt", ...).

new("cpt", ...):

creates a new object with class cpt

Slots

data.set:

Object of class "numeric", the original vector of data

cpttype:

Object of class "character", the type of changepoint that was identified

method:

Object of class "character", the method that was used to search for changepoints, default change in regression

test.stat:

Object of class "character", the test statistic used to analyse the data

pen.type:

Object of class "character", the penalty type specified in the analysis

pen.value:

Object of class "numeric", the value of the penalty used in the analysis

minseglen:

Object of class "numeric", the minimum segment length (no. of observations between changepoints) used in the analysis.

cpts:

Object of class "numeric", vector of changepoints identified

ncpts.max:

Object of class "numeric", maximum number of changepoint that can be identified

param.est:

Object of class "list", list where each element is a vector of parameter estimates, if requested

date:

Object of class "character", date and time the changepoint analysis was run

version:

Object of class "character", version number of the package used when the analysis was run.

Methods

cpts

signature(object = "cpt.reg"): retrieves cpts slot

cpttype

signature(object = "cpt.reg"): retrieves cpttype slot

data.set

signature(object = "cpt.reg"): retrieves data.set slot

test.stat

signature(object = "cpt.reg"): retrieves test.stat slot

ncpts.max

signature(object = "cpt.reg"): retrieves ncpts.max slot

method

signature(object = "cpt.reg"): retrieves method slot

minseglen

signature(object = "cpt"): retrieves minseglen slot

param.est

signature(object = "cpt.reg"): retrieves param.est slot

pen.type

signature(object = "cpt.reg"): retrieves pen.type slot

pen.value

signature(object = "cpt.reg"): retrieves pen.value slot

cpts<-

signature(object = "cpt.reg"): replaces cpts slot

cpttype<-

signature(object = "cpt.reg"): replaces cpttype slot

data.set<-

signature(object = "cpt.reg"): replaces data.set slot

test.stat<-

signature(object = "cpt.reg"): replaces test.stat slot

ncpts.max<-

signature(object = "cpt.reg"): replaces ncpts.max slot

method<-

signature(object = "cpt.reg"): replaces method slot

param.est<-

signature(object = "cpt.reg"): replaces param.est slot

pen.type<-

signature(object = "cpt.reg"): replaces pen.type slot

pen.value<-

signature(object = "cpt.reg"): replaces pen.value slot

print

signature(object = "cpt.reg"): prints details of the cpt object including summary

summary

signature(object = "cpt.reg"): prints a summary of the cpt object

param

signature(object = "cpt.reg"): calculates the parameter estimates for the cpt object

Author(s)

Rebecca Killick

See Also

plot-methods,cpts-methods,cpt

Examples

showClass("cpt.reg")

x=new("cpt.reg") # creates a new object with the cpt.reg class defaults
data.set(x)  # retrieves the data.set slot from x
data.set(x)<-matrix(1:10,nrow=5,ncol=2) # replaces the data.set slot from x with a matrix

Identifying Changes in Variance

Description

Calculates the optimal positioning and (potentially) number of changepoints for data using the user specified method.

Usage

cpt.var(data,penalty="MBIC",pen.value=0,know.mean=FALSE,mu=NA,method="PELT",Q=5,
test.stat="Normal",class=TRUE,param.estimates=TRUE,minseglen=2)

Arguments

Details

This function is used to find changes in variance for data using the test statistic specified in the test.stat parameter. The changes are found using the method supplied which can be single changepoint (AMOC) or multiple changepoints using exact (PELT or SegNeigh) or approximate (BinSeg) methods. A changepoint is denoted as the last observation of the segment / regime. Note that for the test.stat="CSS" option the preset penalties are log(.) to allow comparison with test.stat="Normal".

Value

If class=TRUE then an object of S4 class "cpt" is returned. The slot cpts contains the changepoints that are returned. For class=FALSE the structure is as follows.

If data is a vector (single dataset) then a vector/list is returned depending on the value of method. If data is a matrix (multiple datasets) then a list is returned where each element in the list is either a vector or list depending on the value of method.

If method is AMOC then a vector (one dataset) or matrix (multiple datasets) is returned, the columns are:

If method is PELT then a vector is returned containing the changepoint locations for the penalty supplied. This always ends with n. If the penalty is CROPS then a list is returned with elements:

If method is SegNeigh then a list is returned with elements:

If method is BinSeg then a list is returned with elements:

Author(s)

Rebecca Killick

References

Normal: Chen, J. and Gupta, A. K. (2000) Parametric statistical change point analysis, Birkhauser

CSS: C. Inclan, G. C. Tiao (1994) Use of Cumulative Sums of Squares for Retrospective Detection of Changes of Variance, Journal of the American Statistical Association 89(427), 913–923

PELT Algorithm: Killick R, Fearnhead P, Eckley IA (2012) Optimal detection of changepoints with a linear computational cost, JASA 107(500), 1590–1598

CROPS: Haynes K, Eckley IA, Fearnhead P (2014) Efficient penalty search for multiple changepoint problems (in submission), arXiv:1412.3617

Binary Segmentation: Scott, A. J. and Knott, M. (1974) A Cluster Analysis Method for Grouping Means in the Analysis of Variance, Biometrics 30(3), 507–512

Segment Neighbourhoods: Auger, I. E. And Lawrence, C. E. (1989) Algorithms for the Optimal Identification of Segment Neighborhoods, Bulletin of Mathematical Biology 51(1), 39–54

MBIC: Zhang, N. R. and Siegmund, D. O. (2007) A Modified Bayes Information Criterion with Applications to the Analysis of Comparative Genomic Hybridization Data. Biometrics 63, 22-32.

See Also

cpt.mean,cpt.meanvar,plot-methods,cpt

Examples

# Example of a change in variance at 100 in simulated normal data
set.seed(1)
x=c(rnorm(100,0,1),rnorm(100,0,10))
cpt.var(x,penalty="SIC",method="AMOC",class=FALSE) # returns 100 to show that the null hypothesis
#was rejected and the change in variance is at 100
ans=cpt.var(x,penalty="Asymptotic",pen.value=0.01,method="AMOC")
cpts(ans)# returns 100 to show that the null hypothesis was rejected, the change in variance is at
#100 and we are 99% confident of this result

# Example of multiple changes in variance at 50,100,150 in simulated data
set.seed(1)
x=c(rnorm(50,0,1),rnorm(50,0,10),rnorm(50,0,5),rnorm(50,0,1))
cpt.var(x,penalty="Manual",pen.value="log(2*log(n))",method="BinSeg",test.stat="CSS",Q=5,
class=FALSE) # returns optimal number of changepoints is 4, locations are 50,53,99,150.

# Example of using CROPS in the above example
set.seed(1)
x=c(rnorm(50,0,1),rnorm(50,0,10),rnorm(50,0,5),rnorm(50,0,1))
out=cpt.var(x,pen.value=c(log(length(x)),100*log(length(x))),penalty="CROPS",method="PELT")
cpts.full(out) # returns 7 segmentations for penalty values between log(n) and 100log(n).
# We find segmentations with 7, 5, 4,3,2,1 and 0 changepoints.
# Note that the empty final row indicates no changepoints.
pen.value.full(out) # gives associated penalty transition points
# CROPS does not give an optimal set of changepoints thus we may wish to explore further
plot(out,diagnostic=TRUE)
# looks like the segmentation with 3 changepoints, 50,100,150 is the most appropriate
plot(out,ncpts=3)

# Example multiple datasets where the first row has multiple changes in variance and the second row
#has no change in variance
set.seed(10)
x=c(rnorm(50,0,1),rnorm(50,0,10),rnorm(50,0,5),rnorm(50,0,1))
y=rnorm(200,0,1)
z=rbind(x,y)
cpt.var(z,penalty="Asymptotic",pen.value=0.01,method="SegNeigh",Q=5,class=FALSE) # returns list that
#has two elements, the first has 3 changes in variance at 50,100,149 and the second has no changes
#in variance
ans=cpt.var(z,penalty="Asymptotic",pen.value=0.01,method="PELT")
cpts(ans[[1]]) # same results as for the SegNeigh method.
cpts(ans[[2]]) # same results as for the SegNeigh method.

Generic Function - cpts

Description

Generic function

Usage

cpts(object,...)

Arguments

Details

Generic function.

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

cpts-methods

Examples

x=new("cpt") # new cpt object
cpts(x) # retrieves the cpts slot from x

~~ Methods for Function cpts<- ~~

Description

~~ Methods for function cpts<- ~~

Methods

signature(x = "cpt")

Assigns the value following <- to the cpts slot in x, from version 1.0 this no longer requires the last entry to be the length of the dataset.

signature(x = "cpt.reg")

Assigns the value following <- to the cpts slot in x, from version 1.0 this no longer requires the last entry to be the length of the dataset.

signature(x = "cpt.range")

Assigns the value following <- to the cpts slot in x, from version 1.0 this no longer requires the last entry to be the length of the dataset.

Generic Function - cpts<-

Description

Generic function

Usage

cpts(object)<-value

Arguments

Details

Generic function.

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

cpts<–methods

Examples

x=new("cpt") # new cpt object
cpts(x)<-10 # replaces the vector of changepoint in object x with 10

~~ Methods for Function cpts ~~

Description

~~ Methods for function cpts ~~

Methods

signature(object = "cpt")

Retrieves cpts slot from an object of class cpt, from version 1.0 this no longer prints the length of the dataset.

signature(object = "cpt.reg")

Retrieves cpts slot from an object of class cpt.reg, from version 1.0 this no longer prints the length of the dataset.

signature(object = "cpt.range",ncpts=NA)

Retrieves the row in the cpts.full slot from an object of class cpt.range that has length ncpts, from version 1.0 this no longer prints the length of the dataset.

Generic Function - cpts.full

Description

Generic function

Usage

cpts.full(object)

Arguments

Details

Generic function.

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

cpts.full-methods

Examples

x=new("cpt.range") # new cpt.range object
cpts.full(x) # retrieves the cpts.full slot from x

~~ Methods for Function cpts.full<- ~~

Description

~~ Methods for function cpts.full<- ~~

Methods

signature(x = "cpt.range")

Assigns the value following <- to the cpts.full slot in x. This is required to be a matrix.

Generic Function - cpts.full<-

Description

Generic function

Usage

cpts.full(object)<-value

Arguments

Details

Generic function.

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

cpts.full<–methods

Examples

x=new("cpt.range") # new cpt.range object
cpts.full(x)<-matrix(c(10,20,10,NA),nrow=2,byrow=TRUE) 
# replaces the vector of changepoint in object x with the given matrix

~~ Methods for Function cpts.full ~~

Description

~~ Methods for function cpts.full ~~

Methods

signature(object = "cpt.range")

Retrieves cpts.full slot from an object of class cpt.range.

Generic Function - cpts.ts

Description

Generic function

Usage

cpts.ts(object)

Arguments

Details

Generic function.

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

cpts.ts-methods

Examples

x=new("cpt") # new cpt object
cpts.ts(x) # retrieves the cpts slot from x but unlike cpts, displays the "date" index rather than
#the position within the vector

~~ Methods for Function cpts.ts ~~

Description

~~ Methods for function cpts.ts ~~

Methods

signature(object = "cpt")

Retrieves cpts slot from an object of class cpt, from version 1.0 this no longer prints the length of the dataset. Contrary to the cpts function, cpts.ts displays the changepoints using the "date" index according to the start and frequency of the time series data.set(object)

signature(object = "cpt.reg")

Retrieves cpts slot from an object of class cpt.reg, from version 1.0 this no longer prints the length of the dataset. Contrary to the cpts function, cpts.ts displays the changepoints using the "date" index according to the start and frequency of the time series data.set(object)

Generic Function - cpttype

Description

Generic function

Usage

cpttype(object)

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

cpttype-methods

Examples

x=new("cpt") # new cpt object
cpttype(x) # retrieves the cpttype slot from x

~~ Methods for Function cpttype<- ~~

Description

~~ Methods for function cpttype<- ~~

Methods

signature(x = "cpt")

Assigns the value following <- to the cpttype slot in x

signature(x = "cpt.reg")

Assigns the value following <- to the cpttype slot in x

Generic Function - cpttype

Description

Generic function

Usage

cpttype(object)<-value

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

cpttype<–methods

Examples

x=new("cpt") # new cpt object
cpttype(x)<-"mean" # replaces the existing cpttype in object x with "mean"

~~ Methods for Function cpttype ~~

Description

~~ Methods for function cpttype ~~

Methods

signature(object = "cpt")

Retrieves cpttype slot from an object of class cpt

signature(object = "cpt.reg")

Retrieves cpttype slot from an object of class cpt.reg

Generic Function - data.set

Description

Generic function

Usage

data.set(object)

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

data.set-methods

Examples

x=new("cpt") # new cpt object
data.set(x) # retrieves the data.set slot from x

~~ Methods for Function data.set<- ~~

Description

~~ Methods for function data.set<- ~~

Methods

signature(x = "cpt")

Assigns the value following <- to the data.set slot in x

signature(x = "cpt.reg")

Assigns the value following <- to the data.set slot in x

Generic Function - data.set<-

Description

Generic function

Usage

data.set(object)<-value

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

data.set<–methods

Examples

x=new("cpt") # new cpt object
data.set(x)<-c(1,2,3,4,5) # replaces the existing data.set slot in x with c(1,2,3,4,5)

~~ Methods for Function data.set ~~

Description

~~ Methods for function data.set ~~

Methods

signature(object = "cpt")

Retrieves the data.set slot from objects with class cpt

signature(object = "cpt.reg")

Retrieves the data.set slot from objects with class cpt.reg

Generic Function - data.set.ts

Description

Generic function

Usage

data.set.ts(object)

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

data.set.ts-methods

Examples

x=new("cpt") # new cpt object
data.set.ts(x) # retrieves the data.set slot from x.  This is a ts object.

~~ Methods for Function data.set.ts ~~

Description

~~ Methods for function data.set.ts ~~

Methods

signature(object = "cpt")

Retrieves the data.set slot from objects with class cpt. This returns a ts class object.

signature(object = "cpt.reg")

Retrieves the data.set slot from objects with class cpt.reg. This returns a ts class object.

Decision Function - Only intended for developer use.

Description

Uses the function parameters to decide if a proposed changepoint is a true changepoint or due to random variability. Test is conducted using the user specified penalty.

This function is called by cpt.mean, cpt.var and cpt.meanvar when method="AMOC". This is not intended for use by regular users of the package. It is exported for developers to call directly for speed increases or to fit alternative cost functions.

WARNING: No checks on arguments are performed!

Usage

decision(tau,null,alt=NA,penalty="MBIC",n=0,diffparam=1,pen.value=0)

Arguments

Details

This function is used to test whether tau is a true changepoint or not. This test uses the null-alternative as the test statistic and performs the test where the null hypothesis is no change point and the alternative hypothesis is a single changepoint at tau. The test is (null-alt)>=penalty, if TRUE then the changepoint is deemed a true changepoint, if FALSE then n (length of data) is returned.

If the test statistic is already known then it replaces the null value and the alternative is not required (default NA). In this case the test is null>=penalty, if TRUE then the changepoint is deemed a true changepoint, if FALSE then n (length of data) is returned.

This function is exported for developer use only. It does not perform any checks on inputs and is included for convenience and speed for those who are developing their own cost functions.

Value

A list is returned with two elements, cpt and pen.

Author(s)

Rebecca Killick

References

SIC/BIC: Schwarz, G. (1978) Estimating the Dimension of a Model, The Annals of Statistics 6(2), 461–464

MBIC: Zhang, N. R. and Siegmund, D. O. (2007) A Modified Bayes Information Criterion with Applications to the Analysis of Comparative Genomic Hybridization Data. Biometrics 63, 22-32.

AIC: Akaike, H. (1974) A new look at the statistical model identification, Automatic Control, IEEE Transactions on 19(6), 716–723

Hannan-Quinn: Hannan, E. J. and B. G. Quinn (1979) The Determination of the Order of an Autoregression, Journal of the Royal Statistical Society, B 41, 190–195

See Also

cpt.mean,cpt.var,cpt.meanvar

Examples

# Example of finding a change
out=c(100,765.1905,435.6529) # tau, null, alt
decision(out[1],out[2],out[3],penalty="SIC",n=200,diffparam=1) # returns 100 as a true changepoint

# Example of no change found
out=c(53,-22.47768,-24.39894) # tau, null, alt
decision(out[1],out[2],out[3],penalty="Manual",n=200,diffparam=1,pen.value="2*log(n)")

Generic Function - distribution

Description

Generic function

Usage

distribution(object)

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

distribution-methods

Examples

x=new("cpt") # new cpt object
distribution(x) # retrieves the distribution slot from x

~~ Methods for Function distribution<- ~~

Description

~~ Methods for function distribution<- ~~

Methods

signature(x = "cpt")

Assigns the value following <- to the distribution slot in x

signature(x = "cpt.reg")

Assigns the value following <- to the distribution slot in x

Generic Function - distribution<-

Description

Generic function

Usage

distribution(object)<-value

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

distribution<–methods

Examples

x=new("cpt") # new cpt object
distribution(x)<-"normal" # replaces the current distribution slot of x with "normal"

~~ Methods for Function distribution ~~

Description

~~ Methods for function distribution ~~

Methods

signature(object = "cpt")

Retrieves distribution slot from an object of class cpt

signature(object = "cpt.reg")

Retrieves distribution slot from an object of class cpt.reg

~~ Methods for Function fitted in Package ‘stats’ ~~

Description

~~ Methods for function fitted in Package ‘stats’ ~~

Methods

signature(x = "ANY")

Generic fitted function, see stats package description using ?fitted

signature(x = "cpt")

Returns the fitted values for the model fit to x. Adapts to the specific model type.

signature(x = "cpt.range")

As for the cpt objects except for one optional arguments, ncpts. The ncpts option allows you to specify the fitted values for ncpts changepoints in, i.e. the optimal may be specified as 10 changes but you want to get the fitted values for the segmentation with 5 changes (provided a segmentation with 5 changes is listed in cpts.full(x).

signature(x = "cpt.reg")

Returns the fitted values for the model fit to x. Adapts to the specific model type.

FTSE 100 Daily Returns: 2nd April 1984 – 13th September 2012

Description

This dataset gives the daily returns (c_{t+1}/c_t -1) of the UK FTSE 100 index from 2nd April 1984 until the 13th September 2012.

Usage

ftse100

Format

A matrix of dimension 7187 x 2 where the first column is the Date and the second column is the Daily Return.

Source

Yahoo! Finance

Generic Function - likelihood

Description

Generic function to calculate the likelihood

Usage

likelihood(object)

Arguments

Details

Generic Function to calculate the likelihood.

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

likelihood-methods, cpt.mean,cpt.var,cpt.meanvar

Examples

set.seed(1)
x=c(rnorm(50,0,1),rnorm(50,0,10),rnorm(50,0,5),rnorm(50,0,1))
out=cpt.var(x,penalty="Manual",pen.value="2*log(n)",method="BinSeg",Q=5)
likelihood(out) # returns the raw scaled negative likelihood (925.8085) and the scaled negative
#likelihood + penalty (957.5984)

~~ Methods for Function likelihood ~~

Description

~~ Methods for function likelihood ~~

Methods

signature(object = "cpt")

Returns the likelihood of the data with the fitted changepoints, two values are returned, the raw scaled negative likelihood and the scaled negative likelihood + penalty. Only valid for cpttype="mean","variance" or "mean and variance".

~~ Methods for Function logLik ~~

Description

~~ Methods for function logLik ~~

Methods

signature(object = "cpt")

Returns the -2*log-likelihood of the data with the fitted changepoints, two values are returned, the raw twice negative log-likelihood and twice negative log-likelihood + penalty. Only valid for cpttype="mean","variance" or "mean and variance".

Examples

set.seed(1)
x=c(rnorm(50,0,1),rnorm(50,0,10),rnorm(50,0,5),rnorm(50,0,1))
out=cpt.var(x,penalty="Manual",pen.value="2*log(n)",method="BinSeg",Q=5)
logLik(out) # returns the raw scaled negative likelihood (925.8085) and the scaled negative
#likelihood + penalty (957.5984)

Generic Function - method

Description

Generic function

Usage

method(object)

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

method-methods

Examples

x=new("cpt") # new cpt object
method(x) # retrieves the method slot from x

~~ Methods for Function method<- ~~

Description

~~ Methods for function method<- ~~

Methods

signature(x = "cpt")

Assigns the value following <- to the method slot in x

signature(x = "cpt.reg")

Assigns the value following <- to the method slot in x

Generic Function - method<-

Description

Generic function

Usage

method(object)<-value

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

method<–methods

Examples

x=new("cpt") # new cpt object
method(x)<-"mean" # replaces the existing method slot in x with "mean"

~~ Methods for Function method ~~

Description

~~ Methods for function method ~~

Methods

signature(object = "cpt")

Retrieves method slot from an object of class cpt

signature(object = "cpt.reg")

Retrieves method slot from an object of class cpt.reg

Generic Function - minseglen

Description

Generic function

Usage

minseglen(object)

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

minseglen-methods

Examples

x=new("cpt") # new cpt object
minseglen(x) # retrieves the minseglen slot from x

~~ Methods for Function minseglen<- ~~

Description

~~ Methods for function minseglen<- ~~

Methods

signature(x = "cpt")

Assigns the value following <- to the minseglen slot in x

signature(x = "cpt.reg")

Assigns the value following <- to the minseglen slot in x

signature(x = "cpt.range")

Assigns the value following <- to the minseglen slot in x

Generic Function - minseglen<-

Description

Generic function

Usage

minseglen(object)<-value

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

minseglen<–methods

Examples

x=new("cpt") # new cpt object
minseglen(x)<-5 # replaces the existing minseglen slot in x with 5

~~ Methods for Function minseglen ~~

Description

~~ Methods for function minseglen ~~

Methods

signature(object = "cpt")

Retrieves minseglen slot from an object of class cpt

signature(object = "cpt.range")

Retrieves minseglen slot from an object of class cpt.range

signature(object = "cpt.reg")

Retrieves minseglen slot from an object of class cpt.reg

Generic Function - ncpts

Description

Generic function

Usage

ncpts(object)

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

ncpts-methods

Examples

x=new("cpt") # new cpt object
ncpts(x) # returns the number of changepoints (i.e. length of the cpts slot in x minus 1)

~~ Methods for Function ncpts ~~

Description

~~ Methods for function ncpts ~~

Methods

signature(object = "cpt")

Returns the number of changepoints (i.e. length of the cpts slot minus 1) from an object of class cpt

signature(object = "cpt.reg")

Returns the number of changepoints (i.e. length of the cpts slot minus 1) from an object of class cpt.reg

Generic Function - ncpts.max

Description

Generic function

Usage

ncpts.max(object)

Arguments

Details

Generic function.

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

ncpts.max-methods

Examples

x=new("cpt") # new cpt object
ncpts.max(x) # retrieves the ncpts.max slot from x

~~ Methods for Function ncpts.max<- ~~

Description

~~ Methods for function ncpts.max<- ~~

Methods

signature(x = "cpt")

Assigns the value following <- to the ncpts.max slot in x

signature(x = "cpt.reg")

Assigns the value following <- to the ncpts.max slot in x

Generic Function - ncpts.max<-

Description

Generic function

Usage

ncpts.max(object)<-value

Arguments

Details

Generic function.

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

ncpts.max<–methods

Examples

x=new("cpt") # new cpt object
ncpts.max(x)<-10 # replaces the vector of changepoint in object x with 10

~~ Methods for Function ncpts.max ~~

Description

~~ Methods for function ncpts.max ~~

Methods

signature(object = "cpt")

Retrieves ncpts.max slot from an object of class cpt

signature(object = "cpt.reg")

Retrieves ncpts.max slot from an object of class cpt.reg

Generic Function - nseg

Description

Generic function

Usage

nseg(object,...)

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

nseg-methods

Examples

x=new("cpt") # new cpt object
nseg(x) # returns the number of segments (i.e. length of the cpts slot)

~~ Methods for Function nseg ~~

Description

~~ Methods for function nseg ~~

Methods

signature(object = "cpt")

Returns the number of segments (i.e. length of the cpts slot) from an object of class cpt

signature(object = "cpt.range",ncpts=NA)

Returns the number of segments from an object of class cpt.range. If ncpts is not specified, this the length of the cpts slot of the cpt.range object. If ncpts is specified, this is (trivially) ncpts+1.

signature(object = "cpt.reg")

Returns the number of segments (i.e. length of the cpts slot) from an object of class cpt.reg

Generic Function - param

Description

Generic function that returns parameter estimates.

Usage

param(object,...)

Arguments

Details

Generic Function that returns parameter estimates

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

param-methods,cpt.mean,cpt.var,cpt.meanvar

Examples

set.seed(1)
x=c(rnorm(100,0,1),rnorm(100,0,10))
ans=cpt.var(x,penalty="Asymptotic",pen.value=0.01,method="AMOC",param.estimates=FALSE)
# if estimates were not requested in the analysis then they can be created at a later stage if
#required
ans=param(ans) # fills the param.est slot with the parameter estimes.
param.est(ans) # variance is 0.8067621

~~ Methods for Function param ~~

Description

~~ Methods for function param ~~

Methods

signature(object = "cpt")

Replaces the param.value slot in object with the parameter estimates that are appropriate for the changepoint type (cpttype slot). If the Gamma test statistic is used then the shape parameter is required as a variable.

signature(object = "cpt.range")

Returns a new (blank) cpt.range object where the param.value slot contains the parameter estimates for a segmentation with the ncpts specified number of changepoints. This is also tailored to the changepoint type (cpttype slot) of the original object. If the Gamma test statistic is used then the shape parameter is required as a variable. An example of use is given in the cpt.mean help file.

signature(object = "cpt.reg")

Replaces the param.value slot in object with the parameter estimates that are appropriate for the changepoint test statistic (test.stat slot).

Generic Function - param.est

Description

Generic function

Usage

param.est(object)

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

param.est-methods

Examples

x=new("cpt") # new cpt object
param.est(x) # retrieves the param.est slot from x

~~ Methods for Function param.est<- ~~

Description

~~ Methods for function param.est<- ~~

Methods

signature(x = "cpt")

Assigns the value following <- to the param.est slot in x

signature(x = "cpt.reg")

Assigns the value following <- to the param.est slot in x

Generic Function - param.est<-

Description

Generic function

Usage

param.est(object)<-value

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

param.est<–methods

Examples

x=new("cpt") # new cpt object
param.est(x)<-list(mean=0) # replaces the current param.est list in x with list(mean=0)

~~ Methods for Function param.est ~~

Description

~~ Methods for function param.est ~~

Methods

signature(object = "cpt")

Retrieves param.est slot from an object of class cpt

signature(object = "cpt.reg")

Retrieves param.est slot from an object of class cpt.reg

Generic Function - pen.type

Description

Generic function

Usage

pen.type(object)

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

pen.type-methods

Examples

x=new("cpt") # new cpt object
pen.type(x) # retrieves the pen.type slot from x

~~ Methods for Function pen.type<- ~~

Description

~~ Methods for function pen.type<- ~~

Methods

signature(x = "cpt")

Assigns the value following <- to the pen.type slot in x

signature(x = "cpt.reg")

Assigns the value following <- to the pen.type slot in x

Generic Function - pen.type<-

Description

Generic function

Usage

pen.type(object)<-value

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

pen.type<–methods

Examples

x=new("cpt") # new cpt object
pen.type(x)<-"SIC" # replaces the existing pen.type slot in x with "SIC"

~~ Methods for Function pen.type ~~

Description

~~ Methods for function pen.type ~~

Methods

signature(object = "cpt")

Retrieves pen.type slot from an object of class cpt

signature(object = "cpt.reg")

Retrieves pen.type slot from an object of class cpt.reg

Generic Function - pen.value

Description

Generic function

Usage

pen.value(object)

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

pen.value-methods

Examples

x=new("cpt") # new cpt object
pen.value(x) # retrieves the pen.value slot from x

~~ Methods for Function pen.value<- ~~

Description

~~ Methods for function pen.value<- ~~

Methods

signature(x = "cpt")

Assigns the value following <- to the pen.value slot in x

signature(x = "cpt.reg")

Assigns the value following <- to the pen.value slot in x

Generic Function - pen.value

Description

Generic function

Usage

pen.value(object)<-value

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

pen.value<–methods

Examples

x=new("cpt") # new cpt object
pen.value(x)<-5 # replaces the existing pen.value slot in x with 5

~~ Methods for Function pen.value ~~

Description

~~ Methods for function pen.value ~~

Methods

signature(object = "cpt")

Retrieves pen.value slot from an object of class cpt

signature(object = "cpt.reg")

Retrieves pen.value slot from an object of class cpt.reg

Generic Function - pen.value.full

Description

Generic function

Usage

pen.value.full(object)

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

pen.value.full-methods

Examples

x=new("cpt.range") # new cpt.range object
pen.value.full(x) # retrieves the pen.value.full slot from x

~~ Methods for Function pen.value.full<- ~~

Description

~~ Methods for function pen.value.full<- ~~

Methods

signature(x = "cpt.range")

Assigns the value following <- to the pen.value.full slot in x

Generic Function - pen.value.full<-

Description

Generic function

Usage

pen.value.full(object)<-value

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

pen.value.full<–methods

Examples

x=new("cpt.range") # new cpt.range object
pen.value.full(x)<-5 # replaces the existing pen.value.full slot in x with 5

~~ Methods for Function pen.value.full ~~

Description

~~ Methods for function pen.value.full ~~

Methods

signature(object = "cpt.range")

Retrieves pen.value.full slot from an object of class cpt.range.

Penalty Decision Function - Only intended for developer use.

Description

Evaluates the arguments to give a numeric value for the penalty.

This function is called by cpt.mean, cpt.var and cpt.meanvar. This is not intended for use by regular users of the package. It is exported for developers to call directly for speed increases or to fit alternative cost functions.

WARNING: No checks on arguments are performed!

Usage

penalty_decision(penalty, pen.value, n, diffparam, asymcheck, method)

Arguments

Details

This function takes the text string input and converts it to a numerical value for the specific length of data specified by n.

This function is exported for developer use only. It does not perform any checks on inputs and is included for convenience and speed for those who are developing their own cost functions.

Value

The numeric value of the penalty.

Author(s)

Rebecca Killick

References

SIC/BIC: Schwarz, G. (1978) Estimating the Dimension of a Model, The Annals of Statistics 6(2), 461–464

MBIC: Zhang, N. R. and Siegmund, D. O. (2007) A Modified Bayes Information Criterion with Applications to the Analysis of Comparative Genomic Hybridization Data. Biometrics 63, 22-32.

AIC: Akaike, H. (1974) A new look at the statistical model identification, Automatic Control, IEEE Transactions on 19(6), 716–723

Hannan-Quinn: Hannan, E. J. and B. G. Quinn (1979) The Determination of the Order of an Autoregression, Journal of the Royal Statistical Society, B 41, 190–195

See Also

cpt.mean,cpt.var,cpt.meanvar

Examples

# Example of finding a change
out=c(100,765.1905,435.6529) # tau, null, alt
decision(out[1],out[2],out[3],penalty="SIC",n=200,diffparam=1) # returns 100 as a true changepoint

# Example of no change found
out=c(53,-22.47768,-24.39894) # tau, null, alt
decision(out[1],out[2],out[3],penalty="Manual",n=200,diffparam=1,pen.value="2*log(n)")

~~ Methods for Function plot in Package ‘graphics’ ~~

Description

~~ Methods for function plot in Package ‘graphics’ ~~

Methods

signature(x = "ANY")

Generic plot function, see graphics package description using ?plot

signature(x = "cpt")

Plots the data and identifies the changepoints using vertical lines (change in variance), horizontal lines (change in mean). Optional arguments to control the lines: cpt.col equivilent to col to change the colour of the changepoint line; cpt.width equivilent to lwd to change the width of the changepoint line; cpt.style equivilent to lty to change the style of the line.

signature(x = "cpt.range")

As for the cpt objects except for two optional arguments, ncpts and diagnostic. The ncpts option allows you to specify a plot of the segmentation with ncpts changepoints in, i.e. the optimal may be specified as 10 changes but you want to plot the segmentation with 5 changes (provided a segmentation with 5 changes is listed in cpts.full(x). The diagnostic option when set to TRUE plots the number of changepoints in each segmentation against the penalty values that give that number of changepoints. This can aide the decision on the number of changepoints as when a true changepoint is added the cost decreases considerably so it creates a stable region where several penalty values give the same number of changepoints, but when a changepoint due to noise is added the change in cost is small and so a small change in penalty value can vary the number of changes a lot. This is akin to a scree plot in principal component analysis. The idea is that someone may choose to create a plot using diagnostic=TRUE, identify the appropriate number of changes and then replot using ncpts to visualize that segmentation.

signature(x = "cpt.reg")

Plots the combined regressors (model fit) against the response and identifies the changepoints using vertical lines. Optional arguments to control the lines: cpt.col equivilent to col to change the colour of the changepoint line; cpt.width equivilent to lwd to change the width of the changepoint line; cpt.style equivilent to lty to change the style of the line.

~~ Methods for Function residuals in Package ‘stats’ ~~

Description

~~ Methods for function residuals in Package ‘stats’ ~~

Methods

signature(x = "ANY")

Generic residuals function, see stats package description using ?residuals

signature(x = "cpt")

Returns the residuals values from the model fit to x. Adapts to the specific model type.

signature(x = "cpt.range")

As for the cpt objects except for one optional arguments, ncpts. The ncpts option allows you to specify the residuals values for ncpts changepoints in, i.e. the optimal may be specified as 10 changes but you want to get the residuals values for the segmentation with 5 changes (provided a segmentation with 5 changes is listed in cpts.full(x).

signature(x = "cpt.reg")

Returns the residuals values from the model fit to x. Adapts to the specific model type.

Generic Function - seg.len

Description

Generic function

Usage

seg.len(object,...)

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

seg.len-methods

Examples

x=new("cpt") # new cpt object
seg.len(x) # returns the length of each segment in the data (i.e. no. of obs between changepoints)

~~ Methods for Function seg.len ~~

Description

~~ Methods for function seg.len ~~

Methods

signature(object = "cpt")

Returns the length of segments from an object of class cpt, i.e. the number of observations between changepoints

signature(object = "cpt.range",ncpts=NA)

Returns the length of segments from an object of class cpt.range, i.e. the number of observations between changepoints. If ncpts is not specified, this is called on the cpts slot of the cpt.range object. If ncpts is specified, this is called on the cpts.full slot and calculated this for the specific row that gives ncpts.

signature(object = "cpt.reg")

Returns the length of segments from an object of class cpt.reg, i.e. the number of observations between changepoints

~~ Methods for Function print in Package ‘base’ ~~

Description

~~ Methods for function show in Package ‘base’ ~~

Methods

signature(x = "ANY")

Generic print function, see base package description using ?print

signature(x = "cpt")

Prints out information contained within the object x including a summary

signature(x = "cpt.reg")

Prints out information contained within the object x including a summary

~~ Methods for Function summary in Package ‘base’ ~~

Description

~~ Methods for function summary in Package ‘base’ ~~

Methods

signature(object = "ANY")

Generic summary function, see base package description using ?summary

signature(object = "cpt")

Prints out a summary of the object to the terminal.

signature(object = "cpt.range")

Prints out a summary of the object to the terminal.

signature(object = "cpt.reg")

Prints out a summary of the object to the terminal.

Generic Function - test.stat

Description

Generic function

Usage

test.stat(object)

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

test.stat-methods

Examples

x=new("cpt") # new cpt object
test.stat(x) # retrieves the test.stat slot from x

~~ Methods for Function test.stat<- ~~

Description

~~ Methods for function test.stat<- ~~

Methods

signature(x = "cpt")

Assigns the value following <- to the test.stat slot in x

signature(x = "cpt.reg")

Assigns the value following <- to the test.stat slot in x

Generic Function - test.stat<-

Description

Generic function

Usage

test.stat(object)<-value

Arguments

Details

Generic Function

Value

Depends on the class of object, see individual methods

Author(s)

Rebecca Killick

See Also

test.stat<–methods

Examples

x=new("cpt") # new cpt object
test.stat(x)<-"normal" # replaces the current test.stat slot of x with "normal"

~~ Methods for Function test.stat ~~

Description

~~ Methods for function test.stat ~~

Methods

signature(object = "cpt")

Retrieves test.stat slot from an object of class cpt

signature(object = "cpt.reg")

Retrieves test.stat slot from an object of class cpt.reg

Wave data from buoy c44137

Description

This dataset gives the significant wave heights from buoy c44137 obtained from the Fisheries and Oceans Canada, East Scotian Slop. The data are taken at hourly intervals from January 2005 until September 2012.

Usage

wave.c44137

Format

A vector of length 63651.

Source

http://www.meds-sdmm.dfo-mpo.gc.ca/isdm-gdsi/waves-vagues/search-recherche/list-liste/data-donnees-eng.asp?medsid=C44137