Package 'litReview'

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

url	Character. The download URL for the Excel file.
sheet	Character or integer. The sheet name or index to read.

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)

---

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")
}

---

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

data	A data frame.
cols	Character vector of column names to use as axes (left to right).
sep	Character. Separator for multi-value cells. Defaults to "\r\n". When a column contains multi-value cells, each combination generates a separate alluvium.
study_id	Column containing study identifiers (quoted or unquoted). Defaults to StudyID.
colors	Character vector. Fill colors for strata, cycled or matched by name. Defaults to PALETTE.
base_size	Numeric. Base font size in points. Defaults to 12.
na.rm	Logical. Drop rows with missing values? Defaults to TRUE.
na_label	Character. Label for missing values when na.rm = FALSE. Defaults to "Not reported".
labels	Character. What to show on each stratum. One of "none" (default), "prop" (proportion within axis), "count", or "both" (count and proportion).
flow_labels	Logical. If TRUE, show counts on the flows between strata. Defaults to FALSE.
flow_alpha	Numeric. Transparency of flows (0–1). Defaults to 0.25.
stratum_width	Numeric. Width of stratum bars. Defaults to 0.5.
axis_labels	Character vector of custom axis labels (same length as cols), or NULL to use the column names. Defaults to NULL.

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

data	A data frame with at least a study ID column and the column named by col.
col	Column to visualize (quoted or unquoted).
fill	Character. Bar fill color. Defaults to "#7BB0D1".
width	Numeric. Bar width (0–1). Defaults to 0.5.
sep	Character. Separator for multi-value cells. Defaults to "\r\n".
studlabs	Logical. If TRUE, draws study ID labels on bars using ggfittext::geom_bar_text(). Defaults to FALSE.
study_id	Column containing study identifiers (quoted or unquoted). Defaults to StudyID.
label_space	Numeric. Multiplier for x-axis headroom to fit labels. Defaults to 1.6.
base_size	Numeric. Base font size in points; controls proportional scaling of all text and elements. Defaults to 12.
na.rm	Logical. Drop missing values? Defaults to TRUE.
na_label	Character. Label for missing values when na.rm = FALSE. Defaults to "Not reported".
na_in_percent	Logical. Include missing rows in the percentage denominator? Defaults to TRUE.
na_last	Logical. If TRUE, place the missing-value category last regardless of its frequency. Defaults to FALSE.

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

data	A data frame containing at least the column named by col.
col	Numeric column to bin (quoted or unquoted).
fill_by	Optional categorical column to stack the bars by (quoted or unquoted). If NULL (default), bars are drawn in a single color.
bins	Integer. Number of bins. Passed to ggplot2::geom_histogram(). Ignored when binwidth is set. Defaults to 30.
binwidth	Numeric. Optional bin width. Overrides bins when set. Defaults to NULL.
fill	Character. Bar fill color when fill_by is NULL. Defaults to "#7BB0D1".
colors	Character vector. Fill colors cycled across categories when fill_by is set. Defaults to PALETTE.
sep	Character. Separator for multi-value cells in fill_by. Defaults to "\r\n".
base_size	Numeric. Base font size in points; controls proportional scaling of all text and elements. Defaults to 12.
na.rm	Logical. Drop rows with missing values in col (and, when set, in fill_by)? Defaults to TRUE.
na_label	Character. Label for missing values in fill_by when na.rm = FALSE. Defaults to "Not reported".

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

data	A data frame with at least the column named by country_col.
country_col	Country column (quoted or unquoted). Defaults to Country.
sep	Character. Separator for multi-value cells. Defaults to "\r\n".
fill	Character. High-end color for the gradient. Defaults to "#7BB0D1".
base_size	Numeric. Base font size in points. Defaults to 12.
na.rm	Logical. Drop missing values? Defaults to TRUE.

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

data	A data frame with one row per study.
cols	Character vector of criterion column names, in the order they should appear on the x-axis. Each cell holds the code shown in the tile, or NA/"" for no tile.
color_by	Optional column name (character) giving each study's category, mapped to the tile fill (e.g. "DocumentType"). NULL (default) fills all tiles with a single color.
study_id	Column with the study labels for the y-axis (quoted or unquoted). Defaults to StudyID.
levels	Optional named character vector mapping cell codes to descriptions for the "Level" legend, e.g. c(O = "Operationalized", D = "Discussed", M = "Mention"). The names fix the legend order. NULL (default) labels the legend with the codes themselves.
colors	Character vector of fill colors for the color_by categories. Defaults to PALETTE.
show_counts	Logical. Append " (N=k)" to each column header, where k is the number of studies addressing that criterion. Defaults to TRUE.
base_size	Numeric. Base font size in points. Defaults to 12.
label_wrap	Integer. Wrap axis labels longer than this many characters. NULL/Inf disables. Defaults to 20.
empty_fill	Character. Fill for the background grid behind empty cells. Defaults to "#FCFCE6".
tile_color	Character. Border color between tiles. Defaults to "white".
na.rm	Logical. If TRUE (default), cells with a missing/empty value are left blank (the study did not address that criterion). If FALSE, they are drawn as an explicit tile labelled with na_label.
na_label	Character. Code shown in unaddressed cells when na.rm = FALSE. Defaults to "Not reported".

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

