Cast canonical long intensity measures to wide columns.

IML2IMW() is for analysts who need one row per record/component for joins, summaries, or export. It reshapes a canonical long intensity table (IML) so each distinct IM value becomes a column. It does not calculate or convert intensity measures.

Usage

IML2IMW(.x, by = "auto")

Arguments

.x

A table-like object coercible to a data.table::data.table(). A canonical IML has character OCID and IM columns and a numeric value column. Output from TSL2IM() also carries ID and units, plus optional metadata.

by

Row-key metadata. "auto" (the default) uses every column except OCID, ID, IM, value, and units, in input-column order. NULL or character() uses no metadata, leaving OCID as the only row key. A non-empty character vector selects existing metadata columns explicitly; it cannot contain missing names, NA, or any of the five data columns listed above.

Value

A data.table ordered by <selected metadata>, OCID, with those row-key columns first and one column per IM value afterward. Measure columns follow first occurrence in .x; missing row/measure combinations are typed missing values. Canonical numeric value input produces numeric measure columns. A correctly shaped empty input returns its selected metadata and OCID columns with zero rows and no measure columns.

Details

The cast key is <selected metadata>, OCID, IM and must identify at most one input row. Duplicated keys raise an error; values are never aggregated. The ID and units columns are deliberately excluded from the key and output, so wide output does not retain a measure's signal domain or unit. If two domains reuse the same IM under one row key, they collide and the cast fails. Keep canonical measure names unique across domains and retain the long table when per-row units or domains are needed.

Metadata omitted by by are dropped. If their omission makes two rows share a cast key, the duplicate-key check fails. Auto and explicit row-key names are inserted unquoted into a formula and must therefore be syntactic and formula-safe; names such as Record ID, A+B, and a-b can fail. IM values become output column names and may themselves be non-syntactic.

Required columns, by, and uniqueness are validated, but canonical classes, units, and physical compatibility of values are not. The function copies its input and does not intentionally mutate it, warn, message, use random numbers, or read or write files.

Examples

iml <- data.table::data.table(
  RecordID = c("R1", "R1"),
  OCID = c("H1", "H1"),
  ID = c("AT", "AT"),
  IM = c("PGA", "CAV"),
  value = c(500, 120),
  units = c("mm /s2", "mm /s")
)
imw <- IML2IMW(iml)
iml
#>    RecordID   OCID     ID     IM value  units
#>      <char> <char> <char> <char> <num> <char>
#> 1:       R1     H1     AT    PGA   500 mm /s2
#> 2:       R1     H1     AT    CAV   120  mm /s
imw
#> Key: <RecordID, OCID>
#>    RecordID   OCID   PGA   CAV
#>      <char> <char> <num> <num>
#> 1:       R1     H1   500   120
stopifnot(
  identical(names(imw), c("RecordID", "OCID", "PGA", "CAV")),
  identical(unname(as.numeric(imw[1, .(PGA, CAV)])), c(500, 120)),
  !any(c("ID", "units") %in% names(imw))
)