Contents

surv

Survival outcome descriptor

surv() declares a time-to-event outcome: follow-up time, event indicator, and optional competing-event, delayed-entry and time-origin metadata. Write it inline as the outcomes argument of an associate$*() call, on its own or as an element of a list(). evaluate$*() takes binary and continuous outcomes only, and aborts on surv().

Usage

surv(
  time,
  event,
  event.code = 1,
  competing.event = NULL,
  competing.code = NULL,
  entry = NULL,
  origin = NA_character_,
  type = c("cox", "crr"),
  label = NULL
)

Arguments

Argument	Description
`time`	Unquoted expression for follow-up time, resolved from the call's data. Usually a bare column name.
`event`	Unquoted expression for the event indicator, resolved from the call's data.
`event.code`	Value of event marking the event of interest, default 1. Recorded on the descriptor only: associate$*() reads event as coded.
`competing.event`	Unquoted expression for a separate competing-event indicator, or NULL (default) for none.
`competing.code`	Value of competing.event marking the competing event, or NULL (default). Recorded on the descriptor only.
`entry`	Unquoted expression for a left-truncation (delayed) entry time, or NULL (default). Supplying it makes associate$*()'s Cox and Fine-Gray families fit Surv(entry, time, event), restricting each event's risk set to subjects already under observation, as a staggered-enrollment or age-as-timescale cohort requires.
`origin`	Character scalar, default NA_character_. Free-text label for what time = 0 means, e.g. "enrollment" or "birth". Declared, never checked against the data, and carried to $results$time.origin / $fits$time.origin so associate$meta() can warn when pooled studies disagree. Anything other than a length-1 character (or NA) aborts.
`type`	One of "cox" (default), "crr". Recorded on the descriptor only. associate$*() selects Fine-Gray from the presence of competing.event.
`label`	Character scalar, or NULL (default). Recorded on the descriptor only.

Value

An evaluate.survival.spec, also classed PolyGeniusSurvivalSpec: a list holding time, event, event.code, competing.event (aliased as competing), competing.code, entry, origin, type and label. The supplied column arguments are quosures; competing.event and entry are NULL when not given. It carries no data until a call resolves it.

Details

Censoring is not missingness. A subject whose follow-up ended without the event is censored: give it the last-contact time in time and a non-event code in event, and the follow-up is kept and used. A row is dropped only when a value the fit needs is NA, so leaving a subject lost to follow-up as NA silently discards their time at risk.

What each consumer reads. associate$regression re-parses the unevaluated call and honours time, event, competing.event, entry and origin only -- see its own Outcome descriptors section. event.code, competing.code, type and label are recorded on the descriptor, and no consumer reads them. Because that parser reads an unnamed third argument as the competing event, name every argument after event.

Examples

# Right-censored Cox outcome; status coded 1 = event, 0 = censored
surv(time = followup.years, event = ad.event)

# A competing event and a time origin
surv(
  time            = age.at.exit,
  event           = status,
  competing.event = death,
  origin          = "birth"
)


```r

# Left-truncated Cox, in associate
associate$regression(
  study,
  outcomes = surv(time = age.at.exit, event = ad.event, entry = age.at.entry)
)