% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pnadc-apply-periods.R
\name{pnadc_apply_periods}
\alias{pnadc_apply_periods}
\title{Apply Reference Period Crosswalk to PNADC Data}
\usage{
pnadc_apply_periods(
  data,
  crosswalk,
  weight_var,
  anchor,
  calibrate = TRUE,
  calibration_unit = c("month", "fortnight", "week"),
  calibration_min_cell_size = 1,
  target_totals = NULL,
  smooth = FALSE,
  keep_all = TRUE,
  verbose = TRUE
)
}
\arguments{
\item{data}{A data.frame or data.table with PNADC microdata. Must contain
join keys \code{Ano}, \code{Trimestre}, \code{UPA}, \code{V1008}, and
\code{V1014} to merge with the crosswalk.}

\item{crosswalk}{A data.table crosswalk from \code{\link{pnadc_identify_periods}}.}

\item{weight_var}{Character. Name of the survey weight column. Must be specified:
\itemize{
\item \code{"V1028"} for quarterly PNADC data
\item \code{"V1032"} for annual PNADC data (visit-specific or annual releases organized by quarters)
}}

\item{anchor}{Character. How to anchor the weight redistribution. Must be specified:
\itemize{
\item \code{"quarter"} for quarterly data or annual releases organized by quarters (preserves quarterly totals)
\item \code{"year"} for annual visit-specific data (preserves yearly totals)
}}

\item{calibrate}{Logical. If TRUE (default), calibrate weights to external
population totals. If FALSE, only merge the crosswalk without calibration.}

\item{calibration_unit}{Character. Temporal unit for weight calibration.
One of \code{"month"} (default), \code{"fortnight"}, or \code{"week"}.}

\item{calibration_min_cell_size}{Integer. Minimum sample size required in a cell
for it to be used in hierarchical raking. Cells smaller than this threshold
are collapsed to coarser levels. Default: 1 (use all cells).}

\item{target_totals}{Optional data.table with population targets. If NULL
(default), fetches monthly population from SIDRA and derives targets for
fortnight/week. Each time period (month, fortnight, or week) is calibrated
to the FULL Brazilian population from SIDRA.

If providing custom targets, the population column (\code{m_populacao} for
months, \code{f_populacao} for fortnights, \code{w_populacao} for weeks)
must be in \strong{thousands}. The function multiplies by 1000 internally.}

\item{smooth}{Logical. If TRUE, smooth calibrated weights to
remove quarterly artifacts. Smoothing is adapted per time period:
monthly (3-period window), fortnight (7-period window), weekly (no smoothing).
Default: FALSE.}

\item{keep_all}{Logical. If TRUE (default), keep all observations including
those with undetermined reference periods. If FALSE, drop undetermined rows.}

\item{verbose}{Logical. If TRUE (default), print progress messages.}
}
\value{
A data.table with the input data plus crosswalk columns:
\describe{
\item{ref_month_in_quarter, ref_month_in_year}{Month position (1-3 in quarter, 1-12 in year)}
\item{ref_fortnight_in_month, ref_fortnight_in_quarter}{Fortnight position (1-2 in month, 1-6 in quarter)}
\item{ref_week_in_month, ref_week_in_quarter}{Week position (1-4 in month, 1-12 in quarter)}
\item{ref_month_yyyymm, ref_fortnight_yyyyff, ref_week_yyyyww}{Integer period codes}
\item{determined_month, determined_fortnight, determined_week}{Logical determination flags}
\item{weight_monthly, weight_fortnight, or weight_weekly}{Calibrated weights (if calibrate=TRUE)}
}
}
\description{
This function takes a crosswalk from \code{\link{pnadc_identify_periods}} and
applies it to any PNADC dataset (quarterly or annual). It can optionally
calibrate the survey weights to match external population totals at the
chosen temporal granularity (month, fortnight, or week).
}
\details{
Merges a reference period crosswalk with PNADC microdata and optionally
calibrates survey weights for sub-quarterly analysis.
\subsection{Weight Calibration}{

When \code{calibrate = TRUE}, the function performs hierarchical rake weighting:
\enumerate{
\item Groups observations by nested demographic/geographic cells
\item Iteratively adjusts weights so sub-period totals match anchor-period totals
\item Calibrates final weights against external population totals (FULL Brazilian population)
\item Optionally smooths weights to remove quarterly artifacts
}
}

\subsection{Population Targets}{

All time periods (months, fortnights, and weeks) are calibrated to the FULL
Brazilian population from SIDRA. This means:
\itemize{
\item Monthly weights sum to the Brazilian population for that month
\item Fortnight weights sum to the Brazilian population for the containing month
\item Weekly weights sum to the Brazilian population for the containing month
}
}

\subsection{Hierarchical Raking Levels}{

The number of hierarchical cell levels is automatically adjusted based on the
calibration unit to avoid sparse cell issues:
\itemize{
\item \code{"month"}: 4 levels (age, region, state, post-stratum) - full hierarchy
\item \code{"fortnight"}: 2 levels (age, region) - simplified for lower sample size
\item \code{"week"}: 1 level (age groups only) - minimal hierarchy for sparse data
}
}

\subsection{Anchor Period}{

The \code{anchor} parameter determines how weights are redistributed:
\itemize{
\item \code{"quarter"}: Quarterly totals are preserved and redistributed to months/fortnights/weeks
\item \code{"year"}: Yearly totals are preserved and redistributed to months/fortnights/weeks
}

Use \code{anchor = "quarter"} with quarterly V1028 weights, and
\code{anchor = "year"} with annual V1032 weights.
}
}
\examples{
\dontrun{
crosswalk <- pnadc_identify_periods(pnadc_stacked)

result <- pnadc_apply_periods(
  pnadc_2023,
  crosswalk,
  weight_var = "V1028",
  anchor = "quarter"
)

result <- pnadc_apply_periods(
  pnadc_annual,
  crosswalk,
  weight_var = "V1032",
  anchor = "year"
)

result <- pnadc_apply_periods(
  pnadc_2023,
  crosswalk,
  weight_var = "V1028",
  anchor = "quarter",
  calibration_unit = "week"
)

result <- pnadc_apply_periods(
  pnadc_2023,
  crosswalk,
  weight_var = "V1028",
  anchor = "quarter",
  calibrate = FALSE
)
}

}
\seealso{
\code{\link{pnadc_identify_periods}} to build the crosswalk
}
