R/theme_palette_set.R

Defines functions ag_themer `%||%` ag_ground_fill ag_ground set_categorical_theme set_divergent_theme set_highlight_theme set_missing_theme set_ink_theme set_background_theme read_theme_pref forget_theme_pref write_theme_pref theme_pref_file stocnet_theme

Documented in stocnet_theme

#' Setting a consistent theme for all plots
#' @description
#'   This function enables plots to be quickly, easily and consistently themed.
#'   This is achieved by setting a theme option, usually at the start of an R
#'   session, that enables the palette to be used for 
#'   all autograph-consistent plotting methods.
#'   This includes thematic colours for backgrounds, highlights, 
#'   sequential, divergent and categorical colour schemes.
#'   The function sets these palettes to options that are then
#'   used by the various plotting functions.
#'   
#'   If no theme is specified (i.e. the function is called without argument), 
#'   the current theme is reported.
#'   The default theme is "default".
#'   This theme uses a white background, blue and red for
#'   highlighting, and a blue-white-red divergent palette.
#'   The themes can be changed at any time by calling `stocnet_theme()`
#'   or its alias `set_stocnet_theme()` with a different theme name.
#'   
#'   Other themes include those based on the colour schemes of various 
#'   universities, including ETH Zurich, UZH, UNIBE, RUG, and Oxford.
#'   Other themes include "bw" for black and white, "crisp" for a
#'   high-contrast black and white theme, "neon" for a dark theme
#'   with neon highlights, and "rainbow" for a colourful theme.
#'   The "clay" theme follows the palette and fonts used in the slides and
#'   documents that Anthropic's Claude produces: an ivory background,
#'   a slate ink base, and a clay orange highlight.
#'   Most themes are designed to be colour-blind safe.
#'   
#' @name theme_set
#' @family themes
#' @section Fonts: 
#'   Some themes also set a preferred font for use in plots, 
#'   if available on the system (a check is performed).
#'   In some cases, this includes a vector of options to try in sequence.
#'   If none of the preferred fonts are available, a sans-serif font is used.
#'   Themes then look much more alike than they should,
#'   since the typeface carries a good deal of an institution\'s identity.
#'   Call `list_fonts()` to see which font families R can currently see,
#'   and `ag_font()` to see which one the current theme settled on.
#'   
#'   To make more fonts available, there are two steps.
#'   
#'   1. Install the font on your computer.
#'   Many of the fonts these themes prefer are free:
#'   Google Fonts (<https://fonts.google.com>) offers Roboto, Open Sans,
#'   Source Sans 3, Source Serif 4, Noto Serif, Montserrat, and Playfair
#'   Display, among others.
#'   Download the family, then install it as you would any other font:
#'   double-click the files and choose "Install" on Windows,
#'   open them in Font Book on macOS,
#'   or copy them into `~/.local/share/fonts` and run `fc-cache -f` on Linux.
#'   Some fonts are licensed and are only available to members of the
#'   institution concerned, or for purchase;
#'   the theme falls back to a near relative where it can.
#'   2. Make the font available to R.
#'   Install the `{systemfonts}` package and the fonts installed on your system
#'   are found directly, with no further step.
#'   Otherwise, use `extrafont::font_import()` once and
#'   `extrafont::loadfonts()` in each session.
#'   Restart R after installing a font, then call `list_fonts()` to check that
#'   the family is now listed, and set the theme again.
#'   
#'   Note that a font is only used where the graphics device can draw it.
#'   The `{ragg}` devices (for example `ragg::agg_png()`) and `{svglite}` are
#'   the most reliable;
#'   the default PDF device needs the font embedded,
#'   for which `extrafont::embed_fonts()` is available.
#' @section Custom: 
#'   If you have specific needs or preferences, you can
#'   set your own palettes or overwrite part of an existing one using `options()`.
#'   For example, to set a custom base color, you can use:
#'   `options(snet_highlight = c("#1b9e77", "#d95f02", "#7570b3"))`.
#'   This will set a custom highlight color palette.
#'   Similarly, you can set `snet_div` for divergent palettes
#'   and `snet_cat` for categorical palettes.
#' @returns This function sets the theme and palette(s) to be used across all
#'   stocnet packages. The palettes are written to options and held there.
#' @examples
#' stocnet_theme("default")
#' plot(netrics::node_by_degree(ison_karateka))
#' stocnet_theme("uzh")
#' plot(netrics::node_by_degree(ison_karateka))
NULL

