evaluate$incremental

Incremental predictive value beyond baseline covariates

Description

evaluate$incremental() quantifies model gain beyond a baseline covariate model for one or more PRS models.

Usage

evaluate$incremental(models = NULL, on, outcome, baseline.covariates, type = c("auto", "binary", "continuous", "survival"), time = NULL, event = NULL, obs = NULL, scores.layer = X, score.mode = c("compute.if.missing", "require", "recompute"), score.args = list(), metrics = NULL, conf.level = 0.95)

Arguments

models	Optional model specification.
on	Evaluation context (PolyGeniusData or genotype input). When genotype input is supplied, PolyGenius internally materializes a temporary PolyGeniusData object to resolve and evaluate scores.
outcome	Outcome definition. When on is PolyGeniusData: unquoted expression resolved on observations. When on is genotype input: vector of length n_obs, list of vectors (each length n_obs), or table with one or more columns and nrow == n_obs.
baseline.covariates	Unquoted baseline covariate expression(s), for example c(age, sex, pc1, pc2).
type	Outcome type (“auto”, “binary”, “continuous”, “survival”).
time	Unquoted time-to-event expression (required for survival).
event	Unquoted event-indicator expression (required for survival).
obs	Optional unquoted observation subset expression.
scores.layer	Score layer to read/use (symbol or single string).
score.mode	Score resolution mode. If on is a PolyGeniusData object, computed scores are written into that object. If on is genotype input, computed scores exist only in the temporary internal evaluation data object and are not returned.
score.args	Named list passed to compute$scores(…) when needed.
metrics	Optional metric subset; defaults by outcome type when NULL.
conf.level	Confidence level for interval estimates.
logger	Optional logger to pass and use within the function. Defaults NULL - creates a new logger

Value

A PolyGeniusEvaluation object only. Any temporary PolyGeniusData constructed from genotype input is not returned. Incremental artifacts are available via slotArtifacts(), including comparison: one row per outcome-model combination with outcome, model, and model.idx, plus the relevant baseline/full summary columns. Binary outputs include auc, brier, aic, and bic; continuous outputs include r2, rmse, mae, aic, and bic; survival outputs include c.index, aic, and bic, each as .base and .full pairs. Incremental diagnostics are available via slotDiagnostics(), including metric.flags for muffled model-fit warnings.

See Also

Other evaluate: evaluate.benchmark(), evaluate.calibration(), evaluate.compare(), evaluate.discrimination(), evaluate.risk.strata(), evaluate.similarity()