Contents

evaluate$profile

Evaluation profile of PRS models

evaluate$profile() runs the evaluate components in one call, so one object shows how well each PRS model predicts, associates, stratifies risk and compares with the others.

Usage

evaluate$profile(
  data,
  outcomes,
  covariates = NULL,
  scores.layer = X,
  split.by = NULL,
  quantiles = c(0.2, 0.8),
  reference = "lowest",
  compare.metric = NULL,
  reference.model = NULL,
  bootstrap = 1000,
  conf.level = 0.95,
  p.adjust.method = "BH"
)

Arguments

Argument	Description
`data`	A [PolyGeniusStudy](/reference/polygeniusstudy/). Holds the score layer and the sample columns the other arguments name. It is not modified.
`outcomes`	Unquoted outcome expression resolved from data: a bare column, an expression such as status == "case", an [outcome()](/reference/outcome/) descriptor, or a c() or list() of these whose names label the outcomes. The type is binary or continuous, inferred from the values unless the descriptor sets it. A [surv()](/reference/surv/) outcome aborts.
`covariates`	Unquoted covariate expression resolved from data, such as c(age, sex, PC1), or NULL (default). A character vector aborts. Supplying it switches [evaluate$incremental()](/reference/evaluate-incremental/) on, and is passed to it and to [evaluate$association()](/reference/evaluate-association/) and [evaluate$stratification()](/reference/evaluate-stratification/) as their adjustment set.
`scores.layer`	Unquoted name of an existing score layer, default X. The layer is used as supplied: nothing is scored or standardised here.
`split.by`	Unquoted expression naming factor, character or logical sample columns, or NULL (default). Adds rows for each level beside the overall stratum = "all" rows. A level named "all" aborts.
`quantiles`	Numeric vector strictly increasing in (0, 1), default c(0.2, 0.8). The band cut points of [evaluate$stratification()](/reference/evaluate-stratification/).
`reference`	"lowest" (default) or a band label such as "20-80%". The reference band of [evaluate$stratification()](/reference/evaluate-stratification/).
`compare.metric`	Character vector with at most one value per outcome type, or NULL (default). Passed as metric to [evaluate$compare()](/reference/evaluate-compare/), which lists the values and the default.
`reference.model`	Character scalar, a character vector named by outcome, or NULL (default). The reference model of [evaluate$compare()](/reference/evaluate-compare/). NULL takes select's per-outcome top model. Outcomes a named vector leaves out take it too. An outcome with no top model, because every score is NA, takes compare's own NULL rule.
`bootstrap`	Non-negative integer, default 1000. Replicates behind the percentile intervals of [evaluate$performance()](/reference/evaluate-performance/), [evaluate$incremental()](/reference/evaluate-incremental/) and [evaluate$compare()](/reference/evaluate-compare/). 0 returns estimates without bootstrap intervals. Resampling draws from the caller's random number stream.
`conf.level`	Numeric scalar in (0, 1), default 0.95.
`p.adjust.method`	One of stats::p.adjust.methods, default "BH". Passed to every component that carries p-values, which applies it within analysis, outcome, metric and stratum. [evaluate$performance()](/reference/evaluate-performance/) and [evaluate$redundancy()](/reference/evaluate-redundancy/) carry none.

Value

A PolyGeniusEvaluation following the schema-evaluation schema. $results has the columns listed in evaluate and holds every component's rows, one analysis value per component. $artifacts holds the performance artifacts (confusion for a binary outcome, score.outcome.bins for a continuous one). $indices$multiplicity holds every component's adjustment families. $diagnostics holds the components' diagnostics. $provenance describes this call.

$metadata holds the outcome labels, the covariate columns, scores.layer, the split.by columns, quantiles, reference, bootstrap, conf.level and p.adjust.method. When compare runs, it also holds compare's resolved metric per outcome as compare.metric. Per outcome, named by label, it records reference.model, compare's reference, and reference.selected, FALSE only where the caller named the reference. Both are NA when compare does not run.

Details

It always runs evaluate$performance(), evaluate$association() and evaluate$stratification(). It runs evaluate$incremental() only when covariates is given, passing it on together with association and stratification. It runs evaluate$redundancy() and evaluate$compare() only when scores.layer has two or more columns. Redundancy runs with method = "score.pearson" only; call evaluate$redundancy() directly for the variant-overlap methods.

Before compare, it ranks the models with evaluate$select() on the performance and incremental rows. Compare then contrasts every model against select's per-outcome top model, unless reference.model names one. Contrasts against a data-selected reference are biased away from 0.

The parts are combined with merge.PolyGeniusEvaluation(). Each component's p-values stay adjusted within its own families, and nothing is re-adjusted. Rows are told apart by analysis.

Each argument reaches only the components that take it. A model's n therefore differs across components: performance and compare take no covariates, so their complete cases can include samples the others drop. The shared rules and the tune/test pattern for selecting models are on the evaluate page.

bootstrap, conf.level and p.adjust.method are checked before any component runs. Every other argument is checked by the component that takes it.

Examples

ev <- evaluate$profile(study, outcomes = c(case = status == "case"))

# Add incremental value over the covariates, then rank the models.
ev <- evaluate$profile(
  study,
  outcomes   = c(case = status == "case"),
  covariates = c(age, sex, PC1, PC2)
)
evaluate$select(ev)