Package {litReview}

litReview: Summarizing Graphs for Literature Reviews

Description

Summarizes and visualizes categorical data extracted during literature reviews and evidence syntheses, starting from a data frame with one row per study. Generates publication-ready bar, stacked bar, histogram, waffle, donut, treemap, alluvial, trend, co-occurrence, 'UpSet', tree, and study-by-criteria matrix figures, together with world maps and formatted summary tables. Plot functions return standard 'ggplot2' objects that can be further customized, and an interactive 'Shiny' application is included for building figures without writing code. Aims to help researchers report study characteristics consistently across many publications.

Author(s)

Maintainer: Sonsoles López-Pernas sonsoles.lopez@uef.fi [copyright holder]

Authors:

• Kamila Misiejuk

• Mohammed Saqr

See Also

Useful links:

• https://github.com/sonsoleslp/litReview

• https://sonsoles.me/litReview/

• Report bugs at https://github.com/sonsoleslp/litReview/issues

Default Color Palette

Description

A character vector of 8 hex colors for use in literature review plots.

Usage

PALETTE

Format

An object of class character of length 8.

Details

Anywhere a colors (or palette-style fill) argument accepts this vector, you may instead pass the name of an RColorBrewer palette (e.g. "Set2", "Dark2", "Blues"); it is expanded to the number of categories needed. For the heatmap and map fills, a sequential/diverging ColorBrewer name (e.g. "Blues", "RdYlBu") switches to ggplot2::scale_fill_distiller(). Using a ColorBrewer name requires the RColorBrewer package.

See Also

RColorBrewer::brewer.pal()

Examples

PALETTE
# A ColorBrewer palette name works wherever `colors` is accepted:
if (requireNamespace("RColorBrewer", quietly = TRUE)) {
  reviewWaffle(studies, Design, colors = "Set2")
}

Import Data from a Google Drive URL

Description

Downloads an Excel file from a URL and reads a specified sheet.

Usage

import_from_google_drive(url, sheet)

Arguments

Value

A data frame with the contents of the specified sheet.

Examples

## Not run: 
df <- import_from_google_drive(
  "https://drive.google.com/uc?export=download&id=FILE_ID",
  sheet = 1
)

## End(Not run)

Create an Alluvial (Sankey) Plot

Description

Shows co-occurrence and flow between categories across multiple columns. Each study traces a path through the strata. Requires the ggalluvial package.

Usage

reviewAlluvial(
  data,
  cols,
  sep = "\r\n",
  study_id = StudyID,
  colors = PALETTE,
  base_size = 12,
  na.rm = TRUE,
  na_label = "Not reported",
  labels = c("none", "prop", "count", "both"),
  flow_labels = FALSE,
  flow_alpha = 0.25,
  stratum_width = 0.5,
  axis_labels = NULL
)

Arguments

Value

A ggplot2::ggplot object.

Examples

df <- data.frame(
  StudyID  = paste0("S", 1:6),
  Design   = c("RCT", "Cohort", "RCT", "RCT", "Cohort", "RCT"),
  Quality  = c("High", "Low", "High", "Low", "Low", "High"),
  Outcome  = c("Positive", "Negative", "Positive", "Negative",
               "Positive", "Positive"),
  stringsAsFactors = FALSE
)
if (requireNamespace("ggalluvial", quietly = TRUE)) {
  reviewAlluvial(df, c("Design", "Quality", "Outcome"))
}

Create a Summary Bar Chart

Description

Summarizes a column from literature review data and produces a horizontal bar chart with frequency and percentage labels. Returns a standard ggplot2::ggplot object that can be customized with +.

Usage

reviewBar(
  data,
  col,
  fill = "#7BB0D1",
  width = 0.6,
  sep = "\r\n",
  studlabs = FALSE,
  study_id = StudyID,
  label_space = 1.6,
  base_size = 12,
  na.rm = TRUE,
  na_label = "Not reported",
  na_in_percent = TRUE,
  na_last = FALSE
)

Arguments

Value

A ggplot2::ggplot object.

Examples

df <- data.frame(
  StudyID = c("S1", "S2", "S3", "S4"),
  Design = c("RCT", "Cohort", "RCT", "Case-control"),
  stringsAsFactors = FALSE
)
reviewBar(df, Design)
reviewBar(df, Design, fill = "#59a14f") + ggplot2::labs(title = "Designs")

