Skip to contents

Build a reproducible 'Scopus' search plan

Source: R/plan.R
scopus_plan.Rd

A plan is a fully specified, inspectable description of one or more 'Scopus' queries to run. Splitting the act of describing a search from executing it makes workflows reproducible (the plan can be saved, reviewed and version controlled) and lets large retrievals be partitioned, for example one cell per year, so they can be cached and resumed.

Usage

scopus_plan(
  query,
  years = NULL,
  field = NULL,
  view = c("STANDARD", "COMPLETE"),
  page_size = NULL,
  partition = c("none", "year")
)

is_scopus_plan(x)

Arguments

query

Character scalar. The search expression. Give it without a field tag when field is set, since the plan wraps it in that tag. A query that already carries its tags, such as one composed by scopus_query() with .field, is sent as written when field is NULL. Years given through years are sent as the request's separate date parameter, not written into the expression.

years

Optional integer vector of publication years, for example 2015:2020. When partition = "year", one plan cell is created for each distinct year, so c(2015, 2020) searches those two years alone, as scopus_trend() and scopus_compare_topics() do. Otherwise, the plan sends one inclusive range from the earliest year to the latest, so c(2015, 2020) covers every year from 2015 to 2020, as in scopus_count(), scopus_fetch() and scopus_intersections(). An empty vector places no year restriction, as NULL does.

field

Optional character scalar naming a 'Scopus' field tag to wrap the query in, for example "TITLE-ABS-KEY", "TITLE", "AUTH" or "AFFIL". When NULL, the query is used verbatim. See scopus_field_tags() for the common tags.

view

Either "STANDARD" or "COMPLETE". COMPLETE returns more fields, including an authkeywords column (see scopus_records()), but requires a subscriber entitlement and is limited to a smaller page size, which means more requests, and so more quota, for the same number of records. Even where COMPLETE view itself is accessible, the returned author keywords can still be gated separately by your own account (see scopus_records()).

page_size

Integer number of records to request per page, or NULL (the default) to use the largest page the view allows. The 'Scopus' Search API permits up to 200 records per page for the STANDARD view but only 25 for COMPLETE. Because the weekly quota is charged per request, requesting the maximum page size keeps the number of requests, and so the quota, as low as possible for a given result set. Lower it only where you have a reason to.

partition

Either "none" (a single query cell) or "year" (one cell per year in years). Partitioning by year is the recommended way to stay under the API's hard limit of start < 5000.

x

An object to test or print.

Value

A tibble of class scopus_plan, one row per cell, with columns cell, query (field-wrapped), date (year range string or NA), year (integer or NA), view and page_size. Plan-level settings are stored as attributes.

is_scopus_plan() returns a length-one logical.

Query checks

scopus_plan(), scopus_count(), scopus_fetch(), scopus_trend(), scopus_compare_topics() and scopus_intersections() check each query offline, before any request, and refuse three mistakes with a scopus_error_bad_input condition. LIMIT-TO() and EXCLUDE() belong to the web interface's refinement panel, and the Search API ignores them, so the search would run unfiltered. Write such a limit as a search field, for example DOCTYPE(ar), LANGUAGE(english), SUBJAREA(PSYC), SRCTYPE(j) or PUBYEAR > 2015. A field given for a query that already opens with a field tag would nest one tag inside the other, which the API rejects, so leave field as NULL for such a query. Brackets, quotation marks and braces must balance, counting brackets inside a phrase as text. INDEXTERMS(), which pybliometrics documents as not working through the Search API, raises a scopus_warning_query_syntax warning. KEY() searches the index terms together with author keywords, trade names and chemical names. The messages are those of the Python twin, word for word.

See also

scopus_fetch_plan() to execute a plan, scopus_count() to size it.

Examples

scopus_plan("quantum computing", years = 2015:2022, field = "TITLE-ABS-KEY")
#> <scopus_plan> (1 cell, view "STANDARD", partition "none")
#> # A tibble: 1 × 6
#>    cell query                            date       year view     page_size
#> * <int> <chr>                            <chr>     <int> <chr>        <int>
#> 1     1 TITLE-ABS-KEY(quantum computing) 2015-2022    NA STANDARD       200
scopus_plan("immunotherapy", years = 2010:2020, partition = "year")
#> <scopus_plan> (11 cells, view "STANDARD", partition "year")
#> # A tibble: 11 × 6
#>     cell query         date   year view     page_size
#>  * <int> <chr>         <chr> <int> <chr>        <int>
#>  1     1 immunotherapy 2010   2010 STANDARD       200
#>  2     2 immunotherapy 2011   2011 STANDARD       200
#>  3     3 immunotherapy 2012   2012 STANDARD       200
#>  4     4 immunotherapy 2013   2013 STANDARD       200
#>  5     5 immunotherapy 2014   2014 STANDARD       200
#>  6     6 immunotherapy 2015   2015 STANDARD       200
#>  7     7 immunotherapy 2016   2016 STANDARD       200
#>  8     8 immunotherapy 2017   2017 STANDARD       200
#>  9     9 immunotherapy 2018   2018 STANDARD       200
#> 10    10 immunotherapy 2019   2019 STANDARD       200
#> 11    11 immunotherapy 2020   2020 STANDARD       200