% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pulmo_markers.R
\name{pulmo_markers}
\alias{pulmo_markers}
\title{Calculate pulmonary function markers (FEV1/FVC, z-scores, percent predicted, LLN, etc.)}
\usage{
pulmo_markers(
  data,
  col_map = NULL,
  equation = c("GLI", "GLIgl", "NHANES3"),
  na_action = c("keep", "omit", "error"),
  na_warn_prop = 0.2,
  verbose = TRUE
)
}
\arguments{
\item{data}{A data.frame or tibble with columns:
\itemize{
\item \code{age}       (numeric): years
\item \code{sex}       (character or numeric): "male"/"female" (case-insensitive) or codes 1/2 or 0/1
\item \code{height}    (numeric): cm or m (auto-detected)
\item \code{ethnicity} (character): e.g. "Caucasian", "African-American", "NE Asian", "SE Asian", "Other/Mixed"
\item \code{fev1}      (numeric): observed FEV1 in L
\item \code{fvc}       (numeric): observed FVC in L
}}

\item{col_map}{Optional named list mapping canonical keys (\code{age}, \code{sex}, \code{height},
\code{ethnicity}, \code{fev1}, \code{fvc}) to actual column names in \code{data}. If \code{NULL},
column names are inferred automatically.}

\item{equation}{One of \code{c("GLI","GLIgl","NHANES3")} (see \code{rspiro} for details).
GLIgl ignores ethnicity.}

\item{na_action}{One of \code{c("keep","omit","error")} for handling missing values in
required inputs. Default "keep".}

\item{na_warn_prop}{Proportion \eqn{[0,1]} to trigger high-missingness warnings on
required inputs. Default 0.2.}

\item{verbose}{Logical; if \code{TRUE} prints progress messages and a completion summary.}
}
\value{
A tibble with columns:
\itemize{
\item \code{fev1_pred}, \code{fev1_z},   \code{fev1_pctpred}, \code{fev1_LLN}
\item \code{fvc_pred},  \code{fvc_z},    \code{fvc_pctpred},  \code{fvc_LLN}
\item \code{fev1_fvc_ratio}, \code{fev1_fvc_pred}, \code{fev1_fvc_z}, \code{fev1_fvc_pctpred},
\code{fev1_fvc_LLN} (\code{NA} if the equation lacks native FEV1/FVC support in rspiro)
}
}
\description{
Uses the \code{rspiro} reference equations to compute predicted normals,
z-scores, percent predicted and lower limits of normal (LLN) for FEV1, FVC,
and the FEV1/FVC ratio.
}
\details{
Inputs are validated, missingness is handled via \code{na_action}, and heights are
auto-detected as cm when any height > 3; otherwise interpreted as metres (no
automatic unit conversion beyond that heuristic, preserving prior behavior).
}
\note{
\code{fev1_fvc_z}, \code{fev1_fvc_pred}, and \code{fev1_fvc_LLN} are computed via
rspiro's native FEV1/FVC parameter (equivalent to \code{param = "FEV1FVC"}).
If that parameter is not supported by the installed rspiro version or
equation, these columns fall back gracefully: \code{fev1_fvc_z} and
\code{fev1_fvc_LLN} become \code{NA}; \code{fev1_fvc_pred} falls back to
\code{fev1_pred / fvc_pred}.
}
\examples{
if (requireNamespace("rspiro", quietly = TRUE)) {
  df <- data.frame(
    age = c(40, 55), sex = c("male", "female"),
    height = c(175, 162), ethnicity = c("Caucasian", "Caucasian"),
    fev1 = c(3.5, 2.4), fvc = c(4.4, 3.1)
  )
  pulmo_markers(df)
}
}
\references{
\insertRef{quanjer2012}{HealthMarkers}
\insertRef{hankinson1999spirometry}{HealthMarkers}
\insertRef{bowerman2023gli}{HealthMarkers} (race-neutral GLI global equations and interpretation framework; used by rspiro's \code{GLIgl} equation)
}
\seealso{
rspiro
}
