How I Structure My Jupyter Notebooks

Below is how I organize my “daily” notebooks:

  1. Filename = <date of creation>_<initials>_<s1-3 work description>.ipynb

  2. Title

    • <Date of notebook creation> <1-5 word description>n Analysis by <full name>

  3. To Do List

    • Write this first before any code/exposition

    • Not everything on the todo list will be completed. Don’t remove items that weren’t successfully done. If there’s an important reason for not completing an item, record it in the take-aways section.

  4. Take-Aways

    • Most exposition comes here.

  5. Closed Questions

    • These should have both the questions and the answers. Having this section promotes one to actually answer the questions.

  6. Open Questions

    • Put vague thoughts here

  7. Import statements

  8. Load Data

  9. Functions

  10. Code outputting text/visualizations

Note

I try to not spend more than ~36 hours on a notebook. Usually it’s one day working in the notebook and a few hours in the morning editing. After some notebooks have been completed I save them as html and pdfs.

Note

One should be on a regular basis restart and clear all outputs of the cell to avoid mistakes coming from hidden states.

Warning

I freely violate many standard SWE best practices (most notably violations of DRY). I do however, adhere strictly to PEP8 and the Zen of Python