skip to main content

@tonyfast s notebooks

site navigation
notebook summary
title
notebooks and accessibility workshop
description
the path to accessible notebooks is paved in technical debt.
cells
22 total
2 code
state
executed in order
kernel
Python [conda env:p311] *
language
python
name
conda-env-p311-py
lines of code
155
outputs
2
table of contents
  • notebook accessibility and accessible authoring
  • slides for notebooks, accessibility, ada
  • web content accessibility guidelines principles
  • example notebook audit
  • accessibile notebook authoring
  • Authoring Tips (Draft)
  • Use well-formatted Markdown
  • All text in the document needs to appear as plain text
  • Visualization Accessibility
  • Descriptive text for visual areas
  • Organization
  • Color contrast
  • Use “plain language”
  • Use descriptive link names!
  • Lead into your code cells (where relevant)
  • Comment on your code (where relevant)
  • other useful authoring resources
  • extra links
  • data sonification - westerlund 2
    • {"kernelspec": {"display_name": "Python [conda env:p311] *", "language": "python", "name": "conda-env-p311-py"}, "language_info": {"codemirror_mode": {"name": "ipython", "version": 3}, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.11.3"}, "widgets": {"application/vnd.jupyter.widget-state+json": {"state": {}, "version_major": 2, "version_minor": 0}}, "title": "notebooks and accessibility workshop", "description": "the path to accessible notebooks is paved in technical debt."}
    notebook toolbar
    Activate
    cell ordering

    notebooks and accessibility workshop

    the path to accessible notebooks is paved in technical debt.

    time activity
    2:05-2:10 Introduction and workshop structure
    2:10-2:20 what are notebooks to you?
    2:20-2:27 notebooks, wcag, and ada
    2:27-2:40 example of auditing a notebook
    2:40-3:20 audit your notebook
    3:20-3:30 group discussion or share out reflections/findings (depending on number of teams)
    3:30-3:40 notebook inaccessibility in the wild
    3:40-3:50 authoring accessible notebooks
    3:50-3:55 resources sharing for participants.
    3:55-4PM thank you and where do we physically go next

    what are notebooks to y'all?

    10 min

    1. what are notebooks to you?
    2. where have you used them?
    3. where do you wish you could use them?

    notebooks, accessibility, and ada

    skip to timeline

    example notebook audit

    skip to section

    hands on accessibility - auditting notebooks

    take your time exploring accessibility tools on your mobile or desktop device. the goal is to focus on accessibility related aspects of web content, you'll learn to about assistive technology and web accessibility terminology.

    • mobile users do not have access to most of these developers tools. they should practice manually auditting their content with different accessibility settings (eg color filters, magnification, large text, voice control)
    • desktop users can choose manually test content with accessibility settings, use developer tools/bookmarklets to analyze their document, or install different tools to experience them. chrome has the most accessibility developer tools, but we need to test all the browsers.

    Example notebooks - still need fill in the names

    auditting accessibility

    where applicable, build the accessibility floor by using these in ci.

    list of more accessibility tools

    hands work workshop reflections and findings

    • what topics did you discuss the most?
    • what suprised you?
    • did you learn anything new?
    • are there things you now want to learn more about?

    notebook inaccessibility in the wild

    a presentation by venkatesh potluri

    notebook accessibility and accessible authoring

    what makes this page accessible? a demo by tonyfast

    skip to accessible authoring recommendations

    slides for notebooks, accessibility, ada

    a timeline of disability rights, digital accessibility, and interactive computing

    year event
    1955 a proposal for the dartmouth summer research project on artificial intelligence
    1973 Section 504 Rehabilitation Act of 1973
    1973 50 years later, we're still living in the Xerox Alto's world
    1988 Mathematica
    1990 The Americans with Disabilities Act (ADA) protects people with disabilities from discrimination
    1993 the first html website
    1998 Section 508 Rehabilitation Act - eliminate barriers to information technology
    1999 Web Content Accessibility Guidelines 1.0
    1999 HTML 4.1
    1999 Computer programming for everybody
    2001 ANNOUNCE - IPython, a new interactive shell for Python.
    2005 SageMath - open source alternative to Magma, Maple, Mathematica, and MATLAB
    2008 Web Content Accessibility Guidelines 2.0
    2008 Semantic HTML5
    2013 initial react release
    2014 Project Jupyter
    2016 Jupyter Lab

    | 2017 | Project Jupyter wins ACM software systems award | 2017 | Section 508 Rehabilitation Act Updated Web Content Accessibility Guidelines 2.0 AA | | 2017 | Google Colab | | 2018 | Web Content Accessibility Guidelines 2.1 | | 2019 | First Jupyter Accessibility Event | 2023 | Web Content Accessibility Guidelines 2.2 |

    web content accessibility guidelines principles

    let all practice sounding like digital accessibility experts

    when you see WCAG you should hear WUH-CAG.

    let's practice.

    Perceivable
    Information and user interface components must be presentable to users in ways they can perceive.
    Operable
    User interface components and navigation must be operable.
    Understandable
    Information and the operation of user interface must be understandable.
    Robust
    Content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies.

    summarized guidelines on the wcag wikipedia

    • Guideline 1: Provide equivalent alternatives to auditory and visual content
    • Guideline 2: Don't rely on colour alone
    • Guideline 3: Use markup and style sheets, and do so properly
    • Guideline 4: Clarify natural language usage
    • Guideline 5: Create tables that transform gracefully
    • Guideline 6: Ensure that pages featuring new technologies transform gracefully
    • Guideline 7: Ensure user control of time sensitive content changes
    • Guideline 8: Ensure direct accessibility of embedded user interfaces
    • Guideline 9: Design for device independence
    • Guideline 10: User interim solutions
    • Guideline 11: Use W3C technologies and guidelines
    • Guideline 12: Provide context and orientation information
    • Guideline 13: Provide clear navigation mechanisms
    • Guideline 14: Ensure that documents are clear and simple

    example notebook audit

    1. let us hear about lived experiences first.
    2. connect lived experience with accessibility tooling.
      1. developer tools
        • accessibility tree
      2. lighthouse
      3. axe
      4. accessibility bookmarklets
      5. screen reader/magnifier

    With axe-core , you can find on average 57% of WCAG issues automatically. Additionally, axe-core will return elements as "incomplete" where axe-core could not be certain, and manual review is needed.

    adrian roselli provides an in depth comparison of manual and free automated wcag tools

    accessibile notebook authoring

    chartability is a set of heuristics for ensuring that data visualizations, systems, and interfaces are accessible.

    expands POUR principles with...

    Compromising
    (Understandable, yet Robust): Information flows must provide transparency, tolerance, and consideration for different ways that users with assistive technologies and disabilities will prefer to consume different information.
    Assistive
    (Understandable and Perceivable but labor-reducing): Interface must be intelligent and multi-sensory in a way that reduces the cognitive and functional labor required for use.
    Flexible
    (Perceivable and Operable, yet Robust): Design must respect user settings from user agents (browsers, operating systems, applications) and provide presentation and operation control. 
        import requests, requests_cache, IPython
    requests_cache.install_cache()

draft = requests.get(
    "https://raw.githubusercontent.com/Iota-School/notebooks-for-all/main/resources/event-hackathon/accessibility-tips-for-jupyter-notebooks.md"
).text
_, heading, body =  draft.partition("## Authoring Tips (Draft)")
IPython.display.Markdown(heading + body)

    Authoring Tips (Draft)

    Use well-formatted Markdown

    Use content headings. There is only one H1. Do not skip heading levels.

    All text in the document needs to appear as plain text

    • If there’s text in an image, in a chart, in a video, in an audio recording, or other relatively inaccessible formats, it should also be in plain text somewhere. There are multiple ways you can handle this depending on content and context.
    • Options for providing information in plain text alongside other formats include: adding a description, including a caption, or describing everything fully in surrounding paragraphs.

    Visualization Accessibility

    • Include titles in visualizations, such as the outputs from libraries such as Matplotlib. Both in plot and as a property.
    • Label visualization axes, include keys/legends
    • They should have good contrast (the relative difference in tonal hues). Be cautious of low opacity and thin lines, or color choices that are too similar, such as light gray on white. Try https://github.com/Quansight-Labs/accessible-pygments
    • Consider plotting in only black and white. You can always add color later.
    • Don’t rely only on color to convey information. Include labels. Consider using a mix of color and patterns to differentiate values.

    Descriptive text for visual areas

    • When using an image with an .img tag in the HTML, alt text may be used normally
    • When creating a plot or graph, some libraries allow alt text and others don’t. Captions and titles should be used to fill in information that alt text would normally contain when there is no option for it.
    • Legends, Axis labels, numbered tic-marks, and other text in generated graphs cannot currently be read by a screen reader and may be too small for low vision people to find with magnification.
    • When writing alt text for a plot, Include:
      • Type of Plot (bar chart, image, scatter-plot,etc)
      • Title of graph
      • Axis labels and range
      • Key / legend
      • General explanation of graph and what it is communicating
    • It can be very helpful to link to a file containing the original data, or if possible include a data table near the plot so it can be accessed in a non visual way
    • Include a sonification for a plot. You can use Astronify to do this for time series and spectral astronomy data.

    Organization

    To help people orient themselves in the notebook and understand what to expect, give some context at the beginning. We recommend:

    • Give the document a title. This should be the one H1 you use, and it should be at the top.
    • Include a summary of the document under the title.
    • Add a table of contents as an ordered list (even if it cannot contain links)
    • Add the author and affiliation, where relevant
    • Include information such as the date and time first published and the date and time last edited.
    • Link to the notebook source, where it can be used in editable form

    Color contrast

    • Color Contrast for in[] out[] can be templated to be higher contrast, standard does not read well for low vision
    • Use a syntax highlighting theme that considers accessible contrast (examples at ericwbailey/a11y-syntax-highlighting)

    Use “plain language”

    • Define acronyms the first time you use them and use them sparingly
    • Only use field-specific terms when needed. Use approachable language when the terms aren’t critical to understanding the rest of the document or related literature.
    • More general tips on stylistic choices with accessibility considerations can be found on Google’s developer documentation style guide.
    • Do not: Click here!
    • Do: Learn more at Space Telescope

    Lead into your code cells (where relevant)

    • Make sure they are under other content headings (ie. an imports cell can be preceded by a markdown cell with a header “Imports”)
    • Tell what the cell should do before it is done. Usually this is in a markdown cell before, but it also could be a comment in the code cell.
    • Do not list several different ways someone could complete the task unless that is the point of the notebook. Focus on what you are doing first, and mention alternates later if needed.

    Comment on your code (where relevant)

    • This is especially important for long stretches of code or where more specificity is needed.

    other useful authoring resources 

    %%html
<h3><a href="https://science.nasa.gov/mission/hubble/multimedia/sonifications/">data sonification - westerlund 2</a></h3>

<blockquote>
This is a cluster of young stars – about one to two million years old – located about 20,000 light-years from Earth. In its visual image form, data from Hubble (green and blue) reveals thick clouds where stars are forming, while X-rays seen by Chandra (purple) penetrate through that haze. In the sonified version of this data, sounds sweep from left to right across the field of view with brighter light producing louder sound. The pitch of the notes indicates the vertical position of the sources in the image with the higher pitches towards the top of the image. The Hubble data is played by strings, either plucked for individual stars or bowed for diffuse clouds. Chandra’s X-ray data is represented by bells, and the more diffuse X-ray light is played by more sustained tones.
</blockquote>

<iframe width="840" height="473" src="https://www.youtube.com/embed/ESz8Cvirh00" title="Data Sonification: Westerlund 2 (Multiwavelength)" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

    data sonification - westerlund 2

    This is a cluster of young stars – about one to two million years old – located about 20,000 light-years from Earth. In its visual image form, data from Hubble (green and blue) reveals thick clouds where stars are forming, while X-rays seen by Chandra (purple) penetrate through that haze. In the sonified version of this data, sounds sweep from left to right across the field of view with brighter light producing louder sound. The pitch of the notes indicates the vertical position of the sources in the image with the higher pitches towards the top of the image. The Hubble data is played by strings, either plucked for individual stars or bowed for diffuse clouds. Chandra’s X-ray data is represented by bells, and the more diffuse X-ray light is played by more sustained tones.

    The James Webb Space Telescope provides exemplary alt text and are frequently regard for it. The Space Telescope Science Institute provides accessibility services relative most large open science projects.