Skip to contents

Reshape canonical long time series to wide columns

TSL2TSW.Rd

TSL2TSW() is for users who need one row per time and metadata key, with each signal identified by an <ID>.<OCID> column such as AT.H1, VT.H1, or DT.H1. It is a table projection only: it does not process signals or convert units.

Usage

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

Arguments

.x

An object coercible by data.table::as.data.table() to a table containing t, s, ID, and OCID. t is time in seconds, s is the signal value, ID identifies the quantity (commonly AT, VT, or DT), and OCID identifies the component. Other columns are optional metadata.

by

Metadata columns that form row keys. "auto" (the default) uses every column except t, s, ID, and OCID; NULL or character() uses no metadata; a character vector selects explicit metadata columns. Data columns cannot be included.

ids

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

Value

A new wide data.table, sorted and column-ordered as <by columns>, t, <ID>.<OCID>. Each signal column contains the s values for that ID/component pair. Missing combinations are represented by NA. Numeric values and any unit-bearing metadata are preserved without unit validation or conversion.

Preconditions and limits

Every combination of the selected metadata, t, ID, and OCID must be unique; duplicated keys are rejected rather than aggregated. All named by columns must exist. Selected metadata column names must be syntactic names that can appear unquoted in an R formula. Names such as Record ID, A+B, or a-b fail because the cast formula is constructed from the column names. The function does not validate time ordering, signal finiteness, ID vocabulary, component vocabulary, or physical units.

A lossless round trip through TSW2TSL() requires a dense long table with unique keys, non-empty ID and OCID values, ID values that contain no dots, and metadata names that are not mistaken for <ID>.<OCID> signal names. The first dot in a wide signal name separates ID from OCID, so additional dots in OCID are preserved. A dot in ID changes the identifiers on conversion back; an empty ID or OCID creates a wide name that TSW2TSL() does not recognize. Sparse combinations acquire explicit NA rows when converted back. 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

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

Examples

tsl <- data.table::data.table(
  RecordID = "R1",
  OCID = rep("H1", 4),
  ID = rep(c("AT", "VT"), each = 2),
  t = rep(c(0, 0.01), 2),
  s = c(1, 2, 0.1, 0.2)
)
tsw <- TSL2TSW(tsl)
tsw
#> Key: <RecordID, t>
#>    RecordID     t AT.H1 VT.H1
#>      <char> <num> <num> <num>
#> 1:       R1  0.00     1   0.1
#> 2:       R1  0.01     2   0.2
# AT.H1 and VT.H1 retain the corresponding long-table signal values.