Estimates quantiles and confidence intervals for them. This function was completely re-written for version 4.1 of the survey package, and has a wider range of ways to define the quantile. See the vignette for a list of them.

svyquantile(x, design, quantiles, ...)
# S3 method for survey.design
svyquantile(x, design, quantiles, alpha = 0.05,
interval.type = c("mean", "beta","xlogit", "asin","score"),
na.rm = FALSE,  ci=TRUE, se = ci,
qrule=c("math","school","shahvaish","hf1","hf2","hf3",
"hf4","hf5","hf6","hf7","hf8","hf9"),
df = NULL, ...)
# S3 method for svyrep.design
svyquantile(x, design, quantiles, alpha = 0.05,
interval.type = c("mean", "beta","xlogit", "asin","quantile"),
na.rm = FALSE, ci = TRUE, se=ci,
qrule=c("math","school","shahvaish","hf1","hf2","hf3",
"hf4","hf5","hf6","hf7","hf8","hf9"),
df = NULL, return.replicates=FALSE,...)

Arguments

x

A one-sided formula describing variables to be used

design

Design object

quantiles

Numeric vector specifying which quantiles are requested

alpha

Specified confidence interval coverage

interval.type

See Details below

na.rm

Remove missing values?

ci,se

Return an estimated confidence interval and standard error?

qrule

Rule for defining the quantiles: either a character string specifying one of the built-in rules, or a function

df

Degrees of freedom for confidence interval estimation: NULL specifies degf(design)

return.replicates

Return replicate estimates of the quantile (only for interval.type="quantile")

...

For future expansion

Details

The pth quantile is defined as the value where the estimated cumulative distribution function is equal to p. As with quantiles in unweighted data, this definition only pins down the quantile to an interval between two observations, and a rule is needed to interpolate. The default is the mathematical definition, the lower end of the quantile interval; qrule="school" uses the midpoint of the quantile interval; "hf1" to "hf9" are weighted analogues of type=1 to 9 in quantile. See the vignette "Quantile rules" for details and for how to write your own.

By default, confidence intervals are estimated using Woodruff's (1952) method, which involves computing the quantile, estimating a confidence interval for the proportion of observations below the quantile, and then transforming that interval using the estimated CDF. In that context, the interval.type argument specifies how the confidence interval for the proportion is computed, matching svyciprop. In contrast to oldsvyquantile, NaN is returned if a confidence interval endpoint on the probability scale falls outside [0,1].

There are two exceptions. For svydesign objects, interval.type="score" asks for the Francisco & Fuller confidence interval based on inverting a score test. According to Dorfmann & Valliant, this interval has inferior performance to the "beta" and "logit" intervals; it is provided for compatibility.

For replicate-weight designs, interval.type="quantile" ask for an interval based directly on the replicates of the quantile. This interval is not valid for jackknife-type replicates, though it should perform well for bootstrap-type replicates, BRR, and SDR.

The df argument specifies degrees of freedom for a t-distribution approximation to distributions of means. The default is the design degrees of freedom. Specify df=Inf to use a Normal distribution (eg, for compatibility).

When the standard error is requested, it is estimated by dividing the confidence interval length by the number of standard errors in a t confidence interval with the specified alpha. For example, with alpha=0.05 and df=Inf the standard error is estimated as the confidence interval length divided by 2*1.96.

Value

An object of class "newsvyquantile", except that with a replicate-weights design and interval.type="quantile" and return.replicates=TRUE it's an object of class "svrepstat"

References

Dorfman A, Valliant R (1993) Quantile variance estimators in complex surveys. Proceedings of the ASA Survey Research Methods Section. 1993: 866-871

Francisco CA, Fuller WA (1986) Estimation of the distribution function with a complex survey. Technical Report, Iowa State University.

Hyndman, R. J. and Fan, Y. (1996) Sample quantiles in statistical packages, The American Statistician 50, 361-365.

Shah BV, Vaish AK (2006) Confidence Intervals for Quantile Estimation from Complex Survey Data. Proceedings of the Section on Survey Research Methods.

Woodruff RS (1952) Confidence intervals for medians and other position measures. JASA 57, 622-627.

vignette("qrule", package = "survey") oldsvyquantile quantile

Examples