# Themes whose palette order carries meaning of its own, and so is not
# reordered for colour blindness. See the Colour blindness section of ?ag_call.
colorblind_unsorted <- "rainbow"

theme_opts <- c("default", "bw", "crisp", "neon", "clay", 
                "iheid", "ethz", "uzh", "rug", "unibe", 
                "oxf", "unige", "cmu", "iast", "hwu",
                "rainbow")

#' @rdname theme_set
#' @param theme String naming a theme.
#'   By default "default".
#'   The following themes are currently available:
#'   `r autograph:::theme_opts`.
#'   This string can be capitalised or not.
#' @param persist Logical, by default FALSE.
#'   If TRUE, the theme is remembered across sessions,
#'   by writing it to the user's configuration directory
#'   (see `tools::R_user_dir()`).
#'   Nothing is written to disk unless this is set explicitly.
#'   Use `stocnet_theme(persist = FALSE)` when setting a theme
#'   to forget a previously persisted choice.
#' @importFrom manynet snet_info snet_success
#' @export
stocnet_theme <- function(theme = NULL, persist = FALSE){
  if(is.null(theme)){
    theme <- getOption("stocnet_theme", default = "default")
    snet_info("Theme is currently set to {.emph {theme}}.",
              "The following themes are available: {.emph {theme_opts}}.")
  } else {
    if(!is.character(theme) || length(theme) != 1L)
      manynet::snet_abort(
        "{.arg theme} should be the name of a single theme, given as a string.",
        "The themes available are {.val {theme_opts}}.")
    # An unrecognised theme used to warn and leave the theme unchanged, which
    # was easy to miss and left plots looking wrong for no visible reason.
    theme <- .match_name(tolower(theme), theme_opts, "theme", what = "theme")
    options(stocnet_theme = theme)
    set_highlight_theme(theme)
    set_ink_theme(theme)
    set_divergent_theme(theme)
    set_background_theme(theme)
    set_categorical_theme(theme)
    set_missing_theme(theme)
    set_font_theme(theme)
    snet_success("Theme set to {.emph {theme}}.")
    if(persist){
      if(write_theme_pref(theme))
        snet_success("Theme will be remembered in future sessions.")
    } else forget_theme_pref()
  }
}

# The reading and writing itself is shared with any other remembered
# preference; see write_pref() in autograph_utilities.R.
theme_pref_file <- function() pref_file("theme")

write_theme_pref <- function(theme) write_pref("theme", theme)

forget_theme_pref <- function() forget_pref("theme")

read_theme_pref <- function(){
  theme <- read_pref("theme")
  # Guard against a stale file naming a theme this version no longer ships.
  if(is.null(theme) || !is.character(theme) || length(theme) != 1L ||
     !theme %in% theme_opts) return(NULL)
  theme
}

#' @rdname theme_set
#' @export
set_stocnet_theme <- stocnet_theme

set_background_theme <- function(theme){
  if(theme == "neon"){
    options(snet_background = "#070f23")
  } else if(theme == "cmu"){
    options(snet_background = "#E4DAC4")
  } else if(theme == "clay"){
    options(snet_background = "#F0EEE6")
  } else {
    options(snet_background = "#FFFFFF")
  }
}

# The ink is the dark colour a plot writes with: axis text, reference lines,
# and other chrome. It is kept apart from the base, which is the colour of an
# unhighlighted mark, because the two roles pull in opposite directions. A
# base must stand away from the highlight, which for a dark brand colour means
# a lighter grey; ink must stay legible, which means a dark one.
set_ink_theme <- function(theme){
  options(snet_ink = switch(theme,
                            "neon" = "#EDEDF4",
                            "iheid" = "#000010",
                            "oxf" = "#002147",
                            "hwu" = "#0A3E65",
                            "clay" = "#3D3D3A",
                            "crisp" = "#101314",
                            "cmu" = "#1A1A1A",
                            "bw" = "#000000",
                            "rug" = "#000000",
                            "#121212"))
}

# The neutral that data recedes into: missing values, isolates counted out of
# a drawing, and any "other" remainder. It has two jobs at once, and they pull
# apart: it must clear the theme's ground by enough to be seen at all (WCAG
# asks 3:1 of a graphical object), while staying far enough from every
# categorical colour not to be read as one of them. Several palettes hold a
# grey of their own, so which neutral is free depends on the theme, and
# hand-picking sixteen of them would go stale the moment a palette changed.
# It is chosen the way colorblind_sort() chooses an order instead: from a
# ladder of neutrals, take the one that clears the ground and sits furthest
# from anything the palette already uses.
missing_candidates <- c("#4D4D4D", "#595959", "#666666", "#737373", "#808080",
                        "#8C8C8C", "#999999", "#A6A6A6", "#B3B3B3",
                        # A warm and a cool neutral for the tinted grounds.
                        "#6B665C", "#7E766A", "#8A8378", "#96907F",
                        "#5C6270", "#6E7482", "#7F87A0", "#919AAE")