Create a Numeric Histogram

Description

Bins the values of a numeric column and plots the frequency of each bin. Optionally stacks bars by a second categorical column. Returns a ggplot2::ggplot object that can be customized with +.

Usage

reviewHistogram(
  data,
  col,
  fill_by = NULL,
  bins = 30,
  binwidth = NULL,
  fill = "#7BB0D1",
  colors = PALETTE,
  sep = "\r\n",
  base_size = 12,
  na.rm = TRUE,
  na_label = "Not reported"
)

Arguments

Value

A ggplot2::ggplot object.

Examples

df <- data.frame(
  StudyID     = paste0("S", 1:20),
  SampleSize  = c(30, 45, 60, 22, 88, 120, 35, 51, 74, 66,
                  40, 95, 110, 28, 72, 58, 41, 33, 80, 105),
  Design      = rep(c("RCT", "Cohort", "Case-control", "Other"), 5)
)
reviewHistogram(df, SampleSize, bins = 8)
reviewHistogram(df, SampleSize, fill_by = Design, bins = 8)

Create a World Map of Study Counts

Description

Counts the number of studies per country and shades a world map accordingly. Country values may be English names, common aliases (e.g. "United States", "United Kingdom"), or ISO 2- or 3-letter codes (e.g. "US"/"USA", "GB"/"GBR"), all resolved automatically. Any value that cannot be matched to a map region triggers a warning listing it, so it is easy to correct. Returns a ggplot2::ggplot object.

Usage

reviewMap(
  data,
  country_col = Country,
  sep = "\r\n",
  fill = "#7BB0D1",
  base_size = 12,
  na.rm = TRUE
)

Arguments

Details

Unlike the categorical plots, reviewMap() takes only na.rm: a choropleth has no missing-value category to label (na_label) and shows a colour scale rather than a percentage (na_in_percent), so those arguments do not apply. Countries with no data are shaded with a neutral na.value.

Value

A ggplot2::ggplot object.

Examples

df <- data.frame(
  StudyID = c("S1", "S2", "S3"),
  Country = c("Spain", "Spain", "Germany"),
  stringsAsFactors = FALSE
)
if (requireNamespace("maps", quietly = TRUE)) {
  reviewMap(df)
}

Create a Study-by-Criteria Coding Matrix

Description

Draws an evidence / coding matrix: one row per study, one column per criterion, and a tile wherever a study addresses a criterion. The tile fill encodes an optional per-study attribute (e.g. document type) and the letter inside each tile is the cell's own value (e.g. a coding level such as O/D/M). Column headers can carry the number of studies addressing each criterion. Returns a standard ggplot2::ggplot object.

Usage

reviewMatrix(
  data,
  cols,
  color_by = NULL,
  study_id = StudyID,
  levels = NULL,
  colors = PALETTE,
  show_counts = TRUE,
  base_size = 12,
  label_wrap = 20,
  empty_fill = "#FCFCE6",
  tile_color = "white",
  na.rm = TRUE,
  na_label = "Not reported"
)

Arguments

Details

The input is one row per study (wide format): a study-id column, an optional grouping column for the fill, and one column per criterion holding the cell code (or NA/empty where the study does not address that criterion).

Value

A ggplot2::ggplot object.

Examples

studies_wide <- data.frame(
  StudyID  = c("Tam 2024", "Schiff 2021", "Reddy 2023", "Yu 2023"),
  Type     = c("Journal", "Journal", "Journal", "Conference"),
  Accuracy = c("O", "D", "D", "M"),
  Equity   = c(NA, "D", "D", "O"),
  Ethics   = c("O", "D", "D", "O"),
  stringsAsFactors = FALSE
)
reviewMatrix(studies_wide, c("Accuracy", "Equity", "Ethics"),
             color_by = "Type",
             levels = c(O = "Operationalized", D = "Discussed", M = "Mention"))

Create a Co-occurrence Heatmap

Description

Counts how many studies share each combination of values in two columns and displays the result as a tile heatmap. Returns a ggplot2::ggplot object.

Usage

reviewOverlap(
  data,
  col1,
  col2,
  sep = "\r\n",
  fill = "#7BB0D1",
  base_size = 12,
  na.rm = TRUE,
  na_label = "Not reported",
  studlabs = FALSE,
  study_id = StudyID,
  label_wrap = 15
)

Arguments

Value

