# Getting Started with MAIDR

#### JooYoung Seo

#### 2026-07-09

## 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:

1. `show()` - Display an interactive plot in RStudio Viewer or browser
2. `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:

### Keyboard Navigation

- Arrow keys - Navigate between data points
- Tab - Move between interactive elements
- Enter/Space - Activate controls
- Escape - Exit modes

### Screen Reader Announcements

MAIDR plots include:

- Plot titles and descriptions
- Axis labels and ranges
- Data point values
- Navigation instructions

### 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

1. Use clear titles - Describe what the plot shows
2. Label axes properly - Include units of measurement
3. Choose distinct colors - Ensure good contrast
4. Add legends - Explain what colors/shapes mean
5. 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