Normalize gmsp's 0.05-g thresholded CAV prefixes.

TSL2CAV5() is for analysts who need the progress of gmsp's thresholded cumulative absolute velocity. It includes only acceleration samples whose absolute amplitude is at least 0.05 g, then normalizes the prefix history by its own maximum.

Usage

TSL2CAV5(.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 and naming limit

With bar(dt) = mean(diff(t)), the implemented prefix is $$Q_k = \overline{\Delta t}\sum_{i=1}^{k} |a_i|\,\mathbf{1}(|a_i| \mathrel{\geq} 0.05g),$$ and the returned value is Q_k / max(Q). Equality with the threshold is included. The cutoff is 490.3325 mm/s^2, 49.03325 cm/s^2, or 0.4903325 m/s^2. It is converted with standard gravity, so the mask and normalized result are invariant to the chosen valid length unit, apart from floating-point round-off. If no sample reaches the threshold, every ratio is NA_real_.

The 0.05 g cutoff is a gmsp package convention. Despite the function name, it is not the 5 cm/s^2 cutoff in the CAV5 measure introduced by Kramer and Mitchell (2006). Do not interchange the two definitions. As with the other ratio helpers, gmsp uses a mean-step rectangular prefix that includes the first sample rather than exact continuous-time quadrature.

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

Kramer, S. L. and Mitchell, R. A. (2006). Ground motion intensity measures for liquefaction hazard evaluation. Earthquake Spectra, 22(2), 413–438. doi:10.1193/1.2194970

Examples

tsl <- data.table::data.table(
  RecordID = "R1", OCID = "H1", ID = "AT",
  t = seq(0, 1, by = 0.25),
  s = c(0, 400, 500, 400, 0)
)
cav5.long <- TSL2CAV5(tsl, units.source = "mm", output = "long")
cav5.wide <- TSL2CAV5(tsl, units.source = "mm", output = "wide")
cav5.long
#>    RecordID   OCID     t ratio
#>      <char> <char> <num> <num>
#> 1:       R1     H1  0.00     0
#> 2:       R1     H1  0.25     0
#> 3:       R1     H1  0.50     1
#> 4:       R1     H1  0.75     1
#> 5:       R1     H1  1.00     1
cav5.wide
#> Key: <RecordID, t>
#>    RecordID     t    H1
#>      <char> <num> <num>
#> 1:       R1  0.00     0
#> 2:       R1  0.25     0
#> 3:       R1  0.50     1
#> 4:       R1  0.75     1
#> 5:       R1  1.00     1
stopifnot(
  identical(names(cav5.long), c("RecordID", "OCID", "t", "ratio")),
  identical(names(cav5.wide), c("RecordID", "t", "H1")),
  identical(cav5.long$ratio, c(0, 0, 1, 1, 1))
)