Interpolate quantile curves in one UHS slice

Interpolates each non-mean spectral-acceleration quantile at one oscillator period. Supply a single hazard slice, such as one site, model, Vs30, and return period. The function does not group a table containing multiple hazard slices.

Usage

interpolateSaTable(uhs, Tn)

Arguments

uhs

A data.table representing one uniform-hazard-spectrum slice. It must contain:

Tn

Finite, non-negative oscillator periods in seconds.

p

Character quantile labels such as "0.16", with an optional literal "mean" label. Non-mean labels are treated as opaque identifiers; their probability values are not validated.

Sa

Finite, strictly positive spectral accelerations. The package UHS convention is acceleration in units of g.

Each non-mean label must have at least two rows at distinct usable periods. Extra columns are ignored and are not returned.

Tn

A length-one, finite, non-negative numeric target period, in seconds.

Value

A data.table with exactly the columns Tn, p, and Sa. It has one row at the target period for each unique non-mean label, plus a mean row when the input supplies one. Rows are ordered by Tn and p; with character labels at a common target period, p order is lexicographic. Tn retains the target's integer or double storage mode, p is character, and Sa is double. Sa uses the input acceleration units, conventionally g. Grouping and other input columns are not preserved.

Details

Curves are interpolated independently. For input row i, the function uses

x[i] = ln(Tn[i] + 1e-8)
y[i] = ln(Sa[i])
xout = ln(Tn)
Sa(Tn) = exp(linear interpolation of y at xout)

where ln is the natural logarithm. The 1e-8 offset applies to input period nodes, not to the target-period transform. It permits a zero-period PGA node. A target of zero is below the finite transformed nodes and returns the lowest-period endpoint.

stats::approx() is called with rule = 2, so targets below or above the tabulated period range return the corresponding endpoint ordinate rather than extending the last segment. Input row order does not control the result. Duplicate (Tn, p) rows produce one warning and are collapsed by averaging ln(Sa) at the tied period; this is a geometric mean on the original Sa scale. If tie handling or removal of unusable values leaves fewer than two interpolation nodes, stats::approx() produces an error.

The literal "mean" rows follow a separate rule: two or more rows use the same interpolation and extrapolation method, one row is copied unchanged to the target period, and zero mean rows omit it from the result.

The function checks the three required column names, numeric target type and target length, the presence of at least one non-mean label, and two input rows per non-mean label. It does not proactively validate the documented finiteness, sign, distinct-period, slice, or probability-label prerequisites. Unsupported inputs can therefore yield low-level data.table or stats errors, or non-finite output. Warnings raised inside stats::approx() are suppressed; the duplicate-row warning described above is emitted by this function.

Visible input rows, columns, values, and keys are not changed. data.table may cache a secondary index on p in the input as a lookup side effect. The function does not use random numbers or read or write files.

See also

fitDnModel() calls interpolateSaTable() when a required oscillator period is absent. buildGMDP() and fitSaF() produce UHS tables that must be reduced to one hazard slice before interpolation.

Examples

UHS <- data.table::data.table(
  Tn = rep(c(0.2, 0.8), each = 3L),
  p = rep(c("0.16", "0.84", "mean"), 2L),
  Sa = c(1, 2, 1.5, 4, 8, 6)
)

interpolateSaTable(UHS, Tn = 0.4)  # within range: 2, 4, and 3 g
#>       Tn      p    Sa
#>    <num> <char> <num>
#> 1:   0.4   0.16     2
#> 2:   0.4   0.84     4
#> 3:   0.4   mean     3
interpolateSaTable(UHS, Tn = 2)    # above range: 4, 8, and 6 g
#>       Tn      p    Sa
#>    <num> <char> <num>
#> 1:     2   0.16     4
#> 2:     2   0.84     8
#> 3:     2   mean     6