Signal processing: AT2TS / VT2TS / DT2TS • gmsp

This guide is for analysts who have sampled acceleration, velocity, or displacement and need all three quantities on one consistent time grid. You will choose the constructor that matches the measured quantity, supply its units and useful frequency range, and interpret the resulting long or wide table without relying on implementation details.

Choose the constructor

Start with the function named for the quantity in the input table. Each function preserves the input component names and returns a processed bundle containing acceleration (AT), velocity (VT), and displacement (DT):

Use AT2TS() for acceleration in "mm", "cm", "m", "gal", or "g"; it integrates the input to VT and DT.
Use VT2TS() for velocity in "mm", "cm", or "m"; it differentiates the input to AT and integrates it to DT.
Use DT2TS() for displacement in "mm", "cm", or "m"; it differentiates the input to VT and AT.

The length values describe the basis of the physical unit: for example, units.source = "mm" means mm/s^2 for acceleration, mm/s for velocity, and mm for displacement. AT2TS() also accepts "gal" as cm/s^2 and converts "g" using 9806.650 mm/s^2. VT2TS() and DT2TS() reject "gal" and "g" because those are acceleration units.

Set units.target to the common lower-case length basis "mm", "cm", or "m". The resulting units are then target length/s^2 for AT, target length/s for VT, and target length for DT.

Prepare the input

The minimum input is a data.table with more than two rows:

one finite time column in seconds, named t by default;
at least one finite numeric signal column; and
a positive sampling interval that can support an integer sampling frequency after any regularization.

Signal-column names become component identifiers (OCID), such as H1, H2, or UP. Use time = "Time" for a differently named time column; when you do, the table must not also contain t. The functions return a new table and do not modify the input columns by reference.

With isRaw = TRUE, units.source is required, validated, and converted to units.target; raw records are also regularized and edge-tapered. With isRaw = FALSE, the values are assumed already expressed in units.target: omit units.source, because it is neither evaluated nor validated. You are responsible for using a supported target-unit basis in that mode.

Irregular or non-rational time grids are regularized automatically. Set regularize = TRUE to force regularization of processed input as well. Output time starts at zero, so retain the original absolute start time separately if it matters to the analysis.

A deterministic acceleration example

The example uses five seconds sampled at 100 Hz. Its 1.5 Hz acceleration is multiplied by a sine-squared envelope so that the finite record starts and ends at zero. The peak scale is 120 mm/s^2, and Fmax = 5 Hz keeps the stated frequency of interest above the signal frequency. kNyq is deliberately omitted so the constructor selects its sampling target automatically. The default audit = TRUE checks the first signal channel.

library(gmsp)

Time <- seq(0, 5, by = 0.01)
Phase <- pi * Time / max(Time)
Envelope <- sin(Phase)^2
Angle <- 2 * pi * 1.5 * Time
Carrier <- sin(Angle)
Acceleration <- data.table::data.table(
  t = Time,
  H1 = 120 * Envelope * Carrier
)

TSL <- AT2TS(
  Acceleration,
  units.source = "mm",
  units.target = "mm",
  Fmax = 5,
  isRaw = TRUE,
  output = "TSL"
)

Summary <- TSL[, .(
  Peak = signif(max(abs(s)), 5)
), by = .(ID, OCID)]

Grid <- TSL[, .(
  Samples = length(unique(t)),
  Start = min(t)
), by = .(ID, OCID)]
stopifnot(
  all(Grid$Start == 0),
  length(unique(Grid$Samples)) == 1L
)
Summary
#>        ID   OCID     Peak
#>    <char> <char>    <num>
#> 1:     AT     H1 119.9100
#> 2:     VT     H1  13.7680
#> 3:     DT     H1   1.6087

For real records, inspect any audit warnings about content above Fmax, frequency coverage, or the anti-alias transition rather than suppressing them.

The summary has one row for each quantity/component pair. Here every OCID is H1, ID identifies the physical quantity, and the silent assertions confirm that the histories share one time grid starting at zero. Peak must be interpreted with the unit attached to its ID:

`ID`	Unit when `units.target = "mm"`
`AT`	mm/s^2
`VT`	mm/s
`DT`	mm

The canonical TSL result itself has columns t, s, ID, and OCID. t is time in seconds and s is the signal value in the unit selected by ID; units are not stored in a separate TSL column, so keep the target-unit basis with the analysis metadata.

Choose bandwidth and processing behavior

These options affect the public processing result and should be selected from the data and analysis objective, not used as cosmetic tuning controls.

Choice	User-facing effect
`Fmax`	Positive maximum frequency of interest in Hz; guides frequency resolution, resampling, anti-alias filtering, integration, and, where applicable, differentiation.
omitted `kNyq`	Selects a target sampling frequency from the automatic grid.
explicit `kNyq`	Requests a target near `kNyq * Fmax`; explicitly passing the displayed default `3.125` is different from omitting it.
`resample`	Compatibility-only argument; its value does not decide whether resampling occurs. The signal and frequency controls make that decision.
`derivate`	For `VT2TS()` and `DT2TS()`, `"freq"` uses frequency-domain differentiation and `"time"` uses finite differences.
`lowPass`	With `derivate = "freq"`, limits high-frequency amplification near `Fmax`; it has no effect with `derivate = "time"`.
`detrend`	Subtracts channel means at the main processing stages when `TRUE`.
`audit` and `verbose`	`audit = TRUE` can warn from the first channel; `verbose = TRUE` prints diagnostics. Every call sets the session option `gmsp.verbose` to the supplied `verbose` value.

NW, OVLP, and the pass/stop controls refine the frequency-window and anti-alias behavior. Use the constructor help pages for their complete ranges and defaults.

Raw input is smoothly edge-tapered. The additional taper and trim choices differ slightly by starting quantity:

In AT2TS(), flatZeros = TRUE adds an exact acceleration support mask; trimZeros = TRUE retains the union of final nonzero component supports.
In VT2TS() and DT2TS(), flatZeros = TRUE enables the smooth amplitude-based taper for processed input and does not add an exact mask; trimZeros = TRUE retains only the intersection of final nonzero component supports.

Integration and frequency-domain differentiation set their zero-frequency terms to zero. Tapering, regularization, resampling, detrending, and bandwidth controls mean the returned histories are processed together; they should not be treated as algebraically exact derivatives, antiderivatives, or inverses of the original samples. Derivative outputs require more than four samples.

Select an output shape

output = "TSL" is usually the best choice for grouping, plotting, and combining records because quantity and component are explicit columns.

`output`	Shape and columns
`"TSL"`	Long `t`, `s`, `ID`, `OCID`; time starts at zero.
`"TSW"`	Wide `ts` plus `AT.<OCID>`, `VT.<OCID>`, and `DT.<OCID>` columns.
`"AT"`, `"VT"`, or `"DT"`	Processed component columns only, without time or units columns.
`"ATo"`, `"VTo"`, or `"DTo"`	Constructor-specific early wide result with `ts`, `Units`, and original component names.

The available early result matches the constructor: ATo for AT2TS(), VTo for VT2TS(), and DTo for DT2TS(). Consult the corresponding help topic before using an early result because it precedes the later processing steps and has different finiteness guarantees.

Move between long and wide tables

Use TSL2TSW() when a consumer needs one row per time/metadata key and one signal column per ID/OCID pair. Use TSW2TSL() to restore canonical long rows. These functions only reshape values: they do not process signals, infer units, or convert units.

TSW <- TSL2TSW(TSL, by = NULL)
TSLAgain <- TSW2TSL(
  TSW,
  by = NULL
)

writeLines(names(TSW))
#> t
#> AT.H1
#> VT.H1
#> DT.H1
Expected <- TSL[, .(
  OCID,
  ID,
  t,
  s
)]
stopifnot(data.table::fsetequal(
  Expected,
  TSLAgain
))

The wide names show the convention directly: AT.H1, VT.H1, and DT.H1. TSL2TSW() writes canonical time as t; TSW2TSL() accepts either t or the constructor-wide name ts and returns t.

For a lossless long-wide-long round trip:

each metadata/time/ID/OCID key must be unique and the combinations must be dense;
ID and OCID must be non-empty, and ID must not contain a dot;
the first dot in a wide signal name separates ID from OCID; additional dots in OCID are preserved; and
metadata names supplied to TSL2TSW() must be syntactic, formula-safe R names. Names such as Record ID, A+B, and a-b fail.

Sparse long combinations become explicit NA rows after conversion back. With automatic metadata detection, a wide metadata name containing text on both sides of a dot can be mistaken for a signal; pass those metadata columns explicitly through by. Conversion also establishes canonical ordering and need not retain the incoming row order.

See the TSL2TSW() and TSW2TSL() help topics for the exhaustive key, metadata, ordering, and failure contracts.

Reference contracts

The function help pages are the authoritative source for signatures, defaults, validation, warnings, errors, and all return schemas:

AT2TS() for acceleration input;
VT2TS() for velocity input;
DT2TS() for displacement input;
TSL2TSW() and TSW2TSL() for table projection.

Open a local reference topic with, for example, help("AT2TS", package = "gmsp"). The package website links these function names directly to the same reference contracts.

References

Allen, J. B., & 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., & Carlson, R. E. (1980). Monotone piecewise cubic interpolation. SIAM Journal on Numerical Analysis, 17(2), 238–246.
Oppenheim, A. V., & Schafer, R. W. (2010). Discrete-Time Signal Processing (3rd ed.). Pearson.