Normalize cumulative absolute-velocity prefixes.

TSL2CAV() is for analysts who need the progress of cumulative absolute velocity (CAV) through each acceleration component. It returns a dimensionless prefix history, not CAV in length-per-second units.

Usage

TSL2CAV(.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 acceleration samples a_i and bar(dt) = mean(diff(t)), the implemented prefix is $$Q_k = \overline{\Delta t}\sum_{i=1}^{k}|a_i|,$$ and the returned value is Q_k / max(Q). This mean-step rectangular sum includes the first sample and is not exact quadrature of a continuous CAV integral. The common step and unit scale 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

Reed, J. W. and Kassawara, R. P. (1990). A criterion for determining exceedance of the operating basis earthquake. Nuclear Engineering and Design, 123(2–3), 387–396. doi:10.1016/0029-5493(90)90259-Z

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)
)
cav.long <- TSL2CAV(tsl, units.source = "mm", output = "long")
cav.wide <- TSL2CAV(tsl, units.source = "mm", output = "wide")
cav.long
#>    RecordID   OCID     t     ratio
#>      <char> <char> <num>     <num>
#> 1:       R1     H1  0.00 0.0000000
#> 2:       R1     H1  0.25 0.2222222
#> 3:       R1     H1  0.50 0.7777778
#> 4:       R1     H1  0.75 1.0000000
#> 5:       R1     H1  1.00 1.0000000
cav.wide
#> Key: <RecordID, t>
#>    RecordID     t        H1
#>      <char> <num>     <num>
#> 1:       R1  0.00 0.0000000
#> 2:       R1  0.25 0.2222222
#> 3:       R1  0.50 0.7777778
#> 4:       R1  0.75 1.0000000
#> 5:       R1  1.00 1.0000000
stopifnot(
  identical(names(cav.long), c("RecordID", "OCID", "t", "ratio")),
  identical(names(cav.wide), c("RecordID", "t", "H1")),
  isTRUE(all.equal(tail(cav.long$ratio, 1), 1))
)