process_na_build: Handle missing values at the build stage (first layer)

Description

Process NA for `est_pw()` before estimation step. Resolves the `na.action` argument to a standard mode string, applies NA filtering to `sc` and `sp`, subsets the survey design object(s) in `sp_des` to match the filtered `sp`, and produces a summary of exclusions.

Usage

process_na_build(sc, sp, sp_des, p_formula, na.action, n_ref, verbose = FALSE)

Value

A list with the following elements:

`na_mode`: Character string: one of `"omit"`, `"exclude"`, `"fail"`, or `"pass"`.
`sc`: The cleaned nonprobability sample data frame.
`sp`: The cleaned reference survey data frame(s).
`sp_des`: The subsetted survey design object(s).
`keep_sc`: Logical vector indicating which rows of the original `sc` are retained.
`keep_sp`: Logical vector (one-reference) or list of logical vectors (multi-reference) indicating which rows of each `sp` are retained.
`n_sp_orig`: Original row count(s) of `sp_des` before subsetting.
`na_action_obj`: An lm-style `na.action` attribute for `sc`, or `NULL` if no rows were removed.
`log_messages`: Character vector of per-variable NA detail messages from `handle_na_for_ipwm()`, suitable for appending to the running `log_messages` in `est_pw()`.
`na_summary`: A `pw_na_summary` object with row counts before and after NA removal, or `NULL` if no rows were excluded.

Arguments

sc: A data frame. The nonprobability sample (before NA removal).
sp: A data frame (one-reference case) or a named list of data frames (multi-reference case). Analysis data extracted from the reference survey design(s).
sp_des: A single survey design object (one-reference case) or a named list of survey design objects (multi-reference case). Subsetted to align with the filtered `sp`.
p_formula: A one-sided formula (one-reference case) or a list of one-sided formulas (multi-reference case) specifying the participation model variables used to identify rows with missing values.
na.action: A function (`stats::na.omit`, `stats::na.exclude`, `stats::na.fail`, or `stats::na.pass`), an equivalent character string, or `NULL` (which inherits from `getOption("na.action")`).
n_ref: Integer. Number of reference surveys. Controls whether one-reference or multi-reference logic is applied when subsetting `sp_des` and computing `n_sp_orig`.
verbose: Logical. If `TRUE`, prints per-dataset row counts and exclusion totals via `message()`.