Metrics of the Modes of Time-Series Records

Measures every mode and every series of the tables of decomposeTSL, for any of its methods: frequency, bandwidth, energy, energy fraction and mean period of each mode, and number of modes and energy fractions of the remainder and the energy difference described by crossFraction for each series.

Usage

measureModesTSL(decomposition)

Arguments

decomposition: The list of tables of decomposeTSL, with signal, modes and at most one of residue and fitResidual. Its keys are the columns of signal other than t and s: the by columns, the other metadata, OCID and ID; they cannot take the names mode, frequency, bandwidth, energy, energyFraction, meanPeriod, modeCount, residueFraction or crossFraction. t and s are finite numbers and mode holds whole numbers from 1. Each series of signal has two samples or more at distinct times, and each mode and remainder of a series holds exactly the times of that series. decomposition is not modified.

Details

A mode $c$ of a series $x$ with $N$ samples uses the step $\Delta t = (t_N - t_1)/(N - 1)$ of the grid of its group, with its samples ordered by t; the order of the rows does not intervene. Its spectrum is that of the VMD family: the mode is extended to $2N$ samples by reflecting $\lceil N/2 \rceil$ samples at the start and the others at the end, $P_j$ is the squared modulus of the unnormalized discrete Fourier transform of the extension and $|\omega_j| = 2\pi \min(j, 2N - j)/(2N \Delta t)$, $j = 0, \ldots, 2N - 1$. Then frequency is the power centroid $$f = \frac{\sum_j |\omega_j| P_j}{2\pi \sum_j P_j}$$ and bandwidth the power deviation around it on the same grid, $$b = \left[\frac{\sum_j (|\omega_j|/2\pi - f)^2 P_j}{\sum_j P_j}\right]^{1/2},$$ both in Hz. frequency equals the centers of decomposeVMD and decomposeSVMD, except a center fixed at zero, which is not a centroid; in decomposeMVMD it is the centroid of each channel, not the common center. A mode of zero energy determines no centroid: its frequency and bandwidth are NA. energy is $\Delta t \sum_n c[n]^2$, energyFraction is $\sum c^2 / \sum x^2$, and meanPeriod is $N \Delta t$ over the number of maxima of the mode, or $N \Delta t$ without maxima.

For each series, modeCount is the number of its modes; residueFraction is $\sum r^2 / \sum x^2$, with $r$ its residue or fitResidual, and zero when the method returns neither, as decomposeEWT; and crossFraction is $$1 - \frac{\sum_k \sum c_k^2 + \sum r^2}{\sum x^2},$$ the input-energy fraction left after subtracting modal and remainder energies. It equals the normalized cross products when the modes and remainder reconstruct that input. Otherwise it also reflects the reconstruction discrepancy, as with EEMD's retained meanNoise. A series without modes has modeCount 0, and its remainder is the series.

Energy here is a quadratic signal measure, with squared signal units times seconds. Its identification with physical energy requires a relation for the measured quantity. A large modal energy fraction does not establish that the component is free of contamination.

Value

A named list of two data.table tables, each with the keys of decomposition followed by

metrics: mode, frequency in Hz, bandwidth in Hz, energy in the squared units of the series times seconds, energyFraction and meanPeriod in seconds; one row per mode, in the order of modes.
metricsSeries: modeCount, residueFraction and crossFraction; one row per series, in the order of signal.

Conditions

A series of signal with zero energy leaves its energy fractions undefined and stops the function with an error of class xemdZeroEnergy.

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())
OUT <- measureModesTSL(Decomposition)
OUT$metrics[OUT$metrics$OCID == "H1" & OUT$metrics$ID == "AT", ]
#>      OCID     ID  mode frequency  bandwidth   energy energyFraction meanPeriod
#>    <char> <char> <int>     <num>      <num>    <num>          <num>      <num>
#> 1:     H1     AT     1 3.0169666 0.34493374 4.422644     0.05878403  0.3334445
#> 2:     H1     AT     2 0.9245720 0.20175433 4.843884     0.06438299  1.0003334
#> 3:     H1     AT     3 0.4367757 0.09783386 3.800095     0.05050935  1.8006002
OUT$metricsSeries
#>      OCID     ID modeCount residueFraction crossFraction
#>    <char> <char>     <int>           <num>         <num>
#> 1:     H1     AT         3        0.831922  -0.005598394
#> 2:     H1     VT         3        0.831922  -0.005598394
#> 3:     H1     DT         3        0.831922  -0.005598394
#> 4:     H2     AT         3        0.831922  -0.005598394
#> 5:     H2     VT         3        0.831922  -0.005598394
#> 6:     H2     DT         3        0.831922  -0.005598394
#> 7:     UP     AT         3        0.831922  -0.005598394
#> 8:     UP     VT         3        0.831922  -0.005598394
#> 9:     UP     DT         3        0.831922  -0.005598394