% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/derive.R
\name{derive_missing}
\alias{derive_missing}
\title{Handle informative missing labels in UKB decoded data}
\usage{
derive_missing(
  data,
  cols = tidyselect::everything(),
  action = c("na", "unknown"),
  extra_labels = NULL
)
}
\arguments{
\item{data}{(data.frame or data.table) Decoded UKB data, typically output
of \code{\link{decode_values}} followed by \code{\link{decode_names}}.}

\item{cols}{(tidyselect) Columns to process. Default: \code{everything()}
(all columns). Non-character columns in the selection are silently skipped.}

\item{action}{(character) One of \code{"na"} (default) or \code{"unknown"}.
\itemize{
\item \code{"na"}: convert all informative missing labels to \code{NA}.
\item \code{"unknown"}: convert informative missing labels to
\code{"Unknown"}, preserving them as a distinct model category.
}
Empty strings are always converted to \code{NA} regardless of this
parameter.}

\item{extra_labels}{(character or NULL) Additional labels to treat as
informative missing, appended to the built-in list. Default: \code{NULL}.}
}
\value{
The input \code{data} with missing labels replaced in-place.
Always returns a \code{data.table}.
}
\description{
After \code{\link{decode_values}} converts categorical codes to character
labels, some values represent meaningful non-response rather than true data:
\code{"Do not know"}, \code{"Prefer not to answer"}, and
\code{"Prefer not to say"}. This function either converts them to \code{NA}
(for complete-case analysis) or retains them as \code{"Unknown"} (to
preserve the informative missingness as a model category).
}
\details{
Empty strings (\code{""}) are always converted to \code{NA} regardless of
\code{action}, as they carry no informational content.

Only character columns are modified; numeric, integer, Date, and logical
columns are silently skipped.

\strong{data.table pass-by-reference}: when the input is a
\code{data.table}, modifications are made in-place via
\code{\link[data.table]{set}}. The returned object and the original variable
point to the same memory. If you need to preserve the original, pass
\code{data.table::copy(data)} instead.
}
\examples{
dt <- ops_toy(n = 100)
derive_missing(dt)

# Retain informative non-response as a model category
derive_missing(dt, action = "unknown")

# Add a custom label
derive_missing(dt, extra_labels = "Not applicable")
}