data(api)
## population
quantile(apipop$api00,c(.25,.5,.75)) #> 25% 50% 75% #> 565 667 761 ## one-stage cluster sample dclus1<-svydesign(id=~dnum, weights=~pw, data=apiclus1, fpc=~fpc) rclus1<-as.svrepdesign(dclus1) bclus1<-as.svrepdesign(dclus1,type="boot") svyquantile(~api00, dclus1, c(.25,.5,.75)) #>$api00
#>      quantile ci.2.5 ci.97.5       se
#> 0.25      552    492     627 31.47166
#> 0.5       652    561     714 35.66788
#> 0.75      719    696     777 18.88300
#>
#> attr(,"hasci")
#> [1] TRUE
#> attr(,"class")
#> [1] "newsvyquantile"
svyquantile(~api00, dclus1, c(.25,.5,.75),interval.type="beta")
#> $api00 #> quantile ci.2.5 ci.97.5 se #> 0.25 552 502 637 31.47166 #> 0.5 652 555 717 37.76599 #> 0.75 719 689 762 17.01801 #> #> attr(,"hasci") #> [1] TRUE #> attr(,"class") #> [1] "newsvyquantile" svyquantile(~api00, rclus1, c(.25,.5,.75)) #>$api00
#>      quantile ci.2.5 ci.97.5       se
#> 0.25      552    482     629 34.26914
#> 0.5       652    552     720 39.16473
#> 0.75      719    691     781 20.98111
#>
#> attr(,"hasci")
#> [1] TRUE
#> attr(,"class")
#> [1] "newsvyquantile"
svyquantile(~api00, rclus1, c(.25,.5,.75),interval.type="quantile")
#> Warning: Jackknife replicate weights may not give valid standard errors for quantiles
#> $api00 #> quantile ci.2.5 ci.97.5 se #> 0.25 552 452.3926 651.6074 46.44163 #> 0.5 652 558.8913 745.1087 43.41162 #> 0.75 719 679.4477 758.5523 18.44116 #> #> attr(,"hasci") #> [1] TRUE #> attr(,"class") #> [1] "newsvyquantile" svyquantile(~api00, bclus1, c(.25,.5,.75),interval.type="quantile") #>$api00
#>      quantile   ci.2.5  ci.97.5       se
#> 0.25      552 473.6719 630.3281 36.52023
#> 0.5       652 573.4258 730.5742 36.63496
#> 0.75      719 675.2491 762.7509 20.39872
#>
#> attr(,"hasci")
#> [1] TRUE
#> attr(,"class")
#> [1] "newsvyquantile"

svyquantile(~api00+ell, dclus1, c(.25,.5,.75), qrule="math")
#> $api00 #> quantile ci.2.5 ci.97.5 se #> 0.25 552 492 627 31.47166 #> 0.5 652 561 714 35.66788 #> 0.75 719 696 777 18.88300 #> #>$ell
#>      quantile ci.2.5 ci.97.5       se
#> 0.25       16      8      23 3.496851
#> 0.5        26     25      30 1.165617
#> 0.75       37     34      43 2.098111
#>
#> attr(,"hasci")
#> [1] TRUE
#> attr(,"class")
#> [1] "newsvyquantile"
svyquantile(~api00+ell, dclus1, c(.25,.5,.75), qrule="school")
#> $api00 #> quantile ci.2.5 ci.97.5 se #> 0.25 552 492 627 31.47166 #> 0.5 652 561 714 35.66788 #> 0.75 719 696 777 18.88300 #> #>$ell
#>      quantile ci.2.5 ci.97.5       se
#> 0.25       16      8      23 3.496851
#> 0.5        26     25      30 1.165617
#> 0.75       37     34      43 2.098111
#>
#> attr(,"hasci")
#> [1] TRUE
#> attr(,"class")
#> [1] "newsvyquantile"
svyquantile(~api00+ell, dclus1, c(.25,.5,.75), qrule="hf8")
#> $api00 #> quantile ci.2.5 ci.97.5 se #> 0.25 552.1667 491.6476 627.1866 31.59731 #> 0.5 652.0000 559.9436 714.5300 36.03772 #> 0.75 718.6667 691.5805 777.1490 19.94800 #> #>$ell
#>      quantile ci.2.5 ci.97.5       se
#> 0.25       16      8 23.0000 3.496851
#> 0.5        26     25 30.0000 1.165617
#> 0.75       37     34 43.2537 2.157253
#>
#> attr(,"hasci")
#> [1] TRUE
#> attr(,"class")
#> [1] "newsvyquantile"