Quantile function of log spectral acceleration, monotone between its knots

Builds, from the tabulated quantiles of one spectral ordinate, the function \(Q(u) = \ln S_a(u)\) that sampleSpectra() uses to map the uniforms of its Gaussian copula to accelerations when a spectrum is given by quantiles.

Usage

buildQuantileSpline(quantiles)

Arguments

quantiles

A table with the probability levels p (numbers strictly between 0 and 1, or text that converts to them) and the finite positive spectral accelerations Sa of one ordinate. Rows with p equal to "mean" are ignored; a missing p is rejected; at least three quantile rows are required. Any other column must hold a single value, so that the rows belong to one spectrum slice. Duplicate levels signal a warning and are collapsed by the spline.

Value

A function of probabilities \(u\) returning \(\ln S_a\) (natural logarithm of the acceleration, in the units of Sa).

Mathematics

The quantile rows, sorted by probability, give the nodes \((p_i, \ln S_{a,i})\), \(0 < p_i < 1\), with finite logarithms because every \(S_{a,i}\) is finite and positive; a row outside these conditions stops the function. The ordinates are replaced by their running maximum, so that no node descends, and when two consecutive ordinates are then equal every ordinate is lifted by \(i \times 10^{-8}\). The function is the cubic spline through these nodes with the monotonicity filter of Hyman (1983) (stats::splinefun(method = "hyman")). Its argument is clamped to \([0, 1]\); between 0 and the first tabulated probability, and between the last one and 1, the end pieces of the spline extrapolate. The monotonicity filter constrains the spline between the tabulated knots only: an end piece can descend (observed on the tail fixture of the site-response tests above \(u = 0.9916\), on no slice the products sample). A change of the end pieces is a separate scientific candidate.

Examples

Q <- buildQuantileSpline(data.frame(p = c(0.16, 0.50, 0.84), Sa = c(0.3, 0.5, 0.8)))
exp(Q(c(0.16, 0.5, 0.84)))
#> [1] 0.3 0.5 0.8