Before continuing to the general package tutorial, make sure to have received your Scopus and Web of Science API keys. If not, the package will only access PubMed. If you don’t know how to get API keys, have a look at the article Get API keys.
We strongly recommend creating a new R directory for each individual review project. To do so in RStudio:
Go to
File>New Project…>New Directory>New Project
Choose a name for your directory (e.g.,
review_fish_vibrio), then Browse... to choose where to
save the directory.
We suggest to save the directory on your computer
(e.g. C:/users/...) instead of clouds (e.g. OneDrive, Box,
etc.), as restriction access from institution might block
R.
Click Create Project
From your new directory, install LitFetchR from
GitHub:
#This step can be skipped if `LitFetchR` is already installed
#Install using devtools package
install.packages("devtools")
devtools::install_github("thomasdumond/LitFetchR")
#or
#Install using remotes package
install.packages("remotes")
remotes::install_github("thomasdumond/LitFetchR")Then load the package:
Save your API keys in your personal R environment:
#This step can be skipped if your API keys have already been saved. Repeat this step if your API keys changed.
#Load `LitFetchR`
library(LitFetchR)
#Save API keys in your R environment
#Example of what you should see:
#> save_api_keys(wos_api_key = "abcd01234", scp_api_key = "efgh5678")
#Saved key(s) wos_api_key, scp_api_key to -path-to-your-renvironment/.Renviron.
#Restart R for the new environment variable(s) to be available.This will allow LitFetchR to locally access your
personal API keys while keeping them confidential if you need to share
your code with collaborators.
As mentioned by R, it is important to restart your session before continuing:
Session>Restart R
Then load LitFetchR again using
library(LitFetchR)
If you don’t have API keys for Scopus and Web of Science, see Get API keys.
The interactive create_save_search() function will guide
you through its workflow. Here is an example of what you should see:
#Load LitFetchR
library(LitFetchR)
#The following function can help to create your search string(s)
#It has to be used to save your search string(s), we recommend choosing the R project directory as the directory in the function.
# Example of what you should see building the search: fish AND "vibrio harveyi" AND diagnostic
#
# > create_save_search(wos = TRUE,
# scp = TRUE,
# pmd = TRUE,
# directory = "C:/path-to-project-directory")
#
# History had been created.
# Enter your search string (or 'summary' or 'exit'): fish
# [1] "fish"
# [1] "Web of Science: 1793296 results"
# [1] "Scopus: 718644 results"
# [1] "PubMed: 384742 results"
# Enter your search string (or 'summary' or 'exit'): fish AND "vibrio harveyi"
# [1] "fish AND \"vibrio harveyi\""
# [1] "Web of Science: 2084 results"
# [1] "Scopus: 1080 results"
# [1] "PubMed: 727 results"
# Enter your search string (or 'summary' or 'exit'): fish AND "vibrio harveyi" AND diagnostic
# [1] "fish AND \"vibrio harveyi\" AND diagnostic"
# [1] "Web of Science: 126 results"
# [1] "Scopus: 22 results"
# [1] "PubMed: 106 results"
# Enter your search string (or 'summary' or 'exit'): summary
# Search_Term Results_WOS Results_SCP Results_PMD
# 1 fish 1793296 718644 384742
# 2 fish AND "vibrio harveyi" 2084 1080 727
# 3 fish AND "vibrio harveyi" AND diagnostic 126 22 106
# Select the index number for the search string to use in automated retrieval: 3
#
# Selected search string: fish AND "vibrio harveyi" AND diagnostic
# Do you want to save the search string for future use? (yes/no): yes
# Enter a name for the search identification: fish_vibrio
# Search string saved successfully.
# Enter your search string (or 'summary' or 'exit'): exit
# Exiting search tool.After using create_save_search(), two new files will
appear in your directory:
search_list.txt
This file contains the name and search string that you saved
using create_save_search(). It is an essential file to
retrieve the reference later. If you modify the search string in this
file, the modified search string will be used for future reference
retrieval.
history_search.xlsx
This file contains all the search that you run when using the
function create_save_search(). Each time you run the
function, it creates a new sheet named with the current date and saves
both the search string sent to the literature platforms, and the number
of results that they returned.
If you already validated your review search string, use
create_save_search() to save the search string and setup
the file required to continue toward the automation of reference
retrieval.
The automated reference retrieval uses either Windows Task Scheduler
or Cron (Mac/Linux). You do not have to specify it,
LitFetchR will detect the system and setup the task for you
using the following:
#Load LitFetchR
library(LitFetchR)
#We recommend choosing the R project directory as the directory in the function. It has to be the directory where "search_list.txt" and "history_search.xlsx" have been saved.
#We recommend using a single word for the *task_id* or to use underscores "_" to separate words.
#The retrieval frequency is currently available "DAILY", "WEEKLY" or "MONTHLY".
#You need to use a 24H format for the time of reference retrieval.
#If you do not have an API key for WOS and/or SCP or want to exclude any database,
#change "TRUE" to "FALSE" in front of the corresponding database (e.g.`wos = FALSE`).
#Example of what you should see
#> auto_LitFetchR_setup(task_id = "fish_vibrio",
# when = "WEEKLY",
# time = "14:00",
# wos = TRUE,
# scp = TRUE,
# pmd = TRUE,
# directory = "C:/path-to-project-directory",
# dedup = FALSE,
# open_file = TRUE)
#Task scheduled!After running auto_LitFetchR_setup() for the first time,
four new files will be created:
history_id.xlsx
This file contains all the databases unique identifiers (e.g. PMID or SCOPUS_ID). These are saved and used at each reference retrieval to only extract the references that were not retrieved before.
history_dedup_YYYY_MM_HHMMSS.xlsx (if dedup = TRUE)
This file contains the history of each step of the deduplication, using the package ASySD.
citationsCSV_YYYY_MM_HHMMSS.CSV
This file contains the list of references retrieved from the search conducted at the date referenced in the name of the file. It is a CSV file, ready to be imported into the screening tool of your choice or in your reference manager. If the deduplication option was selected (dedup = TRUE), this file contains the unique dedupicated references. This file automatically opens after the reference retrieval ends if the corresponding option is selected (open_file = TRUE).
auto_LitFetchR_code_READ_ONLY.R
This file contains the code that is automatically run by the
scheduled task (uses the function manual_fetch()). It is
set as “READ ONLY” to avoid accidental modification that would impair
the scheduled task action. If you deleted this file by accident, use the
auto_LitFetchR_setup() to create a new task and a new code
file.
Each time auto_LitFetchR_code(READ_ONLY).R runs, new unique history_dedup_ and citationCSV_ files are created and history_id is updated.
Congratulations! Your automated reference retrieval is ready to work!