Convert velocity time series into AT/VT/DT bundles

End-to-end workflow that takes velocity time histories and produces a consistent set of acceleration, velocity, and displacement time series. It optionally regularizes sampling, converts units (for raw data), selects optimal STFT parameters and resampling strategy, applies robust edge tapering, performs spectral-domain derivation and integration, yields post-tapering and optional trimming.

Usage

VT2TS(
  .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,
  verbose = FALSE,
  audit = TRUE,
  output = "TSL",
  isRaw = TRUE,
  lowPass = TRUE
)

Arguments

.x: data.table. Input velocity records with a time column and one or more signal columns.
units.source: character. Source units for input velocity when isRaw = TRUE. Supported: "mm", "cm", "m", "gal", "g" (interpreted for acceleration scaling on derivative/integral paths). 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.
kNyq: numeric. Target Nyquist multiplier (Fs_target ~= kNyq * Fmax) if the user forces it; otherwise an automatic grid is searched.
resample: logical. Kept for compatibility; the actual decision is made by the internal STFT strategy based on Fmax and constraints.
derivate: character. Derivative method for VT -> AT ("time" or "freq").
units.target: character. Target units for output acceleration. Default: "mm".
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 specifications 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.
verbose: logical. Print diagnostic logs.
audit: logical. If TRUE, runs auditSTFT() to validate STFT/resampling strategy and emit warnings for risky configurations. Default: TRUE.
output: character. Early/short-circuit outputs (default: "TSL"): "VTo", "AT", "VT", "DT", "TSW", "TSL".
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 <- VT2TS(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.00000000     AT     H1
#> 2: 0.015625 0.06481575     AT     H1
#> 3: 0.031250 0.57602981     AT     H1
#> 4: 0.046875 1.76308128     AT     H1
#> 5: 0.062500 3.37746175     AT     H1
#> 6: 0.078125 4.84657784     AT     H1