Package 'hvtiPlotR'

Description

hvtiPlotR is an R port of the plot.sas macro suite used by the Cardiovascular Outcomes, Registries and Research (CORR) statistics group within the Heart, Vascular and Thoracic Institute at the Cleveland Clinic. We use it to produce graphics that meet HVTI manuscript, poster, and presentation standards, built on ggplot2 and the officer package.

Worked, rendered examples for every constructor and theme live in the companion HVTI ggplot graphics recipes book, https://ehrlinger.github.io/hvtiGraphics/.

Details

Two-step workflow

Every plot constructor follows the same pattern:

1. Call ⁠hv_*()⁠ to validate and prepare data. It returns an hv_data S3 object that also stores diagnostics (group counts, SMDs, etc.) under ⁠$tables⁠.

2. Call plot() on the object to obtain a bare ggplot2::ggplot you can decorate with scales, labels, annotations, and themes without restriction.

Calling print() on the object gives a concise console summary.

library(ggplot2)
library(hvtiPlotR)

dta <- sample_trends_data(n = 600, seed = 42)
tr  <- hv_trends(dta)

plot(tr) +
  scale_color_manual(values = hv_palette(), name = "Group") +
  labs(x = "Year", y = "Outcome") +
  theme_hv_manuscript()

Every constructor ships with a ⁠sample_*()⁠ companion that generates realistic synthetic data sized and shaped like the corresponding SAS dataset export, so examples and unit tests run without PHI.

Themes

Four ⁠theme_hv_*()⁠ functions follow ggplot2's theme_bw() contract: pass base_size / base_family to control typography, then forward any extra named theme element through ... (e.g. theme_hv_manuscript(legend.position = "right")) or chain a + theme(...) call.

• theme_hv_manuscript(): Clean white-background theme for journal figures.

• theme_hv_poster(): Medium-font theme with visible axis lines for conference posters.

• theme_hv_ppt_dark(): Large-font theme with a black panel for blue-gradient or dark PowerPoint templates.

• theme_hv_ppt_light(): Large-font theme with a transparent panel (appears white on white-background PowerPoint templates). Add + theme(panel.background = element_rect(fill = "white")) if you specifically need an opaque white panel on a non-white slide background.

• theme_hv_ppt_slate(): Large-font theme with a white panel and white axes for the slate template (hv_ppt_template_slate.pptx).

• hv_ppt_layout(): The layout name for a slide role; the same six layouts exist in every bundled template.

All three PPT themes hide the legend by default, use inside-facing axis ticks, and scale axis-text / axis-title margins from base_size via ggplot2's half_line convention.

Saving figures

• save_manuscript(): Save a ggplot at the house manuscript size (6 x 4 in) in one call; the manuscript counterpart of save_ppt(). Pair with theme_hv_manuscript() for 12 pt type.

• save_ppt(): Insert one or more ggplot objects into a PowerPoint file as editable DrawingML vector graphics via officer + rvg.

• make_footnote() / makeFootnote(): Add a draft footnote during analysis; omit for publication-ready output.

Fixed-panel geometry (v2.0.0)

When plots in a set have different axis-label widths (e.g. y-axis ranges from "1.0" to "4567.2"), the usual ggsave() and officer::ph_location() calls let the panel content area drift, which is visually jarring on PPT decks where the black or white panel box should appear constant across slides. Two helpers solve this by making the panel size and slide position the target:

• hv_ggsave_dims(): Given a target panel width and height, computes the ggsave() width/height that preserve that panel size. Returns a named list to splat into ggsave() via do.call(ggplot2::ggsave, c(list(filename = ..., plot = p), dims)).

• hv_ph_location(): Given a target panel rectangle on the slide, computes the officer::ph_location() width/height/left/top that anchor the panel to that rectangle regardless of axis-label width. Warns if chrome overflows the left or top slide edge.

• save_ppt() accepts panel_box = list(width = ..., height = ..., left = ..., top = ...) to apply hv_ph_location() per slide automatically.

Plot constructors

Propensity Score & Matching

• hv_mirror_hist(): Prepare propensity-score distributions for a mirrored histogram comparing binary-matched or IPTW-weighted cohorts. Ports the ⁠tp.lp.mirror-histogram_*⁠ and tp.lp.mirror_histo_before_after_wt SAS scripts.

• hv_balance(): Prepare standardized mean difference data for a covariate balance dot-plot before and after propensity-score matching or weighting. Ports tp.lp.propen.cov_balance.R.

• hv_stacked(): Prepare grouped count or proportion data for a stacked or filled histogram.

Survival & Hazard

• hv_survival(): Fit and prepare Kaplan-Meier or Nelson-Aalen survival curves, risk tables, and report tables. Ports the SAS ⁠%kaplan⁠ and ⁠%nelsont⁠ macros from tp.ac.dead.sas.

• hv_hazard(): Prepare parametric hazard / survival curves from pre-fitted model output, with optional KM empirical overlay and population life-table reference. Ports the ⁠tp.hp.*⁠ template family.

• hv_survival_difference(): Prepare mean survival difference (life gained) over time between two treatment arms, with confidence ribbons. Ports tp.hp.dead.life-gained.sas.

• hv_nnt(): Prepare number-needed-to-treat over time derived from the survival difference. Ports tp.hp.numtreat.survdiff.matched.sas.

Nonparametric Temporal Curves

• hv_nonparametric(): Prepare pre-computed two-phase nonparametric temporal trend curves for binary or continuous outcomes with optional 68%/95% CI ribbon and binned data summary points. Ports the ⁠tp.np.*⁠ template family.

• hv_ordinal(): Prepare grade-specific probability curves from cumulative proportional-odds models (e.g. TR / AR grade). Ports ⁠tp.np.tr.ivecho.*⁠ and tp.np.po_ar.u_multi.ordinal.sas.

Study Design & Goodness of Follow-Up

• hv_followup(): Prepare per-patient follow-up data for a goodness-of-follow-up scatter plot (actual vs. potential follow-up per operation year). Use plot(x, type = "followup") for the death panel and plot(x, type = "event") for the non-fatal event panel. Ports tp.dp.gfup.R.

Longitudinal & Repeated Measures

• hv_trends(): Prepare patient-level data for annual trend lines with optional confidence ribbons for multiple groups. Ports the ⁠tp.lp.trends.*⁠, ⁠tp.rp.trends.*⁠, and tp.dp.trends.R families.

• hv_spaghetti(): Prepare repeated-measures data for individual patient trajectory plots, optionally stratified by group. Ports tp.dp.spaghetti.echo.R.

• hv_longitudinal(): Prepare pre-aggregated counts for a grouped bar chart or text table of patient and measurement counts at discrete follow-up windows. Use plot(x, type = "plot") for the bar chart and plot(x, type = "table") for the numeric table panel.

Flow Diagrams

• hv_alluvial(): Prepare patient-flow data for an alluvial (Sankey) diagram showing transitions between states across time points. Ports tp.dp.female_bicus_preAR_sankey.R.

• hv_sankey(): Prepare cluster-assignment data for a stability Sankey showing how patients redistribute across K values in a PAM analysis.

Exploratory Data Analysis

• hv_eda(): Prepare a single variable for EDA plotting: bar chart (categorical) or scatter + LOESS (continuous). Ports tp.dp.EDA_barplots_scatterplots.R.

• eda_classify_var(): Classify a vector as "Cont", "Cat_Num", or "Cat_Char" using the UniqueLimit heuristic from Barplot_Scatterplot_Function.R.

• eda_select_vars(): Subset and reorder a data frame by a character vector or space-separated column-name string. Replaces Order_Variables().

• hv_upset(): Prepare binary indicator data for an UpSet intersection plot. Ports tp.complexUpset.R.

Legacy single-call plot API

These functions predate the constructor-and-plot() split and return a ggplot directly. They are retained for backward compatibility with scripts written before the ⁠hv_*()⁠ redesign. New code should prefer the constructor form.

• hazard_plot(): Single-call parametric hazard/survival plot, combine-step equivalent of hv_hazard() + plot().

• survival_difference_plot(): Single-call mean-survival-difference plot, equivalent of hv_survival_difference() + plot().

• nnt_plot(): Single-call NNT plot, equivalent of hv_nnt() + plot().

Data class and introspection

All ⁠hv_*()⁠ constructors return objects that inherit from hv_data with a concept-specific subclass (e.g. hv_survival, hv_trends).

• is_hv_data(): Predicate for the shared base class.

• inherits(x, "hv_trends"): Check for a specific constructor's output.

• x$data: The canonical long-format data frame used by plot(x).

• x$meta: Named list of structural metadata (column names, group levels, summary functions).

• x$tables: Concept-specific diagnostic or report tables (SMDs, risk tables, group counts, etc.).

Sample-data generators

• sample_mirror_histogram_data(): Propensity scores via a logistic model with greedy 1:1 caliper matching and optional IPTW weights.

• sample_covariate_balance_data(): Standardized mean differences before and after propensity matching.

• sample_stacked_histogram_data(): Year-by-category count data.

• sample_survival_data(): Exponential survival times with administrative censoring and optional treatment strata.

• sample_hazard_data(): Weibull parametric survival predictions on a fine time grid, matching the predict dataset from ⁠%hazpred⁠.

• sample_hazard_empirical(): Binned Kaplan-Meier empirical points matching the plout / acpdms dataset.

• sample_life_table(): Age-group-specific Gompertz survivorship curves matching US population life-table SAS overlays.

• sample_survival_difference_data(): Mean survival difference between two parametric arms with confidence bands.

• sample_nnt_data(): Number-needed-to-treat derived from survival difference data.

• sample_nonparametric_curve_data(): Two-phase nonparametric curve predictions (binary or continuous outcome) on a fine time grid.

• sample_nonparametric_curve_points(): Binned patient-level data summary points matching the SAS means dataset.

• sample_nonparametric_ordinal_data(): Grade-specific cumulative proportional-odds probability curves.

• sample_nonparametric_ordinal_points(): Binned ordinal data summary points per grade level.

• sample_goodness_followup_data(): Operative cohort with operation dates, follow-up times, death, and non-fatal events.

• sample_trends_data(): Multi-group annual trend data with confidence ribbons.

• sample_spaghetti_data(): Patient-level longitudinal measurements over time.

• sample_longitudinal_counts_data(): Pre-aggregated patient and measurement counts at discrete follow-up windows.

• sample_alluvial_data(): Patient flow between states across multiple time points in wide format.

• sample_cluster_sankey_data(): Cluster assignments across K values for a PAM stability analysis.

• sample_eda_data(): Mixed-type cardiac-surgery registry simulation (binary, ordinal, character-categorical, and continuous variables).

• sample_upset_data(): Binary indicator columns for UpSet intersection analysis.

Scope and versioning

hvtiPlotR targets internal HVTI / CORR use only; it will not be submitted to CRAN. GitHub-only dependencies are declared in ⁠Remotes:⁠ in DESCRIPTION and install cleanly. Install via:

remotes::install_github("ehrlinger/hvtiPlotR")

Releases follow straight semantic versioning (2.0.0, 2.0.1, 2.1.0, 3.0.0 ...). The main branch tracks the most recent release; engineering collects changes staged for the next release. No ⁠.9xxx⁠ pre-release suffix on development builds. Pin against a specific release tag for reproducibility, e.g. remotes::install_github("ehrlinger/[email protected]").

Vignettes

• vignette("hvtiPlotR"): Introductory tutorial paralleling the SAS plot.sas macro, with side-by-side SAS and R examples.

• vignette("plot-functions"): Worked examples for every ⁠hv_*()⁠ constructor with the three-step build/bare-plot/decorate pattern.

• vignette("plot-decorators"): Guide to scales, labels, annotations, coord crops, themes, and ggsave() / save_ppt() patterns, including the panel_box fixed-panel workflow.

• vignette("sas-migration-guide"): SAS plot.sas template name lookup mapping to the corresponding ⁠hv_*()⁠ constructor and a worked R example.

References

Wickham, H. ggplot2: Elegant Graphics for Data Analysis. Springer, 2009.

Gohel, D. officer: Manipulation of Microsoft Word and PowerPoint Documents. R package. https://davidgohel.github.io/officer/

Description

Returns the ⁠$data⁠ slot, the tidy data frame each hv_data subclass carries for ggplot2 consumption. Lets callers use the standard base::as.data.frame() / base::data.frame() coercion in tidyverse pipelines instead of reaching for the ⁠$data⁠ accessor.

Usage

## S3 method for class 'hv_data'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

The data.frame stored in x$data.

Description

Re-exports ggplot2's ggplot2::autoplot() for hv_data objects so callers who prefer the ggplot2-ecosystem verb (broom / ggfortify / ggsurvfit all use it) can write autoplot(km) interchangeably with plot(km).

Usage

## S3 method for class 'hv_data'
autoplot(object, ...)

Arguments

Details

Dispatches to the registered ⁠plot.<subclass>()⁠ method, so any args that work with plot() work with autoplot().

Value

A ggplot object (or a patchwork composite when the underlying plot() method returns one, e.g. for hv_upset).

Description

Replicates the type-detection logic from Barplot_Scatterplot_Function.R: a numeric column is treated as categorical when all non-missing values are non-negative whole numbers with no more than unique_limit distinct values.

Usage

eda_classify_var(
  x,
  unique_limit = 6L,
  unique_bound = 100,
  var_name = NULL,
  type_overrides = NULL
)

Arguments

Value

A length-1 character: "Cont", "Cat_Num", or "Cat_Char".

See Also

hv_eda(), eda_select_vars()

Examples

eda_classify_var(c(0, 1, 1, 0, NA))        # "Cat_Num"
eda_classify_var(c(1, 2, 3, 4))            # "Cat_Num"
eda_classify_var(rnorm(50))                # "Cont"
eda_classify_var(c("A", "B", "A"))         # "Cat_Char"

Description

Returns the subset of data containing only the columns named in vars, in the order given. Replaces the Order_Variables() helper and the Mod_Data <- dta[, Order_Var] pattern from tp.dp.EDA_barplots_scatterplots_varnames.R.

Usage

eda_select_vars(data, vars)

Arguments

Details

vars may be supplied as a character vector or as a single space-separated string (matching the Var_CatList / Var_ContList style from the template).

Value

A data frame containing only the requested columns in the requested order.

See Also

hv_eda()

Examples

dta <- sample_eda_data()

# Vector form
sub <- eda_select_vars(dta, c("male", "cabg", "nyha"))
names(sub)

# Space-separated string (matches template Var_CatList style)
sub2 <- eda_select_vars(dta, "male cabg nyha valve_morph")
names(sub2)

Description

Adds plot to the current slide of an officer presentation with its panel anchored to panel_box, so every plot slide of a slide format puts its panel in the same place. With fit = TRUE the plot's text sizes and text margins are reduced together by hv_fit_location() until axis text, axis titles, facet strips and plot titles lie on the slide and below its title.

Usage

hv_add_plot(
  doc,
  plot,
  panel_box = hv_panel_box(format = .hv_doc_format(doc)),
  fit = TRUE,
  png_fallback = TRUE,
  dpi = 300,
  ...
)

Arguments

Details

The plot goes in as an editable DrawingML vector graphic via rvg::dml(). A dense point cloud can overflow libxml2 and make that insert fail; with png_fallback = TRUE the plot is then rendered to a transparent PNG at exactly the fitted location's size and placed at the same location, so the panel still lands on panel_box.

Add the slide and its title first, with officer::add_slide() and officer::ph_with(); save_ppt() does all of this for a list of plots.

Value

doc, with the plot added, carrying an attribute "hv_fit": a list scale (the text scale used), fits (whether the figure lies inside the slide limits), png (whether the PNG fallback was used), location (the placement, in inches) and panel_box (the panel rectangle used). A message reports reduced text; a warning reports a figure that still does not fit.

See Also

save_ppt(), hv_fit_location(), hv_panel_box().

Examples

p <- ggplot2::ggplot(mtcars, ggplot2::aes(hp, mpg)) +
  ggplot2::geom_point() +
  ggplot2::labs(x = "Horsepower", y = "Miles per gallon") +
  theme_hv_ppt_dark()

template <- system.file("extdata", "hv_ppt_template.pptx",
                        package = "hvtiPlotR")
doc <- officer::read_pptx(template)
doc <- officer::add_slide(doc, layout = hv_ppt_layout("figure"))
doc <- officer::ph_with(doc, "Fuel economy",
                        location = officer::ph_location_type("title"))
doc <- hv_add_plot(doc, p)
attr(doc, "hv_fit")$scale
print(doc, target = file.path(tempdir(), "fitted.pptx"))

Description

Validates a wide alluvial-format data frame and returns an hv_alluvial object. Call plot.hv_alluvial on the result to obtain a bare ggplot2 alluvial diagram that you can decorate with color scales, axis labels, and theme_hv_manuscript.

Usage

hv_alluvial(data, axes, y_col = "freq", fill_col = NULL, axis_labels = NULL)

Arguments

Value

An object of class c("hv_alluvial", "hv_data"):

$data

The validated input data frame.

$meta

Named list: axes, y_col, fill_col, axis_labels, n_axes, n_obs.

$tables

Empty list.

See Also

Worked recipe with rendered output: https://ehrlinger.github.io/hvtiGraphics/sankey.html.

plot.hv_alluvial, sample_alluvial_data

Examples

dta  <- sample_alluvial_data(n = 300, seed = 42)
axes <- c("pre_ar", "procedure", "post_ar")

# 1. Build data object
al <- hv_alluvial(dta, axes = axes, y_col = "freq", fill_col = "pre_ar")
al  # prints axes and observation count

# 2. Bare plot -- undecorated ggplot returned by plot.hv_alluvial
p <- plot(al)

# 3. Decorate: fill/color palettes, axis labels, theme
p +
  ggplot2::scale_fill_manual(
    values = c(None     = "steelblue",
               Mild     = "goldenrod",
               Moderate = "darkorange",
               Severe   = "firebrick"),
    name = "Pre-op AR"
  ) +
  ggplot2::scale_color_manual(
    values = c(None     = "steelblue",
               Mild     = "goldenrod",
               Moderate = "darkorange",
               Severe   = "firebrick"),
    guide = "none"
  ) +
  ggplot2::labs(y = "Patients (n)",
                title = "AV Regurgitation: Pre- to Post-operative") +
  theme_hv_poster()

Description

Renders a numbers-at-risk table as a bare ggplot2 panel, ready to stack under a survival curve with hv_atrisk_compose.

Usage

hv_atrisk(
  x,
  time = NULL,
  status = NULL,
  group = NULL,
  report_times = NULL,
  size = NULL,
  strata_labels = NULL,
  ...
)

Arguments

Value

A bare ggplot object: one text label per stratum and report time, strata as y rows (first stratum on top), time on a continuous x with axis text blanked (the curve carries the axis).

See Also

Worked recipe with rendered output: https://ehrlinger.github.io/hvtiGraphics/survival.html.

hv_atrisk_compose, hv_survival

Examples

km <- hv_survival(sample_survival_data(n = 200, seed = 1))
hv_atrisk(km)

Description

Composes a curve plot over a hv_atrisk panel, aligning the table's x-range to the curve's so the counts sit under the matching times, and stacks them with patchwork.

Usage

hv_atrisk_compose(curve, table, heights = c(3, 1))

Arguments

Value

A patchwork object (the curve above, the table below). Decorate both panels with patchwork's &, e.g. & theme_hv_manuscript().

See Also

hv_atrisk

Examples

km <- hv_survival(sample_survival_data(n = 200, seed = 1))
hv_atrisk_compose(plot(km), hv_atrisk(km))

Description

Validates and orders a long-format standardized-mean-difference data frame for a covariate balance plot, and returns an hv_balance object. Call plot.hv_balance on the result to obtain a bare ggplot2 object that you can decorate with color, shape, axis scales, and theme_hv_manuscript.

Usage

hv_balance(
  data,
  variable_col = "variable",
  group_col = "group",
  std_diff_col = "std_diff",
  var_levels = NULL,
  threshold = 10,
  stat_col = NULL,
  pair_col = NULL,
  stats = "smd",
  vr_threshold = c(0.5, 2),
  ks_threshold = NULL,
  group_labels = c("Before", "After")
)

Arguments

Details

Instead of a long data frame, data may be a cobalt::bal.tab() result, a multi-category bal.tab (one facet row per pair), an hvtiRpropensity ps_match() / ps_weight() object, or a list of any one of those, one per imputation. In those cases the SMD is multiplied by 100 and the *_col arguments are ignored.

A bal.tab() result must be built with binary = "std" and continuous = "std" (the default), so every difference is standardized, and with un = TRUE to draw the Before group: cobalt leaves the unadjusted columns empty otherwise, and hv_balance() then says so in a message and draws the After group only. Ask for the variance ratio and KS statistic with stats = c("m", "v", "ks"); the variance ratio is undefined for binary covariates, so those rows are left out of its panel. A distance or prop.score row (Type "Distance") is drawn as a covariate row, as in cobalt::love.plot(). ps_* objects carry standardized differences only.

A list is pooled across imputations: SMD and KS statistic are averaged, the variance ratio takes the geometric mean, and an NA in any imputation makes the pooled value NA (counted in $meta$n_missing). Every imputation must have the same rows, with one allowance: a covariate cobalt types as binary in some imputations (because it takes two values there) has no variance ratio in those, so its pooled variance ratio is NA.

Value

An object of class c("hv_balance", "hv_data"): a list with three elements:

$data

