Package 'gfplot'

Description

Turns a two-column clinical matrix into a matrix of event indicators, with one column per follow-up limit. Observations beyond a limit are censored at that limit.

Usage

generate_time_event(clinical, limits, labels = NULL)

Arguments

Value

A matrix with one column per limit.

Examples

clinical <- cbind(time = c(1, 5, 10), event = c(1, 0, 1))
generate_time_event(clinical, limits = c(3, 6), labels = c("year3", "year6"))

Description

Returns a vector of journal-style colours. When palette is a vector of length greater than one it is returned unchanged, so the argument can also be used to pass colours through from a caller.

Usage

get_color(palette, n = 6)

Arguments

Value

A character vector of colours.

Examples

get_color("jama", 3)
get_color("house", 4)
get_color(c("#111111", "#222222"))

Description

Returns the colours gfplot uses, addressed by role rather than by hex value. Override any role for a session with options(gfplot.palette = list(primary = "#123456")), which is how the suite is retuned without editing figures.

Usage

gfplot_colors(role = "all")

Arguments

Value

A named character vector of colours.

See Also

get_color() for journal palettes and gfplot_theme() for the type and grid settings that go with these colours.

Examples

gfplot_colors("primary")
gfplot_colors(c("model_curve", "comparator_curve"))
gfplot_colors("series")

Description

Returns an index of the available figure families with the category they belong to and how to call them. Families with type = "spec" are driven by gfplot_spec() and gfplot_render(); families with type = "function" are called directly.

Usage

gfplot_families(category = NULL)

Arguments

Value

A tibble with one row per family: the family name, its title and category, whether it is driven by a specification, the function that draws it, and an example call.

See Also

gfplot_spec() to build a figure programmatically.

Examples

gfplot_families()
gfplot_families("Effect Estimate")

Description

Figures produced by gfplot use Arial. The raster devices supplied by ragg and the quartz device on macOS resolve system fonts such as Arial directly, so most output needs no preparation at all. The base pdf() device keeps its own font table and needs the family registered with it, which extrafont does.

Usage

gfplot_font_setup(font = "Arial", quiet = FALSE)

Arguments

Details

This function reports which routes work in the current session and, when vector PDF output would otherwise be unavailable, registers the font with extrafont so that pdf() can use it.

Value

A named logical vector, invisibly, with one entry per device route: raster (ragg PNG/TIFF/JPEG), quartz (macOS PDF and screen), and pdf (base pdf()). These are the routes gfplot_save() chooses between.

See Also

gfplot_save() to write a figure using a device that can render the font, and plot_KMCurve() for the font argument.

Examples

gfplot_font_setup()

Description

Legends in gfplot figures sit under the panel and wrap onto as many rows as the number of series needs, so a wide legend does not squeeze the panel.

Usage

gfplot_legend(labels, base_size = 11, hide_single = TRUE)

Arguments

Value

A ggplot2 guide specification, or "none" for a single series when hide_single = TRUE.

Examples

gfplot_legend(c("Low risk", "High risk"))

Description

Draw a figure from a specification

Usage

gfplot_render(spec)

Arguments

Value

A ggplot object, ready to print or pass to gfplot_save().

See Also

gfplot_spec()

Examples

effects <- data.frame(
  term = c("Age", "Stage III"),
  hr = c(1.02, 1.84),
  lower = c(0.99, 1.51),
  upper = c(1.05, 2.24)
)
p <- gfplot_render(gfplot_spec(
  "forest",
  data = effects, term = "term",
  estimate = "hr", lower = "lower", upper = "upper"
))

Description

Writing an R figure with Arial is device dependent: the base pdf() device needs the family registered with it, while the ragg raster devices and the macOS quartz device resolve system fonts directly. This function chooses a route that can render font for the requested file extension, so a figure is written with the intended typeface instead of silently falling back to a default.

Usage

