% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/frailty_index.R
\name{frailty_index}
\alias{frailty_index}
\title{Compute Frailty (Deficit) Index using di::di with QA and verbose summaries}
\usage{
frailty_index(
  data,
  cols = NULL,
  invert = NULL,
  rescale = TRUE,
  age = NULL,
  rescale.custom = NULL,
  rescale.avoid = NULL,
  bins = 7,
  visible = FALSE,
  na_action = c("ignore", "warn", "error", "keep", "omit"),
  na_warn_prop = 0.2,
  return = c("list", "data"),
  verbose = TRUE
)
}
\arguments{
\item{data}{A data.frame or tibble of health deficits (ideally binary/logical or
scaled to \eqn{[0,1]}). Non-binary numeric columns can be rescaled by di::di when
rescale = TRUE.}

\item{cols}{Character vector of deficit column names to use. If NULL (default),
all numeric columns are used except age (if supplied).}

\item{invert}{Character vector of column names whose values should be inverted
by di::di (e.g., where higher values indicate better health).}

\item{rescale}{Logical; if TRUE, non-binary columns will be rescaled to \eqn{[0,1]}
by di::di. Default TRUE.}

\item{age}{Optional name of the column holding age (used by di for plotting and
optional age-binned outputs; excluded from auto-selected cols).}

\item{rescale.custom}{Advanced argument passed through to di::di.
See di::di documentation for syntax.}

\item{rescale.avoid}{Advanced argument passed through to di::di;
see di::di documentation for syntax.}

\item{bins}{Integer; number of age bins for FI-by-age plots. Default 7.}

\item{visible}{Logical; if TRUE and age is provided, di will draw a plot (via
plot.di()). Default FALSE.}

\item{na_action}{One of \code{c("keep","omit","error","warn","ignore")}. Controls
handling of missing values in selected deficit columns. \code{"keep"} (and its
backward-compatible alias \code{"ignore"}) passes NAs through to di::di.
\code{"warn"} emits a warning and then keeps NAs (alias for \code{"keep"} with a
missingness warning). \code{"omit"} drops rows with any NA in selected deficits
before computing. \code{"error"} stops if any NA is detected.
Default \code{"ignore"} (retained for backward compatibility; equivalent to \code{"keep"}).}

\item{na_warn_prop}{Proportion in \eqn{[0,1]} above which a high-missingness warning
is emitted (per column) when na_action = "warn". Default 0.2.}

\item{return}{One of c("list","data"). "list" (default) returns the original
di::di result (backward compatible). "data" returns a tibble with one row
per individual, columns: di (the frailty index) plus the selected deficit
columns (post-capping if applied). Age is included if present.}

\item{verbose}{Logical; if TRUE, prints progress and a completion summary.}
}
\value{
\itemize{
\item If return = "list" (default): the object returned by di::di (typically a list
with di and columns).
\item If return = "data": a tibble with di and the selected columns.
}
}
\description{
Thin wrapper around the di package's di() that:
\itemize{
\item Validates inputs and arguments.
\item Coerces tibbles to base data.frames (for di()'s class checks).
\item Auto-selects numeric deficit columns when cols = NULL (excluding age if supplied).
\item Optionally scans for missing/out-of-range values with warnings or errors.
\item Provides step-by-step verbose output and a completion summary.
\item Optionally returns a tidy tibble instead of the original list.
}
}
\details{
Background
The Frailty Index (FI) is computed as the proportion of health deficits present
in an individual across a set of candidate deficits. The approach was introduced
and formalized by Rockwood and Mitnitski and subsequently standardized for
construction and reporting.
}
\examples{
# Minimal example (runs only if the 'di' package is installed)
if (requireNamespace("di", quietly = TRUE)) {
  df <- data.frame(
    age = c(70, 75, 80),
    d1 = c(0, 1, 1),
    d2 = c(0.2, 0.8, 1.0),
    d3 = c(TRUE, FALSE, TRUE)
  )
  # Auto-select numeric deficits; returns list (di, columns)
  res <- frailty_index(df, cols = NULL, age = "age", verbose = TRUE)
  # Tidy tibble return
  tb  <- frailty_index(df, cols = c("d1","d2","d3"), age = "age",
                       return = "data", verbose = TRUE)
}

}
\references{
\insertRef{mitnitski2001deficit}{HealthMarkers}
\insertRef{rockwood2007frailty}{HealthMarkers}
\insertRef{searle2008frailtyindex}{HealthMarkers}
}