set_missing_theme <- function(theme){
  bg <- getOption("snet_background", default = "#FFFFFF")
  pal <- getOption("snet_cat", default = "#4576B5")
  seen <- vapply(missing_candidates,
                 function(x) check_contrast(x, bg)[1, 2], numeric(1))
  keep <- seen >= 3
  if(!any(keep)) keep <- seq_along(seen) == which.max(seen)
  ok <- missing_candidates[keep]
  seen <- seen[keep]
  apart <- vapply(ok, function(x) min(check_separation(c(x, pal))[1, -1]),
                  numeric(1))
  free <- ok[apart >= 10]
  # Among the neutrals that are both visible and unmistakable, take the one
  # nearest the ground. The point of this colour is to recede, so the least
  # contrast that still clears the floor is the right amount, not the most.
  if(length(free)){
    options(snet_missing = unname(free[which.min(seen[apart >= 10])]))
    return(invisible(NULL))
  }
  options(snet_missing = unname(ok[which.max(apart)]))
}

set_highlight_theme <- function(theme){
  hl <- switch(theme,
               "iheid" = c("#000010","#E20020"),
               "unige" = c("#A3A3A3","#CF0063"),
               "rug" = c("#000000", "#dc002d"),
               "uzh" = c("#a3adb7", "#dc6027"),
               "unibe" = c("#121212", "#e4003c"),
               "oxf" = c("#002147", "#c09725"),
               # The ETH grey and blue used to sit 28 apart under
               # simulation, both being mid-dark; the lighter grey separates
               # them by lightness, which every viewer keeps.
               "ethz" = c("#919191", "#0028a5"),
               "cmu" = c("#8F9194", "#C41230"),
               "iast" = c("#555", "#e54a37"),
               "hwu" = c("#0A3E65", "#0095DB"),
               "crisp" = c("#bfbfbf", "#101314"),
               "bw" = c("#CCCCCC", "#000000"),
               # The neon cyan and green scored 12.7 apart under simulation,
               # so the highlight is now a yellow that keeps the same voltage.
               "neon" = c("#5aeafd", "#fdfd54"),
               "clay" = c("#3D3D3A", "#D97757"),
               "rainbow" = c('#1965B0', '#DC050C'),
               c("#4576B5", "#D83127"))
  options(snet_highlight = hl)
}

# "#E20020" - IHEID red
# "#215CAF" - ETH blue
# "#EDEDF4" - ghost white
# "#071013" - rich black
# "#EDAE49" - hunyadi yellow
# "#3C493F" - field green
# "#679289" - viridian

set_divergent_theme <- function(theme){
  # Each triplet runs warm pole, light middle, cool pole, so that a reader
  # meets the same convention in every theme, and so that the poles differ in
  # lightness as well as in hue. Several of these used to pair a red pole with
  # a green or teal one, drawn from the same institutional palette, which is
  # the one pairing that red-green colour blindness cannot resolve: the ETH
  # red and olive poles scored 3.8 apart under simulation, where 10 is already
  # confusable. The poles below are still each theme's own colours, chosen for
  # the widest separation the palette allows. See [check_separation()].
  dv <- switch(theme,
               "iheid" = c("#820C2B","white","#006EAA"),
               "unige" = c("#F42941","white","#0067C5"),
               "ethz" = c("#B7352D","white","#0028a5"),
               "uzh" = c("#FC4C02","white","#0028A5"),
               "unibe" = c("#8a1e22","white","#4767af"),
               "oxf" = c('#FB5607', 'white', '#002147'),
               "cmu" = c("#C41230","#E4DAC4","#007BC0"),
               "iast" = c("#e62117","#999","#3b5998"),
               "hwu" = c("#E38C33","white","#0A3E65"),
               "bw" = c("black","grey","white"),
               "clay" = c("#D97757","#F0EEE6","#6B5B95"),
               "rainbow" = c('#DC050C','#CAE0AB','#882E72'),
               c("#d73027","white","#4575b4"))
    options(snet_div = dv)
}

