Dipeak: Class methods for Dipeak Objects

Description

Common functions to handle "Dipeak" class results, which store information about local extrema and their probability.

Usage

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

Value

The basic data frame returned from find.peaks includes the columns

pos: index in data of local extremum
ismax: TRUE if a local maximum, FALSE if a minimum
valsd: data at extremum, standardized by sd(x)
lht: difference in valsd between maximum and minimum to its left, NA if no minimum or if a minimum
rht: difference in valsd between maximum and minimum to its right, NA if no minimum or if a minimum
lminID: position/index of minimum to the left, NA if not a valid maximum
rminID: position/index of minimum to the right, NA if not a valid maximum
lsuppID: left index of support, NA if not a valid maximum
rsuppID: right index (incl.) of support, NA if not a valid maximum

The indices are located in the data passed to the detector. Valid maxima have minima on both sides. There will always be two extrema at the first and last point.

Dimodal adds several columns. It shifts all indices to the original data, compensating for the invalid points skipped during low-pass filtering or interval spacing. Mapping indices back to the raw data and summarizing the tests, it adds

x: the location of the peak in the original data
ppeak: the best probability of all tests run or NA if none or if not a maximum with minima to both sides
naccept: number of tests passing their acceptance level, 0 if none or ppeak is NA

x can be generated by calling the utility function shiftID.place on the find.peaks result. Dimodal also adds an attribute "source" with value "LP" or "Diw" depending on the filter used.

For low-pass testing the results may include

pht: the probability of the feature per the height model, using the larger of lht and rht
hexcur: the feature height used for the excursion test
pexcur: the probability of the peak using bootstrap sampling of the difference of the low-pass spacing

For interval spacing tests the results may include those based on runs in its signed difference, between the bounding minima

nrun: the number of runs
pnrun: the probability of nrun using the Kaplansky-Riordan test
runlen: the length of the longest run
prunlen: the probability of runlen using a Markov chain model of the entire data sample
runht: the feature height in the signed difference
prunht: the probability of the peak with height runht using a permutation test of the runs
hexcur: the feature height in the interval spacing between minima
pexcur: the probability of the peak with height hexcur using bootstrap sampling from the interval spacing of the whole data

The methods return the object, invisibly.

Arguments

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

Details

A "Dipeak" object is a data frame that describes local extrema, including their position in the low-pass or interval spacing and equivalent raw value, their height and width, and any tests that have run to judge the significance of the feature. The basic information comes from the find.peaks detector, and the Dimodal analysis adds the feature analysis. The class inherits from "data.frame".

The print method shows the position (index) and raw value of each maximum, the minimum to either side, and if different the support. It then has two tables with the statistic (test value) and probability for any tests that have been run, as well as the acceptance levels. These come from the options "alpha.ht" for the model test, "alpha.pkexcur.lp" and "alpha.pkexcur.diw" for the excursion test, and "alpha.nrun" and "alpha.runlen" and "alpha.runht" for the runs tests. If the option "mark.alpha" is TRUE then probabilities at or below the acceptance level are underlined. Set the option FALSE if your terminal does not support ANSI escape codes, or see the crayon package for the extensive tests needed to determine this automatically. These options are set at the global level and cannot be overridden for a single call to print. The pass column after the overall peak probability will contain the number of accepted/passing tests, if any. Raw values and statistics are printed with option "digits" significant digits. If the option is set to zero then the standard options()$digits is used.

The summary method lists the position and raw value of each maximum, the overall probability or best result from all tests, and a list of the tests that pass per the Diopt acceptance levels.

Peaks and minima are marked in a spacing graph by vertical lines. Maxima are drawn with dashes and are made thick if the peak passes any test. Minima are drawn with dotted lines. The marks are colored per the option "colID.peak" of the current palette. Histogram annotations include only lines for peaks, drawn thick if significant. They run from the quantile axis on the right to the distribution function curve, then down to the data value. Marking the histogram assumes that Dimodal has added the x column with the peak's original data value and has shifted positions.

select.peaks is a utility function that extracts only those rows with valid peaks, which have a minima to each side.

Examples

Run this code

## We override the analysis option to avoid changepoints,
## which may not be available.
m <- Dimodal(faithful$eruptions, Diopt.local(analysis=c('diw','lp'), diw.window=16))
summary(m$lp.peaks)
m$diw.peaks