Creating Accessible Notebook Experience#
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.
Enhancing the accessibility of the notebook interface:#
The Datahub team constantly collaborates with Jupyter developers to incorporate accessibility enhancements into both the Notebook and Lab interfaces. In that spirit,we encourage instructors to integrate Lab 4 and Notebook 7 into their teaching workflows, as these releases include the latest accessibility enhancements.
JupyterLab 4.0:#
A number of accessibility improvements have been made in JupyterLab 4.0, including improved screen reader and keyboard navigation, more ARIA roles and labels, and a hamburger menu that collapses if there is not enough space to display all items. You can read more about the features of Lab 4 in the blogpost titled “JupyterLab 4.0 is here”. Lab 4 has undergone extensive testing with Data 100 summer 23 instructors within a new hub, and the overall experience has been positive, with the exception of real-time collaboration, which may require further attention.
Jupyter Notebook 7.0:#
The Jupyter Notebook 7.0, set to become the new default notebook interface, is constructed using reusable components derived from Jupyter Lab 4.0. As part of this transition, both the classic notebook and retro notebook will eventually be replaced. Notably, the accessibility enhancements introduced in Lab 4.0 will also be incorporated into Notebook 7.0. For more details on Notebook 7.0, you can refer to the blog post titled “Announcing Jupyter Notebook 7.”
Enhancing the accessibility of the content within Jupyter notebooks:#
There are scenarios where notebooks are designed to be inaccessible. This could include issues with alt text, captioning the images, color contrast issues in the image etc.. One can avoid such accessibility issues by following the best practices recommended to create accessible notebooks.
Sharing couple of resources from the Iota School team who has compiled the best practices for creating accessible notebooks into checklists and tips,
Add alt-text to all static images and charts in your notebook:#
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.
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.
Have clear headings throughout the notebook:#
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 notebook to html format for consumption:#
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.
Install WCAG 2.0/2.1 standards compliant themes:#
Jupyter classic notebook and lab have 3rd party themes that give more control to the notebook developers to customize the notebook themes and improve accessibility as a result .
Theme/Font compatibility with varied versions of notebook/lab#
Interface |
Recommended Themes/Fonts |
Comments |
|---|---|---|
Jupyter Lab >=4.0 |
JupyterLab-Accessible-Themes package compatibility with the latest lab version is a work in progress as per the maintainer’s page. |
|
Jupyter Lab <= 3.0 |
||
Jupyter Notebook >= 7.0 |
JupyterLab-Accessible-Themes package compatibility with the latest notebook version is a work in progress as per the maintainer’s page |
|
Jupyter Notebook < 7.0 |
JupyterLab-Accessible-Theme#
JupyterLab-Accessible-Themes is a lab theme that allows notebook creators to customize the lab experience. There are three different types of themes which are included as part of this package, a) Pitaya Smoothie and b) Github Light c) 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 command
!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 themeby selecting Settings -> Theme -> Github Light and/orPitaya Smoothie themeby selecting Settings -> Theme -> Pitaya Smoothie and/orGithub Dark themeby selecting Settings -> Theme -> Github Dark
Jupyter Theme#
Jupyter Themes 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 following command,
!pip install jupyterthemes
The different types of themes are onedork, grade3, oceans16, chesterish, monokai, solarizedI, solarizedd. You can explore these themes using the documentation in this web page. 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:
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.
Enhancing the accessibility of content in the R notebooks:#
If you are using R/RStudio as part of your instructional workflow then please check the following resources that provide better ways to make notebook content accessible,
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
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