Weighted Quantiles for Hydrological Ensembles
wquantile.RdComputes weighted quantiles for each column of a matrix or data frame, or for each row when byrow=TRUE.
This function is a wrapper around wtd.quantile from the Hmisc package, adapted to hydrological ensemble analysis. It is particularly useful for summarising ensembles of simulated streamflow, groundwater levels, storage, or model parameters produced by multiple behavioural parameter sets, likelihood weights, or posterior samples.
In hydrology, this function is especially convenient for deriving uncertainty bands such as the 95% prediction uncertainty interval, weighted medians, or other weighted summary limits from GLUE-style or Bayesian ensembles.
Usage
wquantile(x, weights=NULL, byrow=FALSE, probs=c(.025, .5, .975),
normwt=TRUE, verbose=TRUE)Arguments
- x
A numeric matrix or data frame containing the values from which weighted quantiles will be computed.
By default, quantiles are computed for each column of
x. Therefore, rows usually represent ensemble members, behavioural parameter sets, posterior samples, or any other realisations, and columns represent variables, parameters, stations, or time steps.- weights
A numeric vector of weights used to compute the weighted quantiles. See
wtd.quantilefor details. Ifweightsis omitted,NULL, or a zero-length vector, the function returns the usual unweighted quantile estimates.When
byrow=FALSE,length(weights)must be equal tonrow(x).When
byrow=TRUE,length(weights)must be equal toncol(x).- byrow
Logical. Indicates whether weighted quantiles should be computed by column or by row.
When
byrow=FALSE(default), weighted quantiles are computed for each column ofx. This is the most common setting for hydrological applications in which rows correspond to alternative model runs or parameter sets, and columns correspond to time steps, sites, variables, or model parameters.When
byrow=TRUE, weighted quantiles are computed for each row ofx. This is useful when the values to be summarised are stored across columns instead of rows.- probs
Numeric vector of probabilities defining the quantiles to be computed. See
wtd.quantile.The default is c(.025, .5, .975), corresponding to the 2.5%, 50%, and 97.5% quantiles. In hydrological uncertainty analysis, these are often used to characterise the lower limit, median, and upper limit of an ensemble.
- normwt
Logical argument passed to
wtd.quantile. WhenTRUE, the suppliedweightsare normalised so that they sum to the effective sample size after removal of missing values.- verbose
Logical. If
TRUE, a progress bar is shown while quantiles are computed.
Value
A numeric matrix with one row for each summarised column of x when byrow=FALSE, or one row for each summarised row of x when byrow=TRUE. The number of columns in the returned matrix is length(probs).
Column names correspond to the requested quantiles expressed as percentages, for example "2.5%", "50%", and "97.5%". When available, row names are inherited from colnames(x) if byrow=FALSE, or from rownames(x) if byrow=TRUE.
References
Beven, K. and Binley, A. (2014). GLUE: 20 years on. Hydrological Processes, 28(24), 5897–5918. doi:10.1002/hyp.10082 .
Beven, K. and Binley, A. (1992). The future of distributed models: model calibration and uncertainty prediction. Hydrological Processes, 6(3), 279–298. doi:10.1002/hyp.3360060305 .
Author
Mauricio Zambrano-Bigiarini, mzb.devel@gmail.com
Examples
#########################################################################
# Example 1: Weighted quantiles of model parameters (Param1, ..., ParamN)
#########################################################################
# Matrix with 100 behavioural parameter sets (rows) and 10 parameters
# (columns). In this layout, quantiles are computed for each parameter.
set.seed(123)
params <- matrix(rnorm(1000), nrow=100, ncol=10)
colnames(params) <- paste0("Param", 1:10)
# Equal weights for all parameter sets
wquantile(params, weights=rep(1, nrow(params)), byrow=FALSE)
#>
|
| | 0%
|
|======= | 10%
|
|============== | 20%
|
|===================== | 30%
|
|============================ | 40%
|
|=================================== | 50%
|
|========================================== | 60%
|
|================================================= | 70%
|
|======================================================== | 80%
|
|=============================================================== | 90%
|
|======================================================================| 100%
#> 2.5% 50% 97.5%
#> Param1 -1.621172 0.061756309 1.925078
#> Param2 -1.610118 -0.225830038 2.051234
#> Param3 -1.467529 0.035914708 1.980068
#> Param4 -2.034167 -0.003508661 1.869833
#> Param5 -2.142979 0.165080945 1.753264
#> Param6 -1.736151 -0.087179580 1.761113
#> Param7 -2.023018 -0.106876884 1.833885
#> Param8 -1.951292 0.228719938 2.138721
#> Param9 -1.804381 0.103350994 2.245124
#> Param10 -1.815937 -0.023791526 2.302477
# Example with unequal GLUE-style weights
w <- runif(nrow(params))
wquantile(params, weights=w, byrow=FALSE, probs=c(0.05, 0.5, 0.95))
#>
|
| | 0%
|
|======= | 10%
|
|============== | 20%
|
|===================== | 30%
|
|============================ | 40%
|
|=================================== | 50%
|
|========================================== | 60%
|
|================================================= | 70%
|
|======================================================== | 80%
|
|=============================================================== | 90%
|
|======================================================================| 100%
#> 5% 50% 95%
#> Param1 -1.222952 0.11726848 2.050085
#> Param2 -1.464401 -0.03406725 1.913509
#> Param3 -1.240310 0.07062602 1.868627
#> Param4 -1.753237 -0.04250903 1.504666
#> Param5 -1.438507 0.17358411 1.712903
#> Param6 -1.456466 -0.10234651 1.375705
#> Param7 -1.859718 0.03763243 1.701522
#> Param8 -1.944379 0.28448595 1.745595
#> Param9 -1.464171 0.06022920 1.674855
#> Param10 -1.508059 -0.07753897 2.021328
#########################################################################
# Example 2: Weighted quantiles of simulated streamflow ensembles
#########################################################################
# Matrix with 10 behavioural parameter sets (rows) and 100 time steps
# (columns). In this layout, quantiles are computed for each simulated
# time step, yielding an uncertainty envelope through time.
sims <- matrix(rnorm(1000), nrow=10, ncol=100)
colnames(sims) <- paste0("t", 1:100)
# Equal weights for all simulations
wquantile(sims, weights=rep(1, nrow(sims)), byrow=FALSE)
#>
|
| | 0%
|
|= | 1%
|
|= | 2%
|
|== | 3%
|
|=== | 4%
|
|==== | 5%
|
|==== | 6%
|
|===== | 7%
|
|====== | 8%
|
|====== | 9%
|
|======= | 10%
|
|======== | 11%
|
|======== | 12%
|
|========= | 13%
|
|========== | 14%
|
|========== | 15%
|
|=========== | 16%
|
|============ | 17%
|
|============= | 18%
|
|============= | 19%
|
|============== | 20%
|
|=============== | 21%
|
|=============== | 22%
|
|================ | 23%
|
|================= | 24%
|
|================== | 25%
|
|================== | 26%
|
|=================== | 27%
|
|==================== | 28%
|
|==================== | 29%
|
|===================== | 30%
|
|====================== | 31%
|
|====================== | 32%
|
|======================= | 33%
|
|======================== | 34%
|
|======================== | 35%
|
|========================= | 36%
|
|========================== | 37%
|
|=========================== | 38%
|
|=========================== | 39%
|
|============================ | 40%
|
|============================= | 41%
|
|============================= | 42%
|
|============================== | 43%
|
|=============================== | 44%
|
|================================ | 45%
|
|================================ | 46%
|
|================================= | 47%
|
|================================== | 48%
|
|================================== | 49%
|
|=================================== | 50%
|
|==================================== | 51%
|
|==================================== | 52%
|
|===================================== | 53%
|
|====================================== | 54%
|
|====================================== | 55%
|
|======================================= | 56%
|
|======================================== | 57%
|
|========================================= | 58%
|
|========================================= | 59%
|
|========================================== | 60%
|
|=========================================== | 61%
|
|=========================================== | 62%
|
|============================================ | 63%
|
|============================================= | 64%
|
|============================================== | 65%
|
|============================================== | 66%
|
|=============================================== | 67%
|
|================================================ | 68%
|
|================================================ | 69%
|
|================================================= | 70%
|
|================================================== | 71%
|
|================================================== | 72%
|
|=================================================== | 73%
|
|==================================================== | 74%
|
|==================================================== | 75%
|
|===================================================== | 76%
|
|====================================================== | 77%
|
|======================================================= | 78%
|
|======================================================= | 79%
|
|======================================================== | 80%
|
|========================================================= | 81%
|
|========================================================= | 82%
|
|========================================================== | 83%
|
|=========================================================== | 84%
|
|============================================================ | 85%
|
|============================================================ | 86%
|
|============================================================= | 87%
|
|============================================================== | 88%
|
|============================================================== | 89%
|
|=============================================================== | 90%
|
|================================================================ | 91%
|
|================================================================ | 92%
|
|================================================================= | 93%
|
|================================================================== | 94%
|
|================================================================== | 95%
|
|=================================================================== | 96%
|
|==================================================================== | 97%
|
|===================================================================== | 98%
|
|===================================================================== | 99%
|
|======================================================================| 100%
#> 2.5% 50% 97.5%
#> t1 -0.9190035 0.400963565 1.05855523
#> t2 -1.0636710 0.193330112 1.71223972
#> t3 -0.9591599 -0.353141464 0.53043370
#> t4 -1.7356576 -0.111033503 1.68303554
#> t5 -1.9844581 0.464193220 1.60581589
#> t6 -1.3826095 -0.095015848 0.89003388
#> t7 -1.7603251 0.377477752 2.23342332
#> t8 -1.5388189 -0.317226372 2.78157999
#> t9 -1.0138459 -0.126527577 1.51612405
#> t10 -0.8243475 -0.129901176 0.99592047
#> t11 -1.1343496 0.030244525 1.21782103
#> t12 -1.8544449 -0.090591328 1.32023100
#> t13 -1.5938242 -0.055055815 1.21268540
#> t14 -1.8892283 -0.175303022 1.37872484
#> t15 -0.8507555 0.161026371 2.16459077
#> t16 -0.9364831 0.457101732 1.10544502
#> t17 -2.0424918 -0.794566972 0.70031104
#> t18 -1.9258682 -0.014141547 1.09277590
#> t19 -1.9097961 -0.257183294 1.74122925
#> t20 -0.7710852 0.467929040 1.41990438
#> t21 -1.0820251 0.409852414 1.23740835
#> t22 -0.3013224 0.583648932 1.36385603
#> t23 -0.2415052 0.139142193 0.92967448
#> t24 -2.2412413 -0.419344154 -0.06960293
#> t25 -0.6863340 0.220178709 1.71022653
#> t26 -1.2036012 -0.160995359 0.59804915
#> t27 -1.4884732 -0.059085486 1.32519644
#> t28 -1.9340133 -0.071857911 3.05553459
#> t29 -1.7691278 -0.252463762 0.78920540
#> t30 -1.4401234 -0.682578757 1.22326150
#> t31 -1.4818173 -0.075003898 1.75751141
#> t32 -0.9437714 0.622597775 1.76628951
#> t33 -1.3975318 -0.745383166 1.14547211
#> t34 -1.7928971 0.432174733 0.70547927
#> t35 -1.1889323 0.309946549 1.25013232
#> t36 -1.5631010 -0.026530670 1.34898421
#> t37 -0.9323158 0.407937434 0.89868982
#> t38 -0.5234044 0.144284870 1.45891950
#> t39 -2.5767743 -0.042768202 0.75639562
#> t40 -1.9359839 -0.020794182 1.18968858
#> t41 -0.2932992 0.806173519 1.74229720
#> t42 -0.8596481 0.297638276 0.72006621
#> t43 -1.8396409 -0.771825413 0.82909380
#> t44 -0.7300079 0.695971744 2.01345121
#> t45 -1.1049468 0.491243545 2.01524047
#> t46 -0.8959518 0.496591563 1.90067038
#> t47 -1.2848896 -0.177769705 1.04638163
#> t48 -1.1854272 -0.103885601 1.32972101
#> t49 -0.2797247 0.315622254 1.58810423
#> t50 -1.2235069 0.221847467 1.53663449
#> t51 -1.2568400 -0.390069979 0.94050917
#> t52 -1.0465519 0.053879463 0.97576624
#> t53 -1.3969851 -0.276753898 1.21199530
#> t54 -1.2905623 -0.120515734 1.56292628
#> t55 -2.2253366 -0.101047078 1.71744463
#> t56 -1.4591638 0.223532491 2.29803173
#> t57 -1.3717200 0.285262568 1.11898617
#> t58 -0.5003895 0.592646314 2.92736854
#> t59 -1.9141834 -0.277413585 1.31221377
#> t60 -1.7345094 -0.383091455 1.57912646
#> t61 -2.1125078 -0.500723016 1.29275198
#> t62 -1.4312703 0.502434714 1.47813999
#> t63 -0.6331576 0.421155193 1.38032982
#> t64 -2.2106611 -0.101203392 1.16395622
#> t65 -1.6388296 -0.143810521 1.56618077
#> t66 -2.6098356 0.415091250 1.85105346
#> t67 -1.1195745 -0.144951285 2.36248123
#> t68 -1.9417481 -0.725783724 0.25798233
#> t69 -1.3970210 0.127463695 1.44122542
#> t70 -1.1705955 -0.099314136 1.75817515
#> t71 -1.0263645 0.313234335 1.37971346
#> t72 -1.5548686 -0.022658995 2.06930143
#> t73 -1.7517024 -0.025717696 1.82358920
#> t74 -1.0549784 0.228353178 1.09039268
#> t75 -1.0605356 0.136751316 1.35238743
#> t76 -1.3786300 -0.004635510 1.51304522
#> t77 -0.6332518 -0.004951647 0.94560868
#> t78 -1.3515418 0.234208543 1.64661779
#> t79 -1.8711580 -0.186881572 1.39369186
#> t80 -1.4408521 -0.255918217 0.91509004
#> t81 -2.4425329 0.378903949 2.09366211
#> t82 -1.3503689 -0.164287412 1.45899274
#> t83 -1.6537851 0.604999322 2.24440867
#> t84 -1.5578544 0.225631422 1.23845860
#> t85 -1.1925634 -0.122377406 1.27650701
#> t86 -2.2428007 -0.180850211 1.61438564
#> t87 -0.9973887 0.177740989 2.17220171
#> t88 -2.1629680 0.061935099 1.24855884
#> t89 -2.1448382 -0.397104830 1.20341979
#> t90 -0.7779871 0.129762739 2.47527417
#> t91 -0.4112554 0.073141686 1.82849452
#> t92 -1.8707659 -0.079033522 1.86410398
#> t93 -1.1225024 0.112321095 1.47515685
#> t94 -1.4656678 0.184649980 1.68090735
#> t95 -1.2388633 0.161721438 0.83806381
#> t96 -1.5451703 -0.526596447 1.85999083
#> t97 -1.0968717 0.196208178 1.03917356
#> t98 -1.0603512 0.030202463 2.04349360
#> t99 -1.0515288 0.042072814 1.17135327
#> t100 -1.5052148 -0.185094583 0.63520642
# Weighted uncertainty band using likelihood-based weights, one weight
# for each one of the 10 behavioural parameter sets
wsim <- c(0.30, 0.15, 0.10, 0.10, 0.08, 0.08, 0.07, 0.05, 0.04, 0.03)
wquantile(sims, weights=wsim, byrow=FALSE, probs=c(0.025, 0.5, 0.975))
#>
|
| | 0%
|
|= | 1%
|
|= | 2%
|
|== | 3%
|
|=== | 4%
|
|==== | 5%
|
|==== | 6%
|
|===== | 7%
|
|====== | 8%
|
|====== | 9%
|
|======= | 10%
|
|======== | 11%
|
|======== | 12%
|
|========= | 13%
|
|========== | 14%
|
|========== | 15%
|
|=========== | 16%
|
|============ | 17%
|
|============= | 18%
|
|============= | 19%
|
|============== | 20%
|
|=============== | 21%
|
|=============== | 22%
|
|================ | 23%
|
|================= | 24%
|
|================== | 25%
|
|================== | 26%
|
|=================== | 27%
|
|==================== | 28%
|
|==================== | 29%
|
|===================== | 30%
|
|====================== | 31%
|
|====================== | 32%
|
|======================= | 33%
|
|======================== | 34%
|
|======================== | 35%
|
|========================= | 36%
|
|========================== | 37%
|
|=========================== | 38%
|
|=========================== | 39%
|
|============================ | 40%
|
|============================= | 41%
|
|============================= | 42%
|
|============================== | 43%
|
|=============================== | 44%
|
|================================ | 45%
|
|================================ | 46%
|
|================================= | 47%
|
|================================== | 48%
|
|================================== | 49%
|
|=================================== | 50%
|
|==================================== | 51%
|
|==================================== | 52%
|
|===================================== | 53%
|
|====================================== | 54%
|
|====================================== | 55%
|
|======================================= | 56%
|
|======================================== | 57%
|
|========================================= | 58%
|
|========================================= | 59%
|
|========================================== | 60%
|
|=========================================== | 61%
|
|=========================================== | 62%
|
|============================================ | 63%
|
|============================================= | 64%
|
|============================================== | 65%
|
|============================================== | 66%
|
|=============================================== | 67%
|
|================================================ | 68%
|
|================================================ | 69%
|
|================================================= | 70%
|
|================================================== | 71%
|
|================================================== | 72%
|
|=================================================== | 73%
|
|==================================================== | 74%
|
|==================================================== | 75%
|
|===================================================== | 76%
|
|====================================================== | 77%
|
|======================================================= | 78%
|
|======================================================= | 79%
|
|======================================================== | 80%
|
|========================================================= | 81%
|
|========================================================= | 82%
|
|========================================================== | 83%
|
|=========================================================== | 84%
|
|============================================================ | 85%
|
|============================================================ | 86%
|
|============================================================= | 87%
|
|============================================================== | 88%
|
|============================================================== | 89%
|
|=============================================================== | 90%
|
|================================================================ | 91%
|
|================================================================ | 92%
|
|================================================================= | 93%
|
|================================================================== | 94%
|
|================================================================== | 95%
|
|=================================================================== | 96%
|
|==================================================================== | 97%
|
|===================================================================== | 98%
|
|===================================================================== | 99%
|
|======================================================================| 100%
#> 2.5% 50% 97.5%
#> t1 -0.78026714 0.331434398 1.05855523
#> t2 -0.89426543 1.076342313 1.71223972
#> t3 -0.92583562 0.004275170 0.53513796
#> t4 -1.54150868 0.496206816 1.90504358
#> t5 -1.98445814 0.795030389 1.76990411
#> t6 -1.30735656 0.480449948 0.91599206
#> t7 -0.85049280 0.377477752 2.23342332
#> t8 -1.25827250 -0.484210256 2.78157999
#> t9 -0.93413490 0.186180961 1.33415591
#> t10 -0.65943691 -0.329038830 0.99299293
#> t11 -0.93040944 0.030244525 1.21782103
#> t12 -1.14512042 0.141437012 1.26367359
#> t13 -0.87137552 0.385154824 1.34164029
#> t14 -0.79636093 0.040732199 1.37872484
#> t15 -0.69698756 0.161026371 2.16459077
#> t16 -0.75751016 0.619850075 1.10544502
#> t17 -1.50839147 0.032850300 0.70031104
#> t18 -1.90093287 0.014473894 1.09277590
#> t19 -1.60611390 -0.366368559 1.95366788
#> t20 -0.77108522 0.365911465 1.41990438
#> t21 -0.76010023 0.622905462 1.23740835
#> t22 -0.30132236 0.741277377 1.34975982
#> t23 -0.24144230 0.513392084 0.92967448
#> t24 -2.10023236 -0.419344154 -0.06960293
#> t25 -0.01112403 0.653495766 1.77323863
#> t26 -1.10193531 -0.535665928 0.59804915
#> t27 -0.73379341 0.577702536 1.34262392
#> t28 -1.70331706 -0.188079517 3.05553459
#> t29 -1.28443709 -0.252463762 0.78920540
#> t30 -1.08507522 -0.218593817 1.45996594
#> t31 -1.43356218 -0.146427488 1.75751141
#> t32 -0.10786025 1.008241467 1.90013633
#> t33 -1.39753180 -0.491405300 1.14547211
#> t34 -0.89499735 0.446313017 0.70547927
#> t35 -1.07364299 -0.165829605 1.25013232
#> t36 -1.08611824 -0.356168690 1.34898421
#> t37 -0.89149483 0.285598045 0.89868982
#> t38 -0.25051029 0.144284870 1.45891950
#> t39 -2.03706250 0.435966260 0.78443825
#> t40 -1.61468375 -0.006846303 1.37305204
#> t41 0.45546596 1.101588428 1.85057170
#> t42 -0.86822405 0.297638276 0.72956036
#> t43 -1.77347479 -0.433389022 0.82195054
#> t44 -0.45481941 0.956717552 2.01345121
#> t45 -1.10494680 0.768007714 2.01524047
#> t46 -0.88384796 -0.307257233 1.90067038
#> t47 -1.27373681 -0.238248696 1.04638163
#> t48 -0.52912411 0.051734173 1.23431471
#> t49 -0.24145112 0.577645998 1.76202090
#> t50 -0.07296487 0.862651686 1.53663449
#> t51 -1.09529852 -0.021794540 0.94050917
#> t52 -0.68602400 -0.100272080 0.99347998
#> t53 -0.73787904 0.081912310 1.32590834
#> t54 -1.29056231 -0.632016102 1.56292628
#> t55 -2.14489702 -0.390159754 1.57604709
#> t56 -0.56239452 -0.249235849 2.29803173
#> t57 -0.57137012 0.901116045 1.14426271
#> t58 -0.54762762 0.349363952 3.29051744
#> t59 -2.09481463 -0.448814258 1.31221377
#> t60 -1.22844457 -0.523259455 1.57912646
#> t61 -2.16260815 -0.500723016 1.29275198
#> t62 -1.38212575 0.796490362 1.47460360
#> t63 -0.63315764 0.421155193 1.38032982
#> t64 -0.81528051 0.352826406 1.16395622
#> t65 -1.63882962 0.296472169 1.56618077
#> t66 -2.46779640 -0.192560211 1.85105346
#> t67 -1.11957453 -0.391563058 2.57726810
#> t68 -1.35454416 0.209632833 0.25921795
#> t69 -1.39702096 0.628643462 1.59848755
#> t70 -0.83383463 -0.060013253 1.75817515
#> t71 -1.02636452 0.150548955 1.37971346
#> t72 -1.55486864 -0.556961652 2.06930143
#> t73 -0.74325614 -0.049677912 1.82358920
#> t74 -0.83517098 0.256559481 1.09039268
#> t75 -1.06053557 0.307227748 1.35238743
#> t76 -1.28936419 -0.150484494 1.51304522
#> t77 -0.53555358 0.249570906 0.92360084
#> t78 -1.24085359 0.000669868 1.64661779
#> t79 -1.67930919 0.015460510 1.27048443
#> t80 -1.02070719 0.405922111 0.91509004
#> t81 -2.62932544 0.273320574 2.09366211
#> t82 -1.21317463 0.466214356 1.39695797
#> t83 -0.40505289 1.163214544 2.24440867
#> t84 -1.55782225 -0.054598655 1.23845860
#> t85 -1.28901947 -0.168153251 1.31432067
#> t86 -0.87641575 0.694079181 1.61438564
#> t87 -0.99738867 0.858580218 2.44799801
#> t88 -2.33594733 -0.084213957 1.24855884
#> t89 -1.35461872 -0.195898856 1.20341979
#> t90 -0.77798708 1.028492954 2.47527417
#> t91 -0.34033282 0.126147069 1.82849452
#> t92 -1.42845961 -0.079033522 2.01129298
#> t93 -1.02935610 0.865535746 1.47515685
#> t94 -1.46412936 0.248959433 1.65290452
#> t95 -1.09713965 -0.106843177 0.92551124
#> t96 -0.63728823 -0.511603722 1.85999083
#> t97 -0.83599931 0.196208178 1.03917356
#> t98 -0.69740811 0.130006761 2.04349360
#> t99 -1.09321744 -0.225429834 1.11103518
#> t100 -1.39918403 0.045993767 0.65272261