Dipeak: Class methods for Dipeak Objects

In Dimodal: Spacing Tests for Multi-Modality

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 class 'Dipeak'
print(x, ...)
## S3 method for class 'Dipeak'
summary(object, ...)
## S3 method for class 'Dipeak'
mark(x, hist=NULL, opt=Diopt(), ...)

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.

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.

See Also

find.peaks, Dimodal, Diopt, data.frame, select.peaks shiftID.place

Examples

m <- Dimodal(faithful$eruptions, Diopt.local(diw.window=16))
summary(m$lp.peaks)
m$diw.peaks

Dimodal documentation built on May 2, 2026, 1:06 a.m.