gfplot_save(
  plot,
  filename,
  width = NULL,
  height = NULL,
  dpi = 300,
  size = NULL,
  font = "Arial",
  provenance = FALSE,
  call = NULL,
  ...
)

Arguments

Value

filename, invisibly. The path of the provenance file is attached as the "provenance" attribute when one is written.

See Also

gfplot_font_setup() to see which devices can render a font.

Examples

p <- plot_Boxplot(c(rnorm(20), rnorm(20, 1)), rep(c("A", "B"), each = 20))
path <- tempfile(fileext = ".png")
gfplot_save(p, path, width = 4, height = 3)
unlink(path)

Description

Captures the data and the settings for one figure as a value, validates them, and returns an object that gfplot_render() turns into a ggplot. Use this when the figure is decided in one place and drawn in another, or when a specification needs to be stored, compared, or passed across a process boundary.

Usage

gfplot_spec(family, ...)

Arguments

Details

Call gfplot_families() for the available families and their required arguments.

Value

An object of class gfplot_spec.

See Also

gfplot_render(), plot_forest()

Examples

effects <- data.frame(
  term = c("Age", "Stage III"),
  hr = c(1.02, 1.84),
  lower = c(0.99, 1.51),
  upper = c(1.05, 2.24)
)
spec <- gfplot_spec(
  "forest",
  data = effects, term = "term",
  estimate = "hr", lower = "lower", upper = "upper"
)
spec

Description

The theme every gfplot figure is drawn with: bold axis titles, a thin major grid, a panel border, and a horizontal legend under the panel. Sizes derive from base_size, so one number rescales the figure.

Usage

gfplot_theme(
  base_size = 11,
  font = "Arial",
  grid = TRUE,
  border = TRUE,
  legend = c("bottom", "right", "top", "left", "none"),
  margin = c(9, 10, 8, 10)
)

Arguments

Details

This theme is also the session baseline: attaching gfplot sets it as the global ggplot2 theme so that figures drawn by other packages match. Set options(gfplot.set_theme = FALSE) before library(gfplot) to keep an existing theme instead.

Value

A ggplot2 theme object.

See Also

gfplot_colors() for the colours that go with it.

Examples

library(ggplot2)
p <- ggplot(mtcars, aes(wt, mpg)) +
  geom_point() +
  gfplot_theme()

Description

Computes the enrichment score with DOSE::gseaScores() and the p-value with fgsea, then draws the running score with the leading-edge position.

Usage

ggGSEA(input, gs, title = "")

Arguments

Value

A ggplot object.

Description

Draws the mean of value per group with standard error bars, and adds pairwise significance labels when comparisons is supplied.

Usage

plot_barplot(
  value,
  group,
  comparisons = NULL,
  palette = "house",
  color = NULL,
  ylab = "Score",
  xlab = NULL,
  title = NULL,
  font = "Arial",
  label = "p.signif"
)

Arguments

Details

This function replaced the 0.1.0 plot_barplot(), which took no arguments and could not be called.

Value

A ggplot object.

Examples

set.seed(1)
p <- plot_barplot(
  value = c(rnorm(20), rnorm(20, 1)),
  group = rep(c("A", "B"), each = 20)
)

if (requireNamespace("ggpubr", quietly = TRUE)) {
  p <- plot_barplot(
    value = c(rnorm(20), rnorm(20, 1), rnorm(20, 2)),
    group = rep(c("A", "B", "C"), each = 20),
    comparisons = list(c("A", "B"), c("B", "C"))
  )
}

Description

Boxplot with optional pairwise significance annotations

Usage

plot_Boxplot(
  value,
  label,
  palette = "house",
  title = NULL,
  ylab = "Expression",
  font = "Arial"
)

Arguments

Value

A ggplot object.

Examples

set.seed(1)
p <- plot_Boxplot(c(rnorm(20), rnorm(20, 1)), rep(c("A", "B"), each = 20))

Description

