Written and maintained by CASRAI Editorial Board
Published · Last updated
On this page
The survey R package (also searched as “survey package in R” or “survey package R”) is the CRAN package survey, written for analysing data from complex survey designs: stratified, clustered and multistage samples with unequal selection probabilities. You describe the design once with svydesign(), then pass that design object to functions such as svymean(), svytotal(), svyby() and svyglm() so that estimates and standard errors respect the sampling design. This page is for researchers and analysts working in R, with a note on the Python route at the end. Package details below were read from CRAN and the package documentation on 2026-11-11.
What the survey package is used for in research
Ordinary R functions such as mean() or lm() treat every row as an independent, equally likely draw. Survey data usually are not: respondents are sampled within strata and clusters and carry sampling weights. The package’s own site describes it as software for “analyzing data from complex surveys”, covering means, totals, ratios, quantiles, contingency tables, regression, loglinear models, survival curves and rank tests, for the whole sample and for subpopulations (domains).
According to the package site, variances can be computed by Taylor linearization or by replicate weights (BRR, jackknife, bootstrap or user-supplied), and the package handles multistage and probability-proportional-to-size (PPS) sampling, post-stratification, calibration (including GREG), weight trimming, two-phase designs, multiply imputed data and database-backed designs. Its companion book is Thomas Lumley, Complex Surveys: a guide to analysis using R. For background on how samples are drawn, see sampling methods and survey research methods.
How to install or access it
The package is published on CRAN. At the time of reading, CRAN listed version 4.5 (published 2026-02-24), depending on R (>= 4.1.0) plus grid, methods, Matrix and survival. The maintainer is Thomas Lumley, with Peter Gao, Ben Schneider and Stas Kolenikov listed as authors on the CRAN page. Install and load it with standard R commands (if you are new to installing packages, see how to install libraries in R):
install.packages("survey")library(survey)
The package website is r-survey.r-forge.r-project.org/survey. It still displays an older version number, so rely on the CRAN page for the current release.
Step-by-step: from a design to an estimate
The steps below use the api example data that ship with the package, and the example calls come from the svydesign help page.
- Load the package and the example data.
library(survey)thendata(api). This provides data frames includingapistrat(stratified sample) andapiclus1(one-stage cluster sample). - Declare the design with
svydesign(). The usage issvydesign(ids, probs=NULL, strata=NULL, variables=NULL, fpc=NULL, data=NULL, nest=FALSE, check.strata=!nest, weights=NULL, pps=FALSE, ...). Map your sampling plan to its arguments using the table below. Documented examples:dstrat <- svydesign(id=~1, strata=~stype, weights=~pw, data=apistrat, fpc=~fpc)dclus1 <- svydesign(id=~dnum, weights=~pw, data=apiclus1, fpc=~fpc)dclus2 <- svydesign(id=~dnum+snum, fpc=~fpc1+fpc2, data=apiclus2) - Estimate a mean or total.
svymean(~api00, dclus1, deff=TRUE)andsvytotal(~enroll, dclus1, deff=TRUE). The signature issvymean(x, design, na.rm=FALSE, deff=FALSE, ...). - Estimate by group.
svyby()computes survey statistics on subsets defined by factors; its signature issvyby(formula, by, design, FUN, ...), for examplesvyby(~births, ~oblevel, mydesign, svytotal). - Fit a model.
svyglm(formula, design, subset=NULL, family=stats::gaussian(), ...)fits a generalised linear model “with inverse-probability weighting and design-based standard errors”. Usesummary()on the result.
Mapping your sampling plan to svydesign arguments
| Design feature | Argument | What the documentation says |
|---|---|---|
| Clusters (PSUs) | ids (also written id) |
A formula of cluster identifiers from largest to smallest; ~0 or ~1 means no clusters. |
| Strata | strata |
A formula naming the stratification variable. |
| Finite population correction | fpc |
Population size per stratum, or the sampled fraction. |
| Sampling weights | weights (alternative to probs) |
Weights supplied as a formula; probs takes selection probabilities instead. |
| Cluster ids repeat across strata | nest=TRUE |
Relabels cluster ids so they nest within strata. |
| Probability-proportional-to-size sampling | pps |
Argument in the signature, default FALSE; the package site lists PPS designs as supported (see also the “Analysing PPS designs” vignette). |
Output and how to read it
A worked example from the UCLA Advanced Research Computing (OARC) FAQ on stratified random sampling (code tested there in 2013 with survey 3.29-5, so treat the numbers as an illustration, not as output of the current release) declares a stratified design and then estimates births in a sample of hospitals:
mydesign <- svydesign(id=~1, strata=~oblevel, data=mydata, weight=~weighta, fpc=~tothosp)svymean(~births, mydesign)svytotal(~births, mydesign)svyby(~births, ~oblevel, mydesign, svytotal)
That page reports a mean of 1164 (standard error 215), a total of 183,983 (standard error 34,014), and stratum totals of 14,931 (SE 2,670), 117,117 (SE 33,068) and 51,935 (SE 7,508) for strata 1 to 3.
- Estimate and SE. Each function returns the point estimate with a design-based standard error. Use the SE, not a naive standard deviation divided by the square root of n, when reporting uncertainty.
- Design effect. With
deff=TRUE,svymean()andsvytotal()also return the design effect, which the help page defines relative to simple random sampling without replacement;deff="replace"compares with sampling with replacement. A value above 1 means the design gives less precise estimates than simple random sampling of the same size. - Subgroups.
svyby()returns one row per level of thebyfactor, each with its own SE.
Troubleshooting
- Estimates return NA.
svymean()andsvytotal()default tona.rm=FALSE; setna.rm=TRUEto drop missing values. - Cluster ids are only unique within strata. Set
nest=TRUEso cluster identifiers are relabelled to nest within strata. Note thatcheck.stratadefaults to!nest. - Standard errors look too small or too large. Check that
weights(orprobs),strataandfpcwere all supplied as the sampling plan specifies; omittingfpcremoves the finite population correction. - Package will not install. The CRAN page lists R (>= 4.1.0) as a dependency; update R if yours is older.
- Next steps. CRAN lists vignettes for small area estimation, multiphase computations, estimates in subpopulations, two-phase designs in epidemiology, analysing PPS designs, pre-calibrated weights, quantile rules and a survey analysis example. For time-to-event outcomes in unweighted data, see survival analysis in R.
Free alternatives and related options
| Option | Language | What the source says |
|---|---|---|
| survey (this page) | R | Complex-survey estimation, regression, replicate weights, calibration, database-backed designs (CRAN, package site). |
| samplics | Python | PyPI: version 0.6.1 (released 2026-09-20), MIT licence, Python >=3.10,<3.15, installed with pip install samplics. The project page states samplics is no longer maintained and names svy (pip install svy) as the successor. |
If you are comparing R with menu-driven statistics software for this kind of work, see SPSS vs R.
FAQ
What is the survey package in R?
It is a CRAN package for analysing complex survey data. You define the sampling design with svydesign() and then use design-aware functions such as svymean(), svytotal(), svyby() and svyglm().
How do I install the survey package in R?
Run install.packages("survey") and then library(survey). CRAN lists R (>= 4.1.0) as a requirement for version 4.5.
Which function do I use to set up the design?
svydesign(), with ids for clusters, strata for strata, fpc for finite population correction and weights or probs for selection weights or probabilities.
Can I use survey weights with a regression model?
Yes. svyglm() takes a design object and fits a generalised linear model with inverse-probability weighting and design-based standard errors.
Is there a Python equivalent?
samplics on PyPI covers complex-sample selection, weighting and analysis, but its project page says it is no longer maintained and points to svy as the successor.
Sources
- CRAN: survey package page (version 4.5, read 2026-11-11).
- survey package website (read 2026-11-11).
- Package help pages for svydesign, svymean/svytotal, svyby and svyglm (read 2026-11-11).
- UCLA OARC: analysing survey data with a stratified random sampling design (read 2026-11-11).
- samplics on PyPI (read 2026-11-11).







