## ----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"))
  }
})
# The plotting chunks below need ggplot2, which is only a suggested package.
# Skip them when it is not installed.
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)

## ----eval = FALSE-------------------------------------------------------------
# cmp <- scopus_compare_topics(
#   reference_query  = "deep learning",
#   comparison_terms = c("computer vision", "natural language processing",
#                        "medical imaging", "drug discovery"),
#   years            = 2013:2021,
#   field            = "TITLE-ABS-KEY"
# )

## -----------------------------------------------------------------------------
years <- 2013:2021
ref_n <- round(seq(400, 1600, length.out = length(years)))
mk <- function(from, to) round(seq(from, to, length.out = length(years)))
counts <- list(
  "computer vision" = mk(140, 720),
  "natural language processing" = mk(90, 540),
  "medical imaging" = mk(15, 260),
  "drug discovery" = mk(8, 170)
)
cmp <- tibble::tibble(
  query = "q",
  query_type = c(rep("reference", length(years)),
                 rep("comparison", length(counts) * length(years))),
  abridged_query = c(rep("deep learning", length(years)),
                     rep(names(counts), each = length(years))),
  year = rep(years, length(counts) + 1),
  n = c(ref_n, unlist(counts, use.names = FALSE)),
  reference_n = rep(ref_n, length(counts) + 1),
  comparison_percentage = 100 * c(ref_n, unlist(counts, use.names = FALSE)) /
    rep(ref_n, length(counts) + 1),
  average_comparison_percentage = c(rep(100, length(years)),
                                    rep(c(40, 33, 15, 9), each = length(years)))
)
class(cmp) <- c("scopus_comparison", class(cmp))

# The whole table is too long to read here, so show its first year across every
# topic. The `query` column is left out because a real comparison carries the
# whole query string sent to the API in it, which is too long for a table. The
# illustrative table built above holds a placeholder there instead.
cmp[cmp$year == min(cmp$year), setdiff(names(cmp), "query")]

## ----eval = has_ggplot2, fig.alt = "Four application areas' share of the deep-learning literature from 2013 to 2021, with shaded uncertainty bands and an in-panel legend", fig.width = 8, fig.height = 4.6----
plot_scopus_comparison(cmp, legend_inside = TRUE)

## -----------------------------------------------------------------------------
years <- 2013:2021
ends <- c(18, 18.6, 19.2, 19.8, 20.4, 21)
names(ends) <- c(
  "graphene", "perovskites", "MXenes", "COFs", "MOFs", "aerogels"
)
ref_n <- round(seq(500, 2000, length.out = length(years)))
converge <- function(end) round(end *
  (0.5 + 0.5 * (0:(length(years) - 1)) / (length(years) - 1)) * ref_n / 100)
counts <- lapply(ends, converge)

cmp_converging <- tibble::tibble(
  query = "q",
  query_type = c(rep("reference", length(years)),
                 rep("comparison", length(counts) * length(years))),
  abridged_query = c(rep("energy materials", length(years)),
                     rep(names(counts), each = length(years))),
  year = rep(years, length(counts) + 1),
  n = c(ref_n, unlist(counts, use.names = FALSE)),
  reference_n = rep(ref_n, length(counts) + 1),
  comparison_percentage = 100 * c(ref_n, unlist(counts, use.names = FALSE)) /
    rep(ref_n, length(counts) + 1),
  average_comparison_percentage = c(rep(100, length(years)),
                                    rep(ends, each = length(years)))
)
class(cmp_converging) <- c("scopus_comparison", class(cmp_converging))

## ----eval = has_ggplot2, fig.alt = "Six materials-science sub-areas converging to similar shares by 2021, with end labels automatically spread apart so that none overlaps", fig.width = 8, fig.height = 4.6----
plot_scopus_comparison(cmp_converging)

## ----eval = has_ggplot2, fig.alt = "The same chart with the medical-imaging topic highlighted against the others in grey", fig.width = 8, fig.height = 4.6----
plot_scopus_comparison(cmp, highlight = "medical imaging")

## ----eval = has_ggplot2, fig.alt = "The comparison chart without record counts or bands", fig.width = 8, fig.height = 4.6----
plot_scopus_comparison(cmp, pub_count_in_legend = FALSE, interval = FALSE)

## -----------------------------------------------------------------------------
comp <- cmp[cmp$query_type == "comparison", ]
unique(comp[, c("abridged_query", "average_comparison_percentage")])