The input data frame with a cb_index column added for y-axis positioning, a stat factor (levels = stats) and a pair column (NA when there are no comparisons, otherwise a factor in order of first appearance). If data already has its own stat or pair column it is left untouched and these values go in .cb_stat / .cb_pair.

$meta

Named list: variable_col, group_col, std_diff_col, var_levels, threshold, n_vars, n_groups, stats, pairs, stat_var and pair_var (the names of the columns holding the statistic and the comparison), n_imputations, vr_threshold, ks_threshold, suggested_height.

$tables

Empty list (no accessory tables).

See Also

Worked recipe with rendered output: https://ehrlinger.github.io/hvtiGraphics/balance.html.

plot.hv_balance, sample_covariate_balance_data

Examples

library(ggplot2)
dta <- sample_covariate_balance_data()

# 1. Build data object
cb <- hv_balance(dta)
cb  # prints variable count, group count, threshold

# 2. Bare plot -- undecorated ggplot returned by plot.hv_balance
p <- plot(cb)

# 3. Decorate: color/shape palettes, x-axis range, labels, theme
p +
  scale_color_manual(
    values = c("Before match" = "red4", "After match" = "blue3"),
    name   = NULL
  ) +
  scale_shape_manual(
    values = c("Before match" = 17L, "After match" = 15L),
    name   = NULL
  ) +
  scale_x_continuous(limits = c(-45, 35), breaks = seq(-40, 30, 10)) +
  labs(x = "Standardized difference (%)", y = "") +
  theme_hv_poster()

# 4. From a cobalt::bal.tab() result: SMD, variance ratio and KS panels
if (requireNamespace("cobalt", quietly = TRUE)) {
  lal <- cobalt::lalonde
  ps  <- fitted(glm(treat ~ age + educ + race + married + nodegree + re74 + re75,
                    data = lal, family = binomial()))
  bt <- cobalt::bal.tab(
    treat ~ age + educ + race + married + nodegree + re74 + re75,
    data = lal, weights = ifelse(lal$treat == 1, 1 / ps, 1 / (1 - ps)),
    binary = "std", s.d.denom = "pooled", stats = c("m", "v", "ks"), un = TRUE
  )
  plot(hv_balance(bt, stats = c("smd", "variance_ratio", "ks")))
}

Description

Covariate labels overprint when a balance plot is drawn too short. This returns a height that leaves about 0.17 in per covariate row at 12 pt, plus room for the x axis, its title and a legend, scaled by base_size.

Usage

hv_balance_height(n_rows, base_size = 12, n_pairs = 1)

Arguments

Value

Height in inches, a numeric scalar.

See Also

hv_balance(), whose ⁠$meta$suggested_height⁠ holds this value at base_size = 12.

Examples

hv_balance_height(38)                 # about 8 in
hv_balance_height(38, base_size = 16)
hv_balance_height(12, n_pairs = 3)    # three-group design

Description

Reads the stage metadata stored in an hv_consort_tracker, auto-derives the orders and side_box arguments for consort::consort_plot(), and returns an hv_consort object wrapping the grid diagram.

Usage

hv_consort(
  tracker,
  side_box = "all",
  cex = 0.9,
  width = NULL,
  height = NULL,
  ...
)

Arguments

Value

An hv_consort object, a list with:

⁠$plot⁠

The grid object returned by consort::consort_plot().

⁠$meta⁠

Named list: n_stages, width, height, orders, side_box.

⁠$tracker⁠

The original hv_consort_tracker.

See Also

Worked recipe with rendered output: https://ehrlinger.github.io/hvtiGraphics/consort.html.

hv_consort_start(), hv_consort_exclude(), plot.hv_consort()

Examples

cohort <- data.frame(
  mrn  = paste0("P", 1:100),
  age  = sample(15:80, 100, TRUE),
  echo = sample(c(TRUE, FALSE), 100, TRUE, prob = c(0.9, 0.1))
)
tracker <- hv_consort_start(cohort, patient_id = mrn) |>
  hv_consort_exclude(label = "Eligible", col = "excl_screen",
                      age < 18 ~ "Age < 18") |>
  hv_consort_exclude(label = "Analyzed", col = "excl_eligible",
                      !echo ~ "Missing echocardiogram")
fig <- hv_consort(tracker)
plot(fig)

Description

Evaluates formula-based exclusion rules against the currently-active patient population and appends two new columns to the tracker's data frame: a character column (col) recording the first-matching exclusion reason for each patient, and a boolean column (pass_col) marking the survivors. Patients already excluded by a prior stage are automatically gated out.

Usage

hv_consort_exclude(
  tracker,
  label,
  col,
  ...,
  excl_label = "Excluded",
  pass_col = NULL
)

Arguments

Value

The updated hv_consort_tracker (invisibly, so it is pipe-safe).

See Also

hv_consort_start(), hv_consort()

Examples

cohort <- data.frame(
  mrn  = paste0("P", 1:100),
  age  = sample(15:80, 100, TRUE),
  echo = sample(c(TRUE, FALSE), 100, TRUE, prob = c(0.9, 0.1))
)

tracker <- hv_consort_start(cohort, patient_id = mrn) |>
  hv_consort_exclude(
    label    = "Eligible",
    col      = "excl_screen",
    age < 18 ~ "Age < 18"
  ) |>
  hv_consort_exclude(
    label  = "Analyzed",
    col    = "excl_eligible",
    !echo  ~ "Missing echocardiogram"
  )

Description

Returns the IDs of patients who are active at a given stage (or who were excluded for a specific reason at a given stage).

Usage

hv_consort_patients(tracker, stage, reason = NULL)

Arguments

Value

A character vector of patient IDs (from the column named in tracker$patient_id_col).

See Also

hv_consort_start(), hv_consort_exclude(), hv_consort_summary()

Examples

tracker <- hv_consort_start(data.frame(id = 1:10, age = c(rep(15,3), rep(30,7))),
                             patient_id = id) |>
  hv_consort_exclude(label = "Eligible", col = "excl_screen",
                      age < 18 ~ "Age < 18")
hv_consort_patients(tracker, "eligible")
hv_consort_patients(tracker, "screened", reason = "Age < 18")

Description

Creates an hv_consort_tracker object with one row per patient and a boolean column indicating that every patient is in the initial (screened) population. Build the tracker incrementally with hv_consort_exclude(), then convert to a diagram with hv_consort().

Usage

hv_consort_start(data, patient_id, label = "Screened", pass_col = NULL)

Arguments

Value

An hv_consort_tracker object, a list with:

⁠$data⁠

Patient-level data frame with boolean/character columns appended per stage.

⁠$stages⁠

Ordered list of stage descriptors (label, include_col, excl_col, excl_label).

⁠$patient_id_col⁠

Column name of the patient identifier.

See Also

hv_consort_exclude(), hv_consort()

Examples

cohort  <- data.frame(mrn = paste0("P", 1:100), age = sample(15:80, 100, TRUE))
tracker <- hv_consort_start(cohort, patient_id = mrn)
print(tracker)

Description

Returns a data frame with one row per stage showing patient counts and the exclusion column name, suitable for a methods-section table.

Usage

hv_consort_summary(tracker)

Arguments

Value

A data frame with columns label, include_col, n_included, excl_col, n_excluded. n_excluded and excl_col are NA for the final stage (no downstream exclusion defined yet).

See Also

hv_consort_patients()

Examples

hv_consort_summary(sample_consort_data())

Description

The scatter-plot-matrix analogue of SAS ⁠proc corr ... plots=matrix⁠: one scatter panel per unordered pair of vars, lower triangle only. It is the plot half of the dc-tables job in the hvtiR job catalog. Call plot() on the result for a bare ggplot; the coefficient table with Fisher intervals is hvtiRtables::hv_correlation_table().

Usage

hv_correlation_matrix(
  data,
  vars,
  labels = NULL,
  method = c("pearson", "spearman")
)

Arguments

Details

Rows missing either coordinate are dropped panel by panel (pairwise deletion, as ⁠proc corr⁠ does), so a variable with missing values thins only the panels it appears in.

A single warning() names variables with fewer than 3 non-missing values or no variation, and otherwise-usable pairs with fewer than 3 pairwise-complete observations. These panels are sparse or flat, so their coefficients may be unstable or NA.

At large sizes (about 73 MB at 17 variables by 11,000 rows), write a raster format such as PNG rather than PDF, since every point is a vector object in a PDF, and lower alpha so overplotted panels stay legible.

Value

An object of class c("hv_correlation_matrix", "hv_data"): ⁠$data⁠ (columns col_var, row_var, x, y), ⁠$meta⁠ (vars, labels, method, n_obs, which is nrow(data) before any pairwise deletion, not a per-panel count), and ⁠$tables$coefficients⁠, the pairwise coefficient matrix.

References

SAS template: descriptive/dc.tables.ods.sas.

See Also

plot.hv_correlation_matrix(), sample_correlation_data()

Examples

d <- sample_correlation_data()
cm <- hv_correlation_matrix(d, c("a1c", "glucose", "creatinine", "albumin"))
plot(cm) + theme_hv_manuscript()
# strip.placement moves the variable names outside the axis
plot(cm) + ggplot2::theme(strip.placement = "outside")

Description

Classifies y_col using eda_classify_var, pre-processes categorical levels (adding an explicit "(Missing)" level), and returns an hv_eda object. Call plot.hv_eda on the result to obtain a bare ggplot2 barplot or scatter plot that you can decorate with color scales and theme_hv_manuscript.

Usage

hv_eda(
  data,
  x_col = "year",
  y_col = "ef",
  y_label = NULL,
  unique_limit = 6L,
  unique_bound = 100,
  type_overrides = NULL,
  show_percent = FALSE
)

Arguments

Details

Iterate over variables with lapply() after selecting columns with eda_select_vars.

Value

An object of class c("hv_eda", "hv_data"):

$data

Pre-processed data frame ready for plotting. For continuous variables: two columns x and y. For categorical variables: columns x (factor) and fill (factor with "(Missing)" as explicit level).

$meta

Named list: x_col, y_col, y_label, var_type ("Cont", "Cat_Num", or "Cat_Char"), show_percent, n_obs.

$tables

For continuous variables: rug_data, the rows where y_col is NA, used for the rug layer. Empty list for categorical variables.

References

R templates: tp.dp.EDA_barplots_scatterplots.R, tp.dp.EDA_barplots_scatterplots_varnames.R; helper: Barplot_Scatterplot_Function.R (Function_DataPlotting(), Order_Variables()).

See Also

Worked recipe with rendered output: https://ehrlinger.github.io/hvtiGraphics/bar.html.

plot.hv_eda, sample_eda_data, eda_classify_var, eda_select_vars

Examples

dta <- sample_eda_data(n = 300, seed = 42)

# 1. Build data object (binary categorical)
ed <- hv_eda(dta, x_col = "year", y_col = "male", y_label = "Sex")
ed  # prints var_type and observation count

