# Intensity measures: TSL2IM / getIntensity

    # 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)
    #>       RSN   OCID     ID     IM    value  units
    #>    <char> <char> <char> <char>    <num> <char>
    #> 1:     R1     H1     AT     AI 200.2208  mm /s
    #> 2:     R1     H1     AT    AIu 100.1104  mm /s
    #> 3:     R1     H1     AT    AId 100.1104  mm /s
    #> 4:     R1     H1     AT    PGA 499.0134 mm /s2
    #> 5:     R1     H1     AT   ARMS 353.3767 mm /s2
    #> 6:     R1     H1     AT    AZC  39.0000      -

`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)))]
    #> [1] "RSN"  "OCID" "AI"   "AIu"  "AId"  "PGA"

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.