% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pnadc-experimental-periods.R
\name{pnadc_experimental_periods}
\alias{pnadc_experimental_periods}
\title{Experimental Period Identification Strategies}
\usage{
pnadc_experimental_periods(
  crosswalk,
  strategy = c("probabilistic", "upa_aggregation", "both"),
  confidence_threshold = 0.9,
  upa_proportion_threshold = 0.5,
  verbose = TRUE
)
}
\arguments{
\item{crosswalk}{A crosswalk data.table from \code{pnadc_identify_periods()}}

\item{strategy}{Character specifying which strategy to apply.
Options: "probabilistic", "upa_aggregation", "both"}

\item{confidence_threshold}{Numeric (0-1). Minimum confidence required to
assign a probabilistic period. Used by probabilistic and combined strategies.
Default 0.9.}

\item{upa_proportion_threshold}{Numeric (0-1). Minimum proportion of UPA
observations (within quarter) that must have strict identification with consensus
for extending to unidentified observations. Default 0.5.}

\item{verbose}{Logical. If TRUE, print progress information.}
}
\value{
A modified crosswalk with additional columns. Output is directly compatible
with \code{pnadc_apply_periods()}:
\itemize{
\item \code{ref_month_in_quarter}, \code{ref_month_in_year}, \code{ref_month_yyyymm}:
Month position (combined strict + experimental, strict takes priority)
\item \code{ref_fortnight_in_month}, \code{ref_fortnight_in_quarter}, \code{ref_fortnight_yyyyff}:
Fortnight position (combined strict + experimental)
\item \code{ref_week_in_month}, \code{ref_week_in_quarter}, \code{ref_week_yyyyww}:
Week position (combined strict + experimental)
\item \code{determined_month}, \code{determined_fortnight}, \code{determined_week}:
TRUE if period is assigned (strictly or experimentally)
\item \code{determined_probable_month}, \code{determined_probable_fortnight},
\code{determined_probable_week}: TRUE if period was assigned by probabilistic strategy
\item \code{probabilistic_assignment}: TRUE if any period was assigned experimentally
(vs strictly deterministic)
\item \code{week_1_start}, \code{week_1_end}, ..., \code{week_4_start}, \code{week_4_end}:
IBGE week boundaries for the assigned month
}
}
\description{
Three experimental strategies are available, all properly nested by period:
\itemize{
\item \strong{probabilistic}: For narrow ranges (2 possible periods),
classifies based on where most of the date interval falls. Assigns only
when confidence exceeds threshold.
\item \strong{upa_aggregation}: Extends strictly identified periods to other
observations in the same UPA-V1014 within the quarter, if a sufficient
proportion already have strict identification.
\item \strong{both}: Sequentially applies probabilistic strategy first, then
UPA aggregation on top. Guarantees identification rate >= max of individual strategies.
}
}
\details{
Provides experimental strategies for improving period identification rates
beyond the standard deterministic algorithm. All strategies respect the nested
identification hierarchy: weeks require fortnights, fortnights require months.
\subsection{Nesting Enforcement}{

All strategies enforce proper nesting:
\itemize{
\item Fortnights can only be assigned if month is identified (strictly OR experimentally)
\item Weeks can only be assigned if fortnight is identified (strictly OR experimentally)
}
}

\subsection{Probabilistic Strategy}{

For each period type (processed in order: months, then fortnights, then weeks):
\enumerate{
\item Check that the required parent period is identified
\item If bounds are narrowed to exactly 2 sequential periods, calculate
which period contains most of the date interval
\item Calculate confidence based on the proportion of interval in the likely period (0-1)
\item Only assign if confidence >= \code{confidence_threshold}
}

For months: aggregates at UPA-V1014 level across all quarters (like strict algorithm)
For fortnights and weeks: works at household level within quarter
}

\subsection{UPA Aggregation Strategy}{

Extends strictly identified periods based on consensus within geographic groups:
\itemize{
\item \strong{Months}: Uses UPA level within quarter
\item \strong{Fortnights/Weeks}: Uses UPA level within quarter (all households in same UPA
are interviewed in same fortnight/week within a quarter)
}
\enumerate{
\item Calculate proportion of observations with strictly identified period
\item If proportion >= \code{upa_proportion_threshold} AND consensus exists, extend
\item Apply in nested order: months first, then fortnights, then weeks
}
}

\subsection{Combined Strategy ("both")}{

Sequentially applies both strategies to maximize identification:
\enumerate{
\item First, apply the probabilistic strategy (captures observations with
narrow date ranges and high confidence)
\item Then, apply UPA aggregation (extends based on strict consensus
within UPA/UPA-V1014 groups)
}

This guarantees that "both" identifies at least as many observations as
either individual strategy alone. The strategies operate independently
(UPA aggregation considers only strict identifications), so the result
is the union of both strategies.
}

\subsection{Integration with Weight Calibration}{

The output can be passed directly to \code{pnadc_apply_periods()} for weight calibration.
The derived columns combine strict and experimental assignments, with strict taking priority. Use the
\code{probabilistic_assignment} flag to filter if you only want strict determinations.
}
}
\note{
These strategies produce "experimental" assignments, not strict determinations.
The standard \code{pnadc_identify_periods()} function should be used for
rigorous analysis. Experimental outputs are useful for:
\itemize{
\item Sensitivity analysis
\item Robustness checks
\item Research into identification algorithm improvements
}
}
\examples{
\dontrun{
crosswalk <- pnadc_identify_periods(pnadc_data)

crosswalk_exp <- pnadc_experimental_periods(
  crosswalk,
  strategy = "probabilistic",
  confidence_threshold = 0.9
)

crosswalk_exp[, .(
  strict = sum(!is.na(ref_month_in_quarter) & !probabilistic_assignment),
  experimental = sum(probabilistic_assignment, na.rm = TRUE),
  total = sum(determined_month)
)]

result <- pnadc_apply_periods(pnadc_data, crosswalk_exp,
                              weight_var = "V1028", anchor = "quarter")

strict_only <- crosswalk_exp[
  probabilistic_assignment == FALSE | is.na(probabilistic_assignment)
]
}

}
\seealso{
\code{\link{pnadc_identify_periods}} to build the crosswalk that this function modifies.
\code{\link{pnadc_apply_periods}} to apply period crosswalk and calibrate weights.
}