Predicted probability against the observed proportion of events. A model whose points sit on the diagonal predicts the level it claims; one above the diagonal under-predicts risk and one below over-predicts.

Usage

plot_calibration(
  probability,
  outcome,
  positive = NULL,
  bins = 10,
  smooth = FALSE,
  show_ci = TRUE,
  palette = "house",
  ci_level = 0.95,
  xlab = "Predicted probability",
  ylab = "Observed proportion",
  title = NULL,
  font = "Arial"
)

Arguments

Value

A ggplot object.

See Also

plot_ROC() for discrimination, plot_decision_curve() for whether acting on the predictions helps.

Examples

set.seed(1)
outcome <- rbinom(200, 1, 0.4)
probability <- plogis(rnorm(200) + outcome * 0.5)
p <- plot_calibration(probability, outcome)

Description

Predicted against actual class, with the count in each cell. Percentages are given per actual class, which is the direction that shows sensitivity and specificity; overall percentages would hide a class the model misses.

Usage

plot_confusion(
  predicted = NULL,
  actual = NULL,
  predicted_labels = NULL,
  actual_labels = NULL,
  positive = NULL,
  show = c("count", "percent", "both"),
  digits = 1,
  title = NULL,
  font = "Arial"
)

Arguments

Value

A ggplot object.

Examples

set.seed(1)
actual <- rbinom(200, 1, 0.4)
predicted <- ifelse(runif(200) < 0.8, actual, 1 - actual)
p <- plot_confusion(predicted, actual, positive = 1)

Description

Plot the correlation between two variables

Usage

plot_cor(x, y, groups = NULL, xlab = NULL, ylab = NULL, legend.pos = "top")

Arguments

Value

A ggplot object.

Examples

p <- plot_cor(iris$Sepal.Length, iris$Sepal.Width)

Description

The probability of each event type over follow-up, in the presence of competing events. When a patient can experience one of several mutually exclusive events, a Kaplan-Meier estimate of any single one is biased upward, because patients who had a competing event are still counted as being at risk of the event of interest. The cumulative incidence function accounts for them.

Usage

plot_cumulative_incidence(
  time,
  status,
  group = NULL,
  event = NULL,
  conf_int = FALSE,
  palette = "house",
  xlab = "Follow up",
  ylab = "Cumulative incidence",
  title = NULL,
  legend_title = NULL,
  font = "Arial"
)

Arguments

Value

A ggplot object.

See Also

plot_KMCurve() for a single event where no competing risk applies.

Examples

set.seed(1)
time <- rexp(200)
status <- sample(c(0, 1, 2), 200, replace = TRUE, prob = c(0.4, 0.4, 0.2))
p <- plot_cumulative_incidence(time, status, group = rep(c("A", "B"), 100))

Description

Net benefit across decision thresholds. Net benefit weights the true positives a model finds against the false positives it costs, at the threshold probability a clinician would use to act. It is the figure that answers whether using the model is better than treating everyone or no one.

Usage

plot_decision_curve(
  probability,
  outcome,
  positive = NULL,
  thresholds = seq(0.01, 0.5, by = 0.01),
  treat_all = TRUE,
  treat_none = TRUE,
  palette = "house",
  xlab = "Threshold probability",
  ylab = "Net benefit",
  title = NULL,
  font = "Arial"
)

Arguments

Value

A ggplot object.

See Also

plot_calibration() for whether the predicted levels are honest.

Examples

set.seed(1)
outcome <- rbinom(300, 1, 0.3)
probability <- plogis(rnorm(300) + outcome)
p <- plot_decision_curve(probability, outcome)

Description

Plot samples in a two-dimensional embedding, coloured by group. The embedding can be supplied already computed, or computed here from a feature matrix with stats::prcomp(), Rtsne, or umap.

Usage

plot_embedding(
  data,
  groups,
  method = c("pca", "tsne", "umap", "none"),
  perplexity = 30,
  seed = NULL,
  ellipse = FALSE,
  label_centres = FALSE,
  palette = "house",
  title = NULL,
  xlab = NULL,
  ylab = NULL,
  font = "Arial"
)

