Selection of the Modes of Time-Series Records

Selects the modes of the tables of decomposeTSL with a declared criterion: explicit mode indices, a minimum energy fraction or a frequency band, to keep the modes that meet it or to remove them.

Usage

selectModesTSL(decomposition, metrics, criterion)

Arguments

decomposition

The list of tables of decomposeTSL, as for measureModesTSL; its metadata cannot take the names mode, criterion or retained. It is not modified.

metrics

The table metrics of measureModesTSL for the same decomposition: one row for each of its modes, each with an energyFraction. It is not modified.

criterion

A list with rule, exactly the fields of that rule, and action, "keep" or "remove". The rules are

"modes"

with modes, a table with mode, whole numbers from 1, and key columns of decomposition. Each row names the mode of that index of every series whose keys it matches, so the indices go by group (the by columns and ID) or by series (with OCID); each row names a mode of the decomposition.

"energyFraction"

with minimum, a finite number not below zero: a mode meets it when its energyFraction is not below minimum.

"band"

with fMin and fMax in Hz, \(0 \le f_{\min} \le f_{\max}\): a mode meets the closed band when \(f_{\min} \le\) frequency \(\le f_{\max}\). A mode without frequency, of zero energy, is in no band.

"keep" retains the modes that meet the criterion and "remove" the others.

Details

The criterion is supplied by the caller. Mode indices, energy fractions and centroid frequencies do not by themselves identify uncontaminated physical components. Equal mode indices in independently decomposed series need not represent the same physical contribution.

The band compares frequency alone, whereas the rules keep.Fo and remove.Fo of gmsp 0.8.0 require the interval \([F_o - BW, F_o + BW]\) inside the band.

Value

A named list of two data.table tables:

modes

The rows of modes of decomposition of the retained modes, in its order.

selection

Every mode of decomposition with its keys, mode, criterion and retained, in the order of the decomposition. criterion is the criterion as declared text: "<action> listed modes", "<action> energyFraction >= <minimum>" or "<action> frequency in [<fMin>, <fMax>] Hz", such as "keep frequency in [2, 15] Hz".

See also

measureModesTSL, reconstructTSL, decomposeTSL

Examples

Time <- seq(0, 9, length.out = 3000)
Signal <- sin(pi * Time) + sin(2 * pi * Time) + sin(6 * pi * Time) +
    0.5 * Time
# The same series under three IDs and three components.
TSL <- data.table::rbindlist(lapply(c("AT", "VT", "DT"), function(id) {
    data.table::rbindlist(lapply(c("H1", "H2", "UP"), function(ocid) {
        data.table::data.table(ID = id, OCID = ocid, t = Time, s = Signal)
    }))
}))
Sifting <- list(stopRule = "doubleThreshold")
Decomposition <- decomposeTSL(TSL, method = "decomposeEMD",
                              control = list(sifting = Sifting),
                              by = character())
Metrics <- measureModesTSL(Decomposition)$metrics
# Keep the modes whose frequency lies in [2, 15] Hz.
Band <- selectModesTSL(Decomposition, metrics = Metrics,
                       criterion = list(rule = "band", fMin = 2, fMax = 15,
                                        action = "keep"))
Band$selection[Band$selection$OCID == "H1" & Band$selection$ID == "AT", ]
#>      OCID     ID  mode                    criterion retained
#>    <char> <char> <int>                       <char>   <lgcl>
#> 1:     H1     AT     1 keep frequency in [2, 15] Hz     TRUE
#> 2:     H1     AT     2 keep frequency in [2, 15] Hz    FALSE
#> 3:     H1     AT     3 keep frequency in [2, 15] Hz    FALSE
# Remove the first mode of every series of the ID VT.
Listed <- data.frame(ID = "VT", mode = 1)
First <- selectModesTSL(Decomposition, metrics = Metrics,
                        criterion = list(rule = "modes", modes = Listed,
                                         action = "remove"))
table(First$selection$ID, First$selection$retained)
#>     
#>      FALSE TRUE
#>   AT     0    9
#>   DT     0    9
#>   VT     3    6