# 2. Bare plot -- undecorated ggplot returned by plot.hv_eda
p <- plot(ed)

# 3. Decorate: fill palette, x-axis breaks, labels, theme
p +
  ggplot2::scale_fill_manual(
    values = c("0" = "steelblue", "1" = "firebrick", "(Missing)" = "gray80"),
    labels = c("0" = "Female", "1" = "Male", "(Missing)" = "Missing"),
    name   = NULL
  ) +
  ggplot2::scale_x_discrete(breaks = seq(2005, 2020, 5)) +
  ggplot2::labs(x = "Surgery Year", y = "Count") +
  theme_hv_poster()

# Continuous variable -- same 3-step pattern
ed2 <- hv_eda(dta, x_col = "op_years", y_col = "ef",
                y_label = "Ejection Fraction (%)")
plot(ed2) +
  ggplot2::scale_color_manual(values = c("firebrick"), guide = "none") +
  ggplot2::scale_x_continuous(breaks = seq(0, 15, 5)) +
  ggplot2::labs(x = "Years from First Surgery Year") +
  theme_hv_poster()

# Variable selection + lapply (varnames template pattern)
cont_vars <- c(ef = "Ejection Fraction (%)",
               lv_mass = "LV Mass Index (g/m\u00b2)",
               peak_grad = "Peak Gradient (mmHg)")
sub_cont <- eda_select_vars(dta, c("op_years", names(cont_vars)))
p_cont <- lapply(names(cont_vars), function(cn) {
  plot(hv_eda(sub_cont, x_col = "op_years", y_col = cn,
               y_label = cont_vars[[cn]])) +
    ggplot2::scale_color_manual(values = c("steelblue"), guide = "none") +
    ggplot2::scale_x_continuous(breaks = seq(0, 15, 5)) +
    ggplot2::labs(x = "Years from First Surgery Year") +
    theme_hv_poster()
})
p_cont[[1]]

Description

Classifies each variable with eda_classify_var(), keeps the ones that belong to section, and prepares one hv_eda() panel for each. Call plot.hv_eda_pages() on the result to lay the panels out as pages.

Usage

hv_eda_pages(
  data,
  x_col = "year",
  section = c("continuous", "percent", "count"),
  vars = NULL,
  labels = NULL,
  unique_limit = 6L,
  unique_bound = 100,
  type_overrides = NULL
)

Arguments

Details

The three sections split one dataset by variable class:

• "continuous": variables classified "Cont", drawn as scatter plots against x_col.

• "percent": categorical variables ("Cat_Num", "Cat_Char"), drawn as bars filled to 100% in each bin of x_col.

• "count": the same categorical variables, drawn as stacked counts.

The percent and count sections use the same bins. Categorical panels need a discrete x, so x_col is binned once, here, and every categorical panel reads that bin. A whole-valued x_col (a calendar year) is used as it is. A fractional one (years since an origin) is binned by floor(), so each bar is one whole year, and meta$x_binned records that it was. Continuous panels always use x_col unbinned.

Value

An object of class c("hv_eda_pages", "hv_data"):

⁠$data⁠

One row per variable in the section, in page order: variable, label, var_type.

⁠$meta⁠

Named list: x_col, section, x_binned, n_vars, n_obs, n_other, the number of considered variables that belong to other sections, and ignored, the identifier columns vars = NULL left out.

⁠$tables⁠

panels, a named list of hv_eda() objects, one per variable.

See Also

plot.hv_eda_pages(), hv_eda(), eda_classify_var()

Examples

dta <- sample_eda_data(n = 300, seed = 42)

# Continuous variables, four panels to a page
cont <- hv_eda_pages(dta, x_col = "year", section = "continuous")
cont
pages <- plot(cont, ncol = 2, nrow = 2)
length(pages)
attr(pages[[1]], "variables")

# Categorical variables as percentages, decorated across the whole page
pct <- hv_eda_pages(dta, x_col = "year", section = "percent",
                    labels = c(male = "Male", nyha = "NYHA class"))
plot(pct)[[1]] &
  ggplot2::scale_fill_manual(values = hv_palette(), na.value = "gray80") &
  theme_hv_manuscript(base_size = 8)

Description

Anchors the plot's panel to panel_box with hv_ph_location() and checks that the whole figure, panel plus the axis text, axis titles, facet strips and plot titles around it, lies on the slide and below the slide title. If it does not, every text size in the plot's theme is reduced by step (as a fraction of the original size), together with every text margin set in absolute units, until it fits or reaches min_scale. The panel never moves; only the chrome shrinks.

Usage

hv_fit_location(
  plot,
  panel_box,
  slide_width = 13.333,
  slide_height = 7.5,
  title_bottom = 1.38,
  edge = 0.05,
  min_scale = 12/32,
  step = 2/32,
  align = c("panel", "fill"),
  margin = 0.45
)

Arguments

Details

At the PPT themes' 32 pt base size the defaults step the text down 2 pt at a time, to 30, 28, 26 and so on, down to 12 pt.

The figure checked is the placement box plus the actual extent of the title, subtitle and caption text, placed by its hjust (and plot.title.position): a title wider than the slide fails the check even though its cell fits.

Only sizes and margins set in the theme are scaled. The size of text drawn by a geom (geom_text(), geom_label()) is an aesthetic, not part of the theme, and is left alone. For a patchwork, panel_box holds the union of its panels and the whole composition is measured; see hv_ph_location().

Value

A list with elements

• plot: the plot, its text sizes and margins scaled by scale;

• location: the hv_ph_location() result for panel_box, a list width, height, left, top in inches, ready for officer::ph_location();

• scale: the text scale used, 1 when the plot fit as it was;

• fits: TRUE when the figure lies inside the slide limits. When it is FALSE, plot and location are those at min_scale.

• panel_box: the panel rectangle used, panel_box itself unless align = "fill" moved it.

See Also

hv_add_plot(), which places the result on a slide; hv_panel_box(), hv_ph_location().

Examples

p <- ggplot2::ggplot(mtcars, ggplot2::aes(hp, mpg)) +
  ggplot2::geom_point() +
  ggplot2::labs(x = "Horsepower", y = "Miles per gallon") +
  theme_hv_ppt_dark()
fit <- hv_fit_location(p, hv_panel_box("dark"))
fit$scale
fit$location

Description

Validates dates, builds per-patient follow-up frames, and returns an hv_followup object containing the data for both the death panel (type = "followup") and, optionally, the event panel (type = "event"). Call plot.hv_followup on the result to obtain a bare ggplot2 object.

Usage

hv_followup(
  data,
  iv_opyrs_col = "iv_opyrs",
  death_col = "dead",
  death_time_col = "iv_dead",
  event_col = NULL,
  event_time_col = NULL,
  death_for_event_col = NULL,
  origin_year = 1990,
  study_start = as.Date("1990-01-01"),
  study_end = as.Date("2019-12-31"),
  close_date = as.Date("2021-08-06"),
  tolower_names = TRUE,
  death_levels = c("Alive", "Dead"),
  event_levels = c("No event", "Non-fatal event", "Death"),
  segment_drop = 0
)

Arguments

Value

An object of class c("hv_followup", "hv_data"):

$data

Per-patient data frame for the death panel.

$meta

Column names, date parameters, state levels, has_event flag, and the cohort counts n_patients (analyzed), n_input, and n_excluded.

$tables

Named list with diagonal (the study-period reference diagonal) and, when event columns are supplied, event_data.

Missing data

Patients with a missing value in any required column are excluded, with a warning naming the columns responsible. $meta$n_patients reports the analyzed cohort, alongside $meta$n_input and $meta$n_excluded, so the reported N always describes the plotted points.

The event panel requires more columns than the death panel, so the two can have different cohorts: a patient with a complete death record but a missing event time appears in one panel and not the other. Each panel is therefore filtered and warned about separately, and the event panel's counts are reported as $meta$n_event_patients and $meta$n_event_excluded.

See Also

Worked recipe with rendered output: https://ehrlinger.github.io/hvtiGraphics/balance.html.

plot.hv_followup, sample_goodness_followup_data

Examples

dta <- sample_goodness_followup_data()

# 1. Build data object
gf <- hv_followup(dta)
gf  # prints follow-up summary

# 2. Bare plot -- undecorated ggplot returned by plot.hv_followup
p <- plot(gf)

# 3. Decorate: color palette, axis labels, theme
p +
  ggplot2::scale_color_manual(
    values = c("Alive" = "steelblue", "Dead" = "firebrick"),
    name = NULL
  ) +
  ggplot2::labs(x = "Operation Date", y = "Follow-up (years)") +
  theme_hv_poster()

# With event panel -- same 3-step pattern
gf2 <- hv_followup(dta, event_col = "ev_event", event_time_col = "iv_event")
plot(gf2, type = "event") +
  ggplot2::scale_color_manual(
    values = c("No event" = "blue", "Non-fatal event" = "green3",
               "Death" = "red"),
    name = NULL
  ) +
  ggplot2::scale_shape_manual(values = c(1, 2, 4), name = NULL) +
  ggplot2::labs(x = "Operation Date", y = "Follow-up (years)") +
  theme_hv_poster()

Description

Checks a set of death and event panels against the data, works out the study window they share, and prepares one hv_followup() object per panel. Call plot.hv_followup_panels() on the result for the figures.

Usage

hv_followup_panels(
  data,
  opyrs_col = "iv_opyrs",
  origin_year,
  panels,
  events = list(),
  close_date = NULL
)

Arguments

Details

The study window starts on 1 January of origin_year, because hv_followup() draws its potential-follow-up diagonal from origin_year whatever study_start is. It ends at the latest operation in the data.

The close date is close_date when given. When NULL it is estimated as the latest operation plus follow-up in the data: the date follow-up is known to reach, which is not necessarily the date it was closed. meta$close_source says which, so a report can too.

Every check runs before any panel is built. Every column named anywhere is checked at once, and the error lists all that are missing. A panel name is also its figure's name, so a name used twice, within panels or across panels and events, is an error. The origin is checked for plausibility: operation years outside 1900 to next year are the wrong-origin mistake, which otherwise slides every point along the x-axis without any other symptom, and stop.

An operation before the origin, a negative opyrs_col, is drawn where it falls, to the left of where the diagonal starts, with a warning, and counted in meta$n_opyrs_negative. It usually means the build counted opyrs_col from a later origin than origin_year, and a figure that shows the affected patients makes that a problem a reader can see, where a refusal would hide the figure and the patients with it. When every operation is before the origin, the origin is wrong for the whole cohort and there is no window to draw, so that stops.

Value

An object of class c("hv_followup_panels", "hv_data"):

⁠$data⁠

One row per panel, in order, death panels first: panel, type ("followup" or "event"), title, n_drawn and n_excluded.

⁠$meta⁠

