Normalize cumulative Arias-intensity prefixes.

TSL2AI() is for earthquake-motion analysts who need the progress of Arias intensity through an acceleration record, rather than its final scalar value. It extracts canonical acceleration (AT) rows, computes a cumulative prefix sum, and normalizes each component history by its own maximum.

Usage

TSL2AI(.x, units.source, units.target = "mm", output = c("wide", "long"))

Arguments

.x: A table-like object coercible to a data.table::data.table(). A canonical long time-series table (TSL) has required columns OCID, ID, t, and s, plus optional record metadata. t is numeric time in seconds; on AT rows, s is acceleration in units.source per second squared.
units.source: One character value giving the length unit underlying s: "mm", "cm", or "m" (case-insensitive). Acceleration units such as "gal" and "g", and verbose forms such as "mm/s2", are rejected.
units.target: One character value, "mm", "cm", or "m", used for the intermediate calculation. The default is "mm". The normalized ratio is dimensionless and is invariant to a consistent valid unit conversion, apart from floating-point round-off.
output: Output layout. "wide" (the default) returns row-key columns followed by one ratio column per OCID. "long" returns eligible metadata followed by OCID, t, and numeric ratio.

Value

A data.table. Long output has columns <eligible metadata>, OCID, t, ratio; wide output has columns <eligible metadata>, t, <one column per OCID>. Ratios are dimensionless, nondecreasing, and in [0, 1] when the cumulative maximum is finite and positive. If that maximum is zero or nonfinite, including a zero signal or arithmetic overflow, every ratio in the group is NA_real_.

Method

For samples a_i and the mean step bar(dt) = mean(diff(t)), the implemented cumulative quantity is $$Q_k = \frac{\pi\,\overline{\Delta t}}{2g} \sum_{i=1}^{k} a_i^2,$$ and the returned value is Q_k / max(Q). Here g is standard gravity: 9806.650 mm/s^2, 980.665 cm/s^2, or 9.806650 m/s^2. This is a mean-step rectangular prefix sum that includes the first sample; it is not exact quadrature of the continuous Arias integral, so its first value can be nonzero. The common step and scale factors cancel during normalization.

Shared table and ratio contract

Only rows with ID == "AT" are used; other signal domains are ignored. At least one AT row is required. Candidate metadata are columns other than t, s, ID, and OCID; only columns whose first class is character, factor, or integer become grouping keys and appear in output. Numeric, logical, date-time, and other metadata are excluded. Convert a record key to an eligible class when it must distinguish histories; otherwise exclusion can collapse records and produce a duplicate-key error.

Keys <eligible metadata>, OCID, t must be unique. Rows may arrive out of time order: each group is sorted before calculation and output. Every group must contain at least two finite numeric t and s values. Equal times are duplicate keys and fail; after sorting, times must be strictly increasing. Uneven spacing is accepted, but individual intervals are not weighted: the implementation uses one mean(diff(t)) factor, which cancels from the normalized ratio.

Wide output constructs an unquoted formula from the eligible metadata names. Those names must therefore be syntactic and formula-safe; names such as Record ID, A+B, and a-b can fail. Long output does not have this formula restriction. Long rows and wide row keys are sorted with missing keys last; wide component columns follow their first occurrence in the sorted long result.

Empty input or input without AT rows, missing required columns, unsupported units, duplicate keys, fewer than two samples, and nonfinite values raise an error. The function copies its input. It does not intentionally mutate the caller's object, warn, message, use random numbers, or read or write files. TSL2CAV() and TSL2CAV5() share this table, validation, normalization, and side-effect contract but use different cumulative quantities. Use TSL2IM() when final dimensional scalar measures are required.

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. https://www.osti.gov/biblio/4167721

Examples

tsl <- data.table::data.table(
  RecordID = "R1", OCID = "H1", ID = "AT",
  t = seq(0, 1, by = 0.25),
  s = c(0, 200, 500, 200, 0)
)
ai.long <- TSL2AI(tsl, units.source = "mm", output = "long")
ai.wide <- TSL2AI(tsl, units.source = "mm", output = "wide")
ai.long
#>    RecordID   OCID     t     ratio
#>      <char> <char> <num>     <num>
#> 1:       R1     H1  0.00 0.0000000
#> 2:       R1     H1  0.25 0.1212121
#> 3:       R1     H1  0.50 0.8787879
#> 4:       R1     H1  0.75 1.0000000
#> 5:       R1     H1  1.00 1.0000000
ai.wide
#> Key: <RecordID, t>
#>    RecordID     t        H1
#>      <char> <num>     <num>
#> 1:       R1  0.00 0.0000000
#> 2:       R1  0.25 0.1212121
#> 3:       R1  0.50 0.8787879
#> 4:       R1  0.75 1.0000000
#> 5:       R1  1.00 1.0000000
stopifnot(
  identical(names(ai.long), c("RecordID", "OCID", "t", "ratio")),
  identical(names(ai.wide), c("RecordID", "t", "H1")),
  isTRUE(all.equal(tail(ai.long$ratio, 1), 1))
)