Getting Started with litReview

The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

Overview

litReview helps you summarize and visualize categorical data extracted during a literature review. Every plot function returns a standard ggplot that you can customize with +. Column names can be passed bare or quoted.

library(litReview)
data(studies)
head(studies)
#>   StudyID       bibKey         Author Year
#> 1     S01 author1_2018  Garcia et al. 2020
#> 2     S02 author2_2022    Chen et al. 2024
#> 3     S03 author3_2018 Mueller et al. 2018
#> 4     S04 author4_2018   Patel et al. 2022
#> 5     S05 author5_2019 Johnson et al. 2019
#> 6     S06 author6_2021     Kim et al. 2019
#>                                                        Reference
#> 1  Garcia et al. (2020). Title of study S01. Journal Name, 1-10.
#> 2    Chen et al. (2024). Title of study S02. Journal Name, 1-10.
#> 3 Mueller et al. (2018). Title of study S03. Journal Name, 1-10.
#> 4   Patel et al. (2022). Title of study S04. Journal Name, 1-10.
#> 5 Johnson et al. (2019). Title of study S05. Journal Name, 1-10.
#> 6     Kim et al. (2019). Title of study S06. Journal Name, 1-10.
#>                             Country          Design SampleSize FollowUpWeeks
#> 1                             Egypt     Qualitative         50             8
#> 2                             Italy          Cohort        300             8
#> 3                    Nigeria\nGhana     Qualitative        300             4
#> 4 Saudi Arabia\nTurkey\nSwitzerland Cross-sectional        150             8
#> 5                            Mexico   Mixed methods         75            12
#> 6         Belgium\nSingapore\nIndia             RCT       1200            NA
#>               AgeGroup      Setting     Intervention
#> 1               Adults Primary care              CBT
#> 2             Children    Community        Education
#> 3         Older adults       Online         Combined
#> 4               Adults        Mixed         Combined
#> 5               Adults        Mixed         Exercise
#> 6 Adults\nOlder adults     Hospital CBT\nMindfulness
#>                           Outcome    AnalysisApproach RiskOfBias FundingSource
#> 1                        Function   Thematic analysis        Low          <NA>
#> 2                 Quality of life               ANOVA   Moderate          None
#> 3                 Quality of life               ANOVA        Low    University
#> 4 Pain\nFunction\nQuality of life Narrative synthesis        Low    Foundation
#> 5                            Pain               ANOVA       High          None
#> 6       Function\nQuality of life       Mixed methods        Low      Industry
#>   OpenAccess InterventionType    PubType Randomization Blinding
#> 1         No       Behavioral Conference          <NA>     <NA>
#> 2        Yes      Educational    Journal          <NA>     <NA>
#> 3         No       Multimodal Conference          <NA>     <NA>
#> 4         No       Multimodal Conference          <NA>     <NA>
#> 5         No         Physical    Journal          <NA>     <NA>
#> 6         No       Behavioral Conference             P        F
#>   SampleJustification AttritionReported EthicsApproval Preregistration
#> 1                   F                 F              P            <NA>
#> 2                <NA>              <NA>              F            <NA>
#> 3                   P                 F              F            <NA>
#> 4                   P              <NA>           <NA>               P
#> 5                   M                 P           <NA>            <NA>
#> 6                   F                 M              F               P
#>   EffectSize LimitationsDiscussed
#> 1       <NA>                    P
#> 2          M                    P
#> 3          M                    F
#> 4          F                    P
#> 5          F                    P
#> 6          F                    P

Bar chart

reviewBar() produces a horizontal bar chart with frequency and percentage labels.

reviewBar(studies, Design)

Customize with + like any ggplot:

library(ggplot2)
reviewBar(studies, Design, fill = "#59a14f") +
  labs(title = "Study Designs", subtitle = "n = 12 studies")

Study labels on bars

Set studlabs = TRUE to overlay the contributing study IDs on each bar:

reviewBar(studies, Design, fill = PALETTE[2], studlabs = TRUE)

Multi-value columns

The Outcome column contains multiple values per cell separated by "\r\n":

reviewBar(studies, Outcome, fill = PALETTE[4], width = 0.6)

Adjusting label space

If labels are clipped, increase label_space (default 1.6):

reviewBar(studies, Country, fill = PALETTE[6], label_space = 2)

