Convert canonical long time series to response spectra.

TSL2PS() is the spectra helper for canonical TSL tables produced by AT2TS(), VT2TS(), and DT2TS(). It derives grouping keys from the TSL schema instead of exposing BY or column-name arguments.

Usage

TSL2PS(
  .x,
  xi = 0.05,
  Tn = NULL,
  output = "PSL",
  D50 = FALSE,
  D100 = FALSE,
  nTheta = 180L
)

Arguments

.x: Canonical TSL data.table with columns t, s, ID, and OCID, plus optional metadata columns.
xi: numeric. Damping ratio(s) 0..1. Scalar input preserves the historical output schema; vector input adds an xi column.
Tn: numeric vector. Natural periods in seconds. Must not include 0; the Tn = 0 peak-value anchor is prepended internally.
output: character. One of "PSL" or "PSW". Default "PSL".
D50: logical scalar. If TRUE, add the median rotated horizontal component as OCID = "D50" for every metadata group with H1 and H2.
D100: logical scalar. If TRUE, add the maximum rotated horizontal component as OCID = "D100" for every metadata group with H1 and H2.
nTheta: integer. Number of rotation angles in [0, 180) for D50 = TRUE or D100 = TRUE. Default 180L (1-degree step).

Value

A data.table.

output = "PSL" returns a long table with metadata columns, OCID, Tn, spectral ID ("PSA", "PSV", "SD"), and S. If xi is a vector, the output also includes xi.
output = "PSW" returns a wide table with metadata columns, Tn, and spectral component columns such as PSA.H1, PSV.H1, and SD.H1. If xi is a vector, the output also includes xi. If requested, D50 and D100 appear as ordinary component suffixes such as PSA.D50 and PSA.D100.

Details

For each source domain d in acceleration (AT), velocity (VT), and displacement (DT), the function solves z'' + 2 xi omega z' + omega^2 z = x_d independently and reports omega^2 max(abs(z)). The resulting PSA, PSV, and SD ordinates retain the units of AT, VT, and DT, respectively. They are domain-normalized gmsp spectra, not classical transformations of one acceleration-driven oscillator state. The internally prepended Tn = 0 rows are the matching peak-value anchors PGA, PGV, and PGD.

Examples

t <- seq(0, 1, by = 0.01)
tsl <- data.table::rbindlist(list(
  data.table::data.table(t = t, s = sin(2 * pi * t),
                         ID = "AT", OCID = "H1"),
  data.table::data.table(t = t, s = cos(2 * pi * t),
                         ID = "VT", OCID = "H1"),
  data.table::data.table(t = t, s = sin(pi * t),
                         ID = "DT", OCID = "H1"),
  data.table::data.table(t = t, s = sin(2 * pi * t + 0.3),
                         ID = "AT", OCID = "H2"),
  data.table::data.table(t = t, s = cos(2 * pi * t + 0.4),
                         ID = "VT", OCID = "H2"),
  data.table::data.table(t = t, s = sin(pi * t + 0.2),
                         ID = "DT", OCID = "H2")
))
ps <- TSL2PS(tsl, Tn = c(0.1, 0.2))
head(ps)
#>      OCID    Tn     ID         S
#>    <char> <num> <char>     <num>
#> 1:     H1   0.0    PSA 0.9999209
#> 2:     H1   0.1    PSA 1.0418729
#> 3:     H1   0.2    PSA 1.0417730
#> 4:     H1   0.0    PSV 1.0000000
#> 5:     H1   0.1    PSV 1.8154973
#> 6:     H1   0.2    PSV 1.7373963
rot <- TSL2PS(tsl, Tn = 0.1, D50 = TRUE, D100 = TRUE, nTheta = 6L)
rot[OCID %in% c("D50", "D100")]
#>       OCID    Tn     ID         S
#>     <char> <num> <char>     <num>
#>  1:   D100   0.0    PSA 1.3517909
#>  2:   D100   0.1    PSA 1.4659578
#>  3:   D100   0.0    PSV 1.3407635
#>  4:   D100   0.1    PSV 2.3467665
#>  5:   D100   0.0     SD 1.3596201
#>  6:   D100   0.1     SD 1.4101479
#>  7:    D50   0.0    PSA 0.9999302
#>  8:    D50   0.1    PSA 1.1066021
#>  9:    D50   0.0    PSV 0.9999987
#> 10:    D50   0.1    PSV 1.6822484
#> 11:    D50   0.0     SD 0.9999274
#> 12:    D50   0.1     SD 1.0311069