% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/adiposity_sds.R
\name{adiposity_sds}
\alias{adiposity_sds}
\title{Calculate standardized scores (SDS) for adiposity measures}
\usage{
adiposity_sds(
  data,
  col_map = NULL,
  ref,
  na_action = c("keep", "omit", "error"),
  extreme_action = c("cap", "NA", "error", "warn", "ignore"),
  sds_cap = 6,
  diagnostics = FALSE,
  warn_thresholds = list(na_prop = 0.05, extreme_prop = 0.01),
  id_col = NULL,
  return_summary = FALSE,
  verbose = TRUE,
  na_strategy = NULL,
  extreme_strategy = NULL
)
}
\arguments{
\item{data}{data.frame or tibble containing the measurement columns.}

\item{col_map}{Optional named list mapping reference variable names to column names
in \code{data}. If NULL, identity mapping is assumed (names(ref) must be in data).}

\item{ref}{Named list where each element is a numeric vector with names
\code{mean} and \code{sd}, e.g. \code{list(BMI = c(mean = 23, sd = 4))}.}

\item{na_action}{One of \code{c("keep","omit","error")} for row handling when any
mapped variable is missing.}

\item{extreme_action}{One of \code{c("cap","NA","error","warn","ignore")} for
SDS values exceeding \code{sds_cap}.}

\item{sds_cap}{Positive numeric; absolute cap used when \code{extreme_action = "cap"}.}

\item{diagnostics}{Logical; if TRUE emit informational/warning messages
(coercions, missingness, extremes). FALSE suppresses non-critical warnings.}

\item{warn_thresholds}{Named list with optional elements \code{na_prop} (default 0.05)
and \code{extreme_prop} (default 0.01) used for proportion-based diagnostic warnings.}

\item{id_col}{Optional column name used only in verbose summaries.}

\item{return_summary}{Logical; if TRUE return a list with elements \code{data},
\code{summary}, and \code{warnings} instead of just the SDS tibble.}

\item{verbose}{Logical; if TRUE print progress and completion summaries.}

\item{na_strategy}{Soft-deprecated alias for \code{na_action} (if provided and
\code{na_action} missing, it is used).}

\item{extreme_strategy}{Soft-deprecated alias for \code{extreme_action} (if provided
and \code{extreme_action} missing, it is used).}
}
\value{
A tibble with one \verb{<var>_SDS} column per reference variable, or a
list when \code{return_summary = TRUE}.
}
\description{
Computes standard deviation (z) scores for anthropometric variables relative to
a single (non-sex-stratified) reference set of means and standard deviations.
Includes input validation, optional raw-value extreme screening/capping,
configurable handling of extreme SDS values, NA row policies, optional concise
summary output, and optional verbose progress messages.
}
\details{
SDS are computed as: (observed - mean) / sd. Rows are removed only when
\code{na_action = 'omit'}. Raw-value extreme screening (if enabled) is applied
before SDS computation. Extreme SDS handling (cap / warn / error / ignore)
is controlled by \code{extreme_action}. Legacy argument aliases (\code{na_strategy},
\code{extreme_strategy}) are soft-deprecated but still accepted.
}
\examples{
ref <- list(BMI = c(mean = 23, sd = 4), waist = c(mean = 80, sd = 12))
df <- data.frame(BMI = c(25, NA, 60, 18), waist = c(85, 70, 300, 55))
adiposity_sds(df, ref)

}
