Construct acceleration, velocity, and displacement from displacement

DT2TS() is for users who have one or more displacement channels and need a consistent acceleration (AT), velocity (VT), and displacement (DT) bundle on one time grid. It can regularize the input grid, convert raw displacement units, choose and audit an STFT/resampling strategy, taper record edges, and differentiate displacement successively to velocity and acceleration.

Usage

DT2TS(
  .x,
  units.source,
  time = "t",
  Fmax = 16,
  kNyq = 3.125,
  resample = TRUE,
  derivate = "freq",
  units.target = "mm",
  NW = 128,
  OVLP = 75,
  flatZeros = FALSE,
  Astop0 = 1e-04,
  Apass0 = 0.001,
  AstopLP = 0.001,
  ApassLP = 0.98,
  trimZeros = FALSE,
  detrend = FALSE,
  regularize = FALSE,
  output = "TSL",
  verbose = FALSE,
  audit = TRUE,
  isRaw = TRUE,
  lowPass = TRUE
)

Arguments

.x

A data.table with more than two rows. It must contain the column selected by time and at least one numeric signal column. Signal-column names become output component identifiers (OCID).

units.source

When isRaw = TRUE, a required non-empty character scalar giving the input displacement length unit. Matching is case-insensitive; accepted canonical values are "mm", "cm", and "m". Acceleration aliases "g" and "gal" are rejected; use AT2TS() for acceleration input. When isRaw = FALSE, this argument may be omitted; if supplied, it is not evaluated or validated.

time

A non-empty character scalar naming the input time column, in seconds. The default is "t". If another name is selected, .x must not also contain a column named t.

Fmax

A finite positive maximum frequency of interest, in Hz. It guides STFT selection, resampling, anti-alias filtering, and differentiation. Default: 16.

kNyq

A finite positive multiplier for the target sampling frequency, approximately kNyq * Fmax. Omitting the argument selects from an automatic sampling-frequency grid; supplying it, including explicitly supplying 3.125, requests that target. Default shown in the signature: 3.125.

resample

A logical compatibility argument. The current implementation does not use its value to decide whether to resample; the STFT strategy makes that decision from the signal and frequency controls. Default: TRUE.

derivate

The lowercase derivative method used for both DT to VT and VT to AT: "freq" applies an STFT-domain derivative, while "time" applies finite differences. Default: "freq".

units.target

The lower-case target length unit: "mm", "cm", or "m". It defines AT, VT, and DT units as length/s^2, length/s, and length, respectively. Default: "mm".

NW

A positive nominal STFT window length in samples. The strategy may adjust it for record length and frequency resolution. Default: 128.

OVLP

Numeric STFT window overlap in percent; use a value from 0 up to, but not including, 100. Default: 75.

flatZeros

If TRUE, enable the amplitude-based smooth edge taper for processed input. Raw input is tapered regardless. Unlike AT2TS(), this argument does not add a separate exact support mask. Default: FALSE.

Astop0, Apass0

Normalized per-channel amplitude thresholds used to locate the stop and pass edges of the taper. Values are relative to each channel's maximum absolute amplitude. Defaults: 1e-4 and 1e-3.

AstopLP, ApassLP

Stopband and passband magnitudes for anti-alias resampling and, when enabled, the derivative low-pass. Defaults: 1e-3 and 0.98.

trimZeros

If TRUE, retain the intersection of final nonzero component supports; a row is kept only when every component's final window is nonzero. Default: FALSE.

detrend

If TRUE, subtract channel means at the main processing stages. Default: FALSE.

regularize

If TRUE, force interpolation to a uniform time grid. Irregular or non-rational grids are regularized regardless; raw input is also always regularized. Default: FALSE.

output

A character scalar selecting exactly one return object: "DTo", "AT", "VT", "DT", "TSW", or "TSL". Default: "TSL".

verbose

If TRUE, print strategy and numerical diagnostics. Every call also sets the session option gmsp.verbose to this logical value. Default: FALSE.

audit

If TRUE, audit the first signal channel and warn about such conditions as substantial content above Fmax, inadequate STFT coverage, or a narrow anti-alias transition. An audit failure is caught and does not replace the constructor result. Default: TRUE.

isRaw

If TRUE, validate and convert units.source, regularize the time grid, and apply the raw-record edge taper. If FALSE, values are assumed already expressed in units.target; no unit conversion or source- unit validation occurs. Default: TRUE.

lowPass

If TRUE, multiply each frequency-domain derivative by an additional low-pass near Fmax to limit high-frequency amplification. It has no effect with derivate = "time". Default: TRUE.

Value

A new data.table; no input columns are modified by reference. The selected output has one of these schemas:

• "DTo": ts, Units, and the original signal columns after time-grid handling and raw-unit conversion, but before detrending, tapering, resampling, or differentiation. ts starts at zero and Units contains the target length unit. This early return does not enforce finite signals.

• "AT", "VT", or "DT": the processed component columns only, with no time or unit column. Units are units.target/s^2, units.target/s, and units.target, respectively.

• "TSW": ts followed by AT.<OCID>, VT.<OCID>, and DT.<OCID> columns in the same units. ts starts at zero.

• "TSL": canonical long rows with columns t, s, ID, and OCID. ID is "AT", "VT", or "DT"; s has the corresponding unit described above, and t starts at zero.

Preconditions and limits

Time values must be finite and must support a positive sampling interval; after any regularization the sampling frequency must be an integer. Supply finite numeric signals for every output except the early "DTo" return. Processed derivative outputs require more than four samples. Frequency- domain differentiation sets its zero-frequency term to zero; finite differences use four-point interior and three-point edge formulas. Tapering, resampling, detrending, and bandwidth controls mean the derived histories are not exact algebraic derivatives of the original samples. units.target is a supported precondition rather than an independently validated argument when isRaw = FALSE.

The function errors for an invalid table shape, time selector, time or signal values, canonical raw unit, derivative option, sampling configuration, non-finite long output, or output selector. It uses no random numbers and reads or writes no files. Apart from setting gmsp.verbose and optional console output/warnings, it has no external side effects.

References

Allen, J. B., and Rabiner, L. R. (1977). A unified approach to short-time Fourier analysis and synthesis. Proceedings of the IEEE, 65(11), 1558–1564.

Harris, F. J. (1978). On the use of windows for harmonic analysis with the discrete Fourier transform. Proceedings of the IEEE, 66(1), 51–83.

Fritsch, F. N., and Carlson, R. E. (1980). Monotone piecewise cubic interpolation. SIAM Journal on Numerical Analysis, 17(2), 238–246.

Oppenheim, A. V., and Schafer, R. W. (2010). Discrete-Time Signal Processing, 3rd ed. Pearson.

See also

AT2TS(), VT2TS(), TSL2TSW(), and TSW2TSL().

Examples

t <- seq(0, 2, by = 0.02)
displacement <- data.table::data.table(
  t = t,
  H1 = sin(2 * pi * t)
)
tsl <- DT2TS(
  displacement,
  Fmax = 4,
  NW = 16,
  audit = FALSE,
  isRaw = FALSE
)
unique(tsl[, c("ID", "OCID")])
#>        ID   OCID
#>    <char> <char>
#> 1:     AT     H1
#> 2:     VT     H1
#> 3:     DT     H1
# AT is in mm/s^2, VT in mm/s, and DT in mm; all share t.
stopifnot(identical(sort(unique(tsl$ID)), c("AT", "DT", "VT")))