maidr maidr logo

Overview

maidr (Multimodal Access and Interactive Data Representation) makes data visualizations accessible to users with visual impairments. It converts ggplot2 and Base R plots, and experimentally lattice charts, into interactive, accessible HTML/SVG formats with keyboard navigation, screen reader support, and sonification. maidr for R is the R binding of MAIDR, the JavaScript core developed by the (x)Ability Design Lab at the University of Illinois Urbana-Champaign; the same accessibility layer is available for Python as py-maidr.

The package provides two main functions:

Installation

maidr requires R 4.0.0 or later. Install the stable release from CRAN:

install.packages("maidr")

Or install the development version from GitHub:

# Using pak (recommended)
pak::pak("xability/r-maidr")

# Alternative: using pacman (auto-installs if missing)
pacman::p_load_gh("xability/r-maidr")

The development version is built from source, and maidr includes C++ code, so this needs a compiler: Rtools on Windows, the Xcode command line tools on macOS.

Usage

ggplot2

library(maidr)
library(ggplot2)

p <- ggplot(mpg, aes(x = class)) +
  geom_bar(fill = "steelblue") +
  labs(title = "Vehicle Classes", x = "Class", y = "Count")

# Display interactive accessible plot
show(p)

# Or save to file
save_html(p, "vehicle_classes.html")

Base R

library(maidr)

# Create plot first
barplot(
  table(mtcars$cyl),
  main = "Cars by Cylinder Count",
  xlab = "Cylinders",
  ylab = "Count"
)

# Then call show() without arguments
show()

plotly, highcharter and echarts4r widgets

maidr_htmlwidget() makes an interactive chart from plotly (plot_ly(), ggplotly()), highcharter or echarts4r accessible. The chart is read in the browser by the MAIDR adapter for the library that draws it, so it works wherever the widget does: the viewer, htmlwidgets::saveWidget(), R Markdown, Quarto and Shiny.

library(maidr)
library(plotly)

plot_ly(mtcars, x = ~wt, y = ~mpg, type = "scatter", mode = "markers") |>
  maidr_htmlwidget()

# ggplotly() keeps your ggplot2 code
ggplotly(ggplot(mtcars, aes(wt, mpg)) + geom_point()) |>
  maidr_htmlwidget()

An echarts4r chart is switched to ECharts' SVG renderer, which MAIDR needs to highlight the mark being read. While an echarts4r chart shows its legend, the visual highlight is off; audio, text and braille are not affected.

An echarts4r fan chart -- a median line with bands drawn as stacked areas -- is read as a percentile band once percentile_bands names its series and the quantiles of each band's edges. The option needs maidr.js 4.15.0 or later, the version bundled with this package; with an older one pinned by maidr.cdn_version it is ignored with a warning. See ?maidr_htmlwidget.

library(maidr)
library(echarts4r)

# A median and a 90% band drawn as a stacked area
fan <- data.frame(
  week = paste("Week", 1:8),
  median = c(10, 12, 13, 15, 16, 18, 19, 21),
  lower = c(8, 9, 9, 10, 10, 11, 11, 12)
)
fan$width <- 2 * (fan$median - fan$lower)

fan |>
  e_charts(week) |>                    # a category x axis
  e_line(median, name = "Median") |>
  e_line(lower, stack = "band", name = "lower", symbol = "none",
         lineStyle = list(opacity = 0)) |>
  e_area(width, stack = "band", name = "90% interval", symbol = "none") |>
  maidr_htmlwidget(
    percentile_bands = list(
      median = "Median",
      bands = data.frame(series = "90% interval", lower = 0.05, upper = 0.95)
    )
  )

lattice

A lattice chart is used the way a ggplot2 object is: printing it opens the maidr viewer, and show() and save_html() take it. Every lattice chart type maidr reads is experimental; the lattice table under Experimental Plot Types lists them.

library(maidr)
library(lattice)

cylinders <- as.data.frame(table(Cylinders = mtcars$cyl))

p <- barchart(
  Freq ~ Cylinders,
  data = cylinders,
  origin = 0,
  main = "Cars by Cylinder Count",
  ylab = "Count"
)

