# LitFetchR (Tutorial)

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.

## Setup

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:

    #Load `LitFetchR`
    library(LitFetchR)

## Save API keys

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.

## Save the review search string(s)

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.

## Setup the automatic 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!

## See also

- Remove or change a scheduled task

- Manual reference retrieval