Contents

outcome

Outcome descriptor for non-survival outcomes

outcome() declares a binary or continuous outcome and how to code it. Write it inline as the outcomes argument of an evaluate$*() or associate$*() call, on its own or as an element of a list().

Usage

outcome(
  value,
  type = c("auto", "binary", "continuous"),
  label = NULL,
  event = NULL,
  positive = NULL,
  transform = NULL,
  prevalence = NULL
)

Arguments

Argument	Description
`value`	Unquoted expression, resolved from the call's data. Usually a bare column name. Required: outcome() without it aborts.
`type`	One of "auto" (default), "binary", "continuous". "auto" infers the type from the resolved values; an explicit type skips inference.
`label`	Character scalar, or NULL (default). Label the results are keyed by; NULL falls back to the outcomes-list name, then to the deparsed value expression.
`event`	Value scored as the event of a binary outcome, or NULL (default). It must be one of the outcome's values. NULL takes TRUE, 1 or a two-level factor's second level; a character column needs it.
`positive`	Alias for event, used only when event is NULL.
`transform`	Function of one argument, or NULL (default). Applied to the resolved value vector before type inference and encoding, e.g. log.
`prevalence`	Numeric scalar in (0, 1), or NULL (default). The population prevalence of a binary outcome. Only evaluate$*() reads it.

Value

An evaluate.outcome.spec, also classed PolyGeniusOutcomeSpec: a list holding value (the captured quosure), type, label, event, transform and prevalence. It carries no data until a call resolves it.

Details

Nothing is evaluated here: value is captured as a quosure and resolved only when a call resolves the descriptor against its data, through PolyGeniusStudy$fetch(.context = "samples"). The column is therefore found wherever it lives on the sample axis ($samples$phenotypes, a scores layer, and so on), and any expression fetch() can evaluate is allowed, not just a bare column.

type = "auto" infers: a logical column is binary; a factor or character column with exactly two levels is binary and anything else aborts; a numeric column is binary when its non-NA values are all 0/1, continuous when it has more than two distinct values, and aborts on one or two distinct values that are not 0/1 -- usually a miscoded missing.

A binary outcome is encoded as value == event, 1 where true. event defaults to TRUE for a logical column, to 1 for a 0/1 numeric column, and to the second level of a two-level factor. A character column, or a factor without two levels, has no default, since its level order does not say which value is the event: name it with event. associate$*() re-parses the descriptor from the unevaluated call and reads only value and type. label, event/positive, transform and prevalence take effect in evaluate$*() only.

prevalence is the population prevalence of a binary outcome. It enables the liability-scale R-squared metrics of evaluate (Lee et al. 2012) and applies to every stratum. A value that is not a single number in (0, 1) aborts here. A prevalence on an outcome that resolves as continuous aborts when an evaluate$*() call resolves it.

Examples

# Explicit binary coding, naming the level that counts as the event
outcome(diagnosis, type = "binary", event = "case")

# Transform the fetched values before they are evaluated
outcome(triglycerides, type = "continuous", transform = log)


```r

evaluate$performance(
  study,
  outcomes = list(
    ad  = outcome(diagnosis, type = "binary", event = "case", prevalence = 0.05),
    bmi = bmi
  )
)