Package 'ggaltdata'

Title: Data-Driven Alternative Text and Data Tables for 'ggplot2' Charts
Description: Generates alternative text that states what a 'ggplot2' chart shows (highest and lowest values, rankings, trends, gaps between groups, overlap of intervals), a long description and the data table, computed from the data of the chart itself. Output for 'R Markdown', 'Quarto', 'Word', saved images and 'Shiny', in English and Italian.
Authors: Federico Ninivaggi [aut, cre]
Maintainer: Federico Ninivaggi <[email protected]>
License: MIT + file LICENSE
Version: 0.1.0
Built: 2026-10-14 18:59:25 UTC
Source: https://github.com/cran/ggaltdata

Help Index

Store a generated alternative text in the plot

Description

Fills labs(alt = ), so that ggplot2::get_alt_text(), Shiny's renderPlot() and tools that read it use the generated text. A text already written by hand is kept unless overwrite = TRUE.

Usage

add_alt(p, lang = "en", max_chars = 250, overwrite = FALSE, area_var = NULL)

Arguments

p

A ggplot object.
lang

Language of the text: "en" (default) or "it".
max_chars

Maximum length of the text in characters (default 250).
overwrite

Replace an existing alternative text.
area_var

For maps (geom_sf), the column with the names of the areas.

Value

The plot, with the alternative text set.

Examples

library(ggplot2)
df <- data.frame(item = c("Apples", "Pears"), score = c(3.6, 2.7))
p <- add_alt(ggplot(df, aes(item, score)) + geom_col())
ggplot2::get_alt_text(p)

The data table of a chart

Description

The data table of a chart

Usage

alt_data(p, area_var = NULL)

Arguments

p

A ggplot object.
area_var

For maps (geom_sf), the column with the names of the areas.

Value

A data frame with the plotted values under readable column names.

Examples

library(ggplot2)
df <- data.frame(item = c("Apples", "Pears"), score = c(3.6, 2.7))
alt_data(ggplot(df, aes(item, score)) + geom_col())

Long description and data table, for reading in the R console

Description

Builds a plain-text description of the chart (title, structure, every finding, ranking) and its data table. Printed in the console, it reads line by line in a screen reader.

Usage

alt_describe(p, lang = "en", n_extremes = 3, area_var = NULL)

Arguments

p

A ggplot object.
lang

Language of the text: "en" (default) or "it".
n_extremes

How many categories to name at the top and bottom when there are many.
area_var

For maps (geom_sf), the column with the names of the areas.

Value

An object of class ggaltdata with elements short_sentences, long, table and facts; its print method writes the long description and the data table.

Examples

library(ggplot2)
df <- data.frame(item = c("Apples", "Pears", "Plums"), score = c(3.6, 2.7, 3.2))
alt_describe(ggplot(df, aes(item, score)) + geom_col())

Generate the short alternative text of a ggplot2 chart

Description

Reads the data drawn by the chart and writes one or two sentences with its main finding: highest and lowest values, gaps between two groups, trends of series, intervals that overlap or not. Every number comes from the data of the chart.

Usage

alt_text(p, lang = "en", max_chars = 250, n_extremes = 3, area_var = NULL)

Arguments

p

A ggplot object.
lang

Language of the text: "en" (default) or "it".
max_chars

Maximum length of the text in characters (default 250).
n_extremes

How many categories to name at the top and bottom when there are many.
area_var

For maps (geom_sf), the column with the names of the areas.

Value

A character string.

Examples

library(ggplot2)
df <- data.frame(item = c("Apples", "Pears", "Plums"), score = c(3.6, 2.7, 3.2))
p <- ggplot(df, aes(item, score)) + geom_col() + labs(y = "average score")
alt_text(p)
alt_text(p, lang = "it")

Add the data table to a Word document

Description

Requires the officer package.

Usage

as_docx_table(x, doc, caption = NULL, lang = "en")

Arguments

x

A ggplot object or the result of alt_describe().
doc

An rdocx object from officer::read_docx().
caption

Optional caption written before the table.
lang

Language of the generated texts, if x is a plot.

Value

The rdocx object with the table added.

Examples

if (requireNamespace("officer", quietly = TRUE)) {
  library(ggplot2)
  df <- data.frame(item = c("Apples", "Pears"), score = c(3.6, 2.7))
  p <- ggplot(df, aes(item, score)) + geom_col()
  doc <- as_docx_table(p, officer::read_docx(), caption = "Data of Figure 1")
  print(doc, target = file.path(tempdir(), "report.docx"))
}

The data table as a Markdown table

Description

The data table as a Markdown table

Usage

as_markdown(x, caption = NULL, digits = NULL, lang = "en")

Arguments

x

A ggplot object or the result of alt_describe().
caption

Optional caption written above the table.
digits

Digits for numbers; by default chosen from the data.
lang

Language used for numbers (decimal mark).

Value

A character string with a pipe table.

Examples

library(ggplot2)
df <- data.frame(item = c("Apples", "Pears"), score = c(3.6, 2.7))
cat(as_markdown(ggplot(df, aes(item, score)) + geom_col()))

Save the alternative text and the data table next to an image

Description

Writes two files beside the image saved with ggplot2::ggsave(): for file = "figure1.png", figure1.alt.txt (short and long text) and figure1.data.csv (the data table).

Usage

save_alt(p, file, lang = "en", max_chars = 250, area_var = NULL)

Arguments

p

A ggplot object.
file

Path of the image (for example "figure1.png").
lang

Language of the text: "en" (default) or "it".
max_chars

Maximum length of the text in characters (default 250).
area_var

For maps (geom_sf), the column with the names of the areas.

Value

Invisibly, the paths of the two files written.

Examples

library(ggplot2)
df <- data.frame(item = c("Apples", "Pears"), score = c(3.6, 2.7))
p <- ggplot(df, aes(item, score)) + geom_col()
f <- file.path(tempdir(), "figure1.png")
ggsave(f, p, width = 4, height = 3)
save_alt(p, f)