set_categorical_theme <- function(theme){
  if(theme == "bw"){
    pal <- c("#CCCCCC", "#000000")
  } else if(theme == "iheid"){
    pal <- c("#006564","#0094D8","#622550",
                         "#268D2B","#3E2682","#820C2B",
                         "#008F92","#006EAA","#A8086E")
  } else if(theme == "unige"){
    pal <- c("#F42941","#0067C5","#96004B",
                         "#007E64","#465F7F","#F1AB00",
                         "#00B1AE","#4B0B71","#FF5C00")
  } else if(theme == "ethz"){
    pal <- c("#215CAF","#007894","#627313",
                         "#8E6713","#B7352D","#A7117A","#6F6F6F")
  } else if(theme == "cmu"){
    pal <- c("#EF3A47","#FDB515","#009647",
                         "#008F91","#043673","#007BC0",
                         "#1F4C4C","#719F94")
  } else if(theme == "iast"){
    pal <- c("#fbda26","#0a0","#9c1a1a",
                         "#1b870b","#3d86d8","#50e3c2",
                         "#7ad03d","#fe0087","#e62117",
                         "#1db6d6","#3b5998","#f58b4c",
                         "#e9711c","#ff2b46","#d9372f",
                         "#2fa7d5","#f0c020","#47c965")
  } else if(theme == "hwu"){
    pal <- c("#342B20","#6A5B49","#947F68","#F7D6A8",
                         "#1A4323","#2C642C","#BBC33E","#D3E3BE",
                         "#5C1F0A","#B25A22","#E38C33","#F5D1A7",
                         "#921E3F","#D32D5C","#DD7488","#E59CBB",
                         "#490C3B","#782066","#B84E8F","#D9AACA",
                         "#031B39","#0A3E65","#0095DB","#C4CEDE")
  } else if(theme == "uzh"){
    pal <- c("#0028A5","#4AC9E3","#A4D233",
                         "#FFC845","#FC4C02","#BF0D3E",
                         "#BDC9E8","#DBF4F9","#ECF6D6",
                         "#FFF4DA","#FFDBCC","#FBC6D4",
                         "#7596FF","#B7E9F4","#DBEDAD",
                         "#FFE9B5","#FEB799","#F78CAA",
                         "#3062FF","#92DFEE","#C8E485",
                         "#FFDE8F","#FE9367","#F3537F",
                         "#001E7C","#1EA7C4","#7CA023",
                         "#F3AB00","#BD3902","#8F0A2E",
                         "#001452","#147082","#536B18",
                         "#A27200","#7E2601","#60061F")
    
  } else if(theme == "unibe"){
    pal <- c("#466553","#668271","#8aa092","#afbfb5","#d6ded9",
                         "#007ea2","#5294b4","#85adc6","#b0c7d9","#d8e2ec",
                         "#203a5d","#4a5575","#757792","#a1a0b4","#d0ced9",
                         "#8a1e22","#a14540","#b86f65","#d19d93","#e8cdc6",
                         "#5a3217","#754e31","#927157","#b49b87","#d7cac0",
                         "#36b5b6","#75c4c5","#a0d3d4","#c4e3e3","#e2f1f2",
                         "#ec627d","#f08797","#f4a9b1","#f8c8cc","#fce4e7",
                         "#4767af","#6e82c0","#949fd1","#b9bee1","#dcdef1",
                         "#c2b600","#cfc43c","#dcd274","#e8e1a4","#f4f0d3",
                         "#ee7402","#f3923e","#f7af70","#fbcba1","#fde6d1")
    
  } else if(theme == "clay"){
    pal <- c("#D97757","#5B6E8F","#788C5D",
                         "#D4A27F","#6B5B95","#B1ADA1",
                         "#A8563C","#8CA3B0","#3D3D3A")
  } else if(theme == "rainbow"){
    pal <- c('#E8ECFB', '#D9CCE3', '#D1BBD7', 
                         '#CAACCB', '#BA8DB4', '#AE76A3', 
                         '#AA6F9E', '#994F88', '#882E72', 
                         '#1965B0', '#437DBF', '#5289C7', 
                         '#6195CF', '#7BAFDE', 
                         '#4EB265', '#90C987', '#CAE0AB', 
                         '#F7F056', '#F7CB45', '#F6C141', 
                         '#F4A736', '#F1932D', '#EE8026', 
                         '#E8601C', '#E65518', '#DC050C', 
                         '#A5170E', '#72190E', '#42150A')
  } else if(theme == "oxf"){
    pal <- c("#776885", '#E08D79', '#ED9390', 
                         '#C4A29E', '#D1BDD5', '#994636', 
                         '#AA1A2D', '#7F055F', '#FE615A', 
                         '#D4CDF4', '#FB5607', '#E6007E', 
                         '#426A5A', '#789E9E', 
                         '#E2C044', '#E4F0EF', '#B9D6F2', 
                         '#A0AF84', '#15616D', '#1D42A6', 
                         '#00AAB4', '#65E5AE', '#95C11F', 
                         '#49B6FF', '#F7EF66')
  } else {
    pal <- c("#1B9E77","#4575b4","#d73027",
                         "#66A61E","#E6AB02","#D95F02","#7570B3",
                         "#A6761D","#E7298A","#666666")
  }
  # The palettes are written above in whatever order their source gives them,
  # which is often a brand's own listing, or families of tints. Neither order
  # separates the first few colours a plot actually uses, so reorder for that.
  # The "rainbow" theme is the exception: its order is the palette, so it is
  # left as the observed spectrum runs.
  spread <- theme %in% colorblind_unsorted
  if(!spread)
    pal <- colorblind_sort(pal, getOption("snet_background", default = "#FFFFFF"))
  # A spectrum is only a spectrum if a plot draws from the whole of it, so a
  # palette left in its own order is sampled across its length instead of
  # taken from the front.
  options(snet_cat = pal, snet_cat_spread = spread)
}

