Introduction & setup

Introduction

This Narrated Illustration of a Transparent Review Outline (NITRO) accompanies the SysRevving book and the metabefor package. Throughout this file, links to the corresponding SysRevving chapters will be provided. For general reference, you may want to keep the SysRevving glossary ready. For convenience, here is the GitLab repo for this project, and here is the URL to the rendered version of this R Markdown file.

In this fictional example, we want to conduct a systematic review about the determinants of substance use, specifically a scoping review. Note that this review is deliberately very rudimentary, to try to avoid the complexity of the review itself from interfering with understanding the structure.

Setup

Here we check for the required packages (without loading them into R’s search path with library() or require(), to safeguard against accidently forgetting to use the package::function() syntax), specify the paths, and set script-wide settings.

###-----------------------------------------------------------------------------
### Packages
###-----------------------------------------------------------------------------

if ((!(requireNamespace("metabefor", quietly = TRUE))) ||
      (packageVersion("metabefor") < "0.3")) {
  stop("You need to have at least version 0.3 of the `metabefor` package installed; ",
       "install it with:\n\ninstall.packages('metabefor');");
}

metabefor::checkPkgs(
  "here",               ### For easily access to files using 'relative paths'
  "preregr",            ### For specifying (pre)registrations
  "synthesisr",         ### For plotting
  "ggplot2"             ### For plotting
);

### Potentially update to the development version of some packages
# ufs::quietGitLabUpdate("r-packages/preregr@dev", quiet = FALSE);
# ufs::quietGitLabUpdate("r-packages/rock@dev", quiet = FALSE);
# ufs::quietGitLabUpdate("r-packages/metabefor", quiet = FALSE);
# ufs::quietRemotesInstall("rmetaverse/synthesisr",
#                          func = "install_github", quiet = FALSE);

###-----------------------------------------------------------------------------
### Paths
###-----------------------------------------------------------------------------

basePath <- here::here();
preregPath <- file.path(basePath, "prereg");
scriptPath <- file.path(basePath, "scripts");
searchPath <- file.path(basePath, "search");
screeningPath <- file.path(basePath, "screening");
extractionPath <- file.path(basePath, "extraction");
rxsSpecPath <- file.path(basePath, "extraction-Rxs-spec");
outputPath <- file.path(basePath, "output");

###-----------------------------------------------------------------------------
### Settings
###-----------------------------------------------------------------------------

knitr::opts_chunk$set(
  echo = TRUE,
  comment = ""
);

###-----------------------------------------------------------------------------
### Extraction script Google sheets URL
###-----------------------------------------------------------------------------

rxsSpec_googleSheetsURL <-
  paste0("https://docs.google.com/spreadsheets/d/",
         "1Ty38BS7MVXOgC-GJ6zzr7E3rC_vQNOMKe-uCvIuHs3c");

Planning

Research Question

(link to corresponding SysRevving chapter)

Example: The research question is whether the exponential explosion of the scientific literature is also reflected in a growing evidence base for health promotion interventions targeting recreational substance use.

Planning: Synthesis

(link to corresponding SysRevving chapter)

Example: To answer the research question, our synthesis will consist of a plot with years on the X axis, cumulative number of publications on the Y axis, and with spearately, differently colored lines for each substance.

Planning: Extraction

(link to corresponding SysRevving chapter)

Example: The R extraction script specification (Rxs spec) is stored in this Rxs spec google sheet. The below chunks load it, convert it into the Rxs template (that will then be copied and completed for each source from which data are extracted), and show these specifications.

R extraction script specification

Basic Rxs tree structure

metabefor::show_rxsTree_in_rxsStructure(
  rxsSpecObject,
  output = outputPath
);

module1

                levelName
1 source                 
2  °--general            
3      ¦--publicationYear
4      ¦--sourceAuthors  
5      °--sourceTitle    
%0 1->2 2->3 2->4 2->5 1 source 2 General 3 Year 4 Authors 5 Title

module2

                     levelName
1 source                      
2  °--methods                 
3      ¦--sample              
4      ¦   ¦--sampleSize      
5      ¦   °--samplingStrategy
6      °--method              
%0 1->2 2->3 2->6 3->4 3->5 1 source 2 Methods 3 Sample 4 Sample size 5 Sampling Strategy 6 Method

module3

                               levelName
1  source                               
2   ¦--methods                          
3   ¦   °--variables                    
4   ¦       °--variable                 
5   ¦           ¦--variableIdentifier   
6   ¦           °--measurementLevel     
7   °--results                          
8       °--associations                 
9           °--association              
10              ¦--associationIdentifier
11              ¦--varId1               
12              ¦--varId2               
13              ¦--r                    
14              °--t                    
%0 1->2 1->7 2->3 3->4 4->5 4->6 7->8 8->9 9->10 9->11 9->12 9->13 9->14 1 source 2 Methods 3 Variables 4 Variable 5 Variable Identifier 6 Measurement Level 7 Results 8 Associations 9 Association 10 Association Identifier 11 Variable Identifier for variable 1 12 Variable Identifier for variable 2 13 Pearson`s r 14 Student`s t

Extraction instructions

cat(rxsSpecObject$rxsInstructions);

Extraction instructions

Introduction

These instructions are for extractors using the minimal rxs example.

More instructions

Normally, these instructions should be comprehensive enough to allow people to extract data reasonably accurately. The instructions with the heading “Opening Remarks” and “Closing Remarks” are added in every rxs file.

Opening Remarks

Welcome to the R Extraction Script (.rxs.Rmd file) for this source!

You can now start extracting. If you haven’t yet studied the extractor instructions, please do so first. If you’re all set, good luck!

Closing Remarks

Well done! You are now done extracting this source. Great job!!!

Now, please knit the R Extraction Script into an HTML file and carefully check whether you entered everything correctly, since it will cost much less time to correct any errors, now that you still have this source in your mind, than later on when you’ll have to dive into it all over.

Entity overview

cat(rxsSpecObject$entityOverview_list);

Extraction script template

This is the extraction script generated based on the extraction script specification.

cat("\n\n<pre><textarea rows='40' cols='124' style='font-family:monospace;font-size:11px;white-space:pre;'>",
    unlist(rxsSpecObject$rxsTemplate),
    "</textarea></pre>\n\n",
    sep="\n");

Planning: Screening

(link to corresponding SysRevving chapter)

Example: …

Preregistration

(link to corresponding SysRevving chapter)

Example: …

Execution

Execution: Screening

(link to corresponding SysRevving chapter)

Example: …

Execution: Extraction

(link to corresponding SysRevving chapter)

Example: …

Execution: Synthesis

(link to corresponding SysRevving chapter)

Example: …