Named list: opyrs_col, origin_year, study_start, study_end, first_operation, close_date, close_source, n_obs, n_opyrs_missing and n_opyrs_negative.

⁠$tables⁠

panels, a named list of hv_followup() objects.

See Also

plot.hv_followup_panels(), hv_followup()

Examples

dta <- sample_goodness_followup_data()
fp <- hv_followup_panels(
  dta, origin_year = 1990,
  panels = list(all = list(status = "dead", time = "iv_dead", title = "All deaths")),
  events = list(ev = list(event = "ev_event", time = "iv_event", death = "deads",
                          death_time = "iv_dead", label = "Non-fatal event"))
)
fp
fp$meta$close_source

Description

Given a fitted ggplot, returns width and height values such that, when passed to ggplot2::ggsave(), the resulting file has a panel content area matching width / height. The "panel content area" is the rectangular bounding box of the gtable cells tagged panel, i.e., the smallest rectangle that encloses every plotting panel. Whatever grobs fall inside that rectangle (e.g., inter-panel gutters and strip rows that sit between facet rows) are counted as part of the target; everything outside it (axes, axis titles, plot title, caption, legend, plot margins, and any strips that sit above/below or beside the panel block such as facet_grid side strips) is counted as chrome.

Usage

hv_ggsave_dims(plot, width, height, units = c("in", "cm", "mm"))

Arguments

Details

Useful for multi-panel figure sets where a constant data region is required across PDFs regardless of label length or legend placement. Always measured with a PDF sizing device, which is why units is limited to length (inches, cm, mm); DPI is irrelevant for vector output.

Value

A named list with elements width, height, units, shaped to splat directly into ggplot2::ggsave() via do.call() (see examples).

See Also

hv_ph_location() for the slide-placement analogue used with save_ppt().

Examples

p <- ggplot2::ggplot(mtcars, ggplot2::aes(hp, mpg)) +
  ggplot2::geom_point() +
  ggplot2::labs(title = "Long title that eats vertical space",
                x = "Horsepower", y = "Miles per gallon")

dims <- hv_ggsave_dims(p, width = 4, height = 3)
do.call(
  ggplot2::ggsave,
  c(list(filename = file.path(tempdir(), "fig.pdf"), plot = p), dims)
)

Description

Wraps ggiraph::girafe() for EDA pages drawn with interactive = TRUE (see plot.hv_eda()), so hovering a bar shows its tooltip.

Usage

hv_girafe(x, width = 6.5, height = 9, ...)

Arguments

Details

No fonts are embedded. By default ggiraph embeds its font files in the widget, which made one 8-panel page 8.6 MB instead of 0.4 MB. Here text is set in Arial (or the nearest system sans serif) and the browser draws it in the reader's own copy. Saved PNG and PDF output is unaffected.

Value

An htmlwidget of class girafe. Printed in a knitr or Quarto HTML document, it is drawn in place.

See Also

plot.hv_eda(), plot.hv_eda_pages()

Examples

if (requireNamespace("ggiraph", quietly = TRUE)) {
  dta <- sample_eda_data(n = 300, seed = 42)
  pages <- plot(hv_eda_pages(dta, section = "percent"),
                ncol = 2, nrow = 2, interactive = TRUE)
  widget <- hv_girafe(pages[[1]], width = 6.5, height = 6)
  class(widget)
}

Description

Validates and stores pre-computed parametric curve data (and optional Kaplan-Meier empirical overlay and population life-table reference) as an hv_hazard object. Pass the result to plot.hv_hazard() to render the figure.

Usage

hv_hazard(
  curve_data,
  x_col = "time",
  estimate_col = "survival",
  lower_col = NULL,
  upper_col = NULL,
  group_col = NULL,
  empirical = NULL,
  emp_x_col = x_col,
  emp_estimate_col = "estimate",
  emp_lower_col = NULL,
  emp_upper_col = NULL,
  emp_group_col = group_col,
  emp_geom = c("point", "step"),
  reference = NULL,
  ref_x_col = x_col,
  ref_estimate_col = estimate_col,
  ref_group_col = NULL
)

Arguments

Details

This constructor covers the complete ⁠tp.hp.dead.*⁠ SAS template family. All column-name mappings and all three data frames are fixed at construction time; aesthetic parameters (ci_alpha, line_width, etc.) are passed to plot().

Value

An S3 object of class c("hv_hazard", "hv_data"); call plot() on the result to render (see plot.hv_hazard()). The object contains: ⁠$data⁠ (curve data frame), ⁠$meta⁠ (all column-name mappings), ⁠$tables$empirical⁠, ⁠$tables$reference⁠.

See Also

Worked recipe with rendered output: https://ehrlinger.github.io/hvtiGraphics/hazard.html.

plot.hv_hazard() to render as a ggplot2 figure, theme_hv_manuscript() for the publication theme, sample_hazard_data(), sample_hazard_empirical(), sample_life_table() for example data.

Other Hazard plot: plot.hv_hazard()

Examples

library(ggplot2)

dat <- sample_hazard_data(n = 500, time_max = 10)
emp <- sample_hazard_empirical(n = 500, time_max = 10, n_bins = 6)

# 1. Build data object
hp <- hv_hazard(dat,
  lower_col     = "surv_lower", upper_col = "surv_upper",
  empirical     = emp,
  emp_lower_col = "lower",     emp_upper_col = "upper"
)
hp  # prints CI and empirical flags

# 2. Bare plot -- undecorated ggplot returned by plot.hv_hazard
p <- plot(hp)

# 3. Decorate: color/fill palettes, axis scales, labels, theme
p +
  scale_color_manual(values = c("steelblue"), guide = "none") +
  scale_fill_manual(values   = c("steelblue"), guide = "none") +
  scale_x_continuous(limits = c(0, 10), breaks = 0:10) +
  scale_y_continuous(limits = c(0, 100), breaks = seq(0, 100, 20),
                     labels = function(x) paste0(x, "%")) +
  labs(x = "Years", y = "Survival (%)") +
  theme_hv_poster()

# Stratified groups -- color scale adds clinical meaning
dat2 <- sample_hazard_data(
  n = 400, groups = c("No Takedown" = 1.0, "Takedown" = 0.65)
)
hp2 <- hv_hazard(dat2,
  lower_col = "surv_lower", upper_col = "surv_upper",
  group_col = "group"
)
plot(hp2) +
  scale_color_manual(
    values = c("No Takedown" = "steelblue", "Takedown" = "firebrick"),
    name   = NULL
  ) +
  labs(x = "Years", y = "Survival (%)") +
  theme_hv_poster()

# --- Global theme + RColorBrewer (set once per session) ------------------

old <- ggplot2::theme_set(theme_hv_manuscript())
plot(hp2) +
  scale_color_manual(values = hv_palette(), name = NULL) +
  scale_fill_manual(values = hv_palette(), guide = "none") +
  scale_x_continuous(limits = c(0, 10), breaks = 0:10) +
  scale_y_continuous(limits = c(0, 100), breaks = seq(0, 100, 20),
                     labels = function(x) paste0(x, "%")) +
  labs(x = "Years", y = "Survival (%)")
ggplot2::theme_set(old)


# See vignette("plot-decorators", package = "hvtiPlotR") for theming,
# color scales, annotation labels, and saving plots.

Description

Inspects a built plot, finds the panel corner with the fewest data points, and anchors the legend there. When no corner is clear of data (e.g. dense multi-curve panels), or the plot is faceted, the legend is sent to an outside position instead. The CORR house convention is in-panel legends placed in dead space; this automates the corner choice.

Usage

hv_legend_inside(
  plot,
  threshold = 0.08,
  box_frac = 0.3,
  pad = 0.02,
  fallback = "right",
  prefer = NULL
)

Arguments

Details

Apply it after the house theme (which sets legend.position = "none") so its position wins.

Value

The input plot with a theme layer added that sets the legend position.

See Also

Worked recipe with rendered output: https://ehrlinger.github.io/hvtiGraphics/legends.html.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  library(ggplot2)
  p <- ggplot(mtcars, aes(wt, mpg, color = factor(cyl))) + geom_point()
  hv_legend_inside(p)
}

Description

Validates a pre-aggregated long-format counts data frame and returns an hv_longitudinal object. Call plot.hv_longitudinal on the result with type = "plot" for the grouped bar chart or type = "table" for the numeric text-table panel. Compose both panels with patchwork.

Usage

hv_longitudinal(
  data,
  x_col = "time_label",
  count_col = "count",
  group_col = "series"
)

Arguments

Value

An object of class c("hv_longitudinal", "hv_data"):

$data

The validated input data frame.

$meta

Named list: x_col, count_col, group_col, n_timepoints, n_groups, n_obs.

$tables

Empty list.

See Also

Worked recipe with rendered output: https://ehrlinger.github.io/hvtiGraphics/bar.html.

plot.hv_longitudinal, sample_longitudinal_counts_data

Examples

dta <- sample_longitudinal_counts_data(n_patients = 300, seed = 42L)

# 1. Build data object
lc <- hv_longitudinal(dta)
lc  # prints group/time-point counts

# 2. Bare plot -- undecorated ggplot returned by plot.hv_longitudinal
library(ggplot2)
p <- plot(lc, type = "plot")

# 3. Decorate: fill palette, y-axis scale, labels, theme
p +
  scale_fill_manual(
    values = c(Patients = "steelblue", Measurements = "firebrick"),
    name   = NULL
  ) +
  scale_y_continuous(labels = scales::comma,
                     breaks = seq(0, 2000, 500),
                     expand = c(0, 0)) +
  coord_cartesian(ylim = c(0, 2200)) +
  labs(x = "Follow-up Window", y = "Count (n)") +
  theme_hv_poster() +
  theme(legend.position = c(0.85, 0.85))

Description

Validates and assembles propensity-score distributions for a mirrored histogram comparing a treated group (bars above the axis) and a control group (bars below the axis), with optional matched and unmatched shading. Returns an hv_mirror_hist object; call plot.hv_mirror_hist on the result to obtain a bare ggplot2 object.

Usage

hv_mirror_hist(
  data,
  score_col = "prob_t",
  group_col = "tavr",
  match_col = "match",
  group_levels = c(0, 1),
  group_labels = c("SAVR", "TF-TAVR"),
  matched_value = 1,
  score_multiplier = HVTI_SCORE_DEFAULT_MULTIPLIER,
  binwidth = 5,
  weight_col = NULL
)

Arguments

Value

An object of class c("hv_mirror_hist", "hv_data"); call plot() on the result to render the figure (see plot.hv_mirror_hist). The list contains:

$data

Tidy data frame of histogram bar coordinates for plot.hv_mirror_hist.

$meta

Named list: score_col, group_col, match_col, group_labels, binwidth, lower, upper, y_breaks, n_obs, n_dropped.

$tables

Named list with two elements:

diagnostics

A named list of diagnostic summaries. Always contains n_input, n_analyzed, n_dropped_missing_or_other_group, group_counts_before (table), score_summary_before (by object), and smd_before (numeric SMD). In binary-match mode, additionally contains group_counts_matched, matched_rate_by_group, score_summary_matched, and smd_matched. In weighted IPTW mode, additionally contains effective_n_by_group and smd_weighted.

working

The per-patient data frame after score rescaling and complete-case filtering, used for custom downstream diagnostics.

See Also

Worked recipe with rendered output: https://ehrlinger.github.io/hvtiGraphics/histograms.html.

plot.hv_mirror_hist to render as a ggplot2 figure, theme_hv_manuscript for the publication theme, sample_mirror_histogram_data for example data.

Other Propensity Score & Matching: hv_rmst_contrast(), hv_rmst_curves(), plot.hv_mirror_hist(), plot.hv_rmst_contrast(), plot.hv_rmst_curves(), sample_covariate_balance_data()

Examples

dta <- sample_mirror_histogram_data(n = 500, separation = 1.5)

# 1. Build data object
mh <- hv_mirror_hist(dta)
mh                    # print diagnostics summary
mh$tables$diagnostics # full diagnostics list

# 2. Bare plot -- undecorated ggplot returned by plot.hv_mirror_hist
p <- plot(mh)

# 3. Decorate: axis labels and theme
p +
  ggplot2::labs(x = "Propensity Score (%)", y = "Count") +
  theme_hv_poster()

Description

Stores pre-computed NNT (or ARR) data as an hv_nnt object. Rows where estimate_col is NA (undefined when ARR is near zero) are optionally removed during construction via na_rm. Pass the result to plot.hv_nnt() to render the plot. Covers the NNT component of tp.hp.numtreat.survdiff.matched.sas.

Usage

hv_nnt(
  nnt_data,
  x_col = "time",
  estimate_col = "nnt",
  lower_col = NULL,
  upper_col = NULL,
  group_col = NULL,
  na_rm = TRUE
)

Arguments

Value

An S3 object of class c("hv_nnt", "hv_data").

See Also

Worked recipe with rendered output: https://ehrlinger.github.io/hvtiGraphics/nnt.html.

plot.hv_nnt(), sample_nnt_data(), hv_survival_difference()

Examples

library(ggplot2)

nnt_dat <- sample_nnt_data(
  n = 500, time_max = 20,
  groups = c("SVG" = 1.0, "ITA" = 0.75)
)

# 1. Build data object
nn <- hv_nnt(nnt_dat, lower_col = "nnt_lower", upper_col = "nnt_upper")
nn  # prints estimate column and CI flags

# 2. Bare plot -- undecorated ggplot returned by plot.hv_nnt
p <- plot(nn)

# 3. Decorate: axis scales, labels, theme
p +
  scale_x_continuous(limits = c(0, 20), breaks = seq(0, 20, 5)) +
  scale_y_continuous(limits = c(0, 50), breaks = seq(0, 50, 10)) +
  labs(x = "Years", y = "Number Needed to Treat (NNT)") +
  theme_hv_poster()

# ARR curve -- same 3-step pattern with a different estimate column
ar <- hv_nnt(nnt_dat, estimate_col = "arr",
               lower_col = "arr_lower", upper_col = "arr_upper",
               na_rm = FALSE)
plot(ar) +
  scale_y_continuous(limits = c(0, 50),
                     labels = function(x) paste0(x, "%")) +
  labs(x = "Years", y = "Absolute Risk Reduction (%)") +
  theme_hv_poster()

Description

Validates pre-computed curve data (and optional CI bounds and binned data summary points) and returns an hv_nonparametric object. Call plot.hv_nonparametric to obtain a bare ggplot2 curve plot that you can decorate with color/fill scales, axis limits, and theme_hv_manuscript.

Usage

hv_nonparametric(
  curve_data,
  x_col = "time",
  estimate_col = "estimate",
  lower_col = NULL,
  upper_col = NULL,
  group_col = NULL,
  data_points = NULL
)

Arguments

Details

Covers the full range of tp.np.* SAS templates:

SAS column mapping:

• estimate_col <- prev, mnprev, _p_, est_fev, est_z0d

• lower_col <- cll_p68 or cll_p95

• upper_col <- clu_p68 or clu_p95

• group_col <- indicator added after wide-to-long reshape

Value

An object of class c("hv_nonparametric", "hv_data"); call plot() on the result to render the figure; see plot.hv_nonparametric. The list contains:

$data

The curve_data data frame.

$meta

Named list: x_col, estimate_col, lower_col, upper_col, group_col, has_ci, has_data_points, n_obs.

$tables

List; contains data_points when supplied.

See Also

Worked recipe with rendered output: https://ehrlinger.github.io/hvtiGraphics/hazard.html.

plot.hv_nonparametric to render as a ggplot2 figure, theme_hv_manuscript for the publication theme, sample_nonparametric_curve_data for example data.

Other Nonparametric curves: plot.hv_nonparametric()

Examples

dat     <- sample_nonparametric_curve_data(n = 500, time_max = 12)
dat_pts <- sample_nonparametric_curve_points(n = 500, time_max = 12)

# 1. Build data object
np <- hv_nonparametric(dat, lower_col = "lower", upper_col = "upper",
                          data_points = dat_pts)
np  # prints CI / data-point flags

# 2. Bare plot -- undecorated ggplot returned by plot.hv_nonparametric
p <- plot(np)

# 3. Decorate: color/fill palettes, axis scales, labels, theme
p +
  ggplot2::scale_color_manual(values = c("steelblue"), guide = "none") +
  ggplot2::scale_fill_manual(values   = c("steelblue"), guide = "none") +
  ggplot2::scale_x_continuous(limits = c(0, 12), breaks = 0:12) +
  ggplot2::scale_y_continuous(limits = c(0, 0.40),
                              breaks = seq(0, 0.40, 0.10),
                              labels = scales::percent) +
  ggplot2::labs(x = "Months", y = "Prevalence of AF") +
  theme_hv_poster()

# --- Global theme (set once per session) ----------------------------------

old <- ggplot2::theme_set(theme_hv_manuscript())
plot(np) +
  ggplot2::scale_color_manual(values = c("steelblue"), guide = "none") +
  ggplot2::scale_fill_manual(values   = c("steelblue"), guide = "none") +
  ggplot2::labs(x = "Months", y = "Prevalence of AF")
# For multi-group curves swap scale_color_manual with:
#   ggplot2::scale_color_manual(values = hv_palette(), name = NULL)
#   ggplot2::scale_fill_manual(values = hv_palette(), guide = "none")
ggplot2::theme_set(old)


# See vignette("plot-decorators", package = "hvtiPlotR") for theming,
# color scales, annotation labels, and saving plots.

Description

Validates pre-computed grade-specific probability curves (and optional binned data summary points) and returns an hv_ordinal object. Call plot.hv_ordinal on the result to obtain a bare ggplot2 multi-grade line plot that you can decorate with color scales and theme_hv_manuscript.

Usage

hv_ordinal(
  curve_data,
  x_col = "time",
  estimate_col = "estimate",
  grade_col = "grade",
  data_points = NULL
)

Arguments

Details

SAS column mapping (predict dataset after averaging):

• time <- iv_echo (or iv_wristm)

• estimate <- one of p0, p1, p2, p3 (individual grade probs, after wide-to-long reshape)

• grade <- a new column created during the reshape

Value

An object of class c("hv_ordinal", "hv_data"):

$data

The curve_data data frame.

$meta

Named list: x_col, estimate_col, grade_col, n_obs, n_grades, has_data_points.

$tables

List; contains data_points when supplied.

References

SAS templates: tp.np.tr.ivecho.average_curv.ordinal.sas, tp.np.po_ar.u_multi.ordinal.sas, tp.np.tr.ivecho.independence.sas, tp.np.tr.ivecho.u.phases.sas.

See Also

Worked recipe with rendered output: https://ehrlinger.github.io/hvtiGraphics/hazard.html.

plot.hv_ordinal, sample_nonparametric_ordinal_data

Examples

dat <- sample_nonparametric_ordinal_data(
  n = 800, time_max = 5,
  grade_labels = c("None", "Mild", "Moderate", "Severe")
)
dat_pts <- sample_nonparametric_ordinal_points(
  n = 800, time_max = 5,
  grade_labels = c("None", "Mild", "Moderate", "Severe")
)

# 1. Build data object
ord <- hv_ordinal(dat, data_points = dat_pts)
ord  # prints grade count and data-point flag

# 2. Bare plot -- undecorated ggplot returned by plot.hv_ordinal
p <- plot(ord)

# 3. Decorate: color palette, axis scales, labels, theme
p +
  ggplot2::scale_color_manual(
    values = c(None     = "steelblue",
               Mild     = "firebrick",
               Moderate = "forestgreen",
               Severe   = "goldenrod3"),
    name = "TR Grade"
  ) +
  ggplot2::scale_x_continuous(breaks = 0:5) +
  ggplot2::scale_y_continuous(limits = c(0, 0.50),
                              breaks = seq(0, 0.50, 0.10),
                              labels = scales::percent) +
  ggplot2::labs(x = "Years", y = "Percent in each TR grade") +
  theme_hv_poster()

Description

Colors for categorical groups in a manuscript, poster or light-background slide figure: the Okabe-Ito colors, ordered for a white background, with every one clearing 3:1 contrast against white. Hand it to a manual scale, scale_color_manual(values = hv_palette()).

Usage

hv_palette(n = NULL)

Arguments

Details

This is the categorical half of the house color rule. Ordered and diverging scales take ColorBrewer "RdBu" or "PuOr" through ggplot2::scale_color_brewer(), and sequential scales take "Blues". Avoid "Set1" and "RdYlGn": their red against green fails for a reader with deuteranopia.

The colors are those of hv_ppt_palette("light"), under a name that does not tie a manuscript figure to slides. For a dark slide, use hv_ppt_palette("dark"). Six colors are supplied, and asking for more is an error rather than a silently recycled palette.

Value

A character vector of hex colors, in group order.

See Also

hv_ppt_palette() for the slide orderings, hv_role_palette() when levels carry a role such as event or censored.

Examples

hv_palette()
hv_palette(n = 3)

Description

The one fixed panel rectangle every plot slide of a slide format anchors its plotting panel to, in inches. The slide format is the slide's aspect ratio: "wide" is 16:9, 13.333 by 7.5 in, the size of every bundled HVTI template; "standard" is 4:3, 10 by 7.5 in. The color template does not matter: the dark, light and slate templates get the same rectangle. save_ppt() and hv_add_plot() read the format from the template's slide size and use this rectangle by default. Axis text, axis titles, facet strips and plot titles flow outside it; hv_fit_location() keeps them on the slide and out of the slide title.

Usage

hv_panel_box(
  mode = c("dark", "light", "slate"),
  format = c("wide", "standard")
)

Arguments

Details

The wide rectangle is 9.98 by 4.11 in, 2.9 in from the left edge and 1.85 in from the top. The numbers leave room for the chrome around the panel:

• 2.9 in on the left for long y-axis labels and the rotated y-axis title;

• about 0.45 in above the panel, below the title placeholder that ends at 1.33 in, for facet strips and plot titles;

• 1.54 in below the panel (7.5 - 1.85 - 4.11), or 1.49 in inside the 0.05 in slide edge, for the x-axis chrome of theme_hv_ppt_dark(), theme_hv_ppt_light() and theme_hv_ppt_slate(): their 32 pt x-axis text and 40 pt x-axis title with its margin need about 1.48 in in Arial Bold, so a plot in these themes fits at full size.

The standard (4:3) rectangle is provisional: no 4:3 template is bundled, and the rectangle has not yet been checked on a real 4:3 deck. It follows the same rules, assuming the 4:3 title placeholder also ends near 1.33 in: the same top (1.85 in) and height (4.11 in), 2.3 in on the left for y labels and 0.45 in on the right, so 7.25 by 4.11 in at 2.3 in left.

In hvtiPlotR 2.8.14 and 2.8.15 both rectangles were 4.15 in high. Through hvtiPlotR 2.8.13 the rectangle was 8.79 by 3.9 in at 2.67 in left, 1.6 in top. Pass panel_box = list(width = 8.79, height = 3.9, left = 2.67, top = 1.6) to save_ppt() or hv_add_plot() to rebuild an old deck at its old geometry.

Value

A named list width, height, left, top, in inches, ready for the panel_box argument of save_ppt() and hv_add_plot().

See Also

save_ppt(), hv_add_plot(), hv_fit_location(), hv_ph_location()

Examples

hv_panel_box()
hv_panel_box(format = "standard")

Description

Chooses ggsave() dimensions from a plot's facet layout, so a faceted figure keeps panels of a readable size however many there are. A plot with one panel gets the standard 6 by 4 inch figure. A plot with several gets 3 by 2 inch panels, half the standard figure in each direction, plus the space its axes, titles, strips and legend need, measured by hv_ggsave_dims().

Usage

hv_panel_size(
  plot,
  max_width = NULL,
  max_height = NULL,
  units = c("in", "cm", "mm")
)

Arguments

Details

When those panels, with the gutters and interior strips between them, would make the figure wider than max_width or taller than max_height, every panel shrinks by the same factor, so each keeps its 3:2 shape. A panel narrower than 1.6 inches leaves no room for 12 pt tick labels, so below that the function stops: the facets do not fit on one page, and ggforce::facet_wrap_paginate() splits them across several. A paginated plot is sized by the one page it draws.

The panel block is measured, not the whole figure, because the chrome around it varies: a long axis title or a legend at the top would otherwise come out of every panel.

Value

A named list with elements width, height and units, shaped to splat into ggplot2::ggsave() via do.call(), as hv_ggsave_dims() returns.

See Also

hv_ggsave_dims(), which measures the chrome.

Examples

p <- ggplot2::ggplot(mtcars, ggplot2::aes(hp, mpg)) +
  ggplot2::geom_point() +
  ggplot2::facet_wrap(~cyl)
dims <- hv_panel_size(p)
do.call(
  ggplot2::ggsave,
  c(list(filename = file.path(tempdir(), "facets.pdf"), plot = p), dims)
)

Description

Given a fitted ggplot and a target panel rectangle (width/height/left/top on the slide), returns the width, height, left, top values to pass to officer::ph_location() such that the panel content area of the plot lands at the specified slide coordinates, regardless of how much room the axis labels, axis titles, legend, plot title, or plot margins consume.

Usage

hv_ph_location(
  plot,
  panel_width,
  panel_height,
  panel_left,
  panel_top,
  units = c("in", "cm", "mm")
)

Arguments

Details

The panel content area is the rectangular bounding box of the gtable cells tagged panel. Strip grobs that sit inside that bounding box are part of the target; strips outside it (e.g. facet_grid side strips, the strip row above a single-row facet_wrap) are treated as chrome.

Use with save_ppt() via panel_box = list(width, height, left, top) to apply this to every slide in a deck.

For a patchwork, the whole composition is measured, through patchwork::patchworkGrob(): the target rectangle holds the union of every plot's panels, with the axes and strips between them, and the outermost axes plus the patchwork::plot_annotation() title, subtitle and caption count as chrome. A nested patchwork counts as one panel, inner chrome included.

Value

A named list with elements width, height, left, top, all in units. Splat into officer::ph_location() via do.call().

See Also

hv_ggsave_dims() for the sizing-only analogue used with ggplot2::ggsave(), and save_ppt() which accepts a panel_box argument that delegates to this helper.

Examples

p <- ggplot2::ggplot(mtcars, ggplot2::aes(hp, mpg)) +
  ggplot2::geom_point() +
  theme_hv_ppt_dark()

loc <- hv_ph_location(
  p,
  panel_width  = 10, panel_height = 5,
  panel_left   = 0.5, panel_top   = 1.5
)
# doc <- officer::read_pptx(template)
# doc <- officer::add_slide(doc, layout = "Title and Content")
# doc <- officer::ph_with(
#   doc, rvg::dml(ggobj = p),
#   location = do.call(officer::ph_location, loc)
# )

Description

Every template bundled with hvtiPlotR (dark, light and slate) has the same six layouts by the same names, so a deck script runs on any of them. Name the role and pass the result to officer::add_slide(). save_ppt() sets a slide title, so its layout must have a title placeholder: it works with "figure", "section", "content" and "two". "title" (Title Slide has ctrTitle and subTitle placeholders) and "blank" (no placeholders) are for officer::add_slide() only.

Usage

hv_ppt_layout(
  role = c("figure", "section", "title", "content", "two", "blank")
)

Arguments

Details

Through hvtiPlotR 2.8.11 the light template named its figure layout "Custom Layout" and its section layout "1_Custom Layout", and the dark template named its section layout "1_Title Only". save_ppt() still accepts those names, with a one-time message; calls to officer::add_slide() must use the new names.

Value

A single character string: the layout's name in every bundled template.

See Also

save_ppt(), hv_panel_box().

Examples

hv_ppt_layout("figure")
hv_ppt_layout("section")

Description

The colors hv_ppt_series() assigns, handed back as a plain character vector. This is the single definition of the series colors, so reach for it when a figure needs them outside the decorator rather than pasting hex codes into a script, where they drift the first time the palette changes.

Usage

hv_ppt_palette(mode = c("dark", "light"), n = NULL)

Arguments

Details

The colors are the Okabe-Ito colorblind-safe palette, reordered for the background: high-luminance hues first on a dark slide, darker ones first on a light slide. Each ordering leads with its highest-contrast hue, 15.9:1 on a black panel and 5.2:1 on a white slide, but past that first entry the order is not a contrast ranking and should not be read as one. Black appears only in the light ordering, and it sits last there despite carrying the highest ratio of anything here (21:1 on white): house style draws annotation in the theme's ink, so a black series would be confusable with the label naming it. On a dark panel black is invisible, which is why that ordering omits it. These are not CORR brand colors.

Every dark color clears 3:1 against the black panel theme_hv_ppt_dark() draws, and every light color clears 3:1 on a white slide background, which is the contrast WCAG 2.2 (success criterion 1.4.11) asks of a graphical object a reader needs to read the chart. theme_hv_ppt_light() leaves its panel transparent so the slide shows through, so the light guarantee holds on a white template, which is what the house light template is. Check the colors again before using them on a tinted slide. One color in the light ordering is not Okabe-Ito's own. Their orange, ⁠#E69F00⁠, reaches only 2.3:1 on white, so the light ordering uses ⁠#9D952B⁠ in its place, Okabe-Ito yellow darkened at the same hue until it clears 3:1. An orange darkened that far would sit too close to vermilion for a reader with red-green color-vision deficiency.

Six colors are supplied. Ask for more than that and you get an error rather than a silently recycled palette, because two series sharing a color is a worse outcome than a stopped script.

Value

A character vector of hex colors, in series order.

See Also

hv_ppt_series(), which applies these to a plot. Annotation text is drawn in the theme's ink, matching the axis, rather than in a series color, so these are not the values to label a curve with.

Examples

hv_ppt_palette("dark")
hv_ppt_palette("light", n = 4)

Description

You already know the two-step shape of a hvtiPlotR figure: a constructor prepares and validates the data, plot() hands back a bare ggplot, and you finish it with +. Across a deck that finishing step is the same few lines on every slide, and copying them plot by plot is how one figure quietly drifts out of step with the rest.

hv_ppt_series() bundles the finishing step into a single object you add once per plot. It carries the PowerPoint theme, a color scale and a matching shape scale, so a whole deck takes its look from one definition.

Usage

hv_ppt_series(
  mode = c("dark", "light"),
  colours = NULL,
  shapes = NULL,
  name = NULL,
  ...,
  colors = colours
)

Arguments

Details

The return value is a plain list, and ggplot2's + unrolls a list element by element, so it composes like a theme:

ppt <- hv_ppt_series()
p1  <- p1 + ppt
p2  <- p2 + ppt

A theme cannot do this job alone. ggplot2::theme() governs the non-data ink, the text, panel, grid and ticks, and nothing that draws from the data, so no theme element sets a series color. Nor can a layer be smuggled in through the theme's ..., which is forwarded to ggplot2::theme() and errors on anything that is not a theme element. Series color and shape live in the scales, and those are what this function adds alongside the theme.

Color and shape carry the same variable

Both scales map the grouping column, so each series is told apart twice. That redundancy is the point. A projector in a dark room flattens color differences that read cleanly on your monitor, and a black and white handout drops them entirely, but the shapes survive both. The two scales share name, so on the rare draft that does draw a legend, ggplot2 merges them into one instead of stacking two.

The default colors are the Okabe-Ito colorblind-safe palette, ordered for the background: high-luminance hues first on a dark slide, darker ones first on a light slide. On a light slide a darkened yellow stands in for Okabe-Ito orange, which is too faint against white; hv_ppt_palette() gives the reasoning. These are not CORR brand colors. Pass colors when a deck calls for a specific set.

Six colors and six shapes are supplied, which covers a grouping variable of up to six levels. A discrete scale errors when it runs out of values, so pass longer vectors for a wider variable.

No legend, by house standard

Every ⁠theme_hv_*()⁠ sets legend.position = "none", and this decorator leaves that alone. CORR figures name the series where the series sits, on a slide, on a poster and in a manuscript alike, so the reader's eye never travels out to a key and back.

Annotation is drawn in the theme's ink, not in the color of the series it names: white on a dark slide, black on a light slide and in a manuscript. That is the ink the theme already gives the axis text and axis lines, so one ink for every label makes the annotation read as part of the figure's frame rather than as one more series.

