measureModesTSL: Metrics of the Modes of Time-Series Records

In xemd: eXtended Empirical Mode Decomposition

Metrics of the Modes of Time-Series Records

Description

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.

See Also

decomposeTSL, selectModesTSL, reconstructTSL

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", ]
OUT$metricsSeries

xemd documentation built on Nov. 9, 2026, 1:09 a.m.