$30 off During Our Annual Pro Sale. View Details »

How to avoid 'death by Jupyter notebooks'? Towards more effective and educational notebooks

How to avoid 'death by Jupyter notebooks'? Towards more effective and educational notebooks

Using Jupyter Notebooks is easy, but developing Jupyter notebooks that are effective and educational for others is not so easy. This talk will guide you through a set of principles to make Jupyter notebooks more educational and enjoyable for others. Concepts that will be covered are modularisation, leveraging html functionalities and converging content in an index notebook.

Julia Wagemann

November 04, 2020
Tweet

More Decks by Julia Wagemann

Other Decks in Technology

Transcript

  1. #JupyterCon2020
    How to avoid ‘death by
    Jupyter notebooks’?
    Towards more effective and educational
    notebooks
    1
    Julia Wagemann

    View Slide

  2. About me
    2
    ● Independent consultant for geospatial data and PhD
    candidate at Philipps University of Marburg
    ● My work is in the intersection of data providers and data
    users with a focus on climate | meteorological |
    atmospheric data
    ● Been using Jupyter notebooks since 2014
    ● Since 2019, I am developing Jupyter-based training on
    atmospheric composition data for the European
    Organisation for the Exploitation of Meteorological
    Satellites (EUMETSAT)
    https://gitlab.eumetsat.int/eumetlab/atmosphere/atmosphere
    ● Github: jwagemann | Twitter: @JuliaWagemann

    View Slide

  3. Motivation
    3
    Over 25k repositories and over
    708k code contributions tagged with Jupyter
    notebooks on GitHub.
    It is ‘trendy’ to share code examples as
    Jupyter notebooks. Which is good. BUT:
    Reality: on the verge of ‘death by Jupyter
    notebooks’

    View Slide

  4. Reality ≠ reproducibility
    4
    Long code blocks
    without explanation
    Unorganized - e.g.
    libraries are loaded
    in the middle of a
    workflow
    Messy - no naming
    convention followed

    View Slide

  5. Overview - Key concepts
    ● Get organised!
    ○ Index notebook
    ○ Follow a naming convention
    ○ Navigation pane
    ● Layout and outline are key!
    ○ Header and Footer
    ○ Table of Contents / Notebook Outline
    ○ Alert boxes
    ○ Other styling options
    ● Outsource and modularize!
    ○ Example: functions
    5

    View Slide

  6. Get organized
    Index notebook
    6
    → 00_index.ipynb
    ● Gives an overview of
    what the notebooks are
    about
    ● Provides an outline and
    links to other notebooks
    with Markdown
    ● Links to additional
    (external) content

    View Slide

  7. Get organized - Follow a naming convention
    7

    View Slide

  8. Get organized - Navigation pane
    8
    html:
    << 01 - Example - How to NOT do
    it

    03 - Example - Functions >>

    View Slide

  9. Layout and outline are key - Footer and Header
    9
    Header
    Footer
    html:
    align='right' width='80%'>

    View Slide

  10. Layout and outline
    are key
    Table of contents
    → 02_jupyter_notebooks_key_concepts.ipynb
    ● Helps your audience to
    navigate through the
    notebook
    ● Provides an overview of the
    notebooks main headings
    ● Helps you audience to
    direct straight to a
    specific section
    Markdown link:
    [GET ORGANIZED](#get_organized)
    html ... statement :
    ## GET
    ORGANIZED

    View Slide

  11. Layout and outline
    are key
    Alert boxes
    → 02_jupyter_notebooks_key_concepts.ipynb
    ● Colorize a cell based on
    ‘alert-levels’
    ● There are four different
    ‘alert-levels’:
    ○ Alert-warning (yellow)
    ○ Alert-success (green)
    ○ Alert-danger (red)
    ○ Alert-info (blue)

    NOTE: Alert level 'warning' colorizes a cell
    yellow.

    View Slide

  12. Layout and outline
    are key
    Other styling options
    → 02_jupyter_notebooks_key_concepts.ipynb
    ● - Horizontal rule

    - Space cell
    ● `code` - Text formatted as
    code

    View Slide

  13. Outsource and modularize - Example: functions
    → functions → 02_jupyter_notebooks_key_concepts
    def generate_geographical_subset(xarray, latmin, latmax,
    lonmin, lonmax):
    """
    Generates a geographical subset of a xarray DataArray
    Parameters:
    xarray (xarray DataArray): a xarray DataArray with
    latitude and longitude coordinates
    latmin, latmax, lonmin, lonmax (int): boundaries
    of
    the geographical subset
    Returns:
    Geographical subset of a xarray DataArray.
    """
    return xarray.where((xarray.latitude < latmax) &
    (xarray.latitude > latmin) & (xarray.longitude < lonmax)
    & (xarray.longitude > lonmin),drop=True)
    from ipynb.fs.full.functions import
    generate_geographical_subset
    ?generate_geographical_subset

    View Slide

  14. Overview - Key principles
    ● Know your audience
    ● Simplify code
    ● Jupyter notebooks ≠ reproducibility
    ● Four eyes see better than two - Quality assurance

    View Slide

  15. Reproducibility does not happen by
    chance
    Reproducibility is going the ‘extra mile’

    View Slide

  16. thanks
    1
    6
    Julia Wagemann
    Independent consultant and PhD
    candidate
    Website: jwagemann.com
    Twitter: @JuliaWagemann
    GitHub: github.com/jwagemann

    View Slide