Jupyter notebook best practices and style guide

This set of notebooks (the 'Guidelines') document some best practices and style conventions with regard to Jupyter/IPython notebooks that have emerged over the years at CBRD. We are open-sourcing this in order to share it with the community and allow others, especially others using notebooks in a scientific context, to adopt, adapt and adjust it to their liking, as well as to form the basis of a consensus style guide for Jupyter notebooks that can be a widely accepted guide for Jupyter style and best practices.

Table of contents

1. General part

1.1. General considerations (doc|nb|issues)
1.2. Markdown and document structure (doc|nb|issues)
1.3. Embedding (doc|nb|issues)
1.4. Data sources and database access (doc|nb|issues)
1.5. Using multiple languages in the same document (doc|nb|issues)

2. Python

2.1. General considerations (doc|nb|issues)
2.2. Functions, classes and type annotation (doc|nb|issues)
2.3. Plotting (doc|nb|issues)

3. R

3.1. General considerations (doc|nb|issues)
3.2. Functions and classes (doc|nb|issues)
3.3. Plotting (ggplot2 and built-in plotting types) (doc|nb|issues)

Contributing

There are multiple ways to contribute.

• One is by raising an issue to comment on a particular provision, share your experiences and discuss. Such discussions must follow a particular format (see template).
• Another is by correcting errors and updating the Guidelines as packages are updated, APIs change, etc.
• Finally, there will be 'flashpoint' questions. These will be open for 30 days, and involve two or more proposals for a particular issue being discussed, at the end of which one of the proposals will be accepted and implemented. These issues are tagged 'flashpoint'.

Adopting the Guidelines

You may adopt all or parts of the Guidelines at your institution or company free of charge and with no restrictions, other than that you must link to the original GitHub repo. You may adapt the Guidelines but you must not remove this notivce. We furthermore appreciate if you add your name below to the list of institutions and companies that have adopted these Guidelines.

Questions

For any questions, please ping us at the Data Engineering Steercom and put "Jupyter Guidelines" in the subject line.