Diflat: Class methods for Diflat Objects

Description

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

Usage

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

Value

The basic data frame returned from find.flats contains the columns

src: the data point that triggered the flat, whose value is nearly centered in the height. This is a unique identifier for the feature.
stID: first data point in the flat
endID: last data point (incl.) in the flat
len: the length of the flat, or endID - stID + 1
srcval: the data value at src
ht: the height of the flat
htsd: the flat height standardized by the data's standard deviation, or ht / sd(x)

There is one row per flat, and the result is an empty data frame with zero rows if there are no flats. The indices of stID and endID are located in the data passed to the detector, which excludes the filter's NA columns.

Dimodal adds several columns. It shifts all indices to the original data, adjusting for the filter or interval size. Mapping indices back to the raw data, it adds

xst: the location of the start point in the original data
xend: the location of the end point (incl.) in the original data

This can be done by calling the utility function shiftID.place on the find.flats result. It also adds an attribute "source" with value "LP" or "Diw" depending on the filter used. As a summary of the results it adds

pflat: the best probability of all tests run, NA if no test results are available
naccept: number of tests passing their acceptance level, 0 if none or pflat is NA

For low-pass spacing the test results may include

plen: the probability of the feature per the length model
hexcur: the flat height used for the excursion test
pexcur: fraction of bootstrap samples from the low-pass spacing generating smaller heights than hexcur

depending on what has been run.

The interval spacing omits the length model test and may perform the excursion test on the difference of the interval spacing.

hexcur: the feature height used for the excursion test
pexcur: fraction of bootstrap samples from the interval spacing that generate smaller heights than hexcur

The methods return the object, invisibly.

Arguments

x: an object of class "Diflat"
object: an object of class "Diflat"
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

A "Diflat" object is a data frame that describes local flats, including their position or span in the low-pass or interval spacing and the equivalent raw values, their length, and any tests that have run to judge the significance of the feature. The basic information comes from the find.flats detector. The analysis in Dimodal moves the positions to the original data and adds the test results. The class inherits from "data.frame".

The print method shows the endpoints (incl.) of the flat and the raw value at each end, the statistics (test values) and separately the probability from each. The acceptance level of the tests are also given underneath. These come from the options "alpha.len", "alpha.ftexcur.lp", and "alpha.ftexcur.diw". 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; Diopt is called internally. The pass column after the overall flat 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 default options()$digits is used.

The summary method gives the endpoints, the overall probability or best result from all tests, and a list of the tests that pass per the Diopt acceptance levels.

Flats are marked in a spacing graph according to the "mark.flat" option, either as a box around the spacing or as a bar above or below it. The border or line is thicker if the flat passes any test at the option acceptance levels. When annotating a histogram the flats are always drawn as bars at the top of the graph. The marks are colored per the option "colID.flat" index of the current palette. Marking the histogram assumes that Dimodal has added the xst and xend columns.

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))
m$lp.flats
summary(m$diw.flats)