AT2TS: Convert acceleration time series into AT/VT/DT bundles

In gmsp: Ground Motion Signal Processing

Convert acceleration time series into AT/VT/DT bundles

Description

End-to-end workflow that takes acceleration 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 integration, and provides post-tapering/optional trimming.

The function is designed for seismic/structural records but is agnostic to the physical origin provided Fmax reflects the analysis band of interest.

Usage

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

Arguments

.x	data.table. Input acceleration records with a time column and one or more signal columns (e.g., H1, H2, V).
units.source	character. Source units for input acceleration when isRaw = TRUE. Supported: "mm", "cm", "m", "gal", "g". 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). Used to set STFT strategy and low-pass regularization in integration. Default: 16.
kNyq	numeric. Target Nyquist multiplier (⁠Fs_target ~= kNyq * Fmax⁠) if the user forces it. If not provided, an automatic grid is searched. Default: 3.125.
resample	logical. Kept for compatibility; the actual decision is made by the internal STFT strategy based on Fmax and constraints. Default: TRUE.
units.target	character. Output target units for acceleration records. Default: "mm".
NW	integer. Nominal STFT window length (samples); may be adjusted by the strategy. Default: 128.
OVLP	numeric. Window overlap percent. Default: 75.
flatZeros	logical. If TRUE, flatten external low-amplitude tails to exact zeros using per-channel normalized acceleration amplitude before optional trimming. If isRaw = TRUE, the historical smooth taper is still applied even when flatZeros = FALSE. Default: FALSE.
Astop0	numeric. Normalized stop threshold ⁠0..1⁠ for taper/flatten; relative to per-channel max amplitude. Astop0 = 1e-3 is equivalent to threshold 10 after normalizing PGA to 10000. Default: 1e-3.
Apass0	numeric. Normalized pass threshold ⁠0..1⁠ for taper/flatten; relative to per-channel max amplitude. Default: 1e-3.
AstopLP	numeric. Stopband attenuation for anti-alias LP (resampling). Default: 1e-3.
ApassLP	numeric. Passband for anti-alias LP (resampling). Default: 0.98.
trimZeros	logical. If TRUE, trims rows outside the final nonzero window support after taper/flatten. Multi-component records use the union of component supports. Default: FALSE.
detrend	logical. Remove mean before/after each main stage. Default: FALSE.
regularize	logical. Force time regularization of input if needed. Default: FALSE.
output	character. Short-circuit outputs (default: "TSL"): "ATo": early wide-frame after units; "AT"/"VT"/"DT": final wide; "TSW": combined wide; "TSL": long table.
verbose	logical. Print diagnostic logs. Default: FALSE.
audit	logical. If TRUE, runs auditSTFT() to validate STFT/resampling strategy and emit warnings for risky configurations. Default: TRUE.
isRaw	logical. If TRUE, perform unit conversion and robust pre/post tapering by default. If FALSE, the input is assumed to be already in units.target and the units.source argument is silently overridden to match; no scale factor is applied. Default: TRUE.

Value

Returns the requested object based on output (no other element is returned alongside it):

• "ATo": wide table with ts (time starting at 0), Units and channels, before any tapering or integration.

• "AT" / "VT" / "DT": wide table with the channels only (no ts column).

• "TSW": wide table with columns ts, ⁠AT.<OCID>⁠, ⁠VT.<OCID>⁠, ⁠DT.<OCID>⁠.

• "TSL" (default): long table with columns t, s, ID (one of "AT", "VT", "DT"), and OCID. Sampling interval and row count are not returned separately; recover them from the output via 1 / diff(ts)[1] and nrow(.).

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 <- AT2TS(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.