Notebook Accessibility Minihack
A one-hour exercise to evaluate HTML Jupyter Notebooks for better accessibility
View Event Details
Overview
In this one-hour exercise, we'll apply our accessible notebook authoring tips to real-life Jupyter Notebooks. We'll be focusing on notebooks exported to HTML, a format that is partially accessible to screen reader users by default.
Step One: Choose a Notebook
You have three options for picking a notebook to evaluate during this minihack. (If you're not sure about this step, pick one of the default notebooks under the first option.)
Option 1
Choose one of the notebooks below. This is the default option.
JWST data files make use of the Advanced Scientific Data Format. This notebook shows how to create an ASDF (Advanced Scientific Data Format) file from a FITS file.
An example of building, compiling, and training a convolutional neural network on simulated astronomical data. The CNN classifies JWST-HST galaxy mergers.
Option 2
Use a notebook created by you or your organization. Since we'll be evaluating the HTML export of the notebook, you will first want to open the notebook in Jupyter, then Choose `File > Download as > HTML (.html)`. This will export your notebook to HTML in the same folder as the notebook. Once you're done, open the notebook in a web browser such as Chrome before going on to the next step.
Option 3
Select a different notebook from an STScI project. The HTML notebooks can be found using the links on the left side of each project page. Screen reader users can navigate by list or list item to jump right to the lists of notebooks.
The jdat_notebooks repository contains notebooks illustrating workflows for post-pipeline analysis of JWST data. Some of the notebooks also illustrate generic analysis workflows that are applicable to data from other observatories as well. This repository and the notebooks are one component of STScI’s larger Data Analysis Tools Ecosystem.
Hello Universe is an initiative at MAST to provide a space for applying machine learning (ML) algorithms to astronomical data. The first set of notebooks are designed to span a range of ML techniques, and to highlight MAST mission data, including user-contributed high-level science products (HLSPs).
Step Two: Evaluate Notebook
Once you've chosen a notebook:
- Choose some criteria from the notebook authoring tips document. For example: focus on the notebook’s plots. Pick whichever area is most interesting to you.
- Take a look at your chosen notebook and evaluate whether or not the notebook follows best practices for authoring notebooks in that area.
- You may wish to divide up some of the main areas of concern within your breakout group—for example, one group might evaluate headings while another looks at code formatting.
Step Three: Review and Share
When we regroup with the rest of the participants, we'll consider each groups answers to these questions:
- What was the most common accessibility issue you encountered?
- What content was already accessible?
- What surprised you the most in this process?
- Do you think you’ll change anything when authoring notebooks or documents going forward?
We have created a collaborative Google doc where you can share your thoughts and see responses from other breakout rooms.
Before returning to the main Zoom room, please choose a member of your breakout room who would be comfortable presenting the results of your discussion.
Step ♾: Extra Credit / After the Hackathon
If you're feeling ambitious or looking for a more direct way to contribute your thoughts and results to STScI (or your organization), here are some ways to make a difference:
Accessible Authoring Checklist
Whether a Jupyter notebook is usable for disabled people can vary widely—it depends on how the document is set up and presented. Notebook authors can use writing and publishing techniques to ensure their notebooks’ content is more accessible.
This checklist is based on the draft authoring tips from the Astronomy Notebooks For All team.
Organization
At the beginning, a notebook should have:
- A title in the form of a
h1 (# in Markdown).
- A brief summary of the notebook.
- A table of contents in an ordered list (
1., 2., etc. in Markdown).
- The author(s) and affiliation(s) (if relevant).
- The date first published.
- The date last edited (if relevant).
- A link to the notebook’s source(s) (if relevant).
Throughout the notebook
- There is only one H1 (
# in Markdown) used in the notebook.
- The notebook uses other heading tags in order (meaning it does not skip numbers).
Images
- All images (jpg, png, svgs) have an image description. This could be
- Alt text (an
alt attribute)
- Empty alt text for decorative images/images meant to be skipped (an
alt attribute with no value)
- Captions
- If no other options will work, the image is described in surrounding paragraphs.
- Any text present in images exists in a text form outside of the image (this can be alt text, captions, or surrounding text.)
Visualizations
- All visualizations have an image description. Review the previous section, Images, for more information on how to add it.
- Visualization descriptions include
- The type of visualization (like bar chart, scatter plot, etc.)
- Title
- Axis labels and range
- Key or legend
- An explanation of the visualization’s significance to the notebook (like the trend, an outlier in the data, what the author learned from it, etc.)
- All visualizations have the following labels
- Title
- Labels on all axes
- Key or legend (if relevant)
- All visualizations and their parts have enough color contrast to be legible. Remember that transparent colors have lower contrast than their opaque versions.
- All visualizations convey information with more visual cues than color coding. Use text labels, patterns, or icons alongside color to achieve this.
- All visualizations have an additional way for notebook readers to access the information. Linking to the original data, including a table of the data in the same notebook, or sonifying the plot are all options.
Text
- All link text is descriptive. It tells users where they will be taken if they open the link.
- Use plain language wherever possible.
- All acronyms are defined at least the first time they are used.
- Field-specific/specialized terms are used when needed, but not excessively.
- Text is broken into paragraphs and/or cells where relevant.
- Text is in complete sentences where relevant.
Code
- Code sections are introduced and explained before they appear in the notebook. This can be fulfilled with a heading in a prior Markdown cell, a sentence preceding it, or a code comment in the code section.
- Code has explanatory comments (if relevant). This is most important for long sections of code.
- If the author has control over the syntax highlighting theme in the notebook, that theme has enough color contrast to be legible.
- Code and code explanations focus on one task at a time. Unless comparison is the point of the notebook, only one method for completing the task is described at a time.
Other content
This list is not exhaustive. If you are reviewing a notebook with content that you do not think fits any of these categories, keep in mind
- Text is flexible. Whether it is in the document or linked out, text can be read visually, be read audibly, be magnified, or be translated to another language. Having a text alternative is a good back up plan.
- Having enough color contrast is required on almost all visual content.
Videos
- All videos have titles in the player or in the text before them.
- All videos have captions/subtitles. This can include visual information descriptions if relevant.
- All videos have transcripts. This can include visual information descriptions if relevant.
- All video players have buttons with labels. This can be a persistent label or appear when hovered.
- All video players have buttons with enough color contrast.
- No videos have flashing images at more than three frames per second.
Sonifications
- Sonifications include a key explaining the mapping of data to sound. A written description can be used to convey this information.
- Sonification outputs reference the method that generated the sonification. This can be done in a code cell or with a link to the file used to generate the sonification.
- Audio players include basic listening controls for starting, pausing, volume, and speed.
- All audio players have buttons with labels. This can be a persistent label or appear when hovered.
- All audio players have buttons with enough color contrast.
The accessibility of interactive widgets varies greatly depending how they are included in the notebook. Review beyond this checklist may be needed.
- All interactive widgets with visual controls have labels. This can be a persistent label or appear when hovered.
- All interactive widgets with visual controls have enough color contrast.
- All interactive widgets have a summary of what they are and what they do in the surrounding text.
- If an interactive widget’s contents are needed to understand the rest of the notebook, the widget either needs to be tested further or have that content fully represented not as a widget elsewhere in the notebook.