Contents

visualize$associations$survival

Survival curves from association artifacts

Draws the survival-curve artifacts carried on a summary-mode PolyGeniusAssociation from associate$regression. Predictor levels are coloured curves in one panel; faceting is reserved for analysis strata.

Usage

visualize.associations.survival(
  results,
  split.by = "auto",
  curves = c("auto", "predicted", "observed"),
  show.ci = TRUE,
  annotate = c("auto", "none"),
  show.censoring = TRUE,
  risk.table = "auto",
  risk.table.times = NULL,
  show.statistics = FALSE,
  show.summary.table = FALSE,
  palette = NULL,
  facet.scales = c("fixed", "free_y"),
  ...
)

Arguments

Argument	Description
`results`	A summary-mode PolyGeniusAssociation carrying an observed.curves or predicted.curves artifact.
`split.by`	Character vector of artifact column names, "auto" (default), "none" or NULL. "auto" facets by stratum when it varies, and additionally by outcome with a warning when several outcomes are mixed in; "none" and NULL draw a single panel; a character vector facets on exactly those columns and aborts on an unknown one. Predictor levels are never faceted -- they are coloured curves.
`curves`	One of "auto" (default), "predicted", "observed". Which curve artifact to plot. "auto" prefers adjusted predicted.curves and falls back to observed.curves; the two explicit values require the named artifact.
`show.ci`	Logical scalar, default TRUE. Draws confidence ribbons for rows with finite lower/upper bounds, and is a no-op when the artifact carries none.
`annotate`	One of "auto" (default), "none". "auto" places compact statistics in the panel corner -- one coloured line per curve for a multi-curve non-Kaplan-Meier fit, otherwise one neutral boxed line per facet. "none" annotates nothing.
`show.censoring`	Logical scalar, default TRUE. Marks censoring times on Kaplan-Meier curves from the artifact's n.censor column. Ignored for adjusted prediction curves.
`risk.table`	"auto" (default), TRUE or FALSE. "auto" and TRUE show the numbers-at-risk strip when a risk.table artifact is present; FALSE suppresses it. Rows match the plotted groups for Kaplan-Meier and observed curves, and are a single overall cohort row for adjusted Cox and Fine-Gray curves. The strip is dropped above three facet panels, with a warning when TRUE was explicit.
`risk.table.times`	Finite numeric vector, a single positive integer-like count, or NULL (default). A vector gives exact time points, a count an approximate number of pretty() columns, and NULL aligns the columns with the curve panel's x-axis breaks. Times outside the panel's x limits are dropped, and the strip is omitted when none remains.
`show.statistics`	Logical scalar, default FALSE. Adds effect and P columns, taken from $results, to the information table beneath the figure.
`show.summary.table`	Logical scalar, default FALSE. Adds group counts and median survival, taken from the group.summary artifact, to the information table beneath the figure. Columns empty for every curve are dropped.
`palette`	Character vector of colours, a palette-system or hue name, a palette function, or NULL (default) for the package categorical palette. A vector named by curve level, e.g. c(Low = "darkgreen", High = "darkorchid4"), maps by name rather than by position, and the same mapping is used by the numbers-at-risk strip.
`facet.scales`	One of "fixed" (default), "free_y". Facet scale freedom when split.by yields several panels. The x axis is always shared so the risk strip stays aligned.
`...`	Unused. An argument arriving here aborts and names itself, so a misspelled dotted argument (risk_table for risk.table) fails loudly rather than being ignored.

Value

A ggplot object when neither a numbers-at-risk strip nor an information table is drawn, and a patchwork composition of the curve panel with those parts otherwise. Both inherit ggplot, so test class(x)[[1]] rather than inherits() if the distinction matters; on the patchwork, + theme(...) applies to the composition and & to the panels.

Details

Plots only the artifacts already attached to the object; it never re-derives a curve, a risk set or a grouping at render time. See visualize-invariants.md § The boundary.

Aborting cases: a result whose schema does not list survival among its allowed plots (only cox, crr and km do), a curve artifact lacking estimate or time, a curve artifact mixing several family values, and curves = "predicted"/"observed" when that named artifact is absent or empty.

Artifacts read

predicted.curves or observed.curves supplies the curve rows, keyed by fit.id and read for estimate, time, family, lower/upper, n.censor, curve.label/curve.id and curve.type. risk.table (time, n.risk) drives the numbers-at-risk strip and group.summary (n, n.events, n.competing, median.time) the summary columns; each is skipped silently when absent. $results supplies the corner annotation and the effect/adj.pval columns, matched to curves on fit.id and contrast.level.

Curve conventions by model family

Kaplan-Meier (family = "km") draws observed step curves descending from 1 with censoring ticks and a per-group numbers-at-risk table. Cox ("cox") draws adjusted curves from the stored prediction profiles, with the risk table reporting the overall observed cohort rather than one row per adjusted curve. Fine-Gray ("crr") draws adjusted cumulative-incidence curves ascending from 0, on a y axis whose upper bound floats.

Examples

fit <- associate$regression(data, outcomes = surv(time = age, event = dementia),
                            predictors = PRS.tertile)
visualize$associations$survival(fit)

# add the per-group statistics table and pin the risk-table columns
visualize$associations$survival(fit, show.statistics = TRUE,
                                risk.table.times = c(0, 5, 10))