visualize$associations$survival

Visualize association-derived survival artifacts

Description

visualize$associations$survival() draws the survival-style curve artifacts stored on a summary-mode PolyGeniusAssociations object returned by associate$regression().

The function is intentionally object-loyal: it plots the curve artifacts that are already attached to the association object, rather than reconstructing new groupings at visualization time.

This means:

colors are always mapped to the stored curve.label values
facets are generated automatically from whichever analysis dimensions vary across the object, using the stored family, outcome, predictor, stratum, and curve.type columns
split analyses produced through split.by are shown directly from the stored artifacts, without inventing extra predictor groupings at plotting time
if the association object mixes several outcomes or predictors, those are shown directly instead of requiring the user to pick one fit first

Supported curve artifacts include:

Kaplan-Meier survival curves from family = “km”
adjusted Cox survival curves from stored prediction profiles
adjusted competing-risk cumulative-incidence curves from stored prediction profiles

When show.statistics = TRUE, show.summary.table = TRUE, and/or show.risk.table = TRUE, compact information tables are rendered beneath the plot. Statistics tables are resolved from the main association table, summary tables come from the stored group.summary artifact, and risk tables come from the stored risk.table artifact.

Usage

visualize.associations.survival(
  results,
  split.by = "auto",
  curves = c("auto", "predicted", "observed"),
  show.ci = TRUE,
  show.summary.table = FALSE,
  show.risk.table = FALSE,
  risk.table.times = NULL,
  show.statistics = TRUE,
  ...
)

Arguments

`results`	A summary-mode `PolyGeniusAssociations` object containing `observed.curves` or `predicted.curves` artifacts.
`split.by`	Controls how plotted survival curves are faceted. Use `“auto”` to facet by the varying stored analysis dimensions, `NULL` to draw all curves in a single panel, or a character vector such as `c(“stratum”)` or `c(“predictor”, “outcome”)` to facet explicitly by those artifact columns.
`curves`	Which curve artifact to plot. Use `“auto”` to prefer adjusted `predicted.curves` when available and otherwise fall back to `observed.curves`, `“predicted”` to require adjusted prediction-profile curves, or `“observed”` to require observed curves.
`show.ci`	Logical; if `TRUE`, draw confidence ribbons when lower/upper bounds are available.
`show.summary.table`	Logical; if `TRUE`, add a compact group/fit-level summary table below the curve plot.
`show.risk.table`	Logical; if `TRUE`, add a compact time-indexed numbers-at-risk table below the curve plot when a `risk.table` artifact is available.
`risk.table.times`	Risk-table time resolution. Use a numeric vector for exact time points, a single integer-like value for an approximate number of `pretty()` time columns, or `NULL` for the default automatic resolution.
`show.statistics`	Logical; if `TRUE`, add inferential statistics derived from the main association table.
`…`	Reserved for future extensions.

Value

A ggplot2 or patchwork plot object.