data	A data frame with at least the columns named by col1 and col2.
col1	First column (quoted or unquoted), mapped to the x-axis.
col2	Second column (quoted or unquoted), mapped to the y-axis.
sep	Character. Separator for multi-value cells. Defaults to "\r\n".
fill	Character. High-end color for the gradient. Defaults to "#7BB0D1".
base_size	Numeric. Base font size in points. Defaults to 12.
na.rm	Logical. Drop missing values? Defaults to TRUE.
na_label	Character. Label for missing values when na.rm = FALSE. Defaults to "Not reported".
studlabs	Logical. If TRUE, show comma-separated study IDs inside each tile instead of (or below) the count. Defaults to FALSE.
study_id	Column containing study identifiers (quoted or unquoted). Used when studlabs = TRUE. Defaults to StudyID.
label_wrap	Integer. Wrap axis tick labels longer than this many characters onto multiple lines. Set to NULL or Inf to disable. Defaults to 15.

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

data	A data frame with at least a study ID column and the column named by col.
col	Column to visualize (quoted or unquoted).
sep	Character. Separator for multi-value cells. Defaults to "\r\n".
colors	Character vector. Fill colors cycled across categories. Defaults to PALETTE.
donut	Logical. If TRUE (default), renders a donut chart. If FALSE, renders a filled pie chart.
study_id	Column containing study identifiers (quoted or unquoted). Defaults to StudyID.
base_size	Numeric. Base font size in points. Defaults to 12.
na.rm	Logical. Drop missing values? Defaults to TRUE.
na_label	Character. Label for missing values when na.rm = FALSE. Defaults to "Not reported".
na_in_percent	Logical. Include missing rows in the percentage denominator? Defaults to TRUE.
na_last	Logical. If TRUE, place the missing-value category last regardless of its frequency. Defaults to FALSE.

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

data	A data frame with at least the columns named by col and group.
col	Primary category (quoted or unquoted); one horizontal bar per value.
group	Grouping/splitting column (quoted or unquoted); mapped to the bar fill.
position	Character. "fill" (default) scales each bar to 100% to compare proportions; "stack" shows raw counts.
fill	Character vector of fill colors for the groups. Defaults to PALETTE.
width	Numeric. Bar width (0–1). Defaults to 0.7.
sep	Character. Separator for multi-value cells. Defaults to "\r\n".
study_id	Column containing study identifiers (quoted or unquoted). Defaults to StudyID. Present for API consistency; not currently used.
base_size	Numeric. Base font size in points. Defaults to 12.
na.rm	Logical. Drop missing values? Defaults to TRUE.
na_label	Character. Label for missing values when na.rm = FALSE. Defaults to "Not reported".
na_last	Logical. If TRUE (and na.rm = FALSE), place the missing category last — at the bottom of the axis and the end of each bar/legend. Defaults to FALSE.
labels	Logical. Draw the count (or percentage) inside each segment? Defaults to TRUE.

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

data	A data frame with at least a study ID column and the column named by col.
col	Column to summarize (quoted or unquoted).
sep	Character. Separator for multi-value cells. Defaults to "\r\n".
study_id	Column containing study identifiers (quoted or unquoted). Defaults to StudyID.
latex	Logical. If TRUE, returns the table as LaTeX code via gt::as_latex() instead of a gt::gt() object. Defaults to FALSE.
cite	Logical. If TRUE, treats values in study_id as BibTeX reference keys and wraps the per-row study list in ⁠\\cite{...}⁠. Defaults to FALSE.
na.rm	Logical. Drop missing values? Defaults to TRUE.
na_label	Character. Label for missing values when na.rm = FALSE. Defaults to "Not reported".
na_in_percent	Logical. Include missing rows in the percentage denominator? Defaults to TRUE.
na_last	Logical. If TRUE, place the missing-value category last regardless of its frequency. Defaults to FALSE.

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

data	A data frame with one row per study.
cols	Character vector of columns defining the hierarchy, from root (first) to leaf (last). Each level branches by that column's values.
study_id	Column with the study labels collected at the leaves (quoted or unquoted). Defaults to StudyID.
sep	Character. Separator for multi-value cells. Defaults to "\r\n".
show_members	Logical. Attach a box listing the contributing studies at each leaf. Defaults to TRUE.
member_wrap	Integer. Wrap the member list at this many characters. Defaults to 36.
label_wrap	Integer. Wrap node labels at this many characters. Defaults to 18.
counts	Character. Annotate each node with the number and/or percentage of studies it covers: "none" (default), "count", "percent", or "both". Counts are distinct studies; percentages are relative to all studies, so sibling branches may sum past 100% when cells are multi-valued.
root_label	Character. Text for the root node. Defaults to "All studies".
colors	Character vector of branch colours (one per level-1 value). Defaults to PALETTE.
root_fill	Character. Fill for the root node. Defaults to "#F4F4C8".
base_size	Numeric. Base font size in points. Defaults to 11.
na.rm	Logical. Drop missing values? Defaults to TRUE.
na_label	Character. Label for missing values when na.rm = FALSE. Defaults to "Not reported".
na_last	Logical. If TRUE (and na.rm = FALSE), order the missing branch last (at the bottom) at every level. Defaults to FALSE.

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