# Printing the chart opens it in the maidr viewer
p

# show() is the explicit form; save_html() writes it to a file
show(p)
save_html(p, "cylinders.html")

A conditioned chart, such as xyplot(mpg ~ wt | factor(cyl), mtcars), is read one panel at a time: each panel is a subplot of its own, named after its strip.

Chart size

A chart is drawn at 7 x 5 inches unless you give it a size, in inches as ggplot2::ggsave() takes one, and its SVG is 72 pixels to the inch (in a knitted page it is shown at the size of the chunk's figure instead). The size is the room the chart is laid out in; the data, titles and axis labels a reader hears are the same at every size. Only a lattice chart conditioned on one variable with no layout = changes for a reader: lattice arranges its panels for the shape of the page, and the order a reader moves through them follows, so give it layout = to keep one. A side over 50 in is refused, as ggsave() refuses one, since it is most likely pixels.

show(p, width = 10, height = 4)
save_html(p, "wide.html", width = 10, height = 4)

# Base R: draw, then show at a size
barplot(table(mtcars$cyl))
show(width = 6, height = 4)

# Shiny: the chart's size; maidr_output()'s width and height size the output
output$plot <- render_maidr(p, fig_width = 10, fig_height = 4)

In R Markdown and Quarto the chunk's fig.width and fig.height set it. Nothing else does: not the device a Base R chart was drawn on, nor the window or Shiny output a chart is shown in, which shrinks a wider chart to fit. A candlestick chart is never drawn smaller than 12 x 6 in; asked for less (in a document, by the chunk's own options), maidr says in a message the size it used. A Base R chart too small for its margins and text, or for the cells a layout() sizes with lcm(), at the size you ask for is an error naming the size. With no size asked for, one too small for 7 x 5 in, such as a par(mfrow) grid of five rows, is drawn larger, at 7 x 7 in or the smallest larger size that leaves each of its plots room to be seen, and a message names the size.

Hover mode

By default, moving the pointer over a chart moves the reader's position with it, and the highlight, sound and announcement follow. hover_mode sets how a chart starts instead: "click" moves the reader only where they click, and "off" leaves the pointer out of it, so only the keyboard moves them. It is the chart's starting value for the reader's own Hover Mode setting, not a lock on it: a reader who has changed that setting keeps theirs.

show(p, hover_mode = "click")
save_html(p, "quiet.html", hover_mode = "off")
output$plot <- render_maidr(p, hover_mode = "click")
maidr_htmlwidget(w, hover_mode = "click")   # highcharter and echarts4r

# Every chart that sets none, R Markdown and Quarto documents included
options(maidr.hover_mode = "click")

Left unset, nothing is written and the reader's setting decides. maidr.js reads it from 4.15.0, the version bundled with this package; an older one, which maidr.cdn_version can pin, ignores it.

R Markdown and Quarto

library(maidr) in a setup chunk is all a document needs. Every plot it draws, with ggplot2, lattice or Base R, becomes an accessible chart:

```{r setup, include = FALSE}
library(maidr)
library(ggplot2)
```

```{r cars, fig.cap = "Cars by cylinder count"}
ggplot(mtcars, aes(factor(cyl))) + geom_bar()
```

How maidr hooks into your session

Supported plot types

maidr supports a wide range of visualization types in both ggplot2 and Base R, in the two tables below. It also reads lattice charts, but only as experimental types, so lattice has no column here: its charts are listed under Experimental Plot Types.

Basic Plot Types

Plot Type ggplot2 Base R
Bar charts geom_bar(), geom_col() barplot()
Grouped/Dodged bars position = "dodge" beside = TRUE
Stacked bars position = "stack" beside = FALSE
Pie charts geom_col()/geom_bar() + coord_polar("y") pie()
Histograms geom_histogram() hist()
Scatter plots geom_point() plot()
Line plots geom_line() plot(type = "l"), lines()
Step plots geom_step() plot(type = "s"), plot(type = "S")
Box plots geom_boxplot() boxplot()
Heatmaps geom_tile() image()
Contour plots — (geom_contour() is [experimental], see below) contour()
Violin plots geom_violin() — (vioplot::vioplot() is [experimental], see below)
Candlestick (OHLC) tidyquant::geom_candlestick() (+ geom_ma(), + patchwork volume) quantmod::chartSeries() (OHLC-only; no TA / no volume)
Density/Smooth geom_smooth(), geom_density() lines(density())

