Notebook Style Guide

Estimated Run Time: 5 seconds

This notebook is a self explanatory template. There should be a H1 Level header with the document name, the authors, the estimated run time, then a couple sentences explaining what the notebook is all about. After this introduction should follow a code block with all of the imports for the entire document, a code block describing the environment under which the notebook was run, a list of single cells describing the versions of the dependencies. For PyBEL, this is the PyBEL and PyBEL tools version numbers, and finally, any additional setup for running the notebook.

Imports



In [1]:

    
import sys
import time

import pybel
import pybel_tools

Environment



In [2]:

    
print(sys.version)









    



3.6.3 (default, Oct  9 2017, 09:47:56) 
[GCC 4.2.1 Compatible Apple LLVM 9.0.0 (clang-900.0.37)]



In [3]:

    
print(time.asctime())









    



Thu Mar 15 14:47:37 2018

Dependencies



In [4]:

    
pybel.utils.get_version()









    Out[4]:





'0.11.2-dev'



In [5]:

    
pybel_tools.utils.get_version()









    Out[5]:





'0.5.2-dev'

Setup



In [6]:

    
print('other code to set up the notebook, such as logging and file system management')









    



other code to set up the notebook, such as logging and file system management

Top Section

The top section has an H1 title, a line with the author(s) and links to their GitHub pages, then a short abstract. It's followed by the imports, organized to two sections - system libraries and external libraries. For these notebooks, the PyBEL version and the time of notebook run should be shown.



In [7]:

    
# code

Middle Sections

After the title, abstract, imports, and setup, there should be 1-3 H2 sections describing the actual work in the notebook. These sections are where code is written, but the markdown cells should be used to explain each block of code so if they are output without the code, it still makes sense. This means the output of the code should be illustrative of the explanation given in markdown. Pretty pictures are preferred!

If you're using more than 3 or 4 H2 section titles, consider that the notebook may have too much content. These notebooks should be vignettes. After the first main point, there may be more! Use H2 titles to help organize the main ideas of the document. For example, you might have sections for Data Acquisition, Analysis, Visualization, then Output.



In [8]:

    
# more code

Style

Code should be broken into notebook cells, hopefully not longer than 50 lines each. Between bits of code should be markdown explaining what's happening in the code, and why
As far as style goes, never use center-aligned text. Keep the markdown as minimalistic as possible so it can be interchangable in many formats
It's also preferred that python notebooks don't have any bash magic in them - do as much as you can with python code
If the input can be acquired from a stable internet source, that's preferred. If you have data that must be stored, then use the root-level /data folder.



In [9]:

    
# even more code

Conclusions

Each notebook should end with a conclusions section that has an H1 heading. This should also only be a couple sentences, describing what the notebook has shown and their implications. Please rerun your notebook before submitting it, so all of the numbers are chronological! It might also be useful to add an additional H1 section following the conclusion to give an appendix, or show more data.