scopusflow (R)

scopusflow is a reproducible, quota-aware workflow layer over the Elsevier Scopus Search API. It turns one-off bibliographic queries into inspectable plans, retrieves records safely with pagination, rate-limit handling, retry with back-off and optional resumable caching, normalises them to a stable tidy schema, tracks changes in DOI sets over time, sizes sets of concepts and their intersections and compares publication trends across topics.

Its Python twin, the package of the same name, follows the same design on top of pybliometrics, so a search written in one language reads much the same in the other.

The figure is drawn by plot_scopus_comparison() from illustrative counts, so that this page builds without an API key and without contacting Elsevier. The Comparing topics over time article builds the same table and explains every column.

Scopus is a trademark of Elsevier. scopusflow is an independent client and is not affiliated with or endorsed by Elsevier. You will need your own Elsevier API key and should use it under Elsevier’s API terms.

Installation

The released version is on CRAN.

install.packages("scopusflow")

The development version, which may be ahead of CRAN, installs from GitHub. NEWS lists what each release added.

# install.packages("pak")
pak::pak("pablobernabeu/scopusflow")

API key

scopusflow never stores your key. It is read, in order, from the api_key argument, the scopusflow.api_key option, or the SCOPUS_API_KEY environment variable. Store it in ~/.Renviron.

SCOPUS_API_KEY=your-key-here
# Optional, for off-campus access to subscriber content:
SCOPUS_INST_TOKEN=your-institutional-token

library(scopusflow)
scopus_has_key()
#> [1] TRUE

The workflow in brief

With a key configured, a search runs as a plan: compose the query, size it, execute it with caching, then export or analyse the result. These calls contact the API and consume quota, so they are not run here.

# Compose a field-tagged query, then a reproducible plan partitioned by
# year to stay under the API's start < 5000 ceiling.
q <- scopus_query("perovskite", "solar cell", .field = "TITLE-ABS-KEY")
plan <- scopus_plan(q, years = 2012:2022, partition = "year")

# Size the search before spending quota, then execute, caching each year
# in a directory of the plan's own so an interrupted run can resume.
scopus_count(q, years = 2012:2022)
records <- scopus_fetch_plan(
  plan,
  cache_dir = file.path(scopus_cache_dir(), "perovskite-solar-cell"),
  resume = TRUE
)

# Save a clean DOI list, or export the records for a reference manager
# (Zotero, EndNote, Mendeley) or a LaTeX bibliography.
scopus_extract_dois(records, file = file.path(tempdir(), "dois.csv"))
as_bibtex(records, file = file.path(tempdir(), "records.bib"))

# Write the search up for the methods section, to the PRISMA-S standard,
# from what the plan and the harvest already record.
scopus_search_report(records, file = file.path(tempdir(), "search-record.md"))

The Get started vignette walks this workflow offline, on records bundled with the package, and the articles each cover one part in depth: designing queries, search plans, quota and the PRISMA-S search record, building a reference set, analysing and visualising a literature (trends, top sources and authors, concept intersections, abstracts and cursor-paged harvests), author keywords and references, comparing topics over time (the chart above) and tracking how a literature changes between retrievals.

Code-free app

run_app() opens a local Shiny app that drives the whole workflow without writing code, and mirrors every choice back as a runnable R script, so it doubles as a way into the package itself. It runs on your own machine, so your API key never leaves it, and a demo mode lets you try the flow with no key, on the corpus of real articles bundled with the package.

run_app()

The retrieval runs in a background process with a live progress terminal, and records appear as a table and as plots with one-click export. It needs the suggested packages shiny, bslib and callr. The Using the code-free app article walks through every panel.

This is the beginning of the README. Read the rest at the original. Read the full README ↗