This bite is based on the author’s experience at the Accessible Notebooks Hackathon, hosted by the Space Telescope Science Institute (STScI), in collaboration with the Iota School, Quansight Labs, and the Jupyter community.
If you’ve ever coded in Python, you’ve likely heard of or worked with a Jupyter Notebook. This is a web-based, open-source interface where users can add a series of executable cells with code, text, images, or videos, thereby creating an interactive notebook. With support for three core programming languages – Julia, Python, and R (hence the name) – notebooks have become a ubiquitous tool for astronomers and students to create and share code in a format that’s easily readable – a dream for researchers who want to share their work with colleagues or the broader scientific community.
Unfortunately, if you’re a blind or visually impaired (BVI) user, using a Jupyter Notebook turns into more of a nightmare. Presently, Jupyter notebooks are not accessible (their website even says so), and assistive technology such as screen readers or voice control do not play nicely with the interface. While there are some basic workarounds, they are still highly limited and do not let a BVI user interact with the software in the same capacity as a sighted user.
Notebooks for All
Luckily, the astronomy community is actively trying to change this. Notebooks for All – a research collaboration between the Space Telescope Science Institute (STScI), the Iota School, Quansight Labs, and Jupyter community – is a project that’s aiming to make Jupyter notebooks more accessible to users with disabilities. While the interactive notebook environment (files ending in .ipynb) has a long way to go to meet accessibility standards, this project starts by figuring out how we can make reading a published, uneditable notebook (.html files) a more accessible experience.
This is not a one-and-done process. The collaboration employs an iterative cycle, whereby they run usability testing with affected users, listening and documenting their concerns and feedback, and then implementing changes based on that feedback. This is then repeated on loop, with users testing the hopefully-improved notebook and assessing the latest changes. Thereby, the collaboration builds up a set of guidelines and practices that improve the accessibility of published notebooks.
Accessible Notebook Hackathon 2023: Tips & Tricks
This process extends beyond the Notebook for All collaboration. In order for disabled users to see these changes implemented, authors need to actively change their habits when writing and publishing Jupyter notebooks. To that end, the Notebooks for All collaboration hosted a mini virtual hackathon in March, inviting researchers, professors, tech professionals, and students to learn about ways they can write more accessible notebooks, evaluate the accessibility of an existing notebook in small groups, and then share their findings with the entire cohort. A PDF of the presentation slides for the event can be found at this link.
The hackathon was led by the core team of Notebooks for All: Patrick Smyth (programmer and chief learner at Iota Schools), Isabela Presedo-Floyd (UX/UI accessibility designer at Quansight Labs) Jenn Kotler (UX researcher at STScI), Tony Fast (freelance developer and scientist), and Erik Tollerud (project scientist at STScI). After an introduction of the Notebooks for All project by Patrick Smyth and a whirlwind ride through the history of computational notebooks by Tony Fast, Isabela Presedo-Floyd presented a lot of useful tricks and tips that anyone can use to write more accessible notebooks.
Since there are a lot of considerations, I’ll only highlight a couple, but you can find all the tips in the link to a PDF of the presentation starting on slide #10. These tips are divided into 5 categories: changes you can make to your organization, images, text, code, and other types of content:
Organization:
- Include context for your notebook, so readers know what to expect. If you’re looking for a particular notebook and don’t have the luxury of doing a quick visual scan to see if you opened the correct file, having a cell at the very beginning of each notebook detailing the title, summary, table of contents, authors, date published and date edited is a lifesaver, so users know what the notebook does and if they have the correct version.
- When using Markdown cells (e.g. cells where you write text to be read as opposed to code to be executed), it’s important to stay consistent. Markdown lets users specify the heading of a block of text. H1 is the top-most heading, reserved for the title. H2 is usually a subtitle, H3 is below that, etc. In Markdown, you can specify the heading with the number of hashtags (#) you put in front of a line (e.g. # this is H1, ## this is H2, etc.). It’s very important not to skip headings or use them out of order, as this can confuse devices like screen readers and makes navigation difficult.
Images:
- Use alt-text and image descriptions so users know what’s in your figures or plots. Alt-text is an HTML feature that lets screen readers access hidden text that gives a quick description of an image, while the image description is a caption or separate paragraph that details the features of the image/figure and its importance. For plots, this should include the type of plot (bar, scatter, histogram, etc.) and info like the axes labels, title, legend, etc.
- When making plots, try to use colorblind-friendly palettes and make sure your colors have good contrast. If possible, use alternate ways to convey the same information color does, such as using different markers for data points or different line styles.
- It’s always good to link to your original data so users can access it in whatever way is most accessible to them. See if you can include an audio representation of your data with a sonification using tools like STScI’s Astronify package. Check out our Astrobites guide to sonification and our write-ups of pioneering sonification work like the Audible Universe conference!
Text:
- Attach hyperlinks to text that describe where the link is taking you, not just a “Click here”.
- Use plain and simple language whenever possible.
Code:
- Let users know what a code block does and what variables they can find in it with a lead-in cell or code comment. E.g. If you’re importing packages, you can write “Imports” and describe the package(s) that will be imported.
Other:
- Interactive controls need to be labeled and have enough contrast
- If including a video, make sure it has subtitles and provide a transcript
With all these tips in our mind, we went on to the “hacking” part of the hackathon. Participants were divided into small groups and had to evaluate an existing Jupyter notebook based on a checklist of accessibility criteria. You can find the instructions for the activity here if you’d like to go through the process yourself using a personal notebook or a sample one listed in the activity page. We then discussed our findings within our groups and then came together to share with all the participants, noting down what was and wasn’t accessible, any surprises we encountered, and reflecting on what changes we would make as notebook authors going forward.
Many groups encountered notebooks with similar issues, such as little to no image descriptions, no introduction or table of contents to the notebook, or missing plot labels and titles. There were also some surprise findings and good questions from groups. For example, some notebooks included code cells with really long lines, meaning a user has to scroll horizontally to see the end of the line. This scroll bar was inaccessible to a screen reader. One participant also commented on the inaccessibility of Latex equations in Markdown (e.g. screen readers have trouble with Greek characters, so writing out “alpha” is preferable to inserting the symbol for it). There was also discussion of the best scenarios to use code comments vs. markdown cells – comments are more useful for pointing out specifics in the code but are easily lost within, while markdown cells are good for providing context to a code cell and are read separately from the code, which can make them easier to navigate.
In the end, every group was very excited to hack their own notebooks and implement changes based on the tips and discussions from the workshop. Participants left with a better understanding of the challenges BVI users might face when confronted with a Jupyter notebook, and a wealth of resources they can utilize to create a more accessible and welcoming scientific community. But the work doesn’t stop here. With these resources, we hope that you too can hack your own notebooks and be a catalyst for positive change in the Jupyter community and beyond.
Resources
Below is a compilation of the resources from the hackathon:
- See and hear the entire presentation from the first part of the hackathon with this web recording.
- Follow along with the presentation with the slides.
- If you’d like to do the minihack activity for yourself or with a group, here’s a link to the instructions and accessibility checklist.
- Learn more information about the Notebooks for All project on their website.
- Find additional resources in the Notebooks for All Github repository
- Iota is an organization that connects accessibility, technical teaching, and research infrastructure development. Sign up for their mailing list or reach out to [email protected].
If you’re interested in digging deeper, Tony Fast and Isabela Presedo-Floyd also assembled a list of resources regarding notebooks and general web accessibility that was shared with the participants, which you can find below:
- ARIA Authoring Practices Guide
- Section 508
- Technica11y: Discussing challenges in technical accessibility
- Fix colors in syntax highlighting
- Interviews and Case Studies of Assistive Tech Use
- Resource for annotating imagesW3C Accessibility Object Model (https://wicg.github.io/aom/spec/)
- ARIA Patterns
- I Hate Notebooks (some issues with notebooks)
- Jupyter Book intro
- NB Viewer Notebook renderer
- MyST – Markedly Structured Text
- Quarto (Evolution of RMarkdown)
- Figure/chart resource
- WebAIM
- Axe (automated testing) browser extensions
- Markdown Cheat Sheet
- Disclosure (Show/Hide) Pattern – ARIA Authoring Practices Guide (APG)
- Image Description General Guidelines – DIAGRAM Center
- Chartability
- Rendering Dataframes For screen Readers With Pandas by Tony Fast
Astrobite edited by Ali Crisp
Featured image credit: https://github.com/jupyter/jupyter.github.io/blob/master/assets/share.png, Cameron Oelsen
Copyright © 2017 Project Jupyter Contributors
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of Project Jupyter Contributors nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
This software is provided by Project Jupyter Contributors “as is” and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall Project Jupyter Contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage
