What is this?

A few years back I chanced upon studyspo tumblr, a place where the drudgery of note-taking is celebrated as an art form (or at least that’s my interpretation). Here, I hope to collect similar findings in the realm of inspirational documentation for programming languages and frameworks.

I’m not yet sure who the target audience is for this (aside from yours truly), or if this document will hold any meaning unto itself. But, for now, I quite literally need a place to keep my notes.

JavaScript

JavaScript

// Two slashes start single-line comments

var x;  // declaring a variable

x = 3 + y;  // assigning a value to the variable `x`

foo(x, y);  // calling function `foo` with parameters `x` and `y`
obj.bar(3);  // calling method `bar` of object `obj`

// A conditional statement
if (x === 0) {  // Is `x` equal to zero?
    x = 123;
}

// Defining function `baz` with parameters `a` and `b`
function baz(a, b) {
    return a + b;
}

ReactJS

Getting Started

The structure is everything! There may not be list agreement, but the options at the top of React’s “Getting Started” (React Contributors 2021), as seen in Figure 1, are pretty darn good: try React, learn React, staying informed, versioned documentation, something missing.

Maybe I’d kill off “something missing” (from that header menu, not get rid of it on the whole), but it’s concise and gives the primary things someone would be looking for in getting-started-style documentation.

In Learn React they expressly break things down again:

• If you prefer to learn by doing, start with our practical tutorial.
  
• If you prefer to learn concepts step by step, start with our guide to main concepts.

You also have the sidebar navigation showing you the other sections, some of which might be what someone was actually looking for when they went to the getting-started page (e.g. add React to a website, create a new React app). I also like the wording of “Main Concepts” (and how prominent it is in the menu)—most people aren’t trying to learn all the things, and it lets you know that this subset probably holds the key concepts you need to get going.

Adventures with {highcharter} and the Highcharts accessibility module

CSS Grid: Power and responsibility

A quick reminder as to how we got here: Quarto’s HTML theming is powered by Bootstrap—specifically, Bootstrap 5.3 with CSS Grid enabled. Quarto has plenty of built-in article-layout and page-layout features, but, for page-layout: custom you’d want to get to know CSS Grid a bit better.

I should note, I think CSS Grid is great, and I’ve had a blast playing around with it in Quarto (e.g. in my Quarto page-layout demo)! It also has a lot of really great documentation and guides, such as A Complete Guide to Grid (House 2023), which makes it all the more fun to learn about. And, because Grid is a tool for responsive design, it can be used to enhance accessibility across devices.

Accessibility is a huge topic, and CSS Grid is by no means immune to the challenges inherent in it. The aforementioned A11y Project and the W3C Web Accessibility Initiative are two great places for finding general resources—Developing for Web Accessibility - Tips for Getting Started (White, Abou-Zahra, and Henry 2019) is a good starting point if this is new to you. There are two broad areas, though, where Grid (if not wielded properly) can yield accessibility problems: content re-ordering, and “markup flattening.”

The accessibility tree

Understanding the big picture (e.g. how assistive technologies¹ interact with web content) makes inclusive, accessible development much easier. I strongly recommend reading these brief background appendices from The Accessibility Object Model (AOM) - Explainer (Boxhall et al. 2021):

The appendices, above, are the source of the notes and figures that follow in this section.

Assistive technologies interact with web pages and applications through platform-specific accessibility APIs that expose a tree of objects referred to as the accessibility tree.

In web browsers, the structure and content of a web page’s markup is represented by a Document Object Model (DOM) tree (MDN Contributors 2021b). The DOM tree is, then, translated into both the visual representation (what you see in the browser), and the accessibility tree, which can be accessed by platform-specific accessibility APIs, which bring the information to the user via assistive technologies.

Each node of the accessibility tree (referred to as an accessibility node) has a role², which indicates its semantic purpose. Native HTML elements are implicitly mapped to accessibility notes with their semantic roles—e.g. an <img> element becomes an accessibility node with the role of “image”.

Some nodes have a grouping role, helping users to meaningfully navigate the page. Others, such as <summary>, have a state (in the case of <summary>, collapsed or expanded). For more on Accessible Rich Internet Application (ARIA) role types, see the Mozilla Developer Network (MDN) Using ARIA: Roles, states, and properties.

For more formal definitions of the accessibility tree see:

• Accessibility tree (MDN Contributors 2021c) in the MDN Web Docs Glossary, and

• The Accessibility Tree (Kearney, Gash, and Boxhall 2020) from Google Dev Web Fundamentals.

I also recommend How accessibility trees inform assistive tech by accessibility expert, Hidde de Vries (de Vries 2019).

Preface

I am not a front-end engineer. Sure, I know how to hackily make a few adjustments to a CSS file—I’ve lived through enough web scraping to learn a little about selectors—but things like Gulp and Grunt just sound like Babel to me.¹

What I do know about front-end development always comes as a result of falling down a rabbit hole. There’s something I want to customize, one link leads to another, and suddenly I’m trying to grok larger concepts that I won’t be putting to use on the regular—which is why I’m taking notes!

In this instance, I was reading up on Quarto (Allaire and Dervieux 2024), which led to docs on Quarto’s HTML Theming (and “More About Quarto Themes”), which somehow got me elbow-deep in the Sass lang documentation, trying to get a handle on how Bootswatch themes modify the underlying Bootstrap framework.

Before/if you proceed, keep these things in mind:

Sass-i-ness

Sass (Lintorn-Catlin et al. 2021) bills itself as CSS with superpowers, and I’m inclined to believe it. Actually, some of these superpowers (namely “at-rules”) are built right into CSS these days.²

If you’ve read the Quarto-theme docs, you might be wondering why I’m going on about Sass when all of the files for customization end in .scss. Apparently Sass supports two syntaxes: SCSS (the files for which end in .scss), and “the indented syntax” (which uses the file extension .sass). Both .scss and .sass files are “Sass stylesheets”—so, just run with it.

Quarto themes are SCSS text files that use “decorators” (special comments) to denote the “type” (in a non-technical sense of the word) of SCSS thing going on in that area. The regions are: uses, functions, defaults, mixins, and rules, each of which gets a decorator that follows the format /*-- scss:TYPE --*/ (where TYPE is, e.g. functions, or rules).

Expand the code below to see an example of a Quarto theme with region decorators:

SCSS

/*-- scss:functions --*/
@function colorToRGB ($color) {
  @return "rgb(" + red($color) + ", " + green($color) + ", " + blue($color)+ ")";
}

/*-- scss:defaults --*/
$h2-font-size:          1.6rem !default;
$headings-font-weight:  500 !default;
$body-color:            $gray-700 !default;

/*-- scss:rules --*/
h1, h2, h3, h4, h5, h6 {
  text-shadow: -1px -1px 0 rgba(0, 0, 0, .3);
}

You might not need a sass:uses region (which wasn’t a thing when I first wrote this post in January of 2022, so I used @import instead — they both let you load other “modules”/stylesheets). Sass requires that the @use rule must come before any other rules in the stylesheet, which is why this section of your theme has to come first. If you put @use elsewhere in your theme, it will error out with:

Terminal

# @use rules must be written before any other rules.

The defaults section is made up of default values for Sass variables (not to be confused with CSS variables). You can tell you’re reading the name of a Sass variable if it starts with a $. You can tell a default is being set when the value ends in !default. Sass style rules are basically the same as CSS rulesets: elements are chosen with selectors, and then styled with property declarations (i.e. how elements that match the selector are styled).

Functions are defined with the @function at-rule, and take arguments (just like R functions). For example, Bootstrap has the following Sass functions, tint-color() and shade-color(), that lighten or darken colors by a given amount.

SCSS

// Tint a color: mix a color with white
@function tint-color($color, $weight) {
  @return mix(white, $color, $weight);
}

// Shade a color: mix a color with black
@function shade-color($color, $weight) {
  @return mix(black, $color, $weight);
}

I go into more detail about Sass mixins later on in these notes.

All this Sass stuff can work independent of Bootstrap innards. The Quarto Sass variables can be specified within an SCSS file.

Bootstrap

Bootstrap is a front-end open source “toolkit.” Lifting straight from the Quarto-theme docs here:

Bootstrap defines over 1,400 variables that control fonts, colors, padding, borders, and much more.

You can see the raw Bootstrap Sass variables in Bootstrap’s _variables.scss file.

Bootstrap can be used to design full-blown user interfaces. Since this is well beyond the scope of what I want to do, I use the Bootstrap docs in an ad hoc manner. If I find myself wanting to tinker with something—say, typography or text alignment—I go to the Bootstrap reference before I bother to implement something on my own. Chances are, they’ve already got it covered—actually, Quarto probably has its own user-friendly layer of abstraction over it, so maybe go to the Quarto docs then Bootstrap.

Other useful tidbits

Markdown

::: {#hello .greeting"}
Hello **world**!
:::

HTML

<div id="hello" class="greeting">
  Hello world!
</div>

Markdown

::: {style="color: red; border: solid black;"}
Goodbye, world.
:::

HTML

<div style="color: red; border: solid black;">
  Goodbye, world.
</div>

SCSS

$font-size-base:              1rem; // Assumes the browser default, typically `16px`
$font-size-sm:                $font-size-base * .875;
$font-size-lg:                $font-size-base * 1.25;

SCSS

// CSS defines one inch as 96 pixels.
@debug 1in + 6px; // 102px or 1.0625in

@debug 1in + 1em;
//     ^^^^^^^^
// Error: Incompatible units em and in.

SCSS

@mixin reset-list {
  margin: 0;
  padding: 0;
  list-style: none;
}

nav ul {
  @include horizontal-list;
}

CSS

nav ul {
  margin: 0;
  padding: 0;
  list-style: none;
}

SCSS

@mixin name(<arguments...>) { ... }

CSS Grid

For article and page layout, Quarto uses Bootstrap 5’s alternate layout system, CSS Grid. Though the feature is opt-in by default for Bootstrap (as of Bootstrap v5.1.0), it’s turned on by default in Quarto (i.e. $enable-cssgrid: true).

CSS grid is an incredibly powerful layout system, and there’s more than enough to get you started in the Bootstrap docs linked to above. A Complete Guide to CSS Grid (House 2023) on CSS Tricks is also an excellent resource.

Chances are, you’ll be making use of Quarto’s built-in layouts (which I’ve put to use on this Quarto page-layout demo here). However, should you decide to define your own “tracks” (rows and columns), there’s an abundance of options and units. As with rems in typography, CSS-layout units have also evolved to accommodate a variety of devices more easily.

New to me was the flex fraction or fr unit, “which represents a fraction of the leftover space in the grid container” (Brufau et al. 2020). Flex fractions (frs) are particularly useful in consort with the CSS grid-template-* properties: grid-template-columns, and grid-template-rows. Mastery Games’ CSS Grid Track Options provides a helpful overview of the various units relevant to defining your grid layout.

Another neat feature is that you can name the lines of your grid when defining it with grid-template-rows and grid-template-columns. This is helpful as you can then reference these named lines when placing items in your grid using the grid-row- and grid-column- start and end properties.

NotePro Tip

Your browser’s built-in developer tools are a great way to learn more about CSS grid. If you inspect a page’s HTML, grid elements will have a little grid pill button next to them which you can click to toggle a grid overlay display. The Layout pane gives you more options, such as showing grid-line or area names, and has a listing of all of the grid overlays on the page.

For more details on viewing the grid with browser developer tools for Chrome (or Chromium-based browsers), check out Inspect CSS Grid (Yeen 2021). For Firefox, see CSS Grid Inspector: Examine grid layouts (MDN Contributors 2021a).

Learn like an a11y

If, like me, you’ve sort of stumbled into learning more about CSS, be sure to take the time to zoom back out and read up a bit on best practices, especially when it comes to accessibility. Quarto and Bootstrap are both built with accessibility in mind, but if you’re tweaking things on your own, there are some quick things worth checking for to ensure you haven’t borked said accessibility efforts. Writing CSS with Accessibility in Mind (Matuzović 2017a) isn’t the newest article on the matter, but I found it concise and helpful—plus, it gives you many more resources to explore.⁴ Also worth peeping Writing HTML with Accessibility in Mind while you’re in the neighborhood (Matuzović 2017b).

Since there was so much to learn from these resources, I’ve continued my notes in a second post, CSS Grid and accessibility.

Summary stats

Let’s peep a quick summary of the data using skimr::skim().

skimr::skim(read_2021)

Books over time

So, having fixed those entries with missing date_read manually, let’s take a peek at what my reading looked like over the course of the year.

View code

read_2021_rev |> 
  ggplot(aes(x = date_read, y = cumsum(read_count))) +
  geom_line() +
  scale_x_date(NULL,
               breaks = scales::date_breaks(width = "1 month"),
               labels = scales::label_date_short()) +
  labs(
    title = "Sum of books Mara read over the course of 2021",
    alt = "With x-axis range from January 2021 to January 2022, shows relatively steady increase in cumulative sum of books read over time (from zero to ~200, where y-max = 188).",
    x = "Time",
    y = "Total books read"
  ) +
  hrbrthemes::theme_ipsum_rc()

Not particularly riveting. It’s a pretty steady climb, and I think the slope increases mainly where I went on series benders (e.g. the Parker books at the end of the summer), and also after the Batpig died in November (I read when I’m sad).

What about for pages?

View code

read_2021_rev |> 
  mutate(number_of_pages = replace_na(number_of_pages, 0)) |> 
  mutate(total_pages = cumsum(number_of_pages)) |> 
  ggplot(aes(x = date_read, y = total_pages)) +
  geom_line() +
  scale_x_date(NULL,
               breaks = scales::date_breaks(width = "1 month"),
               labels = scales::label_date_short()) +
  scale_y_continuous(labels = scales::label_comma()) +
  labs(
    title = "Sum of pages Mara read over the course of 2021",
    alt = "With x-axis range from January 2021 to January 2022, shows relatively steady increase in cumulative sum of pages read over time (from zero to ~60000, where y-max = 59390).",
    x = "Time",
    y = "Total pages read"
  ) +
  hrbrthemes::theme_ipsum_rc()

Still looks like a steady climb. Translation: Nothing much to see here.

The books

Keeping in mind that just because I read a book doesn’t mean I recommend it (I have a thing about finishing books—that “thing” being that I have to do it), here’s a little widget of what I read in the year 2021 Anno Domini.

.dotfiles 101

Dotfiles (so named because they usually start with a .) are plain-text configuration files that store your settings for various programs on your computer. For example, your Git settings/credentials are probably stored in a .gitconfig file. If you’ve never seen such a thing, that’s probably because they’re hidden by default on Unix-based systems. If that’s you (which is totally fine), you might want to check out a quick primer on viewing/creating dotfiles, e.g. What is a Dotfile and How to Create it in Mac and Linux (Lemonaki 2021), before continuing here.

It’s pretty safe to say that the general consensus is that it’s worth managing your dotfiles with version control somehow, there are a range of opinions when it comes to the mechanics of dotfile management (see the Tools section of Awesome dotfiles). I tried all the tools out there, so I can’t really pass judgement. Prior to yadm, I was using GNU Stow, which takes a “symlinking” approach to dotfile management—essentially, you hoodwink your computer into thinking all your dotfiles are stored in a single directory. If Stow or symlinks were inherently bad, no one would use them (which isn’t the case). That said, I happen to like yadm’s approach a bit better.

yadm

There’s no way I’m going to outdo yadm’s own overview, so I’m not even going to try:

If you know how to use Git, you already know how to use yadm. yadm helps you maintain a single repository of dotfiles, while keeping them where they belong—in $HOME.

That’s right, with yadm, your dotfiles can stay where they are! You’ll point them out to yadm (once you’ve installed it), and BOOM you’re keeping track of them (OK, there are a couple of other set-up steps, but it’s still pretty amazing).

How you install yadm depends on your operating system. I’m on a Mac (and a die-hard Homebrew fan), so I installed it with:

Terminal

brew install yadm

If you’re embarking on this journey, you should probably just follow yadm’s Getting Started (much of which I’ll regurgitate here, but I can’t promise it’ll be the latest and greatest). The gist of it is as follows: you’ll start out by initializing yadm in an empty local repo¹ with yadm init.

To add a file, you’re going to use yadm add <file> with the full path to the file (you’re not moving your dotfiles anywhere—yadm doesn’t need a directory, just a repository). For example, here is how I added .zshrc:

Terminal

yadm add ~/.zshrc

The file doesn’t have to be right in your home directory (though that’s where most dotfiles reside). If I wanted to add my RStudio-preferences JSON file, for example, I’d write:

Terminal

yadm add ~/.config/rstudio/rstudio-prefs.json

Since yadm wraps Git, the subsequent steps won’t be surprising. You’ll want to: commit your changes, add a remote, and push your local repo to said remote:

Terminal

# commit changes
yadm commit -m "Message if I want to write one."

# add remote named origin
yadm remote add origin <url>

# push your changes to main branch of remote
yadm push -u origin main

If you peek at yadm’s Common Commands, you’ll see lots of familiar Git commands. The one with the most surprising output coming from Git is probably yadm status, since yadm kind of flips Git’s default ignoring behaviour on its head by ignoring untracked files (i.e. any file that hasn’t explicitly been added won’t show up). Like Git, though, yadm status will let you know if you’ve got any changes to the files you are tracking.

You can print a list of all the files managed by yadm from anywhere with yadm list -a. My results look something like the following (I’ve commented the output out):

Terminal

yadm list -a
# .Renviron
# .Rprofile
# .gitconfig
# .gitignore
# .you-get-the-idea

All the annotations

Our {palmerpenguins} plot had a single annotation, which was recorded in the “Chart annotations summary” of the screen-reader section as an item in an unordered list.¹

The chart we’re re-creating here (which plots elevation and distance of the 2017 Tour de France) has lots of annotations. We want these annotations to show up in the screen-reader section with the text itself and information about where it is on the chart (in terms and distance and elevation).

Up until now, we’ve been using elements of the Highcharts JavaScript API that are configured inside of Highcharts.chart({...});. For example, when we specify the valueSuffix for a tooltip using hc_tooltip(), we are referencing tooltip.valueSuffix, which is defined inside of Highcharts.chart({});.

However, there are some options that are defined outside of the chart object. These are set with Highcharts.setOptions({...});, and are divided up into global and lang. As it turns out, configuring accessibility strings takes place in lang.accessibility.

library(tidyverse)
url <- "https://gist.githubusercontent.com/batpigandme/1916d95323ddb29274bddf3316041fd3/raw/a8f394cb85b4ae995798c2596ffe912491d2fb7c/2017-tour-de-france-stage-8.csv"
tdf_data <- read_csv(url) |>
  drop_na() # have some from data export

JavaScript

    lang: {
        accessibility: {
            screenReaderSection: {
                annotations: {
                    descriptionNoPoints: '{annotationText}, at distance {annotation.options.point.x}km, elevation {annotation.options.point.y} meters.'
                }
            }
        }
    }

library(highcharter)

options(
  highcharter.lang = list(
    accessibility = list(
      screenReaderSection = list(
        annotations = list(
          descriptionNoPoints = '{annotationText}, at distance {annotation.options.point.x}km, elevation {annotation.options.point.y} meters.'
        )
      )
    )
  )
)

highchart() |>
  hc_add_dependency(name = "modules/accessibility.js") |>
  hc_add_dependency(name = "modules/annotations.js") |>
  hc_add_dependency(name = "modules/exporting.js") |>
  hc_add_dependency(name = "modules/export-data.js") |>
  hc_add_series(tdf_data, "area", hcaes(x = Distance, y = Elevation),
                lineColor = "#434348",
                color = "#90ed7d",
                fillOpacity = 0.5,
                marker = list(enabled = FALSE)) |>
  hc_xAxis(
    title = list(text = "Distance"),
    labels = list(format = "{value} km"),
    minRange = 5,
    accessibility = list(
      rangeDescription = "Range: 0 to 187.8 km."
    )
  ) |>
  hc_yAxis(
    title = list(text = ""),
    labels = list(format = "{value} m"),
    startOnTick = TRUE,
    endOnTick = FALSE,
    maxPadding = 0.35,
    accessibility = list(
      description = "Elevation",
      rangeDescription = "Range: 0 to 1,553 meters"
    )
  ) |>
  hc_title(text = "2017 Tour de France Stage 8: Dole - Station des Rousses") |>
  hc_caption(text = "An annotated line chart illustrates the 8th stage of the 2017 Tour de France cycling race from the start point in Dole to the finish line at Station des Rousses. Altitude is plotted on the Y-axis, and distance is plotted on the X-axis. The line graph is interactive, and the user can trace the altitude level along the stage. The graph is shaded below the data line to visualize the mountainous altitudes encountered on the 187.5-kilometre stage. The three largest climbs are highlighted at Col de la Joux, Côte de Viry and the final 11.7-kilometer, 6.4% gradient climb to Montée de la Combe de Laisia Les Molunes which peaks at 1200 meters above sea level. The stage passes through the villages of Arbois, Montrond, Bonlieu, Chassal and Saint-Claude along the route.") |>
  # begin annotations
  # note that the points are grouped into separate lists
  # so that they can be styled in those groups
  hc_annotations(
    list(
      labelOptions = list(
        backgroundColor = 'rgba(255,255,255,0.6)',
        verticalAlign = 'top',
        y = 15
      ),
      labels = list(
        list(
          point = list(xAxis = 0, yAxis = 0, x = 27.98, y = 255),
          text = "Arbois"
        ),
        list(
          point = list(xAxis = 0, yAxis = 0, x = 45.5, y = 611),
          text = "Montrond"
        ),
        list(
          point = list(xAxis = 0, yAxis = 0, x = 63, y = 651),
          text = "Mont-sur-Monnet"
        ),
        list(
          point = list(xAxis = 0, yAxis = 0, x = 84, y = 789),
          x = -10,
          text = "Bonlieu"
        ),
        list(
          point = list(xAxis = 0, yAxis = 0, x = 129.5, y = 382),
          text = "Chassal"
        ),
        list(
          point = list(xAxis = 0, yAxis = 0, x = 159, y = 443),
          text = "Saint-Claude"
        )
      )
    ),
    list(
      labels = list(
        list(
          point = list(xAxis = 0, yAxis = 0, x = 101.44, y = 1026),
          x = -30,
          text = "Col de la Joux"
        ),
        list(
          point = list(xAxis = 0, yAxis = 0, x = 138.5, y = 748),
          text = "Côte de Viry"
        ),
        list(
          point = list(xAxis = 0, yAxis = 0, x = 176.4, y = 1202),
          text = "Montée de la Combe <br>de Laisia Les Molunes"
        )
      )
    ),
    list(
      labelOptions = list(
        shape = "connector",
        align = "right",
        justify = FALSE,
        crop = TRUE,
        style = list(
          fontSize = "0.8em",
          textOutline = "1px white"
        )
      ),
      labels = list(
        list(
          point = list(xAxis = 0, yAxis = 0, x = 96.2, y = 783),
          text = "6.1 km climb <br>4.6% on avg."
        ),
        list(
          point = list(xAxis = 0, yAxis = 0, x = 134.5, y = 540),
          text = "7.6 km climb <br>5.2% on avg."
        ),
        list(
          point = list(xAxis = 0, yAxis = 0, x = 172.2, y = 925),
          text = "11.7 km climb <br>6.4% on avg."
        )
      )
    )
  ) |>
  hc_tooltip(
    headerFormat = "Distance: {point.x:.1f} km<br>",
    pointFormat = "{point.y} m a. s. l.",
    shared = TRUE
  ) |>
  hc_legend(enabled = FALSE) |>
  hc_exporting(
    enabled = TRUE,
    accessibility = list(
      enabled = TRUE
    )
  ) |>
  hc_plotOptions(
    accessibility = list(
      enabled = TRUE,
      keyboardNavigation = list(enabled = TRUE),
      linkedDescription = 'This line chart uses the Highcharts Annotations feature to place labels at various points of interest. 
The labels are responsive and will be hidden to avoid overlap on small screens. 
Image description: An annotated line chart illustrates the 8th stage of the 2017 Tour de France cycling race from the start point in Dole to the finish line at Station des Rousses. 
Altitude is plotted on the Y-axis, and distance is plotted on the X-axis. 
The line graph is interactive, and the user can trace the altitude level along the stage. 
The graph is shaded below the data line to visualize the mountainous altitudes encountered on the 187.5-kilometre stage. The three largest climbs are highlighted at Col de la Joux, Côte de Viry and the final 11.7-kilometer, 6.4% gradient climb to Montée de la Combe de Laisia Les Molunes which peaks at 1200 meters above sea level. 
The stage passes through the villages of Arbois, Montrond, Bonlieu, Chassal and Saint-Claude along the route.',
      landmarkVerbosity = "one"
    ),
    area = list(
      accessibility = list(
        description = "This line chart uses the Highcharts Annotations feature to place labels at various points of interest. The labels are responsive and will be hidden to avoid overlap on small screens. Image description: An annotated line chart illustrates the 8th stage of the 2017 Tour de France cycling race from the start point in Dole to the finish line at Station des Rousses. Altitude is plotted on the Y-axis, and distance is plotted on the X-axis. The line graph is interactive, and the user can trace the altitude level along the stage. The graph is shaded below the data line to visualize the mountainous altitudes encountered on the 187.5-kilometre stage. The three largest climbs are highlighted at Col de la Joux, Côte de Viry and the final 11.7-kilometer, 6.4% gradient climb to Montée de la Combe de Laisia Les Molunes which peaks at 1200 meters above sea level. The stage passes through the villages of Arbois, Montrond, Bonlieu, Chassal and Saint-Claude along the route."
      )
    )
  )

HTML

<div>
"Chart annotations summary"
<ul style="list-style-type: none">
  <li>Arbois, at distance 27.98km, elevation 255 meters.</li>
  <li>Montrond, at distance 45.5km, elevation 611 meters.</li>
  ...
</ul>
</div>

An accessible penguin plot

First thing’s first, we’ll need both packages loaded in order to get plotting.

library(highcharter)
library(palmerpenguins)

In addition to the ones we’ve used in previous posts (accessibility, export, and export-data), we’ll also attach Highcharts’ annotations module. In the alt-text for Silvia’s initial version of this chart (which is what I’ll use for our caption), she mentioned a specific observation—so, we’ll annotate that point in our re-creation.

The original also specified colours, and we’ll do the same. However, as I note in comments in the code, we’ll do this outside of aesthetic specifications to avoid losing the dual encoding with shapes that Highcharts gives you by default.

highchart() |>
  hc_add_dependency(name = "modules/accessibility.js") |>
  hc_add_dependency(name = "modules/annotations.js") |>
  hc_add_dependency(name = "modules/exporting.js") |>
  hc_add_dependency(name = "modules/export-data.js") |>
  hc_add_series(
    penguins, 
    "scatter", 
    hcaes(x = flipper_length_mm,
          y = bill_length_mm,
          group = species)
  ) |>
  # n.b. by not adding color above, you get "automatic" dual encoding
  # of points with a different shape for the markers for each species
  hc_xAxis(
    title = list(text = "Flipper length (mm)"),
    accessibility = list(
      enabled = TRUE,
      description = "flipper length in millimeters"
    )
  ) |>
  hc_yAxis(
    title = list(text = "Bill length (mm)"),
    accessibility = list(
      enabled = TRUE,
      description = "bill length in millimeters"
    )
  ) |>
  hc_title(
    text = "Flipper length vs. bill length in <b>{palmerpenguins}</b>",
    style = list(useHTML = TRUE)
           ) |>
  hc_subtitle(
    text = "Grouped by species: Adelie, Chinstrap, and Gentoo"
    ) |>
  hc_annotations(
    list(
      labels = list(
        list(
          point = list(x = 201, y = 54.2, xAxis = 0, yAxis = 0),
          text = "Chinstrap<br/>x: {x}<br/>y: {y}",
          shape = "connector" # defaults to 'callout'
        )
      ),
      # below gives you screen-reader descriptions of annotations
      labelOptions = list(
        accessibility = list(
          # wouldn't hard code description here if there was
          # more than one point annotated, need lang options
          description = "A Chinstrap penguin observation mapping to a flipper length of 201mm and bill length of 54.2mm."
      )
    )
  )
  )|>
  hc_caption(text = "Scatterplot of the palmerpenguins dataset showing data points clustered by species (Adelie, Chinstrap, and Gentoo) using the highcharter package making it possible to focus on one cluster and identify the x and y values of a specific data point. In this case the data point is a Chinstrap penguin observation mapping to a flipper length of 201mm and bill length of 54.2mm.") |>
  hc_exporting(
    enabled = TRUE,
    accessibility = list(
      enabled = TRUE
    )
  ) |>
  hc_plotOptions(
    accessibility = list(
      enabled = TRUE,
      keyboardNavigation = list(enabled = TRUE)
    )
  ) |>
  # use the custom colors and keep shape per group if added here
  hc_colors(c("darkorange", "purple", "#057276"))

Looking at the code for this chart, you may be wondering if I lost control of the keyboard when writing the descriptions of the axes, since I didn’t capitalize their first letters. Fear not! It was intentional—I wanted the text to look right in something I’ve mentioned, but not gone through in detail: the screenReaderSection.

HTML

<div id="highcharts-screen-reader-region-before-0" 
aria-label="Chart screen reader information." role="region" 
aria-hidden="false" style="position: relative;"></div>

HTML

<{headingTagName}>{chartTitle}</{headingTagName}><div>{typeDescription}</div>
<div>{chartSubtitle}</div><div>{chartLongdesc}</div><div>{playAsSoundButton}</div>
<div>{viewTableButton}</div>
<div>{xAxisDescription}</div><div>{yAxisDescription}</div>
<div>{annotationsTitle}{annotationsList}</div>

HTML

<p>Flipper length vs. bill length in {palmerpenguins}</p>
<div>Scatter chart with 3 data series.</div>
<div>Grouped by species: Adelie, Chinstrap, and Gentoo</div>

HTML

<div>The chart has 1 X axis displaying flipper length in millimeters. Range: 171.41 to 231.59.</div>
<div>The chart has 1 Y axis displaying bill length in millimeters. Range: 30 to 70.</div>

HTML

<li>A Chinstrap penguin observation mapping to a flipper length of 201mm and bill length of 54.2mm.</li>

Accessible pie chart

Highcharts’ accessible pie chart isn’t what I’d call “easy on the eyes.” Heck, they even added an option to turn the pattern fills off (a feat that I do not accomplish below).

library(highcharter)
highchart() |>
  # add dependencies
  hc_add_dependency(name = "modules/exporting.js") |>
  hc_add_dependency(name = "modules/export-data.js") |>
  hc_add_dependency(name = "modules/accessibility.js") |>
  hc_add_dependency(name = "modules/pattern-fill.js") |>
  hc_tooltip(
    valueSuffix = "%",
    borderColor = "#8ae"
  ) |>
  hc_title(text = "Primary desktop/laptop screen readers") |>
  hc_subtitle(text = "Source: WebAIM.") |>
  hc_caption(text = "Pie chart demonstrating some accessibility features of Highcharts. The chart shows which screen reader is used as the primary screen reader by the respondents, with NVDA currently being the most popular one. The JAWS screen reader is following closely behind.") |>
  hc_exporting(
    enabled = TRUE,
    accessibility = list(
      enabled = TRUE
    )
  ) |>
  hc_add_series(
    type = "pie",
    name = "Screen reader usage",
    data = list(
      list(
        name = "NVDA",
        y = 40.6,
        color = list(
          pattern = list(
            path = "M 0 0 L 5 5 M 4.5 -0.5 L 5.5 0.5 M -0.5 4.5 L 0.5 5.5",
            color =  "#0b7383",
            width = 5,
            height = 5,
            patternTransform =  "scale(1.4 1.4)"
          )
        )
      ),
      list(
        name = "JAWS",
        y = 40.1,
        color = list(
          pattern = list(
            path = "M 0 5 L 5 0 M -0.5 0.5 L 0.5 -0.5 M 4.5 5.5 L 5.5 4.5",
            color = "#4372da",
            width = 5,
            height = 5,
            patternTransform = "scale(1.4 1.4)"
          )
        )
      ),
      list(
        name = "VoiceOver",
        y = 12.9,
        color = list(
          pattern = list(
            path = "M 2 0 L 2 5 M 4 0 L 4 5",
            color = "#6B26F0",
            width = 5,
            height = 5,
            patternTransform = "scale(1.4 1.4)"
          )
        )
      ),
      list(
        name = "ZoomText",
        y = 2,
        color = list(
          pattern = list(
            path = "M 0 2 L 5 2 M 0 4 L 5 4",
            color = "#222",
            width = 5,
            height = 5,
            patternTransform = "scale(1.4 1.4)"
          )
        )
      ),
      list(
        name = "Other",
        y = 4.4,
        color = list(
          pattern = list(
            path = "M 0 1.5 L 2.5 1.5 L 2.5 0 M 2.5 5 L 2.5 3.5 L 5 3.5",
            color = "#D42D1A",
            width = 5,
            height = 5,
            patternTransform = "scale(1.4 1.4)"
          )
        )
      )
    )
  ) |>
  hc_plotOptions(
    series = list(
      dataLabels = list(
        enabled = TRUE,
        connectorColor = "#777",
        format = "<b>{point.name}</b>: {point.percentage:.1f} %"
      ),
      cursor = "pointer",
      borderWidth = 3
    ),
    accessibility = list(
      enabled = TRUE,
      keyboardNavigation = list(enabled = TRUE)
    )
  )

As with the first version of the accessible line chart in part 2 of this series, the code here doesn’t look terribly R-like (in fact, we’re not using a data-frame object at all). The reason is the same, too: in order to get the dual encoding (in this case, colour + pattern), each item was defined individually.

The code above is very much reflects the fact that I reverse engineered this chart from the original version, which combined the indexed pattern definitions from the Highcharts pattern fill module with colours (see un-run JavaScript code below).

JavaScript

var clrs = Highcharts.getOptions().colors;
var pieColors = [clrs[2], clrs[0], clrs[3], clrs[1], clrs[4]];
// Get a default pattern, but using the pieColors above.
// The i-argument refers to which default pattern to use
function getPattern(i) {
    return {
        pattern: Highcharts.merge(Highcharts.patterns[i], {
            color: pieColors[i]
        })
    };
}
// Get 5 patterns
var patterns = [0, 1, 2, 3, 4].map(getPattern);

I imagine there’s a way to reference the patternIndex from the R code, but I wasn’t able to figure it out. I actually ran the JavaScript in my console to get the color/pattern definitions (e.g. Highcharts.patterns[0]) used for each item in the series.

Laying the groundwork

Before you make a chart, you need data! Since the original version of the visualization uses the Highcharts export module, I was able to simply export the data as a CSV (which I then stashed in a Gist), and read the data back in using readr::read_csv().

suppressPackageStartupMessages(library(tidyverse))
library(highcharter)

# read in the data
url <- "https://gist.githubusercontent.com/batpigandme/aeb30566f899cdcdeb6024c0344d1ae1/raw/9cbafbbc99311c04b1a675e0ebb3953692fd51b8/pop-screenreaders.csv"
raw_dat <- read_csv(url)

Without any modification, this is what the data (which I name raw_dat) looks like:

Line chart: original edition

Though this data isn’t “tidy” (more on that later), the format lends itself to a solid re-creation of the original version. So, all I did in terms of cleanup was remove the periods from the abbreviated months, and convert Category into an ordered factor.

# turn Category into ordered factor and remove inconsistent period
sr_dat1 <- raw_dat |> 
  mutate(Category = str_replace_all(Category, "\\.", "")) |> 
  mutate(Category = as_factor(Category))

Because I was following the {highcharter} Modules & plugins vignette (particularly the one on using pattern fills), I made this chart in two parts: first setting up a base chart without the data, and then adding the data to it. I’m not sure this was necessary or helpful, but, since I didn’t take that approach with the other charts in this series, I’ll keep it here for variety’s sake.

I add the dependency modules first, though it works fine if you add them at the end too. If not for the JavaScript code, I wouldn’t have known that there was actually a series-label module to add, in addition to our export, export-data, and accessibility modules.

You’ll also notice that I seem to (and do) add the same text twice. I have yet to get the linkedDescription accessibility option to work correctly. However, it’s supposed to appear in a special, hidden div especially for screen readers that appears before the chart, along with much of the other metadata you see below.²

hc_sr_setup <- highchart() |> 
  # add dependencies
  hc_add_dependency(name = "modules/series-label.js") |> 
  hc_add_dependency(name = "modules/accessibility.js") |> 
  hc_add_dependency(name = "modules/exporting.js") |> 
  hc_add_dependency(name = "modules/export-data.js") |> 
  hc_chart(
    type = "spline",
    accessibility = list(
        enabled = TRUE,
        keyboardNavigation = list(enabled = TRUE),
        linkedDescription = "Line chart demonstrating some accessibility features of Highcharts. 
      The chart displays the most commonly used screen readers in surveys taken by WebAIM from December 2010 to September 2019. 
      JAWS was the most used screen reader until 2019, when NVDA took over.
      VoiceOver is the third most used screen reader, followed by Narrator.
      ZoomText/Fusion had a surge in 2015, but usage is otherwise low.
      The overall use of other screen readers has declined drastically the past few years."
      ),
    dateTimeLabelFormats = list(
      month = list(main = "%b %Y")
    )
    ) |> 
  hc_title(text = "Most common desktop screen readers") |> 
  hc_subtitle(text = "Source: WebAIM.") |> 
  hc_caption(text = "Line chart demonstrating some accessibility features of Highcharts. The chart displays the most commonly used screen readers in surveys taken by WebAIM from December 2010 to September 2019. JAWS was the most used screen reader until 2019, when NVDA took over. VoiceOver is the third most used screen reader, followed by Narrator. ZoomText/Fusion had a surge in 2015, but usage is otherwise low. The overall use of other screen readers has declined drastically the past few years.") |> 
  hc_xAxis(categories = sr_dat1$Category,
           title = list(text = "Time"),
           accesibility = list(
             enabled = TRUE,
             description = "Time from December 2010 to September 2019",
             range = "December 2010 to September 2019"
             )
  ) |> 
  hc_yAxis(
    title = list(text = "Percentage usage"),
    accessibility = list(description = "Percentage usage")
  ) |>
  hc_legend(symbolWidth = 40) |>
  hc_plotOptions(
    spline = list(
      accessibility = list(
        enabled = TRUE,
        keyboardNavigation = list(enabled = TRUE)
      )
    )
  )

Now we need to add data! The following code is not very parsimonious. I add each screen reader as its own series (which is why I kept the data in its original format, with each screen reader represented by a column). This allows me to get dual encoding by manually specifying dashStyle and marker.symbol for each group in addition to colour.

I also try to give a description for the x-axis range again. This was another feature I wasn’t able to get working manually, but which works well when the range is numeric (which you’ll see in the second version of the chart).

hc_sr_setup |>
  hc_xAxis(categories = sr_dat1$Category,
           title = list(text = "Time"),
           accesibility = list(
             enabled = TRUE,
             description = "Time from December 2010 to September 2019",
             range = "December 2010 to September 2019"
           ),
           dateTimeLabelFormats = list(
             month = list(main = "%b %Y")
           )
  ) |>
  hc_add_series(
    data = sr_dat1$NVDA,
    name = "NVDA",
    color = "#0b7383",
    label = list(enabled = TRUE),
    marker = list(symbol = "circle")
  ) |>
  hc_add_series(
    data = sr_dat1$JAWS,
    name = "JAWS",
    color = "#4372da",
    dashStyle = "ShortDashDot",
    label = list(enabled = TRUE),
    marker = list(symbol = "diamond")
  ) |>
  hc_add_series(
    data = sr_dat1$VoiceOver,
    name = "VoiceOver",
    color = "#222222",
    dashStyle = "ShortDot",
    label = list(enabled = TRUE),
    marker = list(symbol = "square")
  ) |>
  hc_add_series(
    data = sr_dat1$Narrator,
    name = "Narrator",
    color = "#76767A",
    dashStyle = "Dash",
    label = list(enabled = TRUE),
    marker = list(symbol = "triangle")
  ) |>
  hc_add_series(
    data = sr_dat1$`ZoomText/Fusion`,
    name = "ZoomText/Fusion",
    color = "#3D239E",
    dashStyle = "ShortDot",
    label = list(enabled = TRUE),
    marker = list(symbol = "triangle-down")
  ) |>
  hc_add_series(
    data = sr_dat1$Other,
    name = "Other", 
    color = "#6B26F0",
    dashStyle = "ShortDash",
    label = list(enabled = TRUE),
    marker = list(symbol = "circle")
  ) |>
  hc_exporting(
    enabled = TRUE,
    accessibility = list(
      enabled = TRUE
    )
  ) |>
  hc_tooltip(valueSuffix = "%")

Line chart: simpler edition

The {higcharter} package was designed with a syntax meant to be “intuitive” to R users, in particular those familiar with {ggplot2}. For example, rather than making each screen reader its own series, each group could be defined in the hcaes() argument, which:

Define[s] aesthetic mappings. Similar in spirit to ggplot2::aes (Kunst 2021).

The downside of doing things this way is that you do not get the dual encoding for the splines (i.e. different line styles and different colours). The shapes for the points are different, you just don’t get to specify them manually (which isn’t a very big deal).

In order to use screen_reader as a grouping variable, I’ll have to reshape the data a bit. Since we’re mixing things up here, I also create a year variable, which means that Highcharts will be able to automatically generate a rangeDescription (since it’s numeric).

# replace July with proper abbreviation
raw_dat[4,1] <- "Jul 2015"
# turn into "tidy" data format for categories
sr_dat2 <- raw_dat |>
  separate(Category, into = c("month", "year")) |>
  select(-month) |>
  pivot_longer(!year, names_to = "screen_reader", values_to = "pct_usage") |>
  mutate(year = parse_number(year)) |>
  drop_na()

The resulting data is longer (appropriate, since we used the pivot_longer() function), and looks like this:

Whereas before I used highchart() to set up the chart before adding data, this time I’ll send the data into hchart() from the start.

hchart(
  sr_dat2,
  "spline",
  hcaes(x = year, y = pct_usage, group = screen_reader),
  accessibility = list(
    enabled = TRUE,
    keyboardNavigation = list(enabled = TRUE),
    linkedDescription = "Line chart demonstrating some accessibility features of Highcharts. The chart displays the most commonly used screen readers in surveys taken by WebAIM from December 2010 to September 2019. JAWS was the most used screen reader until 2019, when NVDA took over. VoiceOver is the third most used screen reader, followed by Narrator. ZoomText/Fusion had a surge in 2015, but usage is otherwise low. The overall use of other screen readers has declined drastically the past few years."
  ),
  exporting = list(
    enabled = TRUE,
    accessibility = list(enabled = TRUE)
  )
) |>
  hc_title(text = "Most common desktop screen readers") |>
  hc_subtitle(text = "Source: WebAIM.") |>
  hc_caption(text = "Line chart demonstrating some accessibility features of Highcharts. The chart displays the most commonly used screen readers in surveys taken by WebAIM from December 2010 to September 2019. JAWS was the most used screen reader until 2019, when NVDA took over. VoiceOver is the third most used screen reader, followed by Narrator. ZoomText/Fusion had a surge in 2015, but usage is otherwise low. The overall use of other screen readers has declined drastically the past few years.") |>
  hc_xAxis(
    title = list(text = "Time"),
    accesibility = list(
      enabled = TRUE,
      description = list(text = "Time from December 2010 to September 2019"),
      rangeDescription = "2010 to 2019"
    )
  ) |>
  hc_yAxis(
    title = list(text = "Percentage usage"),
    accessibility = list(description = "Percentage usage")
  ) |>
  hc_exporting(
    enabled = TRUE,
    accessibility = list(
      enabled = TRUE
    )
  ) |>
  hc_tooltip(valueSuffix = "%") |>
  hc_legend(symbolWidth = 40) |>
  hc_colors(c('#0b7383', '#6B26F0', '#76767A', '#4372da', '#222222', '#3D239E')) |>
  hc_add_dependency(name = "modules/accessibility.js") |>
  hc_add_dependency(name = "modules/exporting.js") |>
  hc_add_dependency(name = "modules/export-data.js") |>
  hc_add_dependency(name = "modules/series-label.js") |>
  hc_plotOptions(
    series = list(
      label = list(enabled = TRUE)
    )
  )

As you can see, the charts are quite similar, and the aesthetics are defined in a way that would definitely be familiar to a ggplot2 user: hcaes(x = year, y = pct_usage, group = screen_reader).

Incidentally, if you view the chart as a data table (View data table is the last option in the export menu at the top right corner), the format is the same as it was for the original (i.e. the output data doesn’t look long).

R accessibility resources and motivating examples

Silvia Canelón recently posted Resources for Data Viz Accessibility:

A selection of general and R-specific resources on how and why to make accessible data visualizations (Canelón 2021).

I noticed that, at the time (it had been last updated on 2021-10-14), it suggested that the accessibility module didn’t work with {highcharter}, and linked to a couple of GitHub issues in its repo (specifically #707, and #719) where unsuccessful in getting accessibility features to work through {highcharter}.

Having worked with {highcharter} a bit in the past, and knowing that “if you can do it in Highcharts, you can do it with {highcharter}” usually holds true, I thought I’d give it a whirl.

Licenses

Copyleft

From Kyle E. Mitchell’s How to Speak Copyleft (2018):

To implement a copyleft rule, a drafter must make four independent design decisions:

1. Trigger: When must licensees share other work?
   
2. Reach: What other work must licensees share?
   
3. Licensing: On what terms must licensees share that work?
   
4. Distribution: How must licensees share source for that work?

Several licenses, such as the GPL variants, contain an obligation for reciprocity; you can use this, but only if whatever you make using this is also available under this same license. This is a gross oversimplification, and the scope of the reciprocal obligation varies across licenses (and is often vaguely worded in the license itself). As Lawrence Rosen describes in Open Source Licensing: Software Freedom and Intellectual Property Law (2004):

Licenses like the GPL contain vague provisions about derivative and collective works; some licensors prefer that ambiguity because it results in more software licensee contributions licensed under the GPL.

From the Free Software Foundation’s What is Copyleft? (2018):

To copyleft a program, we first state that it is copyrighted; then we add distribution terms, which are a legal instrument that gives everyone the rights to use, modify, and redistribute the program’s code, or any program derived from it, but only if the distribution terms are unchanged.

Though this sounds simple enough, ambiguity tends to make corporate folks (or at least their lawyers) nervous. And, when it comes to code, there are added layers of complexity, many of which have yet to be ruled on in a court of law.

In the ongoing case of Oracle v. Google, both plaintiff and defendant have issued motions for “judgment as matter of law” (“JMOL”) both successfully and unsuccessfully for: fair use (denied), the “rangeCheck” computer routine (denied), and eight decompiled security files (granted–see Oracle Am., Inc. v. Google Inc., No. C 10-3561, 2012 U.S. Dist. (N.D. Cal. May 11, 2012) (“Order Granting JMOL on Decompiled Files”)).

Throughout the case parties have distinguished “declaring code” and “implementing code” (see Oracle America, Inc. v. Google Inc., 750 F. 3d 1339 - Court of Appeals, Federal Circuit 2014), and as oral arguments have been presented to the Supreme Court, the copyrightability of an Application Programming Interface (API) remains undecided (see Transcript of Oral Argument Google LLC v. Oracle America, Inc., U.S. (2020) (No. 18-956) (Argued October 7, 2020)).

Kyle E. Mitchell has several posts highlighting important bits, including Oracle v. Google Oral Argument, and Mix Many Metaphors in which he catalogs the many analogies used by Supreme Court justices and arguing lawyers alike (2020b, 2020a). Wikipedia also does a pretty bang-up job of summarising the now eight-year-long legal battle on their Google LLC v. Oracle America, Inc. (2020c).

Viruses and Freedoms

The first thing any lawyer learns about open source is that there are two kinds of open source licenses: “viral” and “nonviral.”

When lawyers use the term “viral,” they are referring to a license condition that requires the licensee to redistribute source code in outbound licenses only on the same terms as the inbound license (Meeker 2008, 11).

“Reciprocal” means two different things in law and FOSS:

For a more accurate term, I recommend “hereditary,” because the terms of the license initially applied to the software are “inherited” by all subsequent licensees of the same code, subsets of it, or variations of it (Meeker 2008, 13).

GPL

This key part of the second paragraph of the GPL is the most important provision of the license. Derivative works must be licensed under the GPL and be subject to all of its restrictions. Unlike works licensed under the MIT or the BSD License, works derivative of work licensed under the GPL (or the original work itself) may not be made proprietary or otherwise limited in their distribution. If a programmer is looking to create proprietary works, the entire universe of GPL-licensed software is closed off to her. Indeed, as described in Chapter 6, the inclusion of any GPL-licensed code in purportedly proprietary software could prevent the creator of that software from enforcing any of the rights otherwise available under copyright: any person could distribute, sell, or modify that software, in disregard of any rights that would otherwise be granted the creator under the copyright laws (Laurent 2004, 49) [emphasis added].

The Darth Vader Scale of Derivative Works

ImportantImportant

Note that The Darth Vader Scale of Derivative Works (Figure 1) is Lindberg’s interpretation of the FSF’s position on the applicability of the GPL.

To understand the FSF’s position on the applicability of the GPL, it is useful to view the interaction between programs on a scale from “mere aggregation” of differently licensed work to wholesale incorporation of code into a modified GPL-licensed binary. Figure 12-1¹ summarizes the FSF’s view of the situation; anything more than “mere aggregation” moves a user toward violating the GPL (Lindberg 2008, 231).

¹ Figure 12-1 references the figure as it appears in Lindberg’s book (2008). Here, it is reproduced as Figure 1.