Weighted mean and quantiles of pooled yield coefficients

Pools the yield-coefficient realizations of one or more displacement models with their epistemic weights and reduces the pool, at every admissible displacement, to its weighted mean, its weighted quantiles and the weighted share of roots that lie beyond the yield-coefficient grid.

Usage

summarizeKmax(roots, weights, levels)

Arguments

roots: The roots of solveKmax() for one or more models, bound by rows: IDn, realization, Da, kmax and beyond, one row per model, realization and Da; every pooled model must hold the same realizations at every Da.
weights: Named non-negative weights by model; the models with positive weight form the pool and must all be present in roots with the same realizations.
levels: Unique probabilities in (0, 1), distinct at two decimals.

Value

A data.table with one row per Da and level: Da (cm), level ("mean", then each probability formatted "%.2f"), kmax (g), the weighted mean or quantile of the pooled realizations at that Da, beyond, the weighted share of the pool beyond the grid, and n, the number of pooled roots (models times realizations), repeated on every level of one Da.

Mathematics

The positive weights $W_m$ of the pooled models are normalized, $w_m = W_m / \sum_l W_l$. Every model contributes the same realizations $s = 1, \dots, N_s$, so at one $D_a$ the pool holds the $N_m N_s$ roots $k_{m,s}$, each weighted by its model's $w_m$. The mean is $$\bar k_{max} = \frac{\sum_{m,s} w_m k_{m,s}}{\sum_{m,s} w_m}.$$ For the quantile of level $p$, the pooled values are sorted and equal values merged with their summed weights into $x_1 < \dots < x_K$ with cumulative weights $C_1 < \dots < C_K = W$; with $h = 1 + (W - 1) p$, $a = \max(\lfloor h \rfloor, 1)$ and $b = \min(a + 1, W)$, the quantile is $(1 - f)\, x(a) + f\, x(b)$, $f = h - \lfloor h \rfloor$, where $x(c)$ is the smallest $x_k$ with $C_k \ge c$ (or $x_K$ when none). This is the seventh sample quantile definition of Hyndman and Fan (1996) extended to cumulative weights, the estimator newmark 1.7.1 obtained from Hmisc::wtd.quantile(); for one model of unit weight it is the type-7 sample quantile of its $N_s$ roots. The share beyond the grid is $\sum_m w_m \bar b_m$, with $\bar b_m$ the fraction of the realizations of model $m$ whose root lies beyond the grid.

A root of 0 (a target above the ceiling of its realization, see solveKmax()) stays in the pool as a realization of null demand.

References

Hyndman, R. J. and Fan, Y. (1996). Sample quantiles in statistical packages. The American Statistician, 50(4), 361-365. doi:10.1080/00031305.1996.10473566

Examples

ky <- c(0.05, 0.10, 0.20, 0.30, 0.40)
Roots <- rbind(
  solveKmax(ky, matrix(0.10 / ky, 20, 5, byrow = TRUE), PGA = NULL, model = "AM88", Da = 1),
  solveKmax(ky, matrix(0.30 / ky, 20, 5, byrow = TRUE), PGA = NULL, model = "BT07", Da = 1))
summarizeKmax(Roots, weights = c(AM88 = 0.5, BT07 = 0.5), levels = c(0.05, 0.50, 0.95))
#>       Da  level  kmax beyond     n
#>    <num> <char> <num>  <num> <int>
#> 1:     1   mean   0.2      0    40
#> 2:     1   0.05   0.1      0    40
#> 3:     1   0.50   0.2      0    40
#> 4:     1   0.95   0.3      0    40