Skip to contents

Annual publication counts for a query

Source: R/analyse.R
scopus_trend.Rd

Counts how many records match a query in each year, giving the size of a literature over time. It is the single-query companion to scopus_compare_topics(): where the comparison shows topics as a share of a reference, this shows the absolute count.

Usage

scopus_trend(
  query,
  years,
  field = NULL,
  view = c("STANDARD", "COMPLETE"),
  api_key = NULL,
  inst_token = NULL,
  verbose = FALSE
)

Arguments

query

Character scalar. The base search expression.

years

Integer vector of publication years to count over, for example 2010:2020.

field

Optional 'Scopus' field tag to wrap the query in (see scopus_plan()).

view

Either "STANDARD" or "COMPLETE". COMPLETE adds an authkeywords column to scopus_fetch()/scopus_fetch_plan() output (see scopus_records()) at no extra cost beyond COMPLETE's own smaller page size, which already means more requests, and so more quota, for the same number of records.

api_key, inst_token

Optional credentials, resolved by default from options or environment variables (see scopus_has_key()).

verbose

Logical. When TRUE, progress is reported.

Value

A tibble of class scopus_trend with columns query (the field-wrapped query), year (integer) and n (the count that year, as a double so very large counts are exact). A year whose response omits a total is recorded as NA (with a warning) and contributes nothing to the total shown by print().

API access

This performs one count request per year, so it requires a valid API key and internet access; see the API access section of scopus_count().

See also

plot_scopus_trend(), scopus_compare_topics()

Examples

if (FALSE) { # scopusflow::scopus_has_key()
tr <- scopus_trend("graphene supercapacitor", years = 2015:2024,
                   field = "TITLE-ABS-KEY")
tr
}
# The offline companion, which needs no key. 'Scopus' records may not be
# redistributed, so the package bundles a corpus of real articles instead;
# it is a complete harvest of its own query, so tallying its rows by year
# reproduces the yearly counts that query returns.
by_year <- table(example_records$year)
tr <- tibble::tibble(
  query = "TITLE-ABS-KEY(graphene supercapacitor)",
  year = as.integer(names(by_year)),
  n = as.numeric(by_year)
)
class(tr) <- c("scopus_trend", class(tr))
tr
#> <scopus_trend> (10 years, 138 records)
#> # A tibble: 10 × 3
#>    query                                   year     n
#>    <chr>                                  <int> <dbl>
#>  1 TITLE-ABS-KEY(graphene supercapacitor)  2015    15
#>  2 TITLE-ABS-KEY(graphene supercapacitor)  2016     9
#>  3 TITLE-ABS-KEY(graphene supercapacitor)  2017    10
#>  4 TITLE-ABS-KEY(graphene supercapacitor)  2018    15
#>  5 TITLE-ABS-KEY(graphene supercapacitor)  2019    19
#>  6 TITLE-ABS-KEY(graphene supercapacitor)  2020    13
#>  7 TITLE-ABS-KEY(graphene supercapacitor)  2021    13
#>  8 TITLE-ABS-KEY(graphene supercapacitor)  2022    15
#>  9 TITLE-ABS-KEY(graphene supercapacitor)  2023    15
#> 10 TITLE-ABS-KEY(graphene supercapacitor)  2024    14