Convert displacement time series into AT/VT/DT bundles

End-to-end workflow that takes displacement time histories and produces a consistent set of velocity and acceleration, along with the displacement processed outputs. It regularizes sampling if needed, converts units (for raw data), chooses STFT parameters/resampling, applies robust edge tapering, performs spectral/time derivatives, and applies post-tapering/optional trimming.

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: data.table. Input displacement records with a time column and one or more signal columns.
units.source: character. Source units for the input displacement when isRaw = TRUE. Same set as AT2TS / VT2TS: "mm", "cm", "m", plus "gal" (treated as cm scale) and "g" (multiplied by g_mms2). Practical displacement records are virtually always in "mm", "cm" or "m"; the acceleration-flavoured entries are accepted for symmetry with .getSF() but are unusual here. If different from units.target, a scale factor is applied per channel.
time: character. Name of the time column in the input (default "t"). Internally and in TSL output, time is canonicalized to t.
Fmax: numeric. Maximum frequency of interest (Hz). Guides STFT strategy and low-pass regularization during integration.
kNyq: numeric. Target Nyquist multiplier (Fs_target ~= kNyq * Fmax) when forced by the user. Otherwise an automatic grid is searched.
resample: logical. Kept for compatibility; decision is made by the internal STFT strategy.
derivate: character. Derivative method for DT -> VT / AT ("time" or "freq").
units.target: character. Target units for acceleration-related outputs.
NW: integer. Nominal STFT window length (samples). May be adjusted.
OVLP: numeric. Window overlap percent.
flatZeros: logical. Apply edge tapering; if isRaw = TRUE, tapering is applied regardless.
Astop0, Apass0: numeric. Normalized thresholds 0..1 for taper/flatten; relative to the per-channel max amplitude.
AstopLP, ApassLP: numeric. Anti-alias LP specs for resampling.
trimZeros: logical. If TRUE, trims leading/trailing zeros by the final window.
detrend: logical. Remove mean before/after stages.
regularize: logical. Force time regularization of input if needed.
output: character. Early/short-circuit outputs (default: "TSL"): "DTo", "AT", "VT", "DT", "TSW", "TSL".
verbose: logical. Print diagnostic logs.
audit: logical. If TRUE, runs auditSTFT() to validate STFT/resampling strategy and emit warnings for risky configurations. Default: TRUE.
isRaw: logical. If TRUE, handle unit conversion and default tapering.
lowPass: logical. If TRUE, multiply the spectral derivative kernel by an additional Butterworth-like low-pass at Fmax to suppress high-frequency amplification of the numerical derivative. Default: TRUE.

Value

Returns the requested object based on output.

Examples

t <- seq(0, 2, by = 0.02)
x <- data.table::data.table(
  t = t,
  H1 = sin(2 * pi * t),
  H2 = 0.5 * cos(2 * pi * t),
  UP = 0.25 * sin(4 * pi * t)
)
tsl <- DT2TS(x, units.source = "mm", Fmax = 4, NW = 16,
             audit = FALSE, isRaw = FALSE)
head(tsl)
#>           t          s     ID   OCID
#>       <num>      <num> <char> <char>
#> 1: 0.000000  0.0000000     AT     H1
#> 2: 0.015625  0.9811658     AT     H1
#> 3: 0.031250  6.1347884     AT     H1
#> 4: 0.046875 16.8415316     AT     H1
#> 5: 0.062500 29.5703358     AT     H1
#> 6: 0.078125 37.0461068     AT     H1