Arguments

Details

plot_PCA() and plot_UMAP() are thin wrappers around this function, so a figure keeps the same look whichever embedding it shows.

Value

A ggplot object.

See Also

plot_PCA(), plot_UMAP()

Examples

set.seed(1)
data <- matrix(rnorm(200), nrow = 20)
groups <- rep(c("A", "B"), each = 10)
p <- plot_embedding(data, groups, method = "pca")

Description

Draws point estimates with confidence intervals on a horizontal axis, with the numbers printed alongside. This is the standard display for hazard ratios, odds ratios, and mean differences, and it reads a table straight from clinstats::cox_table() or clinstats::logistic_table().

Usage

plot_forest(
  data,
  term,
  estimate,
  lower,
  upper,
  p = NULL,
  group = NULL,
  label = NULL,
  log_scale = FALSE,
  ref_line = NULL,
  estimate_label = "Estimate (95% CI)",
  p_label = "P",
  show_table = TRUE,
  digits = 2,
  xlab = NULL,
  title = NULL,
  font = "Arial"
)

Arguments

Value

A ggplot object, or a composed panel when show_table = TRUE, as with the risk table of plot_KMCurve(). Both print and save the same way.

See Also

gfplot_spec() to build the same figure as a value. The companion package clinstats produces the estimates this draws.

Examples

effects <- data.frame(
  term = c("Age, per year", "Stage III vs II", "MSI-high"),
  hr = c(1.02, 1.84, 0.62),
  lower = c(0.99, 1.51, 0.44),
  upper = c(1.05, 2.24, 0.88),
  p = c(0.21, 4.1e-07, 0.008)
)
p <- plot_forest(
  effects,
  term = "term", estimate = "hr", lower = "lower", upper = "upper",
  p = "p", log_scale = TRUE
)

# Straight from a clinstats table

if (requireNamespace("clinstats", quietly = TRUE)) {
  tbl <- clinstats::cox_table(
    clinstats::clin_crc,
    time = "rfs.delay", event = "rfs.event",
    factors = c("sex", "age", "tnm.stage"), multivariable = "none"
  )
  p <- plot_forest(
    tbl,
    term = "term", estimate = "hr_univariable",
    lower = "univ_ci_lower", upper = "univ_ci_upper", p = "univ_p",
    log_scale = TRUE
  )
}

Description

Plots the most significant terms with gene ratio on the x-axis, term on the y-axis, point size by gene count, and colour by significance.

Usage

plot_GO(gsea, n = 20, font = "Arial")

Arguments

Value

A ggplot object.

Description

Draws the values of a matrix as tiles with a colourbar. This is the display for correlation matrices, signature scores by group, and any rectangular table of values where the pattern matters more than the numbers.

Usage

plot_heatmap(
  matrix,
  row_order = NULL,
  column_order = NULL,
  values = FALSE,
  digits = 2,
  midpoint = NULL,
  diverging = FALSE,
  low = NULL,
  mid = NULL,
  high = NULL,
  legend_label = "Value",
  title = NULL,
  font = "Arial"
)

Arguments

Value

A ggplot object.

Examples

set.seed(1)
m <- cor(matrix(rnorm(60), nrow = 20))
diag(m) <- NA
p <- plot_heatmap(m, diverging = TRUE, midpoint = 0,
                  legend_label = "Correlation")

Description

Radar chart of immune-cell infiltration by group

Usage

plot_immune(res, group, title = "", legend.position = "left")

Arguments

Value

A ggplot object.

Description

Draws survival curves for two or more groups, with an optional number-at- risk table, the log-rank p-value, and, for two groups, the hazard ratio from a univariable Cox model.

Usage

