Convert acceleration time series into AT/VT/DT bundles

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 = 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
)

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. Apply edge tapering to suppress low-level pre/post segments. If isRaw = TRUE, a taper is applied regardless. Default: FALSE.
Astop0: numeric. Normalized stop threshold 0..1 for taper/flatten; relative to per-channel max amplitude. Default: 1e-4.
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 leading/trailing zeros according to the final taper window. 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-related scalars (Fs, dt, df, NP, ...) are computed internally during processing but are not part of the return value; 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)
#>           t          s     ID   OCID
#>       <num>      <num> <char> <char>
#> 1: 0.000000 0.00000000     AT     H1
#> 2: 0.015625 0.09804854     AT     H1
#> 3: 0.031250 0.19509921     AT     H1
#> 4: 0.046875 0.29026096     AT     H1
#> 5: 0.062500 0.38265793     AT     H1
#> 6: 0.078125 0.47141655     AT     H1