Skip to contents

Construct acceleration, velocity, and displacement histories

AT2TS.Rd

AT2TS() is for users who have one or more acceleration channels and need a consistent acceleration (AT), velocity (VT), and displacement (DT) bundle on one time grid. It can regularize the input grid, convert raw acceleration units, choose and audit an STFT/resampling strategy, taper the record edges, and integrate acceleration to velocity and displacement.

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

A data.table with more than two rows. It must contain the column selected by time and at least one numeric signal column. Signal-column names become output component identifiers (OCID).

units.source

When isRaw = TRUE, a required non-empty character scalar giving the input acceleration unit. Matching is case-insensitive; accepted canonical values are "mm", "cm", "m", "gal", and "g". The length values denote the base of acceleration units (for example, "mm" means mm/s^2); "gal" means cm/s^2, and "g" is converted using 9806.650 mm/s^2. When isRaw = FALSE, this argument may be omitted; if supplied, it is not evaluated or validated.

time

A non-empty character scalar naming the input time column, in seconds. The default is "t". If another name is selected, .x must not also contain a column named t.

Fmax

A finite positive maximum frequency of interest, in Hz. It guides STFT selection, resampling, anti-alias filtering, and integration. Default: 16.

kNyq

A finite positive multiplier for the target sampling frequency, approximately kNyq * Fmax. Omitting the argument selects from an automatic sampling-frequency grid; supplying it, including explicitly supplying 3.125, requests that target. Default shown in the signature: 3.125.

resample

A logical compatibility argument. The current implementation does not use its value to decide whether to resample; the STFT strategy makes that decision from the signal and frequency controls. Default: TRUE.

units.target

The lower-case target length basis: "mm", "cm", or "m". It defines AT, VT, and DT units as length/s^2, length/s, and length, respectively. Default: "mm".

NW

A positive nominal STFT window length in samples. The strategy may adjust it for record length and frequency resolution. Default: 128.

OVLP

Numeric STFT window overlap in percent; use a value from 0 up to, but not including, 100. Default: 75.

flatZeros

If TRUE, multiply the edge taper by an exact support mask based on normalized acceleration amplitude. This creates zero tails that trimZeros can remove. Raw input is smoothly tapered even when flatZeros = FALSE. Default: FALSE.

Astop0, Apass0

Normalized per-channel amplitude thresholds used to locate the stop and pass edges of the taper. Values are relative to each channel's maximum absolute acceleration. Defaults: 1e-3 and 1e-3.

AstopLP, ApassLP

Stopband and passband magnitudes for the anti-alias low-pass used when resampling. Defaults: 1e-3 and 0.98.

trimZeros

If TRUE, retain the union of the final nonzero component supports; a row is kept when any component's final window is nonzero. Default: FALSE.

detrend

If TRUE, subtract channel means at the main processing stages. Default: FALSE.

regularize

If TRUE, force interpolation to a uniform time grid. Irregular or non-rational grids are regularized regardless; raw input is also always regularized. Default: FALSE.

output

A character scalar selecting exactly one return object: "ATo", "AT", "VT", "DT", "TSW", or "TSL". Default: "TSL".

verbose

If TRUE, print strategy and numerical diagnostics. Every call also sets the session option gmsp.verbose to this logical value. Default: FALSE.

audit

If TRUE, audit the first signal channel and warn about such conditions as substantial content above Fmax, inadequate STFT coverage, or a narrow anti-alias transition. An audit failure is caught and does not replace the constructor result. Default: TRUE.

isRaw

If TRUE, validate and convert units.source, regularize the time grid, and apply the raw-record edge taper. If FALSE, values are assumed already expressed in units.target; no unit conversion or source- unit validation occurs. Default: TRUE.

Value

A new data.table; no input columns are modified by reference. The selected output has one of these schemas:

  • "ATo": ts, Units, and the original signal columns after time-grid handling and raw-unit conversion, but before detrending, tapering, resampling, or integration. ts starts at zero and Units contains the target length basis. This early return does not enforce finite signals.

  • "AT", "VT", or "DT": the processed component columns only, with no time or unit column. Units are units.target/s^2, units.target/s, and units.target, respectively.

  • "TSW": ts followed by AT.<OCID>, VT.<OCID>, and DT.<OCID> columns in the same units. ts starts at zero.

  • "TSL": canonical long rows with columns t, s, ID, and OCID. ID is "AT", "VT", or "DT"; s has the corresponding unit described above, and t starts at zero.

Preconditions and limits

Time values must be finite and must support a positive sampling interval; after any regularization the sampling frequency must be an integer. Supply finite numeric signals for every output except the early "ATo" return. Integration fixes the zero-frequency integration constant at zero. Tapering, resampling, detrending, and bandwidth controls mean the derived series are processed histories, not algebraically exact antiderivatives of the original samples. units.target is a supported precondition rather than an independently validated argument when isRaw = FALSE.

The function errors for an invalid table shape, time selector, time or signal values, canonical raw unit, sampling configuration, derived result, or output selector. It uses no random numbers and reads or writes no files. Apart from setting gmsp.verbose and optional console output/warnings, it has no external side effects.

References

Allen, J. B., and Rabiner, L. R. (1977). A unified approach to short-time Fourier analysis and synthesis. Proceedings of the IEEE, 65(11), 1558–1564.

Harris, F. J. (1978). On the use of windows for harmonic analysis with the discrete Fourier transform. Proceedings of the IEEE, 66(1), 51–83.

Fritsch, F. N., and Carlson, R. E. (1980). Monotone piecewise cubic interpolation. SIAM Journal on Numerical Analysis, 17(2), 238–246.

Oppenheim, A. V., and Schafer, R. W. (2010). Discrete-Time Signal Processing, 3rd ed. Pearson.

See also

VT2TS(), DT2TS(), TSL2TSW(), and TSW2TSL().

Examples

t <- seq(0, 2, by = 0.02)
acceleration <- data.table::data.table(
  time = t,
  H1 = sin(2 * pi * t)
)
tsl <- AT2TS(
  acceleration,
  time = "time",
  Fmax = 4,
  NW = 16,
  audit = FALSE,
  isRaw = FALSE
)
unique(tsl[, c("ID", "OCID")])
#>        ID   OCID
#>    <char> <char>
#> 1:     AT     H1
#> 2:     VT     H1
#> 3:     DT     H1
# AT is in mm/s^2, VT in mm/s, and DT in mm; all share t.
stopifnot(identical(sort(unique(tsl$ID)), c("AT", "DT", "VT")))