Skip to contents

Reshape wide time-series columns to canonical long rows

TSW2TSL.Rd

TSW2TSL() is for users who need canonical t, s, ID, and OCID rows from a table whose signal columns are named <ID>.<OCID>. It accepts the canonical time name t and the constructor-family legacy name ts, which is renamed to t in the result. It does not process signals or convert units.

Usage

TSW2TSL(.x, by = "auto", ids = c("AT", "VT", "DT"))

Arguments

.x

An object coercible by data.table::as.data.table() to a wide table with t, or otherwise ts, and one or more signal columns named <ID>.<OCID>. The first dot separates ID from OCID; additional dots remain part of OCID. Other columns may be metadata.

by

Metadata columns to retain. "auto" (the default) treats every non-time column matching <ID>.<OCID> as a signal and every other column as metadata. NULL or character() uses no metadata, so every non-time column must be a valid signal name. A character vector selects explicit metadata columns; every remaining non-time column must then be a valid signal name.

ids

A character vector giving the preferred row order of ID values. The default is c("AT", "VT", "DT"). IDs found in .x but absent from ids are retained after the preferred IDs; this argument orders rows and does not filter data.

Value

A new canonical long data.table, sorted and column-ordered as <metadata>, OCID, ID, t, s. ID and OCID are parsed from each wide signal name, t is in seconds, and s is the unchanged signal value. Missing wide values remain explicit NA rows. Signal units are unchanged but are not inferred, validated, or added to the result.

Preconditions and limits

A time column and at least one valid signal column are required. Explicit by columns must exist. Under automatic detection, any metadata name that has text on both sides of a dot is interpreted as a signal column; select such metadata explicitly with by. The function does not validate duplicate time keys, time ordering, signal finiteness, ID vocabulary, component vocabulary, or physical units.

A lossless round trip through TSL2TSW() requires unique dense long-form keys, non-empty ID and OCID values, and ID values that contain no dots. The first dot in a wide signal name separates ID from OCID, so additional dots in OCID are preserved. A dot in an originating ID cannot be distinguished from the separator, and an empty originating ID or OCID does not form a recognized signal name. Conversion establishes canonical row and column order, so it need not preserve the original row order. The input is copied and is not modified by reference. The function uses no random numbers, emits no warnings or messages, and reads or writes no files.

See also

TSL2TSW(), AT2TS(), VT2TS(), and DT2TS().

Examples

tsw <- data.table::data.table(
  RecordID = "R1",
  t = c(0, 0.01),
  AT.H1 = c(1, 2),
  VT.H1 = c(0.1, 0.2)
)
tsl <- TSW2TSL(tsw)
tsl
#>    RecordID   OCID     ID     t     s
#>      <char> <char> <char> <num> <num>
#> 1:       R1     H1     AT  0.00   1.0
#> 2:       R1     H1     AT  0.01   2.0
#> 3:       R1     H1     VT  0.00   0.1
#> 4:       R1     H1     VT  0.01   0.2
# Each wide signal column becomes rows identified by ID and OCID.