% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/core-constructors.R
\name{as_survey_twophase}
\alias{as_survey_twophase}
\title{Create a Two-Phase Survey Design}
\usage{
as_survey_twophase(
  phase1,
  ids2 = NULL,
  strata2 = NULL,
  probs2 = NULL,
  fpc2 = NULL,
  subset,
  method = c("full", "approx", "simple")
)
}
\arguments{
\item{phase1}{A survey design object (inheriting from \code{survey_base})
representing the Phase 1 design. Accepts \code{survey_taylor} or
\code{survey_replicate} objects.
Its \verb{@data} must contain ALL rows from both phases, plus a logical
indicator column for Phase 2 membership. Create with \code{\link[=as_survey]{as_survey()}}
or \code{\link[=as_survey_replicate]{as_survey_replicate()}}.}

\item{ids2}{<\code{\link[tidyselect:language]{tidy-select}}> Phase 2 cluster ID
column(s). For single-stage Phase 2: \code{ids2 = psu2}. For multi-stage:
\code{ids2 = c(psu2, ssu2)}. Omit if Phase 2 has no within-stratum
clustering.}

\item{strata2}{<\code{\link[tidyselect:language]{tidy-select}}> Phase 2
stratification column (a single column). Optional.}

\item{probs2}{<\code{\link[tidyselect:language]{tidy-select}}> Phase 2 inclusion
probability column (a single column, values in (0, 1]). Optional.}

\item{fpc2}{<\code{\link[tidyselect:language]{tidy-select}}> Phase 2 finite
population correction column (a single column). Optional.}

\item{subset}{<\code{\link[tidyselect:language]{tidy-select}}> Single logical column
in \code{phase1@data}. \code{TRUE} = row selected into Phase 2;
\code{FALSE} = Phase 1 only. Required. Must contain both \code{TRUE} and \code{FALSE}
values (non-degenerate).}

\item{method}{Character. Variance estimation method for combining Phase 1
and Phase 2 variability. One of \code{"full"} (default), \code{"approx"}, or
\code{"simple"}. Case-sensitive. See Details.}
}
\value{
A \code{survey_twophase} object.
}
\description{
Creates a two-phase (double) sampling design from an existing
\code{survey_taylor} Phase 1 object. Phase 1 covers all rows; Phase 2 is a
strict subset indicated by a logical column. Uses a tidy-select interface
for all Phase 2 design variable arguments.
}
\details{
\subsection{Variance methods}{
\itemize{
\item \code{"full"} — Full two-phase variance formula. Accounts for variability in
both phases. Requires Phase 2 design information (\code{probs2}, \code{ids2},
\code{strata2}) when Phase 2 is not a simple random subsample. If none of
these are provided, a warning is issued and Phase 2 selection is treated
as SRS within Phase 1 strata.
\item \code{"approx"} — Approximation that ignores Phase 1 sampling variability.
Faster but less accurate than \code{"full"} when the Phase 1 sampling fraction
is non-negligible.
\item \code{"simple"} — Treats Phase 2 as a single-phase design, ignoring Phase 1.
Only valid when Phase 1 is a census (no sampling). Issues a warning when
Phase 1 has PSU cluster variables, because this understates variance for
clustered designs.
}
}
}
\examples{
# Minimal two-phase design: Phase 1 = full cohort, Phase 2 = random subset
df <- data.frame(
  id        = 1:20,
  wt        = rep(2, 20),
  in_phase2 = c(rep(TRUE, 10), rep(FALSE, 10)),
  y         = rnorm(20)
)
phase1 <- as_survey(df, ids = id, weights = wt)
d2 <- as_survey_twophase(phase1, subset = in_phase2)

# With Phase 2 stratification and inclusion probabilities
df2 <- data.frame(
  id          = 1:30,
  wt          = rep(3, 30),
  in_phase2   = c(rep(TRUE, 15), rep(FALSE, 15)),
  arm         = rep(c("A", "B", "C"), 10),
  subsamprate = rep(c(0.5, 0.7, 0.3), 10),
  y           = rnorm(30)
)
phase1b <- as_survey(df2, ids = id, weights = wt)
d2b <- as_survey_twophase(
  phase1b,
  strata2 = arm,
  probs2  = subsamprate,
  subset  = in_phase2,
  method  = "full"
)

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

Breslow, N.E. and Chatterjee, N. (1999) Design and analysis of two-phase
studies with binary outcome applied to Wilms tumour prognosis.
\emph{Applied Statistics} \bold{48}, 457--468.

Breslow, N., Lumley, T., Ballantyne, C.M., Chambless, L.E. and Kulick, M.
(2009) Improved Horvitz-Thompson estimation of model parameters from
two-phase stratified samples: applications in epidemiology.
\emph{Statistics in Biosciences}.
\doi{10.1007/s12561-009-9001-6}
}
\seealso{
\code{\link[=as_survey]{as_survey()}} for Taylor series designs,
\code{\link[=as_survey_replicate]{as_survey_replicate()}} for replicate-weight designs

Other constructors: 
\code{\link{as_survey}()},
\code{\link{as_survey_nonprob}()},
\code{\link{as_survey_replicate}()},
\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}