plot_KMCurve(
  clinical,
  labels,
  limit = NULL,
  annot = NULL,
  color = NULL,
  font = "Arial",
  xlab = "Follow up",
  ylab = "Survival Probability",
  title = NULL,
  legend.pos = "top",
  palette = "house",
  risk.table = TRUE,
  risk.table.ratio = 0.4,
  anno.pos = "bottom",
  anno.x.shift = 0.5
)

Arguments

Value

A ggplot object, or a cowplot grid when risk.table = TRUE.

Examples

if (requireNamespace("survminer", quietly = TRUE)) {
  fit_data <- survival::lung
  p <- plot_KMCurve(
    survival::Surv(fit_data$time, fit_data$status == 2),
    factor(fit_data$sex),
    risk.table = FALSE
  )
}

Description

Draws the coefficient paths of a fitted glmnet model against the log lambda sequence and labels the coefficients that remain non-zero at the selected value of s.

Usage

plot_lasso(fit, s, font = "Arial")

Arguments

Value

A ggplot object.

Examples

if (requireNamespace("glmnet", quietly = TRUE)) {
  set.seed(1)
  x <- matrix(rnorm(100 * 5), nrow = 100)
  y <- rnorm(100) + x[, 1]
  p <- plot_lasso(glmnet::glmnet(x, y), s = 0.05)
}

Description

Each element of scores is matched with the corresponding element of labels, which allows the curves to come from different cohorts or endpoints rather than from different markers of the same cohort.

Usage

plot_MulROC(
  scores,
  labels,
  palette = "house",
  color = NULL,
  legend.pos = "bottom",
  title = NULL,
  font = "Arial",
  percent.style = FALSE
)

Arguments

Value

A ggplot object.

Examples

set.seed(1)
scores <- list(cohortA = rnorm(60), cohortB = rnorm(60))
labels <- list(rbinom(60, 1, 0.5), rbinom(60, 1, 0.5))
p <- plot_MulROC(scores, labels)

Description

Principal component analysis plot

Usage

plot_PCA(
  data,
  labs,
  title = "Evaluate the batch effect between groups",
  palette = "house",
  font = "Arial",
  ...
)

Arguments

Value

A ggplot object.

Examples

set.seed(1)
p <- plot_PCA(matrix(rnorm(200), nrow = 20), rep(c("A", "B"), each = 10))

Description

Precision against recall for a binary outcome. On an imbalanced outcome the ROC curve can look encouraging while precision stays low, which is what this plot exposes: it is the recommended companion when the event is rare.

Usage

plot_pr_curve(
  scores,
  labels,
  positive = NULL,
  palette = "house",
  title = NULL,
  font = "Arial",
  show_auc = TRUE
)

Arguments

Value

A ggplot object.

See Also

plot_ROC() for discrimination, plot_calibration() for the level of the predictions.

Examples

set.seed(1)
outcome <- rbinom(200, 1, 0.15)
score <- outcome * 0.8 + rnorm(200)
p <- plot_pr_curve(score, outcome)

Description

Plot a risk score ordered by patient

Usage

plot_RiskScore(
  rs,
  event,
  legend.position = c(0.2, 0.8),
  palette = "house",
  color = NULL,
  font = "Arial"
)

Arguments

Value

A ggplot object.

Examples

set.seed(1)
p <- plot_RiskScore(rnorm(30), rbinom(30, 1, 0.4))

Description

Plots receiver operating characteristic curves with the area under the curve and its confidence interval in the legend.

Usage

plot_ROC(
  scores,
  labels,
  force05 = FALSE,
  palette = "house",
  legend.pos = "bottom",
  title = NULL,
  font = "Arial",
  percent.style = FALSE
)

Arguments

Value

A ggplot object.

Examples

set.seed(1)
scores <- cbind(marker1 = rnorm(80), marker2 = rnorm(80))
labels <- rep(c(0, 1), each = 40)
p <- plot_ROC(scores, labels)

Description

Plots survival ROC curves at one or more time points using the Kaplan-Meier method of the survivalROC package.

