Skip to main content
v2026.11,986 entries · CC-BY 4.0

Survey R Package: svydesign, svymean and a Worked Example

Install the survey R package, declare a complex design with svydesign(), estimate means and totals with svymean and svytotal, and read SEs and design effects.

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.

  1. Load the package and the example data. library(survey) then data(api). This provides data frames including apistrat (stratified sample) and apiclus1 (one-stage cluster sample).
  2. Declare the design with svydesign(). The usage is svydesign(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)
  3. Estimate a mean or total. svymean(~api00, dclus1, deff=TRUE) and svytotal(~enroll, dclus1, deff=TRUE). The signature is svymean(x, design, na.rm=FALSE, deff=FALSE, ...).
  4. Estimate by group. svyby() computes survey statistics on subsets defined by factors; its signature is svyby(formula, by, design, FUN, ...), for example svyby(~births, ~oblevel, mydesign, svytotal).
  5. 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”. Use summary() 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() and svytotal() 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 the by factor, each with its own SE.

Troubleshooting

  • Estimates return NA. svymean() and svytotal() default to na.rm=FALSE; set na.rm=TRUE to drop missing values.
  • Cluster ids are only unique within strata. Set nest=TRUE so cluster identifiers are relabelled to nest within strata. Note that check.strata defaults to !nest.
  • Standard errors look too small or too large. Check that weights (or probs), strata and fpc were all supplied as the sampling plan specifies; omitting fpc removes 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.
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

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about Survey R Package: svydesign, svymean and a Worked Example

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →