We’d love to collaborate with anyone interested in describing scenarios for
A good example notebook exhibits the following attributes:
Deployment context: Describes a real deployment context, not just a
Real harms: Focuses on real harms to real people.
See Blodget et al. (2020).
Sociotechnical: Models the Fairlearn team’s value that fairness is a
Avoids abstraction traps.
See Selbst et al. (2020).
Substantiated: Discusses trade-offs and compares alternatives.
Describes why using particular Fairlearn functionalities makes sense.
For developers: Speaks the language of developers and data scientists.
Considers real practitioner needs.
Fits within the lifecycle of real practioner work.
See Holstein et al (2019),
Madaio et al. (2020).
Please keep these in mind when creating, discussing, and critiquing examples.
If you’d like to collaborate, please reach out.
The example notebooks in Fairlearn are surfaced through the website’s
example notebook page.
This allows them to be rendered properly with output from all cells.
These notebooks are generated based on plot_*.py files in
of the repository.
To do this yourself make sure to install sphinx and its
add-ons by running python scripts/install_requirements.py --pinned False in the repository
root directory. You may also need to install Pandoc.
The filename must begin with plot_ for the cell output to be rendered as a webpage.
python scripts/install_requirements.py --pinned False
To build the webpage run the following command from the repository root
python -m sphinx -v -b html -n -j auto docs docs/_build/html
Rerunning this after making changes to individual files only rebuilds the
changed pages, so the build time should be a lot shorter.
To edit the notebook we recommend using
Visual Studio Code.
VS Code recognizes the lines starting with # %% as new cells.
Each cell can be executed individually by clicking on Run Cell, and VS Code
opens a Python Interactive tab to show the output.
If you prefer working with Jupyter simply open the .py file with Jupyter.
Changes made in Jupyter automatically show up in the .py file.
Note that the text portion of these notebooks should be written in
restructured text (ReST), not markdown, so that the sphinx documentation build
can render it nicely for the website. When downloading the .ipynb file through
the website the text portions will be in markdown due to automatic conversion from
ReST to markdown by sphinx-gallery. This currently only works for basic ReST
functionality, so try to limit use of ReST directives (e.g., .. note:),
internal links (e.g., :ref:), and other functionality that won’t render well