Usage

plot_TimeROC(
  scores,
  survival,
  time_points,
  groups,
  palette = "house",
  legend.pos = "bottom",
  title = NULL,
  font = "Arial",
  percent.style = FALSE
)

Arguments

Value

A ggplot object.

Examples

if (requireNamespace("survivalROC", quietly = TRUE)) {
  set.seed(1)
  surv <- survival::Surv(rexp(100), rbinom(100, 1, 0.6))
  p <- plot_TimeROC(rnorm(100), surv, c(1, 2), c("year1", "year2"))
}

Description

t-SNE projection of samples coloured by group

Usage

plot_tsne(
  data,
  labs,
  title = "Evaluate the batch effect between groups",
  perplexity = 30,
  seed = 1,
  palette = "house",
  font = "Arial",
  ...
)

Arguments

Value

A ggplot object.

Examples

if (requireNamespace("Rtsne", quietly = TRUE)) {
  set.seed(1)
  p <- plot_tsne(matrix(rnorm(200), nrow = 20), rep(c("A", "B"), each = 10))
}

Description

UMAP projection plot

Usage

plot_UMAP(
  data,
  labs,
  title = "Evaluate the batch effect between groups",
  palette = "house",
  font = "Arial",
  ...
)

Arguments

Value

A ggplot object.

Examples

if (requireNamespace("umap", quietly = TRUE)) {
  set.seed(1)
  p <- plot_UMAP(matrix(rnorm(200), nrow = 20), rep(c("A", "B"), each = 10))
}

Description

Violin plots with the individual observations overlaid, which shows both the shape of each distribution and how much data stands behind it. A boxplot alone hides a bimodal group and a group with four samples.

Usage

plot_violin(
  value,
  group,
  order = NULL,
  show = c("violin", "box", "both"),
  points = TRUE,
  points_maximum = 300,
  show_n = TRUE,
  significance = FALSE,
  palette = "house",
  ylab = NULL,
  xlab = NULL,
  title = NULL,
  font = "Arial"
)

Arguments

Value

A ggplot object.

See Also

plot_Boxplot() for the box-only version.

Examples

set.seed(1)
p <- plot_violin(c(rnorm(40), rnorm(40, 1)), rep(c("A", "B"), each = 40))

Description

Effect size against significance, with the calling thresholds drawn. This is the standard first look at a differential analysis: it separates the features that moved a lot from the ones that moved reliably, and shows how many of each the thresholds produce.

Usage

plot_volcano(
  effect,
  p_value,
  label = NULL,
  effect_threshold = 1,
  p_threshold = 0.05,
  label_top = 10,
  palette = "house",
  repel = TRUE,
  xlab = "Effect size",
  ylab = expression(-log[10] ~ italic(P)),
  title = NULL,
  font = "Arial"
)

Arguments

Value

A ggplot object.

Examples

set.seed(1)
effect <- rnorm(2000)
p_value <- runif(2000)^2
p <- plot_volcano(effect, p_value, paste0("gene", seq_along(effect)))

Description

Patients ranked by response, with the bar height showing how far each departed from baseline and the fill showing the response category. This is the standard display of response in a single-arm trial.

Usage

plot_waterfall(
  response,
  category = NULL,
  patient = NULL,
  label_top = 0,
  thresholds = c(`Partial response` = -30, `Stable disease` = 20),
  threshold_labels = TRUE,
  show_patients = FALSE,
  palette = "house",
  xlab = NULL,
  ylab = "Change from baseline (%)",
  title = NULL,
  font = "Arial"
)

Arguments

Value

A ggplot object.

Examples

set.seed(1)
response <- c(rnorm(40, -10, 20), rnorm(10, 40, 15))
p <- plot_waterfall(response)

Description

Updated version of the viewGSEA() helper distributed with HTSanalyzeR2.

Usage

viewGSEA(object, gscName, gsName, title = "")

Arguments

Value

A ggplot object.