% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bone_markers.R
\name{bone_markers}
\alias{bone_markers}
\title{Compute Bone Health & Body-Composition Markers (HM-CS v3)}
\usage{
bone_markers(
  data,
  col_map = NULL,
  na_action = c("keep", "omit", "error"),
  verbose = TRUE
)
}
\arguments{
\item{data}{A \code{data.frame} or tibble with subject-level DXA/anthropometry data.}

\item{col_map}{Named list mapping keys to column names. Required keys:
\itemize{
\item \code{age}, \code{weight}, \code{height}, \code{ALM}, \code{FM}, \code{BMD}, \code{BMD_ref_mean}, \code{BMD_ref_sd}
Optional (passed-through if present and found in data): \code{TBS}, \code{HSA}, \code{PINP}, \code{CTX}, \code{BSAP}, \code{Osteocalcin}.
}}

\item{na_action}{One of "keep", "omit", or "error" controlling how
missing/non-finite input values are treated.}

\item{verbose}{Logical; if TRUE (default), emits progress messages via \code{hm_inform()}.}
}
\value{
A tibble with columns: \code{OSTA}, \code{ALMI}, \code{FMI}, \code{BMD_Tscore}, and
optionally \code{TBS}, \code{HSA}, \code{PINP}, \code{CTX}, \code{BSAP}, \code{Osteocalcin} (in that order).
}
\description{
Given DXA, anthropometry, and optional bone-turnover markers, computes:
\itemize{
\item OSTA: (weight - age) x 0.2
\item ALMI: Appendicular Lean Mass Index = ALM / height^2
\item FMI: Fat Mass Index = FM / height^2
\item BMD_Tscore: (BMD - ref_mean) / ref_sd
and (if in \code{col_map} + data) passes through: TBS, HSA, PINP, CTX, BSAP, Osteocalcin.
}
}
\details{
Notes:
\itemize{
\item Units: height in meters; ALM, FM, weight in kilograms; BMD in g/cm^2; ALMI/FMI in kg/m^2.
\item Non-finite values are treated as NA; division by zero is prevented by input checks.
\item \code{BMD_ref_mean} and \code{BMD_ref_sd} must be supplied by the user from an appropriate
reference population (for example, study-specific values or external norms such as NHANES).
}
}
\examples{
library(tibble)
df <- tibble(
  age = c(60, 72), weight = c(65, 50), height = c(1.65, 1.58),
  ALM = c(18.2, 14.7), FM = c(22.0, 20.5),
  BMD = c(0.95, 0.80), BMD_ref_mean = c(1.00, 1.00), BMD_ref_sd = c(0.12, 0.12)
)
col_map <- list(
  age = "age", weight = "weight", height = "height",
  ALM = "ALM", FM = "FM", BMD = "BMD",
  BMD_ref_mean = "BMD_ref_mean", BMD_ref_sd = "BMD_ref_sd"
)
bone_markers(df, col_map)

}
\references{
\insertRef{woo2002osta}{HealthMarkers}
\insertRef{who1994osteoporosis}{HealthMarkers}
}
