% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/grs.R
\name{grs_validate}
\alias{grs_validate}
\title{Validate GRS predictive performance}
\usage{
grs_validate(
  data,
  grs_cols = NULL,
  outcome_col,
  time_col = NULL,
  covariates = NULL
)
}
\arguments{
\item{data}{A \code{data.frame} or \code{data.table}.}

\item{grs_cols}{Character vector of GRS column names to validate.
If \code{NULL} (default), all columns whose names contain \code{"grs"}
(case-insensitive) are selected automatically. All specified columns
must be numeric.}

\item{outcome_col}{Character scalar. Name of the outcome column
(\code{0}/\code{1} or \code{TRUE}/\code{FALSE}).}

\item{time_col}{Character scalar or \code{NULL}. Name of the follow-up
time column. When \code{NULL} (default), logistic regression is used;
when supplied, Cox regression is used.}

\item{covariates}{Character vector or \code{NULL}. Covariates for the
fully adjusted model. When \code{NULL}, only unadjusted and age-sex
adjusted models are run.}
}
\value{
A named \code{list} with four \code{data.table} elements:
\itemize{
\item \code{per_sd}: OR / HR per 1-SD increase in GRS.
\item \code{high_vs_low}: OR / HR for High vs Low extreme tertile.
\item \code{trend}: P-trend across Q1–Q4 quartiles.
\item \code{discrimination}: AUC (logistic) or C-index (Cox) with 95\\% CI.
}
}
\description{
For each GRS column, computes four sets of validation metrics:
\enumerate{
\item \strong{Per SD} - OR (logistic) or HR (Cox) per 1-SD increase.
\item \strong{High vs Low} - OR / HR comparing top 20\\% vs bottom 20\\%
(extreme tertile grouping: Low / Mid / High).
\item \strong{Trend test} - P-trend across quartiles (Q1–Q4).
\item \strong{Discrimination} - AUC (logistic) or C-index (Cox).
}
}
\details{
GRS grouping columns are created internally via \code{\link{derive_cut}}
and are not added to the user's data.  When \code{time_col} is
\code{NULL}, logistic regression is used throughout; when supplied, Cox
proportional hazards models are used.

Models follow the same adjustment logic as \code{\link{assoc_logistic}} /
\code{\link{assoc_coxph}}: unadjusted and age-sex adjusted models are
always included; a fully adjusted model is added when \code{covariates}
is non-\code{NULL}.
}
\examples{
\donttest{
dt <- ops_toy(scenario = "association", n = 500)
dt <- grs_standardize(dt, grs_cols = "grs_bmi")

res <- grs_validate(
  data        = dt,
  grs_cols    = "grs_bmi_z",
  outcome_col = "dm_status",
  time_col    = "dm_followup_years"
)
res$per_sd

if (requireNamespace("pROC", quietly = TRUE)) {
  res_logit <- grs_validate(
    data        = dt,
    grs_cols    = "grs_bmi_z",
    outcome_col = "dm_status"
  )
  res_logit$discrimination
}
}
}
