Dicpt: Class methods for Dicpt Objects

Description

Common functions to handle "Dicpt" class results which store information about changepoints, both the individual library results and the majority vote for classifier fusion.

Usage

# S3 method for Dicpt
print(x, ...)
# S3 method for Dicpt
summary(object, ...)
# S3 method for Dicpt
mark(x, hist=NULL, opt=Diopt(), ...)
# S3 method for Dicpt
plot(x, opt=Diopt(), ...)

Value

The Dicpt list contains seven elements. Two describe the individual algorithms that have run and their results.

test: is a data frame with one row per library and detector combination. It contains four columns, "library" with the full changepoint library name, "detector" the function name and/or method and/or test statistic, "abbrev" an abbreviation of the detector used for plot labels, and "npt" the number of changepoints found. The number may be zero.
rawpts: is a list whose length is the same as the number of rows of test. Its elements are each a vector of points whose length matches the "npt" column, or NULL if the detector returned no points or if there were too many per the "maxfncpt" option or if the detector timed out or had some other error.

test will have 0 rows if no detectors were available, and rawpts

will be an empty list. Summarizing the arguments for this first step, the Dicpt list element

rawparam: is a list with elements "cptlibs" the specification of which libraries to use, "maxfncpt" the maximum fraction of the data that can be identified as changepoints, "ncpt" the conversion of maxfncpt to points, "timeout" the run time in seconds allowed for each detector, and "nx" the number of data points. cptlibs, maxfncpt, and timeout come from Diopt options.

To describe the fusion of the detectors the Dicpt list adds four elements.

libpts: is a list of the changepoints found by combining the results of each detector within a library. It has a length equal to the number of libraries that were run, the unique entries of the first column of the test data frame.
voting: is a boolean vector with the same length as libpts and TRUE if that library's points were counted in the voting or FALSE if not.
cpt: is a data frame with three columns that gives the final changepoint list. It has one row per changepoint. Column "pos" is the index of the changepoint in the original data. "val" is the data at the changepoint. "nvote" gives the number of votes the point received.
cptparam: is a list with elements "qvote" the pair of quantile bounds on the library point count used to discard libraries with unusually few or many changepoints, "qpts" the pair translated into an absolute count, "sep" the minimum absolute separation in data points between changepoints, "fsep" the minimum separation as a fraction of the data length, "libsep" the separation while merging library variants, "near" the final minimum separation in data points, and "minvote" the minimum number of votes a point must receive to appear in the final result.

Dimodal adds one column to the cpt data frame. It shifts the changepoints to the original data grid, without the loss of the initial index.

x: the location of the peak in the original data, using the mid-distribution function

This can be done by calling the utility function shiftID.place on the find.cpt result. Dimodal also adds an attribute "source" with value "Di" to show the changepoints lie in the raw spacing.

The methods return the Dicpt object invisibly.

Arguments

x: an object of class "Dicpt"
object: an object of class "Dicpt"
hist: the histogram being marked or NULL for a low-pass or interval spacing graph
opt: local version of options for color scheme
...: extra arguments, ignored for all methods

Details

The "Dicpt" class stores several different items in a list. The analysis in find.cpt takes two steps, first running the spacing without any filtering through all changepoint detectors available on the system and then combining the results into a master list by majority vote over all libraries.

The plot needs a tall window. It shows the changepoints from each variant within a library as dots, labelled on the right side, and the roll-up for each detector as crosses, labelled on the left. The final changepoint list is in the first row at top, and vertical bands show the region within which library points match the final. The plot uses the "palette" option to set its colors.

Changepoints are marked by ticks along the upper edge of the current graph, using option color "colID.cpt" in the palette. Marking the histogram assumes that Dimodal has added the "x" column to the cpt data frame.

The print method gives a table with the changepoints, the spacing at that index and corresponding raw data value, and the number of votes. It also lists the libraries that take part in the voting. The summary gives just the position of the changepoint and the library list. These methods use option "digits" to control the number of significant digits in the table. If the option is set to zero then the usual options()$digits is used.

Examples

Run this code

 ## Not run because detectors may not be available.
 if (FALSE)  m <- Dimodal(faithful$eruptions, Diopt.local(analysis='cpt')) 
 if (FALSE)  m$cpt 
 if (FALSE)  summary(m$cpt) 
 ## You want a tall plot window for this.
 if (FALSE)  dev.new(width=4, height=12) ; plot(m$cpt)