DT2TS: Convert displacement time series into AT/VT/DT bundles

In gmsp: Ground Motion Signal Processing

Convert displacement time series into AT/VT/DT bundles

Description

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)

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