data	A data frame.
col	Column whose values define the rectangles (quoted or unquoted).
color_by	Optional second column (quoted or unquoted) used to fill the rectangles. When supplied the treemap is grouped hierarchically by color_by, with col nested inside. When NULL (default), rectangles are colored by col itself.
sep	Character. Separator for multi-value cells. Defaults to "\r\n".
colors	Character vector. Fill colors, cycled or matched by name. Defaults to PALETTE.
base_size	Numeric. Base font size in points. Defaults to 12.
na.rm	Logical. Drop missing values? Defaults to TRUE.
na_label	Character. Label for missing values when na.rm = FALSE. Defaults to "Not reported".
study_id	Column containing study identifiers (quoted or unquoted). Defaults to StudyID.
studlabs	Logical. If TRUE, show study IDs inside each rectangle. Defaults to FALSE.
border_col	Character. Color of rectangle borders. Defaults to "white".

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

data	A data frame with at least StudyID (or the column set by study_id), the column named by col, and a year column.
col	Column to visualize (quoted or unquoted).
year_col	Year column (quoted or unquoted). Defaults to Year.
sep	Character. Separator for multi-value cells. Defaults to "\r\n".
colors	Character vector. Fill colors cycled across categories. Defaults to PALETTE.
base_size	Numeric. Base font size in points. Defaults to 12.
na.rm	Logical. Drop missing values? Defaults to TRUE.
na_label	Character. Label for missing values when na.rm = FALSE. Defaults to "Not reported".
na_last	Logical. If TRUE (and na.rm = FALSE), place the missing category last in the stack and legend. Defaults to FALSE.
labels	Character. What to display on each bar segment. One of "none" (default), "count", "percent" (within-year), "both" (count and percent), or "studies" (comma-separated study IDs).
study_id	Column containing study identifiers (quoted or unquoted). Used when labels = "studies". Defaults to StudyID.

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

data	A data frame with at least the columns named by col and study_id.
col	Multi-value column to analyze (quoted or unquoted).
sep	Character. Separator for multi-value cells. Defaults to "\r\n".
study_id	Column containing study identifiers (quoted or unquoted). One combination is formed per study. Defaults to StudyID.
base_size	Numeric. Base font size in points. Defaults to 12.
na.rm	Logical. Drop missing values? Defaults to TRUE.
na_label	Character. Label for missing values when na.rm = FALSE. Defaults to "Not reported".
n_intersections	Integer. Maximum number of combinations (bars) to display, keeping the largest. Defaults to 15.
sort_by	Character. Order bars by "freq" (intersection size, default) or "degree" (number of values in the combination).
fill	Character. Bar and matrix-dot color. Defaults to "#7BB0D1".

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

data	A data frame with at least a study ID column and the column named by col.
col	Column to visualize (quoted or unquoted).
sep	Character. Separator for multi-value cells. Defaults to "\r\n".
colors	Character vector. Fill colors cycled across categories. Defaults to PALETTE.
ncol	Integer. Number of columns in the grid. Defaults to 5.
study_id	Column containing study identifiers (quoted or unquoted). Defaults to StudyID.
base_size	Numeric. Base font size in points. Defaults to 12.
na.rm	Logical. Drop missing values? Defaults to TRUE.
na_label	Character. Label for missing values when na.rm = FALSE. Defaults to "Not reported".
na_in_percent	Logical. Include missing rows in the percentage denominator? Defaults to TRUE.
na_last	Logical. If TRUE, place the missing-value category last regardless of its frequency. Defaults to FALSE.

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

...	Arguments passed to shiny::runApp(), such as port or launch.browser.

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

data	A data frame containing at least the columns specified by col and study_id.
col	Column to summarize (quoted or unquoted).
sep	Character. The separator used to split multi-value cells. Defaults to "\r\n".
study_id	Column containing study identifiers (quoted or unquoted). Defaults to StudyID.
na.rm	Logical. If TRUE (default), rows with missing values (NA or empty strings) in col are dropped. If FALSE, they are kept and labelled with na_label.
na_label	Character. Label used for missing values when na.rm = FALSE. Defaults to "Not reported".
na_in_percent	Logical. If TRUE (default), the denominator for percentages is the total number of rows (including missing). If FALSE, only non-missing rows are counted, so non-missing categories sum to $\approx 100\%$.
na_last	Logical. If TRUE, the missing-value row (when na.rm = FALSE) is placed at the bottom of the result regardless of its frequency. Defaults to FALSE (sorted by frequency like all other rows).

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

base_size

Numeric. Base font size in points. Defaults to 12.

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)

---