## ----include = FALSE----------------------------------------------------------
knitr::opts_chunk$set(collapse = FALSE, comment = "")
# Console colour carries no meaning on a rendered page. pkgdown turns it on for
# its own build, and the escape sequences then reach the reader as literal text,
# so colour is switched off here for a plain vignette render and a site build
# alike. The fixed width keeps tibbles inside the documentation column.
options(cli.num_colors = 1, cli.hyperlink = FALSE, crayon.enabled = FALSE,
        width = 80)
# Print data frames and tibbles as formatted tables.
local({
  kp <- function(x, ...) {
    if (any(vapply(x, is.list, logical(1)))) return(knitr::normal_print(x))
    knitr::knit_print(knitr::kable(x))
  }
  for (cls in c("data.frame", "tbl_df", "tbl")) {
    registerS3method("knit_print", cls, kp, envir = asNamespace("knitr"))
  }
})
has_ggplot2 <- requireNamespace("ggplot2", quietly = TRUE)
# Draw the figures on a transparent background so they sit on whatever colour
# the page behind them happens to be. An opaque white matte reads as a white
# slab on the site's dark theme, and worse once pkgdown's dark-mode filter
# inverts it into a black one. Both halves below are needed: the device option
# gives the file an alpha channel, and the theme override clears the white
# rectangle that ggplot2's complete themes paint over it regardless. The
# override belongs here, in the vignette, because a figure saved for a paper
# usually does want a background of its own, so the package's plotting
# functions leave it alone.
knitr::opts_chunk$set(dev.args = list(bg = "transparent"))
if (has_ggplot2) {
  sf_on_page <- ggplot2::theme(
    plot.background  = ggplot2::element_rect(fill = "transparent", colour = NA),
    panel.background = ggplot2::element_rect(fill = "transparent", colour = NA)
  )
  knitr::opts_chunk$set(render = function(x, ...) {
    if (inherits(x, "ggplot")) x <- x + sf_on_page
    knitr::knit_print(x, ...)
  })
}

## ----setup--------------------------------------------------------------------
library(scopusflow)

## -----------------------------------------------------------------------------
records <- example_records
summary(records)

## -----------------------------------------------------------------------------
scopus_top(records, by = "source")
scopus_top(records, by = "author", n = 5)

## -----------------------------------------------------------------------------
multi <- scopus_records(list(entry = list(
  list(`dc:creator` = "Author A.; Author B."),
  list(`dc:creator` = "Author B.")
)))
scopus_top(multi, by = "author")

## ----eval = has_ggplot2, fig.alt = "A horizontal bar chart of the most frequent sources", fig.width = 7, fig.height = 3.5----
plot_scopus_top(scopus_top(records, by = "source"))

## ----eval = has_ggplot2, fig.alt = "A horizontal bar chart of the most frequent authors", fig.width = 7, fig.height = 3.5----
plot_scopus_top(scopus_top(records, by = "author", n = 5))

## ----eval = has_ggplot2, fig.alt = "A bar chart of publications per year from 2015 to 2024, fluctuating around fifteen a year", fig.width = 7, fig.height = 3.5----
ggplot2::autoplot(records)

## ----eval = FALSE-------------------------------------------------------------
# tr <- scopus_trend("graphene supercapacitor", years = 2015:2024,
#                    field = "TITLE-ABS-KEY")
# plot_scopus_trend(tr)

## -----------------------------------------------------------------------------
by_year <- table(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

## ----eval = has_ggplot2, fig.alt = "A line and area chart of publications per year from 2015 to 2024, peaking in 2019", fig.width = 7.5, fig.height = 4----
plot_scopus_trend(tr)

## ----eval = FALSE-------------------------------------------------------------
# sets <- scopus_intersections(
#   concepts = c(
#     "semantic priming"  = "semantic priming",
#     "mental simulation" = "mental simulation",
#     # A synonym set, given as a complete expression and used exactly as given.
#     "embodied simulation" =
#       'TITLE-ABS-KEY("mental simulation") OR TITLE-ABS-KEY("embodied simulation")'
#   ),
#   intersections = list(c("semantic priming", "mental simulation")),
#   field = "TITLE-ABS-KEY"
# )
# plot_scopus_intersections(
#   sets,
#   highlight = sets$label[sets$type == "intersection"]
# )

## ----eval = has_ggplot2, fig.alt = "A log-scale lollipop chart showing three concepts and a small intersection, with the intersection highlighted", fig.width = 7.5, fig.height = 3----
sets <- tibble::tibble(
  label = c("semantic priming", "mental simulation", "embodied simulation",
            "semantic priming × mental simulation"),
  query = c("TITLE-ABS-KEY(semantic priming)",
            "TITLE-ABS-KEY(mental simulation)",
            'TITLE-ABS-KEY("mental simulation") OR TITLE-ABS-KEY("embodied simulation")',
            "(TITLE-ABS-KEY(semantic priming)) AND (TITLE-ABS-KEY(mental simulation))"),
  n = c(6600, 2100, 3400, 15),
  type = c("concept", "concept", "concept", "intersection"),
  size = c(1L, 1L, 1L, 2L),
  members = c("semantic priming", "mental simulation", "embodied simulation",
              "semantic priming; mental simulation")
)
class(sets) <- c("scopus_intersections", class(sets))
plot_scopus_intersections(
  sets,
  highlight = sets$label[sets$type == "intersection"]
)

## ----eval = FALSE-------------------------------------------------------------
# ab <- scopus_abstract(head(scopus_extract_dois(records), 2))

## -----------------------------------------------------------------------------
top2 <- records[order(-records$citations), ][1:2, ]
ab <- tibble::tibble(
  id          = top2$doi,
  scopus_id   = NA_character_,
  doi         = top2$doi,
  title       = top2$title,
  abstract    = "<abstract text, as the API returns it>",
  publication = top2$publication,
  year        = top2$year,
  citations   = top2$citations
)
class(ab) <- c("scopus_abstracts", class(ab))
names(ab)

ab[, c("title", "publication", "year", "citations")]

## ----eval = FALSE-------------------------------------------------------------
# recs <- scopus_fetch("TITLE-ABS-KEY(microplastics)", cursor = TRUE)
# nrow(recs)