# Every autograph plot is drawn on the theme's own ground, not only the graphs
# that graphr() and grapht() draw. A theme with a dark background used to give
# a dark network plot and white-backed panels for everything else, which left
# the "neon" highlights unreadable on the plots that missed out.
ag_ground <- function(base){
  bg <- ag_ground_fill()
  if(bg == "#FFFFFF") return(base)
  out <- base + ggplot2::theme(
    plot.background = ggplot2::element_rect(fill = bg, colour = NA),
    panel.background = ggplot2::element_rect(fill = bg, colour = NA),
    legend.background = ggplot2::element_rect(fill = bg, colour = NA),
    legend.key = ggplot2::element_rect(fill = bg, colour = NA))
  # Only recolour text the base theme actually draws. Handing an element_text()
  # to a theme that had blanked it puts the element back: colouring the axis
  # text of ag_theme_void() drew axis ticks and coordinates onto graphs, which
  # a graph has no use for, and which the white-backed themes never showed.
  for(part in c("text", "axis.text", "strip.text", "legend.text",
                "plot.title", "plot.subtitle", "plot.caption")){
    if(inherits(out[[part]], "element_blank")) next
    inked <- list(ggplot2::element_text(colour = ag_ink()))
    names(inked) <- part
    out <- out + do.call(ggplot2::theme, inked)
  }
  # A theme that blanks its strips has no strip background to fill either.
  if(!inherits(out[["strip.text"]], "element_blank"))
    out <- out + ggplot2::theme(
      strip.background = ggplot2::element_rect(fill = bg, colour = NA))
  out
}

# The colour a plot is drawn on, which is white unless the theme says
# otherwise -- and white again where the medium is print, whatever the theme
# says, since a tinted ground costs ink and is often not reproduced.
ag_ground_fill <- function(){
  medium_background() %||% getOption("snet_background", default = "#FFFFFF")
}

`%||%` <- function(x, y) if(is.null(x)) y else x

# Every ag_theme_*() wrapper wants the same two things of its base theme: the
# theme's typeface, and a text size scaled to the medium the plot is made for.
# Building them from one factory means neither has to be remembered at each of
# the several dozen call sites, and a caller that gives its own base_size --
# a small inset, say -- still has it scaled rather than overridden.
ag_themer <- function(fun){
  function(...){
    args <- list(...)
    if(is.null(args$base_family)) args$base_family <- ag_font()
    if(is.null(args$base_size)) args$base_size <- 11
    args$base_size <- args$base_size * ag_size()
    ag_ground(do.call(fun, args))
  }
}

ag_theme_minimal <- ag_themer(ggplot2::theme_minimal)

ag_theme_classic <- ag_themer(ggplot2::theme_classic)

ag_theme_grey <- ag_themer(ggplot2::theme_grey)

ag_theme_bw <- ag_themer(ggplot2::theme_bw)

ag_theme_void <- ag_themer(ggplot2::theme_void)

Try the autograph package in your browser

Any scripts or data that you put into this service are public.

autograph documentation built on Nov. 16, 2026, 5:08 p.m.