Creating Accessible Notebooks

Improving the accessibility of the notebook experience has consistently been a key priority for the DataHub infrastructure team. This focus stems from the fact that notebooks have presented significant accessibility challenges, including limited compatibility with screen readers and keyboard navigation, difficulties in interpreting content due to color contrast issues, and non-compliance with the WCAG 2.0 AA standards mandated by the University.

Enhancing the accessibility of the notebook experience involves addressing multiple dimensions:

• Ensuring the accessibility of the interface, as exemplified by Lab 4 and Notebook 7.
• Enhancing the accessibility of the content within notebooks.

Notebooks might be inaccessible due to issues with alt text, image captions, color contrast, and other reasons. One can avoid such issues by following recommended best practices.

jupyterlab-a11y-checker¶

The JupyterLab a11y-checker extension performs multiple accessibility checks on Jupyter notebook/Lab cells containing images and headings. It does the following:

1. Verifies the presence of alt-text for images, ensuring that visually impaired users can understand their content.
2. Calculates the colour contrast ratio to ensure readability for low-vision users and c) Evaluates the heading structure to align with WCAG standards, ensuring that headers (h1, h2, etc.) are appropriately structured for optimal accessibility.

Alternative Text¶

Adding alternative text (“alt text”) to images is an important accessibility practice, especially when creating content for the web. Alt text provides a textual description of images, making content accessible to individuals who use screen readers or have other disabilities. Data visualization libraries such as matplotlib and seaborn by default doesn’t support embedding alt text to generated charts by default.

You can add alt text to an image by using the below syntax where the text withing the square brackets denotes the alt text for an image.

![A beautiful landscape](landscape.jpg)

Represent data across multiple mediums¶

It is important that users who use screen readers have additional pathways to make sense of the data visualized in a chart or an image. Some of those pathways include a) Descriptive summary of data represented in the chart and b) HTML formatted table in the form of code or markdown cells.

Representing data in the form of table should take into consideration the impact it has on screen readers. Too many rows and columns can affect screen reader navigation resulting in issues with navigation and comprehension. Ideally, having less than or equal to 5/6 rows in a table is a good rule of thumb to keep in mind.

Avoid creating large notebooks¶

It has been observed that large notebooks causes screen readers like NVDA and JAWS to crash. Keeping notebook size lesser than 10 MB (realistically) or even better around 1 MB (ideally) will make it easy for screen readers to navigate the ipynb files.

Clear Headings¶

Screen readers will be using headers to navigate the notebook. Ensure that the first cell in a notebook has the H1 tag to identify that it is the title. It has been observed that lack of clear header tags including H1 at the start affects the screen reader navigability.

Export to HTML¶

The editable notebook format (.ipynb) is inaccessible for screen readers and keyboard navigation. Much effort has been made to Lab 4 and Notbook 7 to overcome some of the barriers to accessibility. However, it is still not 100% accessible at the moment. To improve the readability of the notebooks, It is recommended that .ipynb files are converted to .html files which are largely designed for web interface and has a more accessible experience. PDFs are generally inaccessible in comparison to html format from a readability standpoint.

Nbconvert is a tool that converts notebooks to various formats including html which improves readability. The command for converting notebooks from .ipynb to html is

jupyter nbconvert --to html mynotebook.ipynb`

One can also customize the themes, font types, sizes etc. as part of the notebook inorder to improve the accessibility.

Accessible Themes¶

Quansight Themes¶

Users may choose to install accessbility-oriented jupyter lab themes. There are three different types of themes which are included as part of this package:

1. Pitaya Smoothie
2. Github Light
3. Github Dark

All the above themes are WCAG 2.1 AAA compliant and have been recommended by the Jupyter a11y community. However, these themes are not compatible with classic notebook interface and are a work in progress in terms of compatibility with JupyterLab 4.0.

You can install this theme by running the following commands:

pip install jupyterlab-accessible-themes==0.1.1

or

conda install -c conda-forge jupyterlab-accessible-themes

Once installed, you can enable this theme by the following steps:

• Save the notebook and restart the kernel by selecting Kernel > Restart Kernel
• Select Github Light theme by selecting Settings > Theme > Github Light and/or Pitaya Smoothie theme by selecting Settings > Theme > Pitaya Smoothie and/or Github Dark theme by selecting Settings > Theme > Github Dark

jupyterthemes¶

jupyterthemes is a notebook theme that offers 7 different types of themes to customize the classic notebook experience. This theme only works with classic notebook interface and is not compatible with JupyterLab and the Notebook 7.0.

You can install themes by running:

pip install jupyterthemes

The different types of themes are onedork, grade3, oceans16, chesterish, monokai, solarizedI, solarizedd. If you are looking for JupyterLab equivalent for those themes then you can explore JupyterLab Legos UI and Darkside UI

Jupyter Font¶

You can use the JupyterLab fonts package to customize the fonts used in the notebook. JupyterLab font is a work in progress and is currently compatible with Lab version 3.0. The compatibility with Lab 4.0 is a work in progress.

pip install jupyterlab-fonts

The sans serif fonts this package ships currently are:

• Anonymous Pro
• Atkinson Hyperlegible
• Dejavu Sans
• Fira Code

Sonify your data¶

“Sonify the data” refers to the process of representing data using sound. Instead of just visualizing data in charts, graphs, or other visual formats alone, sonification translates data into audible sound patterns, allowing users to perceive and understand data through their sense of hearing.

• Use python packages like sonipy to sonify the data
• Open source tools such as TwoTone allow for generating music from data
• In Astronomy, Astronify is used for turning astronomical data into sound

R Notebook Content¶

If you are using R as part of your instructional workflow then please check the following resources that provide better ways to make notebook content accessible,

• Customize themes in R Studio
• BrailleR: R package that allows blind people understand plots better. Here is an example of BrailleR package
• Sonify: R package converts images into audio representation. Here is an example for sonifying a data
• TactileR: R package for creating tactile graphics for users with visual impairments. Here is an example for tacticleR
• Adding alt text content for images produced by knittR
• AccessRMD is the package to improve accessibility of RMD files

Improving accessibility in Jupyter notebooks is an ongoing process that involves attention to both the structural aspects of the content and the interactive elements within the notebooks. It’s important to prioritize accessibility to ensure that your content is inclusive and usable by a broad audience.

References¶

• Potluri et al (2023), Notably Inaccessible - Data Driven Understanding of Data Science Notebook (In)Accessibility, ACM Paper titled notably inaccessible
• Iota school a11y tips for creating and publishing Jupyter notebooks
• JupyterLab Accessibility Meeting Notes
• Iota School has compiled the best practices for creating accessible notebooks into checklists and tips:
  • Checklist for notebook authoring
  • Tips for notebook authoring