dataand.me

What I read in 2021

Mara Averick — Fri, 31 Dec 2021 00:00:00 GMT

document.addEventListener("DOMContentLoaded", () => { // Add skip link to the page let element = document.getElementById("quarto-header"); let skiplink = ''; element.insertAdjacentHTML("beforebegin", skiplink); });

My relationship with reading borders on pathological (and by “borders on” I mean “has literally been a topic of discussion in therapy”). I mean, I’ve gotten it under control somewhat—we’ll use my 2014 Goodreads Reading Challenge as a bar for a bit out of control—which means I can take a look back on my 2021 year in books without too much self-recrimination.

The data

For all its faults (and there are many), I’ve gotten in the habit of using Goodreads to log what I’m reading over the past seven(ish) years. If nothing more, it has a nice enough export function, which lets you (or me, or whomever) retrieve your reading data as a CSV.

I stashed my exported data in Google Sheets. So, I’ll use {googlesheets4} to read it into R with its sheet ID, and make our lives easier by passing it straight through janitor::clean_names().

View code

Madam, I’m yadm

Mara Averick — Thu, 30 Dec 2021 00:00:00 GMT

I recently got a new laptop (see Making the M1 leap if you’re curious how that journey went), and in so doing, got lots of great advice about how other developers set up their machines. The award for biggest game-changer, though, has to go to Patrick Schratz who introduced me to yadm (Yet Another Dotfiles Manager). Here, I’ll give you a quick rundown of what yadm is, how to get started with it, and why I think it’s so darn cool.

.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.

Want to learn a lot more about dotfiles? See the Dotfiles post/lecture from MIT’s ./missing-semester series.

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.

Get used to the format of yadm , it’s how yadm rolls.

To add a file, you’re going to use yadm add 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

yadm bonus features

Got confidential files you want to manage, but don’t want to put them in a public repo? (Good! You shouldn’t put them there.) Enter yadm’s encryption features. Want to use alternate files on different systems? Templates? Hooks? yadm’s got you covered for those things, too.

But how does yadm differ from ?

Answer: Unless it’s Stow, I’m probably not the best person to ask. There is a lovely Comparisons section in the yadm FAQs, though.

All in all, I’m well pleased with yadm. So, major thanks to its author, Tim Byrne, and to Pat Schratz for introducing me to it.

References

Lemonaki, Dionysia. 2021. “Dotfiles – What Is a Dotfile and How to Create It in Mac and Linux.” freeCodeCamp.org. https://www.freecodecamp.org/news/dotfiles-what-is-a-dot-file-and-how-to-create-it-in-mac-and-linux/.

Footnotes

Unless you have an existing remote you want to clone, in which case you clone it.↩︎

Reuse

CC BY-SA 4.0

Citation

BibTeX citation:

@online{averick2021,
  author = {Averick, Mara},
  title = {Madam, {I’m} Yadm},
  date = {2021-12-30},
  url = {https://dataand.me/blog/2021-12_madam-im-yadm/},
  doi = {10.59350/mdrk1-kg921},
  langid = {en-US}
}

For attribution, please cite this work as:

Averick, Mara. 2021. “Madam, I’m Yadm.” December 30, 2021. https://doi.org/10.59350/mdrk1-kg921.

{highcharter} and the accessibility module: Part 5

Mara Averick — Tue, 16 Nov 2021 00:00:00 GMT

This final installment in our series on using the Highcharts accessibility module with {highcharter} is basically “extra credit.” (Read: I took the time to figure this out, so I’m sharing it. But, it’s probably not the most helpful post if you’re just trying to get the accessibility module working with {highcharter}.)

We covered enabling the accessibility module, and getting basic keyboard navigation in part one. In parts two and three we re-created two of the charts from Highcharts’ accessible demos. Lastly, in part four, we made a scatter plot inspired by Silvia Canelón’s compilation of accessible data visualization resources for R, and went into greater detail about the hidden screen-reader

that gets generated when you use the accessibility module.

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.

`lang` options

lang (AKA “the language object”) isn’t defined on a per-chart basis. As the Highcharts documentation describes:

The language object is global and it can’t be set on each chart initialization.

Taking a peek at the {highcharter} source code, it looks like lang options are set when the package is loaded. So, if I want to create a template for the description of the annotations (lang.accessibility.screenReaderSection.annotations), I’m going to have to do so before making my chart.

Tour de France 2017 chart

Once again, I made use of the Highcharts export module to get data out of the original chart in CSV format in order to read it back into R.

View code

Accessible {highcharter}: Part 4

Mara Averick — Mon, 15 Nov 2021 00:00:00 GMT

Back in the first post in this series I mentioned that the impetus for this whole endeavor was Silvia Canelón’s excellent collection of R-specific resources for making data visualizations more accessible (Canelón 2021). I wanted to fill the gap between the possibilities afforded by Highcharts’ accessibility module, and documented examples of module use with the {highcharter} package (Kunst 2021).

Here, we’ll go through the example chart from Silvia’s post (a scatter plot using data from the {palmerpenguins} package (Horst, Hill, and Gorman 2020)), and look at what accessibility features we can enable through {highcharter}.

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.

View code

Highcharts accessibility module with {highcharter}: Part 3

Mara Averick — Sat, 13 Nov 2021 00:00:00 GMT

In the first two parts of this series we introduced the Highcharts accessibility module, the {highcharter} R package, and created some working examples with accessibility features turned on.

Here, we’ll follow in the vein as part 2 by re-creating one of the accessible chart demos from Highcharts.

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).

View code

{higcharter} and the Highcharts accessibility module: Part 2

Mara Averick — Fri, 12 Nov 2021 00:00:00 GMT

Today we’ll be using the Joshua Kunst’s {highcharter} package to re-create the first example from the Highcharts documentation for its accessibility module, an accessible line chart showing screen reader popularity over time, as an htmlwidget.

As mentioned in the first part of this series, this chart was the first in my highcharter-accessibility experiments.¹ Thus, it’s only in hindsight that I realize that it has some features that result in a less R-like syntax than is usually possible when using {highcharter}. So, we’ll go create two versions of the visualization: one that most closely resembles the JavaScript-API-based original, and one that (to me) felt more natural to write.

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().

Code

Adventures with the Highcharts accessibility module: Part 1

Mara Averick — Wed, 10 Nov 2021 00:00:00 GMT

Over the past few weeks I’ve been experimenting with the accessibility module from Highcharts using the {highcharter} package by Joshua Kunst. Highcharts is an SVG-based library for making interactive charts for the web. {highcharter} is an R package that wraps the Highcharts JavaScript library and its modules (Kunst 2021).

One of the things I like about {highcharter} is how it really mirrors the native API (which you can learn more about in its vignette on the topic, JavaScript API basics). Because they’re so closely tied together, all of the Highcharts documentation, in effect, becomes {highcharter} documentation. So, my “experiments” have largely consisted of converting examples from the former into the latter.

In this post, we’ll give a broad overview of the accessibility module, motivating examples, and make a basic, working example with keyboard navigation enabled.

Highcharts ∩ accessibility

Highcharts has fairly extensive accessibility features, and has engaged in some interesting collaborations and research on making data visualizations accessible, especially for those with visual impairments (Bert and Hayes 2018).

The Highcharts accessibility module enables a number of features—most notably usability through keyboard navigation and screen reader technologies. Though not part of the accessibility module, their accessible demo charts also make use of patterns and dash styles to improve contrast for those with colour blindness.

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.

Guiding principles

There are a couple of principles I try to follow when figuring out coding “problems”—both of which are probably just ersatz versions of Jenny Bryan’s reprex do’s and don’ts.

Isolate your variables. Like many of the interactive (usually JavaScript-based) charting packages in R, {highcharter} works with {shiny}¹. However, you can also use {highcharter} without shiny (e.g. in an R Markdown document like this one) and still get a lovely, interactive visualization in the form of an htmlwidget. Since my goal was to see if I could get the accessibility module to work with {highcharter}, I didn’t want to introduce shiny into the equation as an “extraneous” variable.
Follow a working example. Between the {highcharter} site and the Highcharts demos (all of which have options to edit in CodePen and JSFiddle), there is no shortage of working examples available with code! Though I know very little about JavaScript, the aforementioned resemblance between the Highcharts JS API and {highcharter} syntax make reading the “foreign” source code incredibly helpful ².

Getting started…

As I came to discover, the first example in Highcharts’ Getting started with accessibility documentation (an accessible line chart) is actually somewhat complex from an R user’s standpoint. However, my plan was to mimic the examples from the Highcharts docs. So, it’s where I began.

Over in the land of {highcharter} documentation, I gave the Modules & plugins vignette a careful reading, since I’d be making use of at least one module (plus a few more, as I came to discover).

Because this missive has already gotten a bit long, I’m going to save the full line-chart example for a later post. However, something mentioned at the beginning of the Getting started docs turned out to be crucial to solving the mystery of Issue #707—the inclusion of the exporting and the export-data modules.

Keyboard navigation

There’s much more to accessibility than keyboard navigation.³ But it is a nice feature, and it was the ask of the aforementioned issue (which turns out to be relatively concise example, and is what I’ll show you below).

The original poster (@jenfly) does a nice, precise job of describing the desired keyboard navigation seen in the native Highcharts API example on CodePen:

when I use the Tab key in the Codepen output, the focus ring goes first to the “something focusable” link, then to the first bar in the chart, where I can use the right arrow to navigate through the bars (allowing a screen reader to read each one, for example), and if I press tab again, it goes to the legend, then to the context menu button, and finally to the generic “Button” I included at the bottom of the page (Walker 2021).

As with all things code, there’s more than one way to get the same thing done—I most definitely have not fully sussed out how much the order in which you put functions makes a difference. However, the following elements of my code are key (if you will) to getting the above behavior working.

Include all of the modules (accessibility, exporting, and exporting-data) used in the example with hc_add_dependency(). Even though using the hc_exporting() function brings the exporting module along, the explicit reference seems to make the next bit possible.
Expressly enable accessibility for exporting. Yes, exporting has its own accessibility option in the JavaScript API, and you need to enable this option in addition to enabling keyboard navigation for the chart as a whole to be able to tab over to the exporting menu.

Working example

So, with those two keys in mind, here is a the fruits chart with keyboard navigation enabled:

# library(highcharter)
data <- data.frame(
    fruit = c("apple", "banana", "orange", "pear"),
    count = c(2, 3, 5, 4)
    )

highchart() |> 
  hc_add_dependency(name = "modules/accessibility.js") |> 
  hc_add_dependency(name = "modules/exporting.js") |> 
  hc_add_dependency(name = "modules/export-data.js") |> 
  hc_title(text = "Fruits") |> 
  hc_xAxis(categories = data$fruit) |> 
  hc_add_series(
    data = data$count,
    type = "column",
    name = "Count"
  ) |> 
  hc_exporting(
    enabled = TRUE,
    accessibility = list(
      enabled = TRUE
    )
  ) |> 
    hc_plotOptions(
      accessibility = list(
        enabled = TRUE,
        keyboardNavigation = list(enabled = TRUE)
    )
  )

I’ve also re-created the Fruits example on its own (with source code available here), so you won’t have to tab through the other links in this article to see it in action.

Fin

We’ve just scratched the surface of what can be done with the Highcharts accessibility module. Next time we’ll take a step-by-step look at recreating Highcharts’ accessible line chart demo.

References

Bert, Alison, and Lisa Marie Hayes. 2018. “Making Charts Accessible for People with Visual Impairments: A Collaboration Between Elsevier and Highcharts Sets a New Standard for Chart Accessibility.” Elsevier Connect. https://www.elsevier.com/connect/making-charts-accessible-for-people-with-visual-impairments.

Canelón, Silvia. 2021. “Resources for Data Viz Accessibility.” https://silvia.rbind.io/blog/2021-curated-compilations/01-data-viz-a11y/.

Canelón, Silvia, and Elizabeth Hare. 2021. “Revealing Room for Improvement in Accessibility Within a Social Media Data Visualization Learning Community.” https://silvia.rbind.io/talk/2021-05-04-data-viz-accessibility/.

Kunst, Joshua. 2021. Highcharter: A Wrapper for the ’Highcharts’ Library. https://jkunst.com/highcharter.

Walker, Jennifer. 2021. Highcharter. https://github.com/jbkunst/highcharter/issues/707#issue-891688128; GitHub.

Footnotes

See the highcharter Shiny examples vignette for details.↩︎
I also copied these examples to my machine as stand-alone applications to ensure I could make them work outside of the online editors↩︎
In fact, I wouldn’t necessarily call the following example “accessible” per se, since it doesn’t make use of some of the features to subsequently in this series.↩︎

Reuse

CC BY-SA 4.0

Citation

BibTeX citation:

@online{averick2021,
  author = {Averick, Mara},
  title = {Adventures with the {Highcharts} Accessibility Module: {Part}
    1},
  date = {2021-11-10},
  url = {https://dataand.me/blog/2021-11_adventures-with-the-highcharts-accessibility-module-part-1/},
  doi = {10.59350/ts5f7-q3f89},
  langid = {en-US}
}

For attribution, please cite this work as:

Averick, Mara. 2021. “Adventures with the Highcharts Accessibility Module: Part 1.” November 10, 2021. https://doi.org/10.59350/ts5f7-q3f89.

dataand.me

What I read in 2021

The data

Madam, I’m yadm

.dotfiles 101

yadm

yadm bonus features

References

Footnotes

Reuse

Citation

{highcharter} and the accessibility module: Part 5

All the annotations

lang options

Tour de France 2017 chart

Accessible {highcharter}: Part 4

An accessible penguin plot

Highcharts accessibility module with {highcharter}: Part 3

Accessible pie chart

{higcharter} and the Highcharts accessibility module: Part 2

Laying the groundwork

Adventures with the Highcharts accessibility module: Part 1

Highcharts ∩ accessibility

R accessibility resources and motivating examples

Guiding principles

Getting started…

Keyboard navigation

Working example

Fin

References

Footnotes

Reuse

Citation

`lang` options