Contents

visualize$associations$forest

Association results as a forest plot

Publication-style forest plot of the effect estimates in a PolyGeniusAssociation, laid out as names | table.left | forest | table.right. Rows, grouping, ordering and both side tables are unquoted expressions evaluated against the result table.

Usage

visualize.associations.forest(
  results,
  rows.by = predictor,
  group.by = outcome,
  summary.by = NULL,
  order.by = NULL,
  decreasing = FALSE,
  table.left = c(),
  table.right = c(),
  width = NULL,
  palette = NULL,
  shade.tables = TRUE,
  row.height = 0.82,
  show.reference = TRUE,
  ...
)

Arguments

Argument	Description
`results`	A PolyGeniusAssociation. Its $results rows are the rows plotted.
`rows.by`	Unquoted expression selecting the row-label column, default predictor. The default literal is inert: when the argument is omitted the column is chosen from the data instead -- predictor when group.by is outcome, outcome when group.by is predictor or when one predictor spans several outcomes, stratum when one predictor and outcome span several strata, predictor otherwise. Must resolve to a single column.
`group.by`	Unquoted expression adding grouped header rows, default outcome. The default literal is inert: omitting the argument draws a flat, ungrouped plot. When supplied, each group gets a header row and its member labels are indented beneath it.
`summary.by`	Unquoted expression returning one logical per result row, or NULL (default). TRUE rows sink to the bottom of their group ahead of any order.by ordering, are drawn as a bold diamond that keeps its whisker, and NA counts as FALSE. Omitting the argument on a result holding [associate$meta](/reference/associate-meta/) rows resolves it to schema == "meta", so every pooled cell is a diamond; passing NULL explicitly flags no rows.
`order.by`	Unquoted expression giving the sort key, or NULL (default), which keeps the table's own order. Derived expressions such as abs(estimate) are accepted; with group.by, groups keep their first-appearance order and only rows within a group are sorted. NA keys always sink to the bottom.
`decreasing`	Logical scalar, default FALSE. Sort direction for order.by; ignored when order.by is NULL.
`table.left`	Unquoted expression, a c() of expressions, or NULL, default c(). Text columns drawn left of the forest; a named expression uses its name as the header, an unnamed one its expression text. The c() default shows the family's sample counts -- n.cases/n.controls for glm, n/n.events for cox, those plus n.competing for crr, n for lm -- led by n.studies when the result carries it, and aborts when a required count column is absent. NULL suppresses the table.
`table.right`	As table.left, drawn right of the forest, default c(). The c() default shows estimate, lower, upper and adj.pval for lm/glm/cox/crr, combining the first three into one effect (CI) cell, and aborts when those columns are absent; a family-less table gets no right table.
`width`	Numeric vector of positive finite relative widths, or NULL (default), which gives every block equal width. One entry per layout block actually present, left to right: names, table.left if drawn, the forest, table.right if drawn. A wrong length or a non-positive value aborts, naming the expected blocks.
`palette`	Length-2 character vector of alternating data-row background colours, or NULL (default) for grey/white banding. Drawn as given, and the alternation restarts beneath each group header; header rows use a fixed soft green. Any other length aborts.
`shade.tables`	Logical scalar, default TRUE. Extends the row shading to the label and side-table columns; FALSE shades only the forest rows.
`row.height`	Numeric scalar in (0, 1], default 0.82. Relative row height; below 1 leaves whitespace between rows.
`show.reference`	Logical scalar, default TRUE. Draws the family's null line -- 0 for lm, 1 for the ratio families.
`...`	Unused. An argument arriving here aborts and names itself, so a misspelled dotted argument (show_reference for show.reference) fails loudly rather than being ignored.

Value

A patchwork composition on every path: one panel per layout block, plus a significance-key footer when any plotted row has a non-NA adj.pval. It inherits ggplot, so + theme(...) applies to the whole composition; use & to reach the panels individually.

Details

Reads $results and recomputes nothing: estimates are drawn on the family's reporting scale, exponentiated for glm/cox/crr and as stored for lm. Rows whose estimate is missing or non-finite, and rows carrying a recorded fit error, are dropped with a warning; a row with an estimate but no interval is kept and drawn without whiskers.

Aborting cases: a result whose schema does not list forest among its allowed plots (single.variant and km do not), a table mixing several family values, and a table left with no plottable row after the drop.

Result columns read

estimate, lower and upper for the points and whiskers; family for the scale, x-axis label and reference line; alpha for the confidence-interval header, falling back to a bare CI when it is absent or mixed; adj.pval for the significance stars and the footer key. predictor, outcome, stratum, schema and n.studies supply the rows.by, summary.by and table.left defaults where present.

Examples

assoc <- associate$regression(data, outcomes = dementia, predictors = everything())
visualize$associations$forest(assoc)

# strongest effect first, no side tables
visualize$associations$forest(assoc, order.by = abs(estimate), decreasing = TRUE,
                              table.left = NULL, table.right = NULL)

# a meta result draws its pooled cells as diamonds automatically
assoc2 <- associate$regression(replication, outcomes = dementia, predictors = everything())
visualize$associations$forest(associate$meta(cohort1 = assoc, cohort2 = assoc2))