% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pnadc-identify-periods.R
\name{pnadc_identify_periods}
\alias{pnadc_identify_periods}
\title{Identify Reference Periods in PNADC Data}
\usage{
pnadc_identify_periods(data, verbose = TRUE, store_date_bounds = FALSE)
}
\arguments{
\item{data}{A data.frame or data.table with PNADC microdata. Required columns:
\itemize{
\item \code{Ano}: Survey year
\item \code{Trimestre}: Quarter (1-4)
\item \code{UPA}: Primary Sampling Unit
\item \code{V1008}: Household id/sequence within UPA
\item \code{V1014}: Panel identifier
\item \code{V2008}: Birth day (1-31)
\item \code{V20081}: Birth month (1-12)
\item \code{V20082}: Birth year
\item \code{V2009}: Age
}
Optional but recommended:
\itemize{
\item \code{V2003}: Person sequence within household
}}

\item{verbose}{Logical. If TRUE (default), display progress information.}

\item{store_date_bounds}{Logical. If TRUE, stores date bounds and exception
flags in the crosswalk for optimization when calling
\code{pnadc_experimental_periods()}. This enables 10-20x speedup for the
probabilistic strategy by avoiding redundant computation. Default FALSE.}
}
\value{
A data.table crosswalk with columns:
\describe{
\item{Ano, Trimestre, UPA, V1008, V1014}{Join keys (year, quarter, UPA, household, panel)}
\item{ref_month_in_quarter}{Integer. Month position in quarter (1, 2, 3) or NA}
\item{ref_month_in_year}{Integer. Month position in year (1-12) or NA}
\item{ref_fortnight_in_month}{Integer. Fortnight position in month (1 or 2) or NA}
\item{ref_fortnight_in_quarter}{Integer. Fortnight position in quarter (1-6) or NA}
\item{ref_week_in_month}{Integer. Week position in month (1-4) or NA}
\item{ref_week_in_quarter}{Integer. Week position in quarter (1-12) or NA}
\item{date_min}{Date. Lower bound of the interview reference date for the individual. Only returned if store_date_bounds = TRUE}
\item{date_max}{Date. Upper bound of the interview reference date for the individual. Only returned if store_date_bounds = TRUE}
\item{week_1_start}{Date. Sunday of the IBGE first reference week of the month. Only returned if store_date_bounds = TRUE}
\item{week_1_end}{Date. Saturday of the IBGE first reference week of the month. Only returned if store_date_bounds = TRUE}
\item{week_2_start}{Date. Sunday of the IBGE second reference week of the month. Only returned if store_date_bounds = TRUE}
\item{week_2_end}{Date. Saturday of the IBGE second reference week of the month. Only returned if store_date_bounds = TRUE}
\item{week_3_start}{Date. Sunday of the IBGE third reference week of the month. Only returned if store_date_bounds = TRUE}
\item{week_3_end}{Date. Saturday of the IBGE third reference week of the month. Only returned if store_date_bounds = TRUE}
\item{week_4_start}{Date. Sunday of the IBGE fourth reference week of the month. Only returned if store_date_bounds = TRUE}
\item{week_4_end}{Date. Saturday of the IBGE fourth reference week of the month. Only returned if store_date_bounds = TRUE}
\item{month_max_upa}{Integer. Maximum month position across UPA-V1014 group (for debugging). Only returned if store_date_bounds = TRUE}
\item{month_min_upa}{Integer. Minimum month position across UPA-V1014 group (for debugging). Only returned if store_date_bounds = TRUE}
\item{fortnight_max_hh}{Integer. Maximum fortnight position within household (for debugging). Only returned if store_date_bounds = TRUE}
\item{fortnight_min_hh}{Integer. Minimum fortnight position within household (for debugging). Only returned if store_date_bounds = TRUE}
\item{week_min_hh}{Integer. Minimum week position within household (for debugging). Only returned if store_date_bounds = TRUE}
\item{week_max_hh}{Integer. Maximum week position within household (for debugging). Only returned if store_date_bounds = TRUE}
\item{ref_month_yyyymm}{Integer. Identified reference month in the format YYYYMM, where MM follows the IBGE calendar. 1 <= MM  <= 12}
\item{ref_fortnight_yyyyff}{Integer. Identified reference fortnight in the format YYYYFF, where FF follows the IBGE calendar. 1 <= FF  <= 24}
\item{ref_week_yyyyww}{Integer. Identified reference Week in the format YYYYWW, where WW follows the IBGE calendar. 1 <= WW  <= 48}
\item{determined_month}{Logical. Flags if the month was determined.}
\item{determined_fortnight}{Logical. Flags if the fortnight was determined.}
\item{determined_week}{Logical. Flags if the week was determined.}
}
}
\description{
PNADC is a quarterly survey, but each interview actually refers to a specific
temporal period within the quarter. This function identifies which month,
fortnight (quinzena), and week each observation belongs to, enabling
sub-quarterly time series analysis.

The algorithm uses a \strong{nested identification approach}:
\itemize{
\item \strong{Phase 1}: Identify MONTHS for all observations using:
\itemize{
\item IBGE's reference week timing rules (first reference week -- ending in a Saturday -- with sufficient days)
\item Respondent birthdates to constrain possible interview dates
\item UPA-panel level aggregation across ALL quarters (panel design)
\item Dynamic exception detection (identifies quarters needing relaxed rules)
}
\item \strong{Phase 2}: Identify FORTNIGHTS for month-determined observations:
\itemize{
\item Search space constrained to 2 fortnights within determined month
\item Household-level aggregation within each quarter
}
\item \strong{Phase 3}: Identify WEEKS for fortnight-determined observations:
\itemize{
\item Search space constrained to ~2 weeks within determined fortnight
\item Household-level aggregation within each quarter
}
}
}
\details{
Builds a crosswalk containing reference periods (month, fortnight,
and week) for PNADC survey data based on IBGE's interview timing rules.
\subsection{Temporal Granularity}{

The crosswalk contains three levels of temporal granularity:
\itemize{
\item \strong{Month}: 3 per quarter, ~97\\% determination rate with full series (aggregates across quarters)
\item \strong{Fortnight (quinzena)}: 6 per quarter, ~9\\% determination rate (within-quarter only)
\item \strong{Week}: 12 per quarter, ~3\\% determination rate (within-quarter only)
}
}

\subsection{Cross-Quarter Aggregation (Important!)}{

\strong{For optimal month determination rates, input data should be stacked across
multiple quarters} (ideally 4+ years). The algorithm leverages PNADC's
rotating panel design where the same UPA-V1014 is interviewed in the same
relative position across quarterly visits.
}

\subsection{Fortnight Definition}{

Fortnights are numbered 1-6 per quarter (2 per month), based on the IBGE
reference week calendar (not calendar days). Each IBGE "month" consists of
exactly 4 reference weeks (28 days), starting on a Sunday:
\itemize{
\item Fortnight 1 in month: IBGE weeks 1-2 (days 1-14 of the IBGE month)
\item Fortnight 2 in month: IBGE weeks 3-4 (days 15-28 of the IBGE month)
}
}
}
\note{
\subsection{Nested Identification Hierarchy}{

The algorithm enforces strict nesting by construction:
\itemize{
\item Fortnights can ONLY be identified for observations with determined months
\item Weeks can ONLY be identified for observations with determined fortnights
}

This guarantees: \code{determined_week => determined_fortnight => determined_month}
}

\subsection{Aggregation Levels}{

The crosswalk aggregates at different levels:
\itemize{
\item \strong{Months}: UPA-V1014 level across ALL quarters
(PNADC panel design ensures same month position)
\item \strong{Fortnights}: Household level within quarter only
\item \strong{Weeks}: Household level within quarter only
}
}
}
\examples{
\dontrun{
crosswalk <- pnadc_identify_periods(pnadc_stacked)

crosswalk[, .(
  month_rate = mean(determined_month),
  fortnight_rate = mean(determined_fortnight),
  week_rate = mean(determined_week)
)]

crosswalk[determined_fortnight, all(determined_month)]
crosswalk[determined_week, all(determined_fortnight)]

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

}
\seealso{
\code{\link{pnadc_apply_periods}} to apply the crosswalk and
calibrate weights
}
