% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/weigh.R
\name{weigh}
\alias{weigh}
\title{Weigh survey participants}
\usage{
weigh(survey, by, target = NULL, groups = NULL, ...)
}
\arguments{
\item{survey}{a \code{\link[=survey]{survey()}} object (must have been processed by
\code{\link[=assign_age_groups]{assign_age_groups()}} if using data frame target)}

\item{by}{column name in the participant data to weigh by}

\item{target}{target weights: \code{NULL} for direct numeric weighting, an
unnamed numeric vector (with \code{groups}), a named numeric vector, or a
data frame with columns \code{lower.age.limit} and \code{population}}

\item{groups}{a list of value sets mapping column values to groups (used
with unnamed \code{target} vector); must be the same length as \code{target}}

\item{...}{further arguments passed to \code{\link[=pop_age]{pop_age()}} when \code{target} is a data
frame}
}
\value{
the survey object with updated participant weights
}
\description{
Applies weights to participants in a \code{contact_survey} object. Weights are
always multiplied into an existing \code{weight} column (or one is created with
value 1), making multiple calls composable.

The behaviour depends on the combination of arguments:
\describe{
\item{\code{target = NULL}}{Numeric column: multiply \code{weight} by column values
directly.}
\item{Unnamed \code{target} + \code{groups}}{Map column values to groups, assign
\code{target[g] / n_in_group} per participant.}
\item{Named \code{target}}{Names match column values, assign
\code{target[val] / n_with_val} per participant.}
\item{Data frame \code{target}}{Post-stratify against population data (expanded
to single-year ages via \code{\link[=pop_age]{pop_age()}}).}
}
}
\examples{
data(polymod)
# Direct numeric weighting
if ("survey_weight" \%in\% names(polymod$participants)) {
  polymod |> weigh("survey_weight")
}

# Dayofweek weighting with groups (POLYMOD uses 0 = Sunday, 6 = Saturday)
polymod |>
  weigh("dayofweek", target = c(5, 2), groups = list(1:5, c(0, 6)))

}
