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, checked offline before any request (see the Query checks section of scopus_plan()).

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(). The time the counts were taken is attached as the retrieved_at attribute (a POSIXct), as a harvest records its own. 'Scopus' goes on indexing a year's publications after the year has begun, so a count for the year of retrieval is a count so far, and plot_scopus_trend() says so from this time.

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 OpenAlex's exact-phrase search for the same
# phrase, so tallying its rows by year gives the yearly counts of that
# search. A 'Scopus' count of the phrase would differ.
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