Contributing example notebooks¶
We’d love to collaborate with anyone interested in describing scenarios for using Fairlearn!
A good example notebook exhibits the following attributes:
Deployment context: Describes a real deployment context, not just a dataset.
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 sociotechnical challenge. 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.
Formatting of example notebooks¶
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
percent format
in the
examples/notebooks directory
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.
To build the webpage run the following command from the repository root directory:
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 in markdown.