A ggplot2::ggplot object.

Examples

df <- data.frame(
  StudyID = c("S1", "S2", "S3", "S4"),
  Design  = c("RCT", "Cohort", "RCT", "Case-control"),
  Country = c("UK", "UK", "Spain", "Spain"),
  stringsAsFactors = FALSE
)
reviewOverlap(df, Design, Country)
reviewOverlap(df, Design, Country, studlabs = TRUE)

Create a Donut or Pie Chart

Description

Summarizes a column and displays frequencies as a donut (default) or pie chart with count and percentage labels. Returns a ggplot2::ggplot object.

Usage

reviewPie(
  data,
  col,
  sep = "\r\n",
  colors = PALETTE,
  donut = TRUE,
  study_id = StudyID,
  base_size = 12,
  na.rm = TRUE,
  na_label = "Not reported",
  na_in_percent = TRUE,
  na_last = FALSE
)

Arguments

Value

A ggplot2::ggplot object.

Examples

df <- data.frame(
  StudyID = c("S1", "S2", "S3", "S4"),
  Design = c("RCT", "Cohort", "RCT", "Case-control"),
  stringsAsFactors = FALSE
)
reviewPie(df, Design)
reviewPie(df, Design, donut = FALSE)

Create a Stacked / Grouped Bar Chart

Description

Cross-tabulates a primary category (col) against a grouping variable (group) and displays the result as horizontal stacked bars. Use position = "fill" for within-category proportions (each bar sums to 100%) or position = "stack" for raw counts. Both columns may contain multi-value cells, which are split before counting. Returns a standard ggplot2::ggplot object.

Usage

reviewStackedBar(
  data,
  col,
  group,
  position = c("fill", "stack"),
  fill = PALETTE,
  width = 0.7,
  sep = "\r\n",
  study_id = StudyID,
  base_size = 12,
  na.rm = TRUE,
  na_label = "Not reported",
  na_last = FALSE,
  labels = TRUE
)

Arguments

Value

A ggplot2::ggplot object.

Examples

df <- data.frame(
  StudyID = paste0("S", 1:6),
  Design  = c("RCT", "Cohort", "RCT", "Cohort", "RCT", "Cohort"),
  Risk    = c("Low", "High", "Low", "Moderate", "High", "Low"),
  stringsAsFactors = FALSE
)
reviewStackedBar(df, Design, Risk)
reviewStackedBar(df, Design, Risk, position = "stack")

Create a Summary Table

Description

Summarizes a column from literature review data and returns a formatted gt::gt() table showing each category, its associated study IDs, frequency, and percentage.

Usage

reviewTable(
  data,
  col,
  sep = "\r\n",
  study_id = StudyID,
  latex = FALSE,
  cite = FALSE,
  na.rm = TRUE,
  na_label = "Not reported",
  na_in_percent = TRUE,
  na_last = FALSE
)

Arguments

Value

A gt::gt() table, or a LaTeX character string if latex = TRUE. The LaTeX output prints cleanly in the console, and renders automatically in knitr/R Markdown chunks with results = "asis".

Examples

df <- data.frame(
  StudyID = c("S1", "S2", "S3", "S4"),
  Design = c("RCT", "Cohort", "RCT", "Case-control"),
  stringsAsFactors = FALSE
)
reviewTable(df, Design)
reviewTable(df, Design, latex = TRUE, cite = TRUE)

Create a Hierarchical Tree Diagram

Description

Draws a left-to-right node-link tree from a set of columns given in order. The first column forms the top-level branches, the next column their children, and so on; multi-value cells are split so a study can sit in several branches. Each level-1 branch gets its own colour, inherited by its descendants, and the leaves can attach a wrapped list of the studies that reach them. Returns a standard ggplot2::ggplot object.

Usage

reviewTree(
  data,
  cols,
  study_id = StudyID,
  sep = "\r\n",
  show_members = TRUE,
  member_wrap = 36,
  label_wrap = 18,
  counts = c("none", "count", "percent", "both"),
  root_label = "All studies",
  colors = PALETTE,
  root_fill = "#F4F4C8",
  base_size = 11,
  na.rm = TRUE,
  na_label = "Not reported",
  na_last = FALSE
)

Arguments

Value

A ggplot2::ggplot object.

Examples

data(studies)
reviewTree(studies, c("InterventionType", "Intervention"), study_id = Author)

