% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/core-constructors.R
\name{as_survey}
\alias{as_survey}
\title{Create a Taylor Series Linearization Survey Design}
\usage{
as_survey(
  data,
  ids = NULL,
  probs = NULL,
  weights = NULL,
  strata = NULL,
  fpc = NULL,
  nest = FALSE
)
}
\arguments{
\item{data}{A \code{data.frame} containing the survey responses. Must have at
least one row and unique column names.}

\item{ids}{<\code{\link[tidyselect:language]{tidy-select}}> Cluster (PSU) ID
column(s).
For single-stage: \code{ids = psu}. For multi-stage: \code{ids = c(psu, ssu)}.
Omit entirely for simple random sampling.}

\item{probs}{<\code{\link[tidyselect:language]{tidy-select}}> Sampling probability
column (a single column, values in (0, 1]). Converted to weights
\verb{= 1/probs} and stored internally. Cannot be used together with \code{weights}
unless the values are consistent (\code{weights == 1/probs}).}

\item{weights}{<\code{\link[tidyselect:language]{tidy-select}}> Sampling weight
column (a single column, values strictly > 0).}

\item{strata}{<\code{\link[tidyselect:language]{tidy-select}}> Stratification
variable column (a single column).}

\item{fpc}{<\code{\link[tidyselect:language]{tidy-select}}> Finite population
correction column(s). For single-stage designs, supply one column.
For multi-stage designs, supply one column per stage:
\code{fpc = c(fpc_stage1, fpc_stage2)}. Each column accepts either total
population size (integer, all > 1) or sampling fraction (numeric,
all in (0, 1]). Cannot contain \code{NA}. Cannot have more columns than
\code{ids} stages; fewer is allowed (later stages assume infinite population).}

\item{nest}{Logical. If \code{TRUE}, PSU IDs are treated as nested within
strata — i.e., the same ID value in two different strata refers to two
distinct PSUs. Set \code{nest = TRUE} when PSU IDs are not globally unique
(e.g., NHANES, where PSU IDs restart from 1 in each stratum). Requires
\code{strata} to be specified. Default \code{FALSE}.}
}
\value{
A \code{survey_taylor} object.
}
\description{
Creates a survey design object using Taylor series (linearization) for
variance estimation. Supports simple random samples, stratified designs,
single- and multi-stage cluster designs, and designs with finite population
correction. Uses a tidy-select interface for all design variable arguments.
}
\section{Tidy-select}{

All design variable arguments (\code{ids}, \code{probs}, \code{weights}, \code{strata},
\code{fpc}) support tidy-select syntax: bare column names, \code{c()} to combine
multiple columns (multi-stage \code{ids = c(psu, ssu)}, multi-stage \code{fpc}),
and tidyselect helpers like \code{starts_with()}. See the Examples section
below for runnable demonstrations.
}

\section{Simple random sample}{

When no \code{ids} or \code{strata} are specified, the result is a \code{survey_taylor}
object with \code{NULL} ids and strata — i.e., a simple random sample (SRS).
The Taylor variance machinery produces the same estimates as the classical
SRS formula \code{(1 - f) * s^2 / n}. If \code{weights} and \code{probs} are also both
omitted, uniform weights are assigned and a warning is issued.
}

\section{Known limitations}{

\code{as_survey()} does not support probability-proportional-to-size (PPS)
variance estimation. Taylor series linearization treats all designs as
with-replacement, which overestimates (is conservative for) variance in
PPS-without-replacement designs. The Yates-Grundy and Brewer/Overton
estimators available in \code{\link[survey:svydesign]{survey::svydesign()}} via its \code{pps} and \code{variance}
arguments are not supported.

If your design requires PPS-specific variance estimation, create the design
with \code{\link[survey:svydesign]{survey::svydesign()}} and convert it with \code{\link[=from_svydesign]{from_svydesign()}}:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{d_survey <- survey::svydesign(
  ids = ~psu, weights = ~wt, strata = ~stratum,
  pps = "brewer", data = mydata
)
d <- from_svydesign(d_survey)
}\if{html}{\out{</div>}}
}

\examples{
# Full NHANES design: stratified cluster with PSU IDs nested within strata
d <- as_survey(
  nhanes_2017,
  ids     = sdmvpsu,
  weights = wtint2yr,
  strata  = sdmvstra,
  nest    = TRUE
)

# Stratified design without PSU cluster IDs
d_strat <- as_survey(nhanes_2017, weights = wtint2yr, strata = sdmvstra)

# Blood pressure analysis: filter to exam participants, use MEC weight
exam <- nhanes_2017[nhanes_2017$ridstatr == 2, ]
d_bp <- as_survey(exam, ids = sdmvpsu, weights = wtmec2yr,
                  strata = sdmvstra, nest = TRUE)

# c() to combine multiple columns — sketched on a synthetic two-stage frame
df <- data.frame(
  psu = rep(1:5, each = 4),
  ssu = 1:20,
  wt  = runif(20, 0.5, 2)
)
d_ms <- as_survey(df, ids = c(psu, ssu), weights = wt)

# Tidy-select helpers like starts_with() also work
d_h <- as_survey(
  gss_2024,
  ids = vpsu,
  strata = vstrat,
  weights = starts_with("wtssn"),
  nest = TRUE
)

}
\references{
Sarndal, C-E., Swensson, B. and Wretman, J. (1991)
\emph{Model Assisted Survey Sampling}. Springer.

Lumley, T. (2004) Analysis of complex survey samples.
\emph{Journal of Statistical Software} \bold{9}(1), 1--19.

Lumley, T. (2010) \emph{Complex Surveys: A Guide to Analysis Using R}.
John Wiley and Sons.
}
\seealso{
\code{\link[=as_survey_replicate]{as_survey_replicate()}} for replicate-weight designs,
\code{\link[=as_survey_twophase]{as_survey_twophase()}} for two-phase designs,
\code{\link[=set_var_label]{set_var_label()}} to add variable labels

Other constructors: 
\code{\link{as_survey_nonprob}()},
\code{\link{as_survey_replicate}()},
\code{\link{as_survey_twophase}()},
\code{\link{survey_data}()},
\code{\link{survey_glm}()},
\code{\link{survey_glm_fit}()},
\code{\link{survey_nonprob}()},
\code{\link{survey_replicate}()},
\code{\link{survey_taylor}()},
\code{\link{survey_twophase}()}
}
\concept{constructors}
