Intensity measures: TSL2IM / getIntensity

In gmsp: Ground Motion Signal Processing

knitr::opts_chunk$set(collapse = TRUE, comment = "#>", eval = FALSE)

# Minimal executable example
library(gmsp)
library(data.table)
t_vec <- seq(0, 10, by = 0.01)
tsl <- data.table(RSN = "R1", OCID = "H1", ID = "AT",
                  t = t_vec, s = 500 * sin(2 * pi * 2 * t_vec))
im <- TSL2IM(tsl, units.source = "mm", units.target = "mm")
head(im)

TSL2IM() computes intensity measures from a long TSL table containing acceleration (AT), velocity (VT) and displacement (DT) series. getIntensity() remains as a compatibility wrapper around TSL2IM().

References: Arias (1970), Trifunac & Brady (1975), Campbell & Bozorgnia (2012), Inoue et al. (1996), Rathje et al. (1998).

Expected input

TSL must be a data.table with columns:

• RSN — record id,
• OCID — channel id,
• ID ∈ {AT, VT, DT},
• t — time (s),
• s — amplitude.

Units

The function takes:

• units.source — source units for s ("mm", "cm", "m", "gal", "g"),
• units.target — target base-length units ("mm", "cm", "m"; default "mm").

A single factor SFU = .getSF(units.source, units.target) is applied to s for all rows, regardless of ID. This works if your AT, VT and DT series are already consistent in the same base-length unit (e.g. output of AT2TS / VT2TS / DT2TS in units.target).

Warning: if you mix incompatible units (e.g. units.source = "g" while also having VT / DT in the same table), the scaling will be wrong.

Internal unit conventions

After scaling:

• For AT: s is acceleration in units.target/s^2.
• For VT: s is velocity in units.target/s.
• For DT: s is displacement in units.target.

The acceleration of gravity in target units is $g = .getG(\mathrm{units.target})$ (e.g. 9806.65 mm/s² for units.target = "mm").

Implemented measures

Measures are computed per group $(RSN, OCID, ID)$.

Long and wide output

The default output is long IML, with columns for metadata, OCID, ID, IM, value, and units. Use output = "IMW" when a pipeline needs one row per metadata and OCID with intensity measures as columns:

imw <- TSL2IM(tsl, units.source = "mm", output = "IMW")
names(imw)[1:min(6, length(names(imw)))]

The same projection is available for existing long results: IML2IMW(im).

Acceleration (ID = "AT")

Peak and RMS:

$$\mathrm{PGA} = \max_t |a(t)|, \qquad \mathrm{ARMS} = \sqrt{\frac{1}{N}\sum_{i=1}^{N} a_i^2}.$$

Zero crossings and edges:

• AZC — number of zero crossings (discrete count).
• ATo, ATn — first $a(t_1)$ and last $a(t_N)$ value.

Arias intensity (discretised with $\Delta t = \mathrm{mean}(t_i - t_{i-1})$):

$$\mathrm{AI} = \frac{\pi}{2g}\sum_{i=1}^{N} a_i^2\,\Delta t.$$

• AI — total Arias intensity.
• AIu — uses $a_+(t) = \max(a, 0)$ only.
• AId — uses $a_-(t) = \min(a, 0)$ only.

Units: units.target/s.

Significant duration (Husid): the code builds a cumulative curve proportional to energy,

$$H(t_k) = \pi\,\Delta t \sum_{i=1}^{k} a_i^2,$$

and measures the time interval between two fractions of the total.

• D0595 — 5 % → 95 %.
• D0575 — 5 % → 75 %.
• D2080 — 20 % → 80 %.

Units: s.

Mean period $T_m$ (Rathje et al. 1998), from the Fourier amplitude spectrum over a frequency band:

$$T_m = \frac{\sum_{f \in [f_{\min}, f_{\max}]} C(f)^2 / f} {\sum_{f \in [f_{\min}, f_{\max}]} C(f)^2}.$$

TmA is computed on AT with $f_{\min} = 0.1$ Hz, $f_{\max} = 25$ Hz.

Duration / sampling:

• NP — number of samples.
• dt — mean $\Delta t$.
• Fs — $1/\Delta t$.
• Dmax — last time last(t).

Cumulative absolute velocity (CAV):

$$\mathrm{CAV} = \sum_{i=1}^{N} |a_i|\,\Delta t.$$

CAV5 applies the same sum but only over indices where $|a_i| \ge 0.05\,g$. Units: units.target/s.

Derived indices (as implemented; not standardised):

$$\mathrm{EPI} = \frac{0.9}{\pi}\,\mathrm{AI}\,(2g)\,D_{05\text{–}95}, \qquad \mathrm{PDI} = \mathrm{AI}\,\left(\frac{D_{\max}}{\mathrm{AZC}}\right)^{!2}.$$

Units: units.target^2/s^2 for EPI; units.target·s for PDI (with AZC treated as dimensionless).

Note: if AZC = 0, PDI becomes Inf/NaN.

Velocity (ID = "VT")

• PGV — $\max_t |v(t)|$.
• VRMS — RMS of $v$.
• VZC — zero crossings.
• VTo, VTn — first / last value.
• TmV — mean period from the Fourier amplitude spectrum.

Units: units.target/s for PGV / VRMS / VTo / VTn; s for TmV.

Displacement (ID = "DT")

• PGD — $\max_t |d(t)|$.
• DRMS — RMS of $d$.
• DZC — zero crossings.
• DTo, DTn — first / last value.
• TmD — mean period from the Fourier amplitude spectrum.

Units: units.target for PGD / DRMS / DTo / DTn; s for TmD.

What it does not compute

• No Housner-type spectral intensities.
• No component averaging — measures are per OCID.
• No SDOF-response-based intensity measures — those belong to TSL2PS().

References

• Arias, A. (1970). A measure of earthquake intensity. In R. J. Hansen (Ed.), Seismic Design for Nuclear Power Plants (pp. 438–483). MIT Press.
• Trifunac, M. D., & Brady, A. G. (1975). A study on the duration of strong earthquake ground motion. Bulletin of the Seismological Society of America, 65(3), 581–626.
• Inoue, M., Cornell, C. A., & Bourque, L. B. (1996). Cumulative absolute velocity as a measure of seismic demand and its utility in limit-state criteria. Earthquake Engineering & Structural Dynamics, 25(9), 1075–1094.
• Rathje, E. M., Abrahamson, N. A., & Bray, J. D. (1998). Earthquake Ground Motions: Characteristics, the Mean Period and Its Use in Engineering Applications.
• Campbell, K. W., & Bozorgnia, Y. (2012). Ground Motion Prediction Equations for the Average Horizontal Components of PGA, PGV, and 5 %-Damped PSA at Spectral Periods between 0.01 s and 10.0 s. Earthquake Spectra, 28(3), 1087–1114.

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