Create a Treemap

Description

Displays category frequencies as nested rectangles whose area is proportional to the count. Optionally color by a second column for a hierarchical view. Requires the treemapify package.

Usage

reviewTreemap(
  data,
  col,
  color_by = NULL,
  sep = "\r\n",
  colors = PALETTE,
  base_size = 12,
  na.rm = TRUE,
  na_label = "Not reported",
  study_id = StudyID,
  studlabs = FALSE,
  border_col = "white"
)

Arguments

Value

A ggplot2::ggplot object.

Examples

df <- data.frame(
  StudyID = paste0("S", 1:8),
  Design  = c("RCT", "Cohort", "RCT", "RCT", "Cohort", "RCT", "Cohort", "RCT"),
  Quality = c("High", "Low", "High", "Low", "Low", "High", "Low", "High"),
  stringsAsFactors = FALSE
)
if (requireNamespace("treemapify", quietly = TRUE)) {
  reviewTreemap(df, Design)
  reviewTreemap(df, Design, color_by = Quality)
}

Create a Year-Trend Bar Chart

Description

Shows how the values in a column distribute across publication years as a stacked bar chart. Returns a ggplot2::ggplot object.

Usage

reviewTrend(
  data,
  col,
  year_col = Year,
  sep = "\r\n",
  colors = PALETTE,
  base_size = 12,
  na.rm = TRUE,
  na_label = "Not reported",
  na_last = FALSE,
  labels = c("none", "count", "percent", "both", "studies"),
  study_id = StudyID
)

Arguments

Value

A ggplot2::ggplot object.

Examples

df <- data.frame(
  StudyID = c("S1", "S2", "S3", "S4"),
  Year    = c(2020, 2021, 2021, 2022),
  Design  = c("RCT", "Cohort", "RCT", "Case-control"),
  stringsAsFactors = FALSE
)
reviewTrend(df, Design)
reviewTrend(df, Design, labels = "count")
reviewTrend(df, Design, labels = "percent")
reviewTrend(df, Design, labels = "studies")

Create an UpSet Plot of Value Combinations

Description

Visualizes how the values of a multi-value column co-occur across studies. Each study contributes the set of distinct values it reports; the plot shows the size of each observed combination (intersection) as a bar, with a dot matrix beneath indicating which values make up that combination. This scales past the pairwise reviewOverlap() when three or more values can co-occur. Returns a standard ggplot2::ggplot object.

Usage

reviewUpset(
  data,
  col,
  sep = "\r\n",
  study_id = StudyID,
  base_size = 12,
  na.rm = TRUE,
  na_label = "Not reported",
  n_intersections = 15,
  sort_by = c("freq", "degree"),
  fill = "#7BB0D1"
)

Arguments

Details

Requires the ggupset package.

Value

A ggplot2::ggplot object.

Examples

df <- data.frame(
  StudyID = paste0("S", 1:5),
  Outcome = c("Pain", "Pain\nFunction", "Function",
              "Pain\nFunction\nQoL", "QoL"),
  stringsAsFactors = FALSE
)
if (requireNamespace("ggupset", quietly = TRUE)) {
  reviewUpset(df, Outcome, sep = "\n")
}

Create a Waffle Chart

Description

Summarizes a column and displays frequencies as a grid of colored squares. Each square represents one occurrence. Returns a ggplot2::ggplot object.

Usage

reviewWaffle(
  data,
  col,
  sep = "\r\n",
  colors = PALETTE,
  ncol = 5,
  study_id = StudyID,
  base_size = 12,
  na.rm = TRUE,
  na_label = "Not reported",
  na_in_percent = TRUE,
  na_last = FALSE
)

Arguments

Value

A ggplot2::ggplot object.

Examples

df <- data.frame(
  StudyID = c("S1", "S2", "S3", "S4"),
  Design = c("RCT", "Cohort", "RCT", "Case-control"),
  stringsAsFactors = FALSE
)
reviewWaffle(df, Design)

Launch the litReview Shiny App

Description

Opens an interactive Shiny application for uploading literature review data and creating summary plots. The app provides a notebook-style interface where plots are added as cards that can be individually downloaded or exported together as a ZIP file.

Usage

run_app(...)

Arguments

Value

Called for its side-effect (launches the app). Returns the value of shiny::runApp() invisibly.

Examples

if (interactive()) {
  run_app()
}