Note: Volume bars and moving-average overlays for candlestick charts are supported only on the ggplot2 + {tidyquant} + {patchwork} path. On the Base R path, quantmod::chartSeries() TA overlays (addVo(), addSMA(), addEMA()) — and the default TA whenever the input xts carries a Volume column — fall back to native (non-accessible) graphics with a one-time advisory.

Advanced Plot Types

Plot Type ggplot2 Base R
Faceted plots facet_wrap(), facet_grid() par(mfrow/mfcol) + loops
Multi-panel layouts patchwork package par(mfrow), par(mfcol)
Multi-layered plots Multiple geom_* layers Sequential plot calls

Experimental Plot Types

[!WARNING] These are prototypes. Treat them as prototypes. They are under active development, they are unstable, and none of them has been through a user study. Field names, announcement wording and navigation may change without a deprecation period, including in a patch release. If you are building something that has to keep working, build it on the plot types above.

Everything in the two tables above predates the plot coverage roadmap (#137) and has been exercised by real readers over real charts. Everything below was added by that roadmap, by the base R sweeps that followed it (#251, #262) or with the lattice reading (#333), most inside a few weeks.

Each was measured against the chart it reads — that is what the issues and the tests record. But measuring that a reading is faithful to the drawing is a different claim from establishing that it is useful to a reader. Nobody has asked a blind or low-vision reader whether hearing stars() as a radar, or navigating a termplot() panel by panel, is the right way to read one. Until that happens these are proposals about how a chart could be read, not answers.

Feedback is exactly what would move one of these into the tables above.

Elsewhere in these docs — the example articles, the getting-started vignette and the package help — an experimental type is marked [experimental] after its name; a type with no mark is stable. Wherever they list plot types, the stable ones come first and the experimental ones follow in a section of their own, as they do here.

ggplot2

Layer type Drawn by
area geom_area(), geom_ribbon(aes(ymin = 0, ...))
stacked_area stacked geom_area()
stacked_normalized_area geom_area(position = "fill")
stacked_normalized_bar geom_bar(position = "fill")
contour geom_contour(), geom_density_2d()
directed_graph ggraph::ggraph() of a directed graph (the node layer; edges are read from the graph)
error_bar geom_errorbar(), geom_errorbarh(), geom_linerange(), geom_pointrange(), geom_crossbar(), geom_ribbon() as a band other than a median_hilow summary
gantt geom_segment(), geom_curve(), maidr_gantt()
hexbin geom_hex(), stat_bin_2d()
manhattan maidr_manhattan()
percentile_band ggdist::stat_lineribbon(), ggdist::geom_lineribbon() of a median_qi() summary, stat_summary(geom = "ribbon", fun.data = median_hilow) (with its stat_summary() median line)
polygon geom_polygon()
pr_curve maidr_pr_curve(), autoplot() of a yardstick::pr_curve()
roc maidr_roc(), pROC::ggroc(), autoplot() of a yardstick::roc_curve()
rug geom_rug()
survival maidr_survival() of a survfit object or of data, a survminer::ggsurvplot() figure: one Kaplan-Meier curve per stratum, with its censored times and, when drawn, its confidence band
volcano maidr_volcano()

Base R

Layer type Drawn by
biplot biplot()
box_stats bxp()
conditional_density cdplot()
correlogram acf(), pacf(), ccf()
cumulative_periodogram cpgram()
directed_graph igraph's plot() of a directed graph (circle vertices)
dot dotchart() (ungrouped)
filled_contour filled.contour()
fourfold fourfoldplot() (2x2 tables, std = "ind.max" / "all.max")
interaction interaction.plot()
lag lag.plot()
lollipop plot(type = "h")
mosaic mosaicplot() (two-way tables)
pairs pairs()
qq qqnorm()
qqline qqline()
radar stars()
residual assocplot() (two-way tables)
rocr_performance ROCR's plot() of a performance object: a pr_curve layer for performance(pred, "prec", "rec"), a line for any other measure (attach ROCR before maidr)
spectral_density spectrum()
spine spineplot()
stacked_normalized_bar barplot() of proportions
strip stripchart()
subseries monthplot()
survival survival's plot() of a survfit object: one Kaplan-Meier curve per stratum, with its censored times and, when drawn, its confidence band
termplot termplot()
violin vioplot::vioplot()
word_cloud wordcloud::wordcloud()

lattice

Every chart maidr reads from lattice is experimental, including those read as a layer type that is stable for ggplot2 and Base R: a barchart() is emitted as the same bar layer as barplot(), but reading what lattice drew, panel by panel and group by group, is new.

Layer type Drawn by
bar barchart() without groups, histogram() of a factor with one bar per level
dodged_bar barchart() with groups
stacked_bar barchart() with groups and stack = TRUE, barchart() of a table or matrix
hist histogram()
point xyplot(), stripplot(), qqmath(), qq(), dotplot() with several values on a level
line xyplot(type = "l") and the lines of "b", "o" and "a", xyplot() of a time series, and the same types on stripplot(), dotplot(), qqmath() and qq()
step xyplot(type = "s"), xyplot(type = "S")
box bwplot()
heat levelplot(), contourplot(region = TRUE)
contour contourplot(), levelplot(contour = TRUE)
smooth densityplot(), and xyplot(), qqmath() and qq() with type = "r", "smooth" or "spline" on numeric axes
dot dotplot() with one value per level
lollipop xyplot(type = "h"), and type = "h" on stripplot(), dotplot(), qqmath() and qq()

A conditioned chart (y ~ x | g) is read one panel at a time, each panel a subplot, laid out as lattice lays them out; groups gives one point layer per group, or one series per group on a line or curve -- one layer per group when the groups' curves share no x value, since Up and Down only move between series that meet at the x being read. A chart laid out over several pages is read from its first page, with a warning. What the reading does not cover is shown as a static image: cloud(), wireframe(), splom(), parallelplot(), a panel function of your own or one such as panel.violin, levelplot(useRaster = TRUE), latticeExtra layers and compositions, a fit (type = "r", "smooth" or "spline") over a factor axis, as on a stripplot() or dotplot(), and a panel that fails to draw.

The split is the diff of each factory's get_supported_types() against 8de0e98, the last commit on main before #137 was filed. The lattice factory came later, so every type it reads is experimental. tests/testthat/test-plot-type-stability.R checks all three factories — ggplot2, Base R and lattice — and fails if a type one of them supports appears in neither the stable tables nor its experimental table, so a new layer type has to be placed deliberately rather than inherit either promise by being forgotten.

The JavaScript core and the Python binding make the same distinction over their own type lists, with the same boundary and for the same reason, and mark their docs the same way: see the JavaScript core's trace type stability and the Python binding's stability page.

See the examples gallery for a worked example of each plot type.

Accessibility features

The keys a reader needs first, the same on every page of this documentation:

Key Action
Tab Focus the chart; Shift + Tab leaves it
Left / Right Move between data points
Up / Down Move between series, stacked segments, heat map rows or box plot sections, on a chart that has them
Page Up / Page Down Switch between the layers of a chart that has several
B Toggle braille mode
T Toggle text mode
S Toggle sonification
R Toggle review mode
C Toggle high contrast mode
L, then X, Y or T Announce the x axis label, the y axis label or the title
Space Repeat the current sound
Ctrl + / (Cmd + / on macOS) Show or hide the full keyboard shortcut help

Every other shortcut, including autoplay, jumping to the ends, the command palette, settings and the AI chat, is on the MAIDR controls reference.

Offline support

By default, show() and save_html() use the bundled maidr.js library, so the result works offline. save_html() writes the library to a lib/ folder beside the file, and the two have to be shared together: zip the folder that holds both, or copy both. An .html sent on its own loads no maidr.js and shows a plain, inaccessible chart. A knitted R Markdown or Quarto page loads the bundled maidr.js once for all its charts, from its _files folder or embedded in it when it is self_contained / uses embed-resources, so it works offline wherever it was rendered. Widgets, Shiny apps, and the few knitted outputs that keep a chart in an iframe (an HTML fragment, pagedown) auto-detect internet availability and use the CDN when online. A page holding a widget rendered online also carries its own copy of maidr.js, which its charts fall back on when the CDN cannot be reached, so a self_contained / embed-resources page works offline too. Use the use_cdn parameter for explicit control:

# Force CDN: one self-contained file, needs internet whenever it is viewed
show(p, use_cdn = TRUE)
save_html(p, "plot.html", use_cdn = TRUE)

# Force bundled files: works offline, lib/ folder beside the saved file
show(p, use_cdn = FALSE)
save_html(p, "plot.html", use_cdn = FALSE)

The CDN paths load the latest published maidr.js, not the copy bundled with this package, as the Python binding does. The first CDN document in an R session asks jsDelivr (then the npm registry) which version that is, within 3 seconds, and every document in the session names that version. If the lookup cannot be made it costs no error: the document names the bundled version instead, the copy use_cdn = FALSE would serve. Pin a version when a document has to load the same maidr.js whenever it is opened:

options(maidr.cdn_version = "bundled")  # the bundled version, no lookup
options(maidr.cdn_version = "4.9.0")    # a particular release

or set MAIDR_CDN_VERSION in the environment. use_cdn = FALSE never makes that lookup. See ?"maidr-options".

Two things still reach the network from an offline document, and only when a reader uses them. One is a language other than English. maidr.js reads charts in English on its own and fetches Korean, Japanese, Chinese, Spanish, German, French, Italian or Hindi as a small pack from beside itself. This package does not bundle the packs, which would add 0.8 MB against CRAN's size limit, so a use_cdn = FALSE document points maidr.js at the packs of the bundled version on jsDelivr: a reader whose language is not English hears it when online, and English when not. Serve the packs yourself, or turn this off:

options(maidr.locale_base_url = "https://example.org/maidr/")  # your own copy
options(maidr.locale_base_url = FALSE)  # never fetch a pack: English only

The other is connecting a DotPad tactile display. maidr.js does not bundle the DotPad SDK, whose braille engine is a 14 MB liblouis build, and imports the vendor's copy from jsDelivr the first time a DotPad is connected. Rendering, sonification and braille work offline regardless. To keep the DotPad offline too, download the pinned SDK once and every use_cdn = FALSE document carries it in its lib/ folder:

maidr_download_dotpad_sdk()          # ~14 MB, once, into a per-user cache
save_html(p, "plot.html", use_cdn = FALSE)   # lib/dotpad-sdk-<version>/ beside it

A page served from elsewhere, or a knitted R Markdown or Quarto document, which does not carry the downloaded copy, names its copy by URL instead, through options or the environment variables of the same names:

options(
  maidr.dotpad_sdk_url = "https://intranet.example/dotpad/DotPadSDK-3.0.3.js",
  maidr.dotpad_asset_base_url = "https://intranet.example/dotpad/lib/"
)
# or: Sys.setenv(MAIDR_DOTPAD_SDK_URL = "...", MAIDR_DOTPAD_ASSET_BASE_URL = "...")

Every document maidr produces then declares window.MAIDR_DOTPAD_SDK_URL and window.MAIDR_DOTPAD_ASSET_BASE_URL ahead of maidr.js. See ?"maidr-options".

Getting help

Learning more

Related projects

maidr for R is one of three MAIDR packages, all developed by the (x)Ability Design Lab at the University of Illinois Urbana-Champaign:

Citation

If you use maidr in research, please cite the MAIDR papers:

citation("maidr") prints both, plus an entry for the package itself, in text and BibTeX form.