R/data.R

In weightflow: Declarative API for Staged Survey Weights

#' Example target population for weightflow
#'
#' A simulated population (sampling frame) of individuals nested in households
#' and primary sampling units (PSUs) within strata (regions), with demographic
#' auxiliaries and two outcomes. Used to illustrate calibration targets and
#' model calibration, and to validate weighted estimates. Generated by
#' `data-raw/weightflow_data.R`.
#'
#' @format A data frame with one row per person:
#' \describe{
#'   \item{person_id}{individual identifier}
#'   \item{household_id}{household identifier (cluster)}
#'   \item{psu}{primary sampling unit (segment) within the stratum}
#'   \item{region}{stratum: North, South, East or West}
#'   \item{sex}{F or M}
#'   \item{age}{age in years (18-95)}
#'   \item{income}{annual income}
#'   \item{employed}{employment indicator (0/1)}
#' }
"population"

#' Example survey sample (take-all roster)
#'
#' A stratified household sample drawn from `population` where every eligible
#' person in the household is kept (take-all roster). Carries unequal design
#' base weights, an unknown-eligibility flag and a person-level response
#' indicator; survey outcomes (income, employed) are observed only for
#' respondents. Generated by `data-raw/weightflow_data.R`.
#'
#' @format A data frame with one row per sampled person:
#' \describe{
#'   \item{person_id, household_id, psu}{identifiers}
#'   \item{region, sex, age}{frame auxiliaries, known for all units}
#'   \item{pw}{design base weight (inverse sampling fraction)}
#'   \item{unknown_elig}{1 if eligibility is unknown}
#'   \item{responded}{1 if the person responded}
#'   \item{income, employed}{survey outcomes; NA for nonrespondents}
#' }
"sample_survey"

#' Example survey sample (select-one-person, multistage)
#'
#' A realistic multistage design (stratum -> PSU -> household, then one selected
#' person per household). Unknown-eligibility and ineligible addresses appear as
#' single rows with no roster; resolved eligible households are either reached
#' (a roster is obtained) or are household nonresponse; in reached households one
#' person is selected with an unequal within-household probability and may or may
#' not respond. Supports the full household pipeline: household-level eligibility
#' (`cluster`), dropping ineligibles, household and person nonresponse, and
#' `step_select_within`. Generated by `data-raw/weightflow_data.R`.
#'
#' @format A data frame with one row per sampled household (the selected person,
#'   or a single placeholder row for non-roster cases):
#' \describe{
#'   \item{person_id, household_id, psu}{identifiers}
#'   \item{region}{stratum}
#'   \item{sex, age}{selected person's attributes (NA on non-roster rows)}
#'   \item{pw}{design base weight (product of the stage selection probabilities)}
#'   \item{status}{"eligible", "ineligible" or "unknown"}
#'   \item{disposition}{full field disposition as a single factor (a recode of
#'     the indicator columns): "eligible respondent", "eligible nonrespondent",
#'     "household nonresponse", "ineligible" or "unknown eligibility"}
#'   \item{unknown_elig}{1 if eligibility is unknown (no roster)}
#'   \item{ineligible}{1 if the address is out of scope (no roster)}
#'   \item{hh_responded}{1 reached, 0 household nonresponse, NA for non-eligible}
#'   \item{responded}{1 if the selected person responded (NA on non-roster rows)}
#'   \item{n_elig}{number of eligible persons in the household (NA on non-roster rows)}
#'   \item{p_within}{within-household selection probability of the selected person}
#'   \item{income, employed}{survey outcomes; NA unless the person responded}
#' }
"sample_one"