plot(trends) +
  hv_ppt_series("dark") +
  ggplot2::annotate("text", x = 2015, y = 60, label = "Group I",
                    color = "white", size = 8)

The shape scale still earns its place with no legend drawn. Where two curves cross, the plotted summary points are what tells them apart.

Pass legend.position = "top" through ... when a working draft wants a quick key, or hand the finished plot to hv_legend_inside() to drop one into an empty corner of the panel.

Grouped plots only

The scales take effect on a plot that maps color to a grouping column, which means a constructor called with group_col. On an ungrouped plot they sit unused and only the theme applies. There is nothing to fix in that case; a single series needs no palette. To color the raw observations on an ungrouped plot, add your own layer after the decorator, for example + ggplot2::geom_point(color = "yellow").

Value

A list of ggplot2 components: a theme, a color scale and a shape scale. Add it to a ggplot object with +.

See Also

hv_ppt_palette() for the colors themselves; theme_hv_ppt_dark() and theme_hv_ppt_light() for the themes this wraps; hv_legend_inside() when a draft does want a key; save_ppt() to export the finished plots to editable PowerPoint slides.

Examples

dta <- sample_trends_data(n = 400, seed = 42)
trends <- hv_trends(dta, x_col = "year", y_col = "value",
                    group_col = "group")

# One decorator, added to every plot in the deck.
ppt <- hv_ppt_series(mode = "dark")
plot(trends) + ppt

# House style carries no legend, so name the series where it sits. The
# label takes the same ink as the axis: white on a dark slide, black on a
# light one.
plot(trends) + ppt +
  ggplot2::annotate("text", x = 2015, y = 60, label = "Group I",
                    color = "white", size = 8)

# A light template, larger type, and your own colors.
plot(trends) +
  hv_ppt_series(
    mode      = "light",
    colors    = c("#0072B2", "#D55E00", "#009E73", "#CC79A7"),
    base_size = 24
  )

Description

Validates a table of restricted mean survival time (RMST) differences, one row per weighting estimator, and returns an hv_rmst_contrast object. Call plot.hv_rmst_contrast() on the result for a bare dot-and-whisker ggplot2 object: one point per estimator, a whisker for its interval, and a vertical reference line at zero.

Usage

hv_rmst_contrast(
  data,
  estimator = "estimator",
  diff = "diff_days",
  lo = "lo_days",
  hi = "hi_days",
  ...
)

Arguments

Details

The input follows the tables$estimates contract of hvtiRpropensity::ps_rmst(): columns estimator, subset, weighting, n, ess_treated, ess_control, rmst_treated, rmst_control, diff, diff_days, lo_days, hi_days and n_failed, where a positive diff favors the treated arm. Only the estimator, difference and interval columns are used here. hvtiRpropensity is not required: pass a plain data frame, or the ps_rmst object itself and its ⁠$tables$estimates⁠ is read.

Value

An object of class c("hv_rmst_contrast", "hv_data"): a list with

⁠$data⁠

The estimates data frame, with the estimator column as supplied.

⁠$meta⁠

Named list: estimator, diff, lo, hi (column names), estimator_levels, n_estimators, n_missing.

⁠$tables⁠

Empty list.

See Also

plot.hv_rmst_contrast(), hv_rmst_curves()

Other Propensity Score & Matching: hv_mirror_hist(), hv_rmst_curves(), plot.hv_mirror_hist(), plot.hv_rmst_contrast(), plot.hv_rmst_curves(), sample_covariate_balance_data()

Examples

est <- data.frame(
  estimator = factor(c("IPTW", "Overlap", "Matching"),
                     levels = c("IPTW", "Overlap", "Matching")),
  diff_days = c(41, 35, 28),
  lo_days   = c(-5, 2, -14),
  hi_days   = c(87, 68, 70)
)
rc <- hv_rmst_contrast(est)
rc

plot(rc) +
  ggplot2::labs(y = NULL) +
  theme_hv_manuscript()

Description

Validates the step-function curves behind an RMST analysis and returns an hv_rmst_curves object. Call plot.hv_rmst_curves() for a bare ggplot2 object with one facet per estimator and one step curve per arm. With tau, the area under each arm's curve up to tau is shaded (that area is the RMST) and a vertical line marks tau. With estimates, each facet is annotated with its RMST difference and interval.

Usage

hv_rmst_curves(
  curves,
  estimates = NULL,
  tau = NULL,
  facet = "estimator",
  arm = "arm",
  time = "time",
  surv = "surv",
  ...
)

Arguments

Details

The input follows the tables$curves contract of hvtiRpropensity::ps_rmst(): columns estimator, arm ("treated" or "control"), time and surv, as right-continuous steps that start at time 0 with surv 1. hvtiRpropensity is not required: pass plain data frames, or the ps_rmst object itself as curves and its ⁠$tables$curves⁠ (and, when estimates is NULL, ⁠$tables$estimates⁠) are read.

Value

An object of class c("hv_rmst_curves", "hv_data"): a list with

⁠$data⁠

The curves data frame.

⁠$meta⁠

Named list: facet, arm, time, surv (column names), tau, facet_levels, arm_levels, n_missing.

⁠$tables⁠

shade: the staircase polygon under each curve up to tau (zero rows when tau is NULL); labels: one annotation per facet (zero rows when estimates is NULL).

See Also

plot.hv_rmst_curves(), hv_rmst_contrast()

Other Propensity Score & Matching: hv_mirror_hist(), hv_rmst_contrast(), plot.hv_mirror_hist(), plot.hv_rmst_contrast(), plot.hv_rmst_curves(), sample_covariate_balance_data()

Examples

steps <- function(est, arm, rate) {
  t <- c(0, sort(round(stats::rexp(40, rate) * 365)))
  data.frame(estimator = est, arm = arm, time = t,
             surv = c(1, 1 - seq_len(40) / 41))
}
set.seed(1)
curves <- rbind(
  steps("IPTW", "treated", 1 / 3), steps("IPTW", "control", 1 / 2),
  steps("Overlap", "treated", 1 / 3), steps("Overlap", "control", 1 / 2)
)
est <- data.frame(estimator = c("IPTW", "Overlap"),
                  diff_days = c(41, 35), lo_days = c(-5, 2), hi_days = c(87, 68))

rc <- hv_rmst_curves(curves, estimates = est, tau = 365)
rc

plot(rc) +
  ggplot2::labs(x = "Days", y = "Survival") +
  theme_hv_manuscript()

Description

The house color rule for EDA and follow-up figures, as a named vector you can check or reuse: an event is vermillion, censored is blue, missing is light gray, and every other level takes a colorblind-safe color in order. To apply the rule to a plot, use scale_fill_hv() or scale_color_hv(), which call this for each panel.

Usage

hv_role_palette(levels, event = NULL, censored = NULL, missing = "(Missing)")

Arguments

Details

Every color is decided from levels alone:

1. A level named in event is ⁠#D55E00⁠, in censored ⁠#0072B2⁠, and in missing ⁠#CCCCCC⁠. These hold even when the level is the only one.

2. Every other level, in levels order, takes the light series of hv_ppt_palette(): Okabe-Ito blue, vermilion, bluish green and reddish purple, then a darkened yellow and black, so a sole level with no role is blue.

3. When any of levels is named in event or censored, blue and vermillion leave that series, so no other level can be mistaken for the event or for censored. A role name absent from levels changes nothing, so one call can serve panels that do and do not carry the event.

4. When the other levels outnumber the series, all of them switch to Paul Tol's muted palette, without its sand and cyan, and without its rose when a role is present. Beyond that there are no more colorblind-safe colors, and the function stops with an error of class hv_role_palette_capacity.

Every color except the missing gray is at least 2:1 against white. The gray is fainter on purpose: missing is the one level meant to recede.

Value

A character vector of hex colors, named by levels and in the same order.

See Also

scale_fill_hv() and scale_color_hv() to apply the rule to a plot; hv_ppt_palette() for series colors with no role attached.

Examples

hv_role_palette(c("No event", "Reoperation", "Death"),
                event = "Death", censored = "No event")
hv_role_palette(c("Female", "Male", "(Missing)"))

Description

Validates a wide cluster-assignment data frame, resolves node level ordering, computes default node colors if not supplied, and pre-computes the long-format Sankey data. Call plot.hv_sankey on the result to obtain a bare ggplot2 Sankey diagram using ggsankey geoms.

Usage

hv_sankey(
  data,
  cluster_cols = paste0("C", 2:9),
  node_levels = NULL,
  node_colours = NULL,
  node_colors = node_colours
)

Arguments

Details

By default (node_levels = NULL) the node order is read from the data, not from one column's factor levels. We take every label that appears in any cluster_cols column, so no finer-K cluster is dropped to NA, and place each child next to its parent: the coarser-K cluster that contributes most of its members. Siblings end up together, the way leaves sit in a dendrogram, and the flows stay short and uncrossed. Pass node_levels yourself to override this; it is then used as given, but it must name every label in the data.

Value

An object of class c("hv_sankey", "hv_data"):

$data

The long-format Sankey data frame (four columns: x, node, next_x, next_node).

$meta

Named list: cluster_cols, node_levels, node_colors (also as node_colours, for existing code), n_patients, n_k.

$tables

Empty list.

See Also

Worked recipe with rendered output: https://ehrlinger.github.io/hvtiGraphics/sankey.html.

plot.hv_sankey, sample_cluster_sankey_data

Examples

dta <- sample_cluster_sankey_data(n = 300, seed = 42)

if (requireNamespace("ggsankey", quietly = TRUE)) {
  # 1. Build data object
  sn <- hv_sankey(dta)
  sn  # prints cluster cols and node count

  # 2. Bare plot -- undecorated ggplot returned by plot.hv_sankey
  p <- plot(sn)

  # 3. Decorate: axis labels and theme
  p +
    ggplot2::labs(x = NULL, title = "Cluster Stability: K = 2 to 9") +
    theme_hv_poster()
}

Description

Validates a long-format repeated-measures data frame and returns an hv_spaghetti object. Call plot.hv_spaghetti on the result to obtain a bare ggplot2 trajectory plot that you can decorate with color scales, axis labels, and theme_hv_manuscript.

Usage

hv_spaghetti(
  data,
  x_col = "time",
  y_col = "value",
  id_col = "id",
  colour_col = NULL,
  color_col = colour_col
)

Arguments

Value

An object of class c("hv_spaghetti", "hv_data"); call plot() on the result to render the figure; see plot.hv_spaghetti. The list contains:

$data

The validated input data frame.

$meta

Named list: x_col, y_col, id_col, color_col (also as colour_col, for existing code), n_subjects, n_obs.

$tables

Empty list.

See Also

Worked recipe with rendered output: https://ehrlinger.github.io/hvtiGraphics/spaghetti.html.

plot.hv_spaghetti to render as a ggplot2 figure, theme_hv_manuscript for the publication theme, sample_spaghetti_data for example data.