Site-amplified spectral acceleration (NGA-East site-response models)

Computes site-amplified spectral acceleration using two input modes: (A) If the input UHS contains only p == "mean", rock Sa is treated as deterministic and the dispersion in SaF comes solely from the site-response model (sdLnF). (B) If the input UHS contains numeric quantiles (e.g., "0.10", "0.50", ...), ln Sa(Tn) is reconstructed from those quantiles using an empirical inverse quantile function (the Hyman construction also used by buildQSpline). Dependence between PGA and Sa(Tn) is represented by a per-period Gaussian "star" copula with the Baker & Jayaram (2008) correlation rhoBJ(Tn, T0 = 0), which has no distance dependence. The site-response model is evaluated with the paired PGA realization, and ln SaF = ln Sa + ln F with ln F ~ Normal(muLnF, sdLnF). The site-response residual is conditionally independent given PGA; ln Sa and the conditional site-factor moments remain associated through their correlated PGA realization. Each sampled or quadrature-weighted rock marginal is re-centered to its tabulated mean.

Usage

fitSaF(
  uhs,
  vs30,
  vref = 760,
  ns = 1000,
  models = "ST20",
  p_TARGET = c(0.05, 0.1, 0.16, 0.5, 0.84, 0.9, 0.95),
  integrationMethod = "monte-carlo",
  quadratureOrder = 64L
)

Arguments

uhs

data.table with columns Tn, p, Sa.

vs30

target Vs30 (m/s).

vref

reference Vs30 (m/s), default 760.

ns

Monte Carlo size (default 1000).

models

character. Site-response model id: "ST20" (default; Stewart/Hashash 2020 NGA-East generation, see F_ST20) or "ST17" (PEER 2017/05 generation, see F_ST17).

p_TARGET

probabilities to report when only 'mean' is provided, default c(0.05, 0.10, 0.16, 0.50, 0.84, 0.90, 0.95).

integrationMethod

integration method. "monte-carlo" preserves the historical pseudo-random implementation; "quadrature" evaluates the quantile-defined model deterministically, with explicit monotone tails outside the supplied knots.

quadratureOrder

integer number of Gauss–Legendre nodes per latent uniform dimension when integrationMethod = "quadrature" (default 64; at least 4). Ignored by the Monte Carlo method.

Value

data.table with columns Tn, p, Sa, SaF, AF.

Details

The legacy default, integrationMethod = "monte-carlo", estimates both modes with ns pseudo-random draws. With integrationMethod = "quadrature", mode A is evaluated analytically and mode B is integrated without random numbers. Mode B transforms the two independent latent normals of the PGA–Sa Gaussian copula to uniform probability space and uses tensor Gauss–Legendre quadrature there; the independent normal site-response residual is integrated analytically. Before mean re-centering, the reconstructed quantile function passes through the tabulated knots and retains the Hyman spline between them. Outside the supplied probability range, where the data do not determine a tail law, it continues the first and last secant slopes linearly and non-decreasingly. This avoids folded cubic extrapolation while retaining the copula rank construction. Each marginal is then re-centered to its tabulated population mean. The method uses quadratureOrder^2 joint nodes per period and is deterministic and RNG-independent for fixed inputs in a fixed numerical environment.

For scenario (DSHA) tables with analytic mixture components available, prefer fitSaFMixture (exact, sampling-free).

Requirements:

• The input table must have columns Tn, p, Sa.

• It must include exactly one row (Tn == 0, p == "mean") providing PGA on rock.

Output columns: Tn, p, Sa, SaF, AF, where AF = SaF / Sa. In mode (B), the same numeric p values found in the input are returned plus "mean". In mode (A), the set of p values is taken from p_TARGET plus "mean".

Examples

if (FALSE) { # \dontrun{
uhs <- data.table::fread(
  system.file("extdata", "uhs.csv", package = "newmark"))
fitSaF(uhs, vs30 = 360, vref = 760, ns = 500)
fitSaF(uhs, vs30 = 360, vref = 760,
       integrationMethod = "quadrature", quadratureOrder = 64)
} # }