Stacked / grouped bar chart

reviewStackedBar() cross-tabulates a primary category against a second grouping variable, drawing one horizontal bar per category split by group. By default (position = "fill") each bar is scaled to 100%, so you can compare composition across categories:

reviewStackedBar(studies, Design, RiskOfBias)

Use position = "stack" to show raw counts instead:

reviewStackedBar(studies, Design, RiskOfBias, position = "stack")

Both col and group may contain multi-value cells, which are split before counting. Hide the in-segment labels with labels = FALSE.

Waffle chart

Each square represents one study occurrence:

reviewWaffle(studies, Outcome, ncol = 11)

Donut / pie chart

reviewPie(studies, Design)

Set donut = FALSE for a classic pie:

reviewPie(studies, Design, donut = FALSE)

Co-occurrence heatmap

reviewOverlap() shows how two columns co-occur across studies:

reviewOverlap(studies, Design, Outcome, fill = PALETTE[3])

UpSet plot

reviewUpset() visualizes how the values of a multi-value column co-occur across studies. Each study contributes the set of distinct values it reports, and each bar counts the studies sharing that exact combination — a scalable alternative to the pairwise heatmap when three or more values can co-occur. Requires the ggupset package.

reviewUpset(studies, Outcome)

Sort combinations by set size ("degree") instead of frequency, and cap how many are shown with n_intersections:

reviewUpset(studies, Intervention, sort_by = "degree", n_intersections = 10)

Alluvial plot

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

reviewAlluvial(studies, c("Design", "Outcome"))

Add proportion or count labels on each stratum:

reviewAlluvial(studies, c("Design", "Outcome"), labels = "prop")

Show flow counts between strata:

reviewAlluvial(studies, c("Design", "Outcome"), labels = "none",
               flow_labels = TRUE)

Custom axis labels:

reviewAlluvial(studies, c("Design", "Outcome","AgeGroup"),
               axis_labels = c("Study Design", "Reported Outcome", "Age group"))

Treemap

reviewTreemap() displays category frequencies as nested rectangles whose area is proportional to the count. Requires the treemapify package.

reviewTreemap(studies, Design)

Use color_by to add a hierarchical grouping. Here we show interventions colored by their higher-order type:

reviewTreemap(studies, Intervention, color_by = InterventionType)

Show study IDs inside each rectangle:

reviewTreemap(studies, Design, studlabs = TRUE)

Year trend

reviewTrend() shows how categories distribute across publication years:

reviewTrend(studies, Design)

Add counts, within-year percentages, or both on each segment:

reviewTrend(studies, Design, labels = "count")

reviewTrend(studies, Design, labels = "percent")

reviewTrend(studies, Design, labels = "both")

Or overlay study IDs:

reviewTrend(studies, Design, labels = "studies")

World map

reviewMap() shades countries by the number of studies. Common aliases like “United States” or “United Kingdom” are resolved automatically. Requires the maps package (install.packages("maps")):

reviewMap(studies)

Summary table

reviewTable() returns a formatted gt table:

reviewTable(studies, Design)

Design	Studies	Frequency	Percent
RCT	S06, S17, S20, S21, S22, S24, S28, S32, S37, S39, S45	11	22%
Qualitative	S01, S03, S08, S18, S33, S35, S38, S43, S49	9	18%
Mixed methods	S05, S50	2	4%
Cross-sectional	S04, S07, S09, S10, S11, S14, S19, S30, S34, S42, S44, S48	12	24%
Cohort	S02, S12, S15, S16, S25, S26, S29, S31, S40, S41, S46, S47	12	24%
Case-control	S13, S23, S27, S36	4	8%

Handling missing data

Literature review datasets often have missing values. All functions accept na.rm, na_label, and na_in_percent to control how NAs are handled.

Let’s create example data with some missing values:

df_na <- data.frame(
  StudyID = paste0("S", 1:10),
  Design  = c("RCT", "Cohort", NA, "RCT", "Case-control",
              NA, "RCT", "Cohort", NA, "RCT"),
  stringsAsFactors = FALSE
)

Drop NAs, percentages of total (default)

NAs are dropped, but the denominator is all 10 studies. Percentages reflect the share of the full sample, so they do not sum to 100%:

summarize_data(df_na, Design)
#> # A tibble: 3 × 4
#>   Design       Studies         Frequency Percent
#>   <chr>        <chr>               <int>   <dbl>
#> 1 Case-control S5                      1      10
#> 2 Cohort       S2, S8                  2      20
#> 3 RCT          S1, S4, S7, S10         4      40

Drop NAs, percentages of reported only

Set na_in_percent = FALSE so that the denominator only counts the 7 studies that reported a design. Percentages sum to 100%:

summarize_data(df_na, Design, na_in_percent = FALSE)
#> # A tibble: 3 × 4
#>   Design       Studies         Frequency Percent
#>   <chr>        <chr>               <int>   <dbl>
#> 1 Case-control S5                      1    14.3
#> 2 Cohort       S2, S8                  2    28.6
#> 3 RCT          S1, S4, S7, S10         4    57.1

Keep NAs, percentages of total

Set na.rm = FALSE to include a “Not reported” category. All percentages sum to 100%:

summarize_data(df_na, Design, na.rm = FALSE)
#> # A tibble: 4 × 4
#>   Design       Studies         Frequency Percent
#>   <chr>        <chr>               <int>   <dbl>
#> 1 Case-control S5                      1      10
#> 2 Cohort       S2, S8                  2      20
#> 3 Not reported S3, S6, S9              3      30
#> 4 RCT          S1, S4, S7, S10         4      40

Keep NAs with a custom label, percentages of reported

Combine all three parameters. Here “Missing” replaces NA, and the denominator excludes missing rows:

summarize_data(df_na, Design, na.rm = FALSE, na_label = "Missing",
               na_in_percent = FALSE)
#> # A tibble: 4 × 4
#>   Design       Studies         Frequency Percent
#>   <chr>        <chr>               <int>   <dbl>
#> 1 Case-control S5                      1    14.3
#> 2 Cohort       S2, S8                  2    28.6
#> 3 Missing      S3, S6, S9              3    42.9
#> 4 RCT          S1, S4, S7, S10         4    57.1

Using NA options in plots

The same parameters work in every plot function:

reviewBar(df_na, Design, na.rm = FALSE, na_label = "Missing", na_in_percent = FALSE)

reviewPie(df_na, Design, na.rm = FALSE)

Custom study ID column

All functions default to study_id = StudyID. If your data uses a different column, pass it:

df <- data.frame(
  ID = paste0("A", 1:5),
  Type = c("X", "Y", "X", "Z", "X"),
  stringsAsFactors = FALSE
)
reviewBar(df, Type, study_id = ID)

Using `summarize_data()` directly

If you need the raw summary data frame (e.g. for further processing), use summarize_data(). Note that Percent is numeric:

summarize_data(studies, Design)
#> # A tibble: 6 × 4
#>   Design          Studies                                      Frequency Percent
#>   <chr>           <chr>                                            <int>   <dbl>
#> 1 Mixed methods   S05, S50                                             2       4
#> 2 Case-control    S13, S23, S27, S36                                   4       8
#> 3 Qualitative     S01, S03, S08, S18, S33, S35, S38, S43, S49          9      18
#> 4 RCT             S06, S17, S20, S21, S22, S24, S28, S32, S37…        11      22
#> 5 Cross-sectional S04, S07, S09, S10, S11, S14, S19, S30, S34…        12      24
#> 6 Cohort          S02, S12, S15, S16, S25, S26, S29, S31, S40…        12      24

Palette

PALETTE provides 8 colors you can cycle through:

PALETTE
#> [1] "#ff9da7" "#76b7b2" "#f16769" "#b07aa1" "#edc948" "#59a14f" "#7ea9c7"
#> [8] "#F28E2B"

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.

Getting Started with litReview

Overview

Bar chart

Study labels on bars

Multi-value columns

Adjusting label space

Stacked / grouped bar chart

Waffle chart

Donut / pie chart

Co-occurrence heatmap

UpSet plot

Alluvial plot

Treemap

Year trend

World map

Summary table

Handling missing data

Drop NAs, percentages of total (default)

Drop NAs, percentages of reported only

Keep NAs, percentages of total

Keep NAs with a custom label, percentages of reported

Using NA options in plots

Custom study ID column

Using summarize_data() directly

Palette

Using `summarize_data()` directly