VT2TS: Convert velocity time series into AT/VT/DT bundles

In gmsp: Ground Motion Signal Processing

Convert velocity time series into AT/VT/DT bundles

Description

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)

gmsp documentation built on July 18, 2026, 5:07 p.m.