evaluate$discrimination

Discrimination metrics for PRS models

Description

evaluate$discrimination() quantifies how well one or more PRS models separate observations with different outcome values.

The API is model-centric:

  • models defines what to evaluate.

  • on defines where to evaluate (a cohort context).

on may be:

  • a PolyGeniusData object, or

  • one or more GenotypeInfo objects (which are converted to a temporary PolyGeniusData using the supplied models).

Usage

`evaluate$discrimination`(models = NULL, on, outcome, 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, bootstrap = 2000, conf.level = 0.95)

Arguments

models

Optional model specification. Supported forms:

  • NULL (when on is PolyGeniusData: use all models in on)

  • PolyGeniusModel/PolyGeniusModelSet

  • model selector expression when on is PolyGeniusData

  • model perturbation function (when on is PolyGeniusData)

on

Evaluation context: PolyGeniusData, GenotypeInfo, GenotypeInfoSet, or list of GenotypeInfo. 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.

type

Outcome type. One of “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:

  • “require” uses existing scores only,

  • “compute.if.missing” computes only when missing,

  • “recompute” always recomputes. 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 scoring is required.

metrics

Optional metric subset. If NULL, defaults are selected by outcome type.

bootstrap

Number of bootstrap replicates used for AUC and PR-AUC confidence intervals (binary outcomes).

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. Discrimination artifacts are available via slotArtifacts():

  • scores for all outcome types: one row per evaluated observation and model with model, model.idx, obs.idx, score, outcome, and outcome.value; survival outcomes add time.

  • confusion for binary outcomes: one row per threshold with tp, fp, tn, fn, plus derived columns such as sensitivity, specificity, precision, npv, accuracy, recall, tpr, and fpr. For continuous outcomes, undefined pearson.r values (for example due to zero variance) are returned as NA and flagged in slotDiagnostics(x, “metric.flags”).

See Also

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