Example Literature Review Dataset

Description

A synthetic dataset of 50 fictional studies for demonstrating the plotting functions in litReview. Contains 27 columns covering common fields extracted during a literature review, including a block of methodological reporting criteria suitable for reviewMatrix().

Usage

studies

Format

A data frame with 50 rows and 27 variables:

StudyID

Unique study identifier (S01–S50).

bibKey

BibTeX citation key.

Author

Author list (e.g. "Garcia et al.").

Year

Publication year (2018–2024).

Reference

Full reference string.

Country

Country or countries where the study was conducted. Multi-value cells are separated by newlines.

Design

Study design (e.g. RCT, Cohort, Cross-sectional).

SampleSize

Number of participants.

FollowUpWeeks

Follow-up duration in weeks, or NA.

AgeGroup

Target age group. May contain multiple values.

Setting

Study setting (e.g. Hospital, Community, Online).

Intervention

Intervention type (e.g. CBT, Exercise). May contain multiple values.

Outcome

Reported outcome (e.g. Pain, Function). May contain multiple values.

AnalysisApproach

Statistical or analytical approach used.

RiskOfBias

Risk of bias rating (Low, Moderate, High, or NA).

FundingSource

Funding source, or NA.

OpenAccess

Whether the study is open access (Yes, No, or NA).

InterventionType

Higher-order grouping of Intervention (Behavioral, Educational, Physical, Medical, Multimodal).

PubType

Publication type (Journal, Conference, Preprint, Report).

Randomization

Reporting of randomization. Coded "F" (full), "P" (partial), "M" (mentioned), or NA (not addressed). Trial-only item: NA for non-RCT designs.

Blinding

Reporting of blinding, coded as Randomization. Trial-only item: NA for non-RCT designs.

SampleJustification

Reporting of sample-size justification, coded "F"/"P"/"M"/NA.

AttritionReported

Reporting of attrition/dropout, coded as above.

EthicsApproval

Reporting of ethics approval, coded as above.

Preregistration

Reporting of preregistration, coded as above.

EffectSize

Reporting of effect sizes, coded as above.

LimitationsDiscussed

Reporting of study limitations, coded as above.

Details

The reporting-criteria columns (Randomization through LimitationsDiscussed) are coded for how fully each study reports the item — "F" full, "P" partial, "M" only mentioned, or NA not addressed — and are designed for the study-by-criteria reviewMatrix() plot.

Examples

data(studies)
reviewBar(studies, Design)

# Reporting-criteria matrix
criteria <- c("Randomization", "Blinding", "SampleJustification",
              "AttritionReported", "EthicsApproval", "Preregistration",
              "EffectSize", "LimitationsDiscussed")
reviewMatrix(studies, criteria, color_by = "PubType",
             levels = c(F = "Full", P = "Partial", M = "Mention"))

Summarize Frequency of Values in a Column

Description

Splits multi-value cells, counts frequencies, and computes percentages.

Usage

summarize_data(
  data,
  col,
  sep = "\r\n",
  study_id = StudyID,
  na.rm = TRUE,
  na_label = "Not reported",
  na_in_percent = TRUE,
  na_last = FALSE
)

Arguments

Value

A data frame with columns for the grouping variable, Studies (comma-separated study IDs), Frequency, and Percent (numeric, 0–100).

Examples

df <- data.frame(
  StudyID = c("S1", "S2", "S3", "S4"),
  Design = c("RCT", "Cohort", NA, "RCT"),
  stringsAsFactors = FALSE
)

# Drop NAs (default)
summarize_data(df, Design)

# Keep NAs with a custom label
summarize_data(df, Design, na.rm = FALSE, na_label = "Missing")

# Percentages of non-missing only
summarize_data(df, Design, na_in_percent = FALSE)

Literature Review ggplot Theme

Description

A clean, manuscript-ready ggplot2 theme with white background, bold axis titles, and bottom legend. All litReview plot functions use this theme by default. The single base_size parameter controls the proportional scaling of all text and spacing — increase for posters/slides, decrease for multi-panel figures.

Usage

theme_litreview(base_size = 12)

Arguments

Value

A ggplot2::theme object.

Examples

library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) +
  geom_point() +
  theme_litreview()

# Larger for presentations
ggplot(mtcars, aes(wt, mpg)) +
  geom_point() +
  theme_litreview(base_size = 18)