Getting started with depictr

depictr is a toolkit of plots that cover the analysis workflow, from a first look at the data, through model estimates and predictions, to diagnostics, uncertainty and reporting. Every plotting function returns a ggplot2 object (Wickham, 2016), or a patchwork for composite panels, so you can customise it further with the usual + syntax. All plots use the same theme, palette and label conventions.

library(depictr)

Attaching package: 'depictr'
The following object is masked _by_ '.GlobalEnv':

    simulate_figure

Five datasets to explore

The package includes five reproducibly simulated datasets, each chosen to illustrate a different family of plots. They are documented under their own names, as in ?lexical_decision, and load with data():

A tour by task

For a first look at the data, explore_bivariate() chooses a suitable plot for any pair of variables, here a scatter with a trend because both are numeric.

explore_bivariate(crop_yield, fertiliser, yield)

Once a model is fitted, coefficient_plot() draws a forest plot of its estimates.

fit <- lm(yield ~ rainfall + fertiliser + soil_ph + treatment,
          data = crop_yield)
coefficient_plot(fit, order = "descending", title = "Drivers of crop yield")

To see what the model implies, effects_plot() traces the predicted response as one predictor varies.

effects_plot(fit, "fertiliser")

residual_diagnostics_plot() gathers the usual checks of the fit into one panel.

residual_diagnostics_plot(fit)

For uncertainty, posterior_plot() summarises posterior or simulation draws as a distribution per parameter. These are the fixed-effect posterior draws from a Bayesian fit of the lexical-decision model, included with the package.

draws <- readRDS(system.file("extdata", "lexdec_draws.rds",
                             package = "depictr"))
posterior_plot(draws[c("conditionunrelated", "modalityauditory",
                       "word_frequency")],
               labels = c(conditionunrelated = "condition",
                          modalityauditory = "modality",
                          word_frequency = "word frequency"),
               title = "Lexical-decision fixed effects (ms)")

A standard estimate table: tidy_estimates()

Most of the model functions use tidy_estimates(), which turns a model, or a data frame of pre-computed estimates, into one standard table. The plotting functions also accept that table, so estimates from any source, such as Bayesian posteriors, bootstrap intervals or figures taken from a paper, can be supplied directly.

tidy_estimates(fit)
               term     estimate    std.error     conf.low    conf.high
1       (Intercept) -7.156372471 0.7307020339 -8.597465983 -5.715278960
2          rainfall  0.003869765 0.0006025038  0.002681505  0.005058026
3        fertiliser  0.011266582 0.0010906005  0.009115695  0.013417469
4           soil_ph  1.030217728 0.1056219670  0.821909657  1.238525800
5 treatmentenhanced  1.317044684 0.0978270830  1.124109715  1.509979654

A consistent, accessible look

theme_depictr(), depictr_palette() and scale_colour_depictr() style your own plots too:

library(ggplot2)
ggplot(crop_yield, aes(fertiliser, yield, colour = treatment)) +
  geom_point(alpha = 0.7) +
  scale_colour_depictr() +
  theme_depictr()

depictr_palette() returns the palette’s hex colours for use in scale_fill_manual() or a base-graphics col = argument:

depictr_palette(4)
[1] "#005b96" "#e69f00" "#009e73" "#d55e00"

The qualitative palette is based on the Okabe-Ito set (Okabe & Ito, 2008), which stays distinguishable under the common forms of colour-vision deficiency. Sequential and diverging variants are also available, and palette_preview() can draw all three:

palette_preview(type = "all")

palette_preview() can also simulate a colour-vision deficiency and show a palette as a deuteranope (red-green) would see it:

palette_preview(cvd = "deutan")

The simulation is available on its own as simulate_cvd(), and palette_safety() uses it to give a verdict. For normal vision and each deficiency at full severity, palette_safety() reports the smallest perceptual distance between any two colours in a palette, the CIEDE2000 colour difference (Sharma et al., 2005).

palette_safety()
$min_delta_e
[1] 6.43

$by_condition
normal protan deutan tritan 
 21.25  13.44   6.43  11.13 

$worst_condition
[1] "deutan"

$worst_pair
[1] "#cc79a7" "#999999"

$safe
[1] TRUE

$threshold
[1] 5

simulate_figure() applies the same simulation to a whole figure. It covers every colour the figure draws, in the data, the legend keys, the text and any colourbar. The result is a gtable that grid::grid.draw() draws and save_plot() saves. The example draws the scatter plot from the start of this section as a reader with deuteranopia sees it:

by_treatment <- ggplot(crop_yield, aes(fertiliser, yield, colour = treatment)) +
  geom_point(alpha = 0.7) +
  scale_colour_depictr() +
  theme_depictr()

grid::grid.newpage()
grid::grid.draw(simulate_figure(by_treatment, "deutan"))

Auditing the figure you are about to submit

Once a plot has been extended with your own scale, shrunk to fit a journal column or made to distinguish groups by colour alone, the palette’s guarantee no longer describes what a reader will see. check_figure() reads a built plot and reports each value it measured next to the threshold it was measured against.

grouped <- ggplot(crop_yield, aes(fertiliser, yield, colour = treatment)) +
  geom_point(alpha = 0.7) +
  scale_colour_depictr() +
  theme_depictr()

check_figure(grouped)
                        check measured threshold        verdict
1         colour_separability    52.37       5.0           pass
2  colour_separability_protan    48.53       5.0           pass
3  colour_separability_deutan    53.10       5.0           pass
4  colour_separability_tritan    49.09       5.0           pass
5      greyscale_separability    23.06       5.0           pass
6                   text_size     8.80       6.0           pass
7               text_contrast     8.45       4.5           pass
8           geometry_contrast     1.76       3.0           fail
9          redundant_encoding     0.00       1.0           fail
10       annotation_text_size       NA       6.0 not applicable
                                                                        detail
1                      Closest pair #4d8cb6 and #eebc4d of 2 encoding colours.
2                      Closest pair #4d8cb6 and #eebc4d of 2 encoding colours.
3                      Closest pair #4d8cb6 and #eebc4d of 2 encoding colours.
4                      Closest pair #4d8cb6 and #eebc4d of 2 encoding colours.
5                           Closest pair #4d8cb6 and #eebc4d in CIE lightness.
6            Smallest text 8.80 pt, drawn at 17.78 cm and printed at 17.78 cm.
7                          Lowest-contrast text #4d4d4d on #ffffff at 8.80 pt.
8  Lowest-contrast colour #e69f00 at alpha 0.70, drawn as #eebc4d, on #ffffff.
9                                       Colour alone distinguishes the groups.
10                                  The figure draws no text inside the panel.

geometry_contrast measures each encoding colour, as it is drawn, against the panel background. Even when opaque, the palette’s orange falls below the 3:1 that WCAG asks of a graphical object (World Wide Web Consortium, 2024), at 2.25:1, and it falls further when drawn translucent, as these points are. redundant_encoding is zero because nothing but colour tells the two treatments apart. Both rows pass once shape is mapped as well, the darker vermillion is used as the second colour and the points are drawn opaque:

mended <- ggplot(crop_yield, aes(fertiliser, yield, colour = treatment,
                                 shape = treatment)) +
  geom_point() +
  scale_colour_manual(values = c("#005b96", "#d55e00")) +
  theme_depictr()

check_figure(mended)[, c("check", "measured", "threshold", "verdict")]
                        check measured threshold        verdict
1         colour_separability    50.12       5.0           pass
2  colour_separability_protan    49.67       5.0           pass
3  colour_separability_deutan    58.30       5.0           pass
4  colour_separability_tritan    61.99       5.0           pass
5      greyscale_separability    16.92       5.0           pass
6                   text_size     8.80       6.0           pass
7               text_contrast     8.45       4.5           pass
8           geometry_contrast     3.87       3.0           pass
9          redundant_encoding     1.00       1.0           pass
10       annotation_text_size       NA       6.0 not applicable

The vermillion need not be typed by hand. scale_colour_depictr(order = "contrast") draws the groups in the contrast-first order of depictr_palette(). It starts with the brand blue, the vermillion and the reddish purple, the only three of the eight colours that pass every colour row together. The bluish green comes fourth, and with it four groups still keep 3:1 against white. depictr_options(palette = depictr_palette(order = "contrast")) makes that order the default for every later plot. Under that default, the second group takes the vermillion, which depictr also uses as its accent for single highlights.

The audit also takes a stated output width, because most figure text fails unnoticed at its printed width. Text is drawn in points, so the text of a figure saved seven inches wide and then printed in an 8.9 cm column is half the size it was on screen:

subset(check_figure(grouped, width_cm = 8.9), check == "text_size")
      check measured threshold verdict
6 text_size      4.4         6    fail
                                                            detail
6 Smallest text 8.80 pt, drawn at 17.78 cm and printed at 8.90 cm.

A figure saved at the size it will be printed is drawn at that size, so give the saved width as both width_cm and render_width_cm, or leave both at their defaults. save_plot(check = TRUE) runs the audit as it saves, at the width it saves at, and warns about each check the figure fails.

Text drawn inside the panel, such as an annotation, a label or a cell value, has a row of its own, annotation_text_size, held to the same floor as text_size. That floor defaults to 6 pt, which is lenient. As their guidelines stood on 30 September 2026, PLOS and APA Style asked for at least 8 pt, Elsevier for 7 pt and Nature for 5 to 7 pt, and ?check_figure links all four. Nature’s range also has a ceiling, since no text but the panel labels may exceed 7 pt. Passing max_text_pt = 7 adds a row, text_size_max, that holds a figure to that ceiling.

The eight-colour qualitative palette passes every colour-vision check and fails the greyscale check. The Okabe-Ito guarantee covers hue confusion alone. The palette’s orange and sky blue differ by 0.79 in CIE lightness, so a black-and-white printer renders them as the same grey. The greyscale check holds the package’s own palette to the same threshold as any other and reports the measured difference. A figure that may be printed in black and white should use fewer groups or a sequential palette, or add a redundant shape or line type.

eight <- data.frame(g = factor(letters[1:8]), x = 1:8, y = 1:8)
p8 <- ggplot(eight, aes(x, y, colour = g)) +
  geom_point() +
  scale_colour_depictr() +
  theme_depictr()

subset(check_figure(p8), check == "greyscale_separability")
                   check measured threshold verdict
5 greyscale_separability     0.79         5    fail
                                              detail
5 Closest pair #56b4e9 and #e69f00 in CIE lightness.

The audit does not measure a continuous colour or fill scale, such as that of a heatmap. When nothing else in the figure encodes by colour, its colour rows report no result and give the reason. A ramp is read by its lightness, so prefer one whose lightness changes evenly. A perceptually uniform map, such as viridis, is preferable to a rainbow (Crameri et al., 2020). depictr’s own sequential and diverging ramps are perceptually ordered.

Set the look once for a whole script with depictr_options(). It holds the base size and family, the brand, accent and reference-line colours, a custom palette and the colour of NA levels. Called with no arguments, it reports the current settings:

depictr_options()
$base_size
[1] 11

$base_family
[1] ""

$brand
[1] "#005b96"

$accent
[1] "#d55e00"

$reference
[1] "grey60"

$palette
NULL

$na_value
[1] "grey80"

Supplying arguments sets them for every later plot and returns the previous values, so you can put the look back afterwards:

old <- depictr_options(base_size = 13, accent = "#b3589a")
coefficient_plot(fit, title = "Set once, applied everywhere")

do.call(depictr_options, old)   # restore the previous settings

Where to next

The remaining articles go into each area in turn. vignette("exploring-data") covers distributions, categories, bivariate plots, scatter-plot matrices, correlations, missingness, outliers, summary tables and the estimation plots. vignette("model-estimates") covers forest plots, model comparison, predicted values, interactions, random effects, optimiser checks and the frequentist-over-Bayesian-posterior overlay. vignette("diagnostics-and-uncertainty") covers residuals, GLM-appropriate binned residuals, the classification suite (ROC, PR, gains, lift, calibration, thresholds) on an imbalanced outcome, and power curves. Two further articles, vignette("multivariate-and-survival") and vignette("time-series"), cover the remaining methods.

References

Crameri, F., Shephard, G. E., & Heron, P. J. (2020). The misuse of colour in science communication. Nature Communications, 11(1), 5444. https://doi.org/10.1038/s41467-020-19160-7
Okabe, M., & Ito, K. (2008). Color Universal Design (CUD): How to make figures and presentations that are friendly to colorblind people. https://jfly.uni-koeln.de/color/.
Sharma, G., Wu, W., & Dalal, E. N. (2005). The CIEDE2000 color-difference formula: Implementation notes, supplementary test data, and mathematical observations. Color Research & Application, 30(1), 21–30. https://doi.org/10.1002/col.20070
Wickham, H. (2016). ggplot2: Elegant graphics for data analysis (2nd ed.). Springer. https://doi.org/10.1007/978-3-319-24277-4
World Wide Web Consortium. (2024). Web Content Accessibility Guidelines (WCAG) 2.2. W3C Recommendation, https://www.w3.org/TR/WCAG22/.