Getting Started with MAIDR

Introduction to MAIDR

MAIDR (Multimodal Access and Interactive Data Representation) is an R package that makes data visualizations accessible to users with visual impairments. It converts ggplot2 and Base R plots into interactive, accessible formats with:

Keyboard navigation - Explore data using arrow keys
Screen reader support - Full ARIA labels and descriptions
Sonification - Hear data patterns through sound
HTML/SVG output - Standalone accessible visualizations

MAIDR helps data scientists and researchers create inclusive visualizations that everyone can explore, regardless of visual ability.

Installation

Install the development version from GitHub:

# Install the released version from CRAN
install.packages("maidr")

# Or the development version from GitHub:
# install.packages("devtools")
devtools::install_github("xability/r-maidr")

Basic Workflow

MAIDR works with two main functions:

show() - Display an interactive plot in RStudio Viewer or browser
save_html() - Save a plot as a standalone HTML file

Quick Example: ggplot2 Bar Chart

library(maidr)
library(ggplot2)

# Create sample data
sales_data <- data.frame(
  Product = c("A", "B", "C", "D"),
  Sales = c(150, 230, 180, 290)
)

# Create a bar chart
p <- ggplot(sales_data, aes(x = Product, y = Sales)) +
  geom_bar(stat = "identity", fill = "steelblue") +
  labs(
    title = "Product Sales by Category",
    x = "Product",
    y = "Sales Amount"
  ) +
  theme_minimal()

# Display interactively
show(p)

# Or save as HTML file
save_html(p, "sales_chart.html")

Quick Example: Base R Plot

MAIDR also works with Base R plotting functions:

library(maidr)

# Create a simple barplot
categories <- c("A", "B", "C", "D")
values <- c(150, 230, 180, 290)

barplot(
  values,
  names.arg = categories,
  col = "steelblue",
  main = "Product Sales by Category",
  xlab = "Product",
  ylab = "Sales Amount"
)

# Note: For Base R plots, call show() with NO arguments
# after creating the plot
show()

Offline vs CDN Usage

By default, MAIDR auto-detects internet availability and loads the MAIDR.js library from a CDN when online. You can control this behavior with the use_cdn parameter:

library(maidr)
library(ggplot2)

p <- ggplot(mtcars, aes(x = factor(cyl), y = mpg)) +
  geom_bar(stat = "identity")

# Auto-detect (default) - uses CDN if internet available
show(p)

# Force CDN (requires internet when viewing)
show(p, use_cdn = TRUE)

# Force bundled/local files (works offline)
show(p, use_cdn = FALSE)

The same parameter works with save_html():

# Save with CDN links (smaller file, needs internet to view)
save_html(p, "plot_cdn.html", use_cdn = TRUE)

# Save with bundled files (larger file, works offline)
save_html(p, "plot_offline.html", use_cdn = FALSE)

When to use use_cdn = FALSE: - Creating portable HTML files for offline viewing - Sharing files with users who may not have internet access - Ensuring reproducibility with a specific MAIDR.js version

Exploring Accessible Plots

When you open a MAIDR plot, you can explore it using:

Data Sonification

Plots can be heard through:

Pitch mapping (higher values = higher pitch)
Volume changes
Different tones for different series

Supported Plot Types

MAIDR supports a comprehensive range of visualizations:

Basic Plot Types

Bar charts (simple, grouped/dodged, stacked)
Histograms
Scatter plots
Line plots (single and multi-line)
Box plots
Violin plots (ggplot2 only)
Candlestick (OHLC) charts — ggplot2 via {tidyquant} (with optional geom_ma() moving-average overlays and a patchwork volume sub-panel); Base R via quantmod::chartSeries() (OHLC-only — TA overlays such as addVo(), addSMA(), addEMA() are not supported and fall back to native graphics)
Heatmaps
Density/smooth curves

See the Examples article for the full candlestick + MA + volume pipeline and the Base R support matrix.

Advanced Plot Types

Faceted plots - facet_wrap() and facet_grid() in ggplot2
Multi-panel layouts - patchwork for ggplot2, par(mfrow/mfcol) for Base R
Multi-layered plots - Combine multiple geoms (e.g., histogram + density)

Next Steps

Shiny Integration - Use MAIDR in Shiny apps
Package documentation - Run ?maidr::show for function details
Run examples - Try maidr::run_example() to see all available plot types

Example Gallery

Histogram

library(maidr)
library(ggplot2)

# Normal distribution
hist_data <- data.frame(values = rnorm(1000, mean = 100, sd = 15))

p <- ggplot(hist_data, aes(x = values)) +
  geom_histogram(bins = 30, fill = "skyblue", color = "black") +
  labs(
    title = "Distribution of Test Scores",
    x = "Score",
    y = "Frequency"
  ) +
  theme_minimal()

show(p)

Scatter Plot

library(maidr)
library(ggplot2)

# Create sample data
scatter_data <- data.frame(
  height = rnorm(50, 170, 10),
  weight = rnorm(50, 70, 8),
  gender = sample(c("Male", "Female"), 50, replace = TRUE)
)

p <- ggplot(scatter_data, aes(x = height, y = weight, color = gender)) +
  geom_point(size = 3, alpha = 0.7) +
  labs(
    title = "Height vs Weight",
    x = "Height (cm)",
    y = "Weight (kg)"
  ) +
  theme_minimal()

show(p)

Line Plot

library(maidr)
library(ggplot2)

# Time series data
months <- month.abb[1:12]
temperature <- c(5, 7, 12, 18, 22, 26, 28, 27, 23, 17, 11, 6)

temp_data <- data.frame(
  Month = factor(months, levels = months),
  Temperature = temperature
)

p <- ggplot(temp_data, aes(x = Month, y = Temperature, group = 1)) +
  geom_line(color = "red", linewidth = 1.5) +
  geom_point(color = "darkred", size = 3) +
  labs(
    title = "Average Monthly Temperature",
    x = "Month",
    y = "Temperature (°C)"
  ) +
  theme_minimal()

show(p)

Tips for Creating Accessible Plots

Use clear titles - Describe what the plot shows
Label axes properly - Include units of measurement
Choose distinct colors - Ensure good contrast
Add legends - Explain what colors/shapes mean
Keep it simple - Avoid overcrowded visualizations

Getting Help

Run ?maidr::show for function documentation
Visit GitHub issues: maidr/issues
Read the full documentation: help(package = "maidr")

Learn More

Accessibility standards: WCAG 2.1 Guidelines
MAIDR website: More examples and tutorials
Research papers: Understanding multimodal data representation