Better naming convention for Jupyter notebook - jupyter

Question

When naming a Jupyter notebook, if spaces are used, i.e.
This is my notebook.ipynb
then it renders very nicely when opened with the web browser. However, spaces are evil on the command line environment. But if instead:
This_is_my_notebook.ipynb
or
This-is-my-notebook.ipynb
then the title rendered does not look as good. Any suggestions for an alternative convention but still look somewhat nice?

Answer 1

This is really going to depend on your personal preferences, and use cases. Here is the approach I use:
My Approach
[#]_[2-4 word description]_[DS-initials]_[ISO 8601 date].ipynb
e.g.
- jupyter-notebooks
+ 1_exploratory_analysis_ag_2019-02-16.ipynb
+ 1_exploratory_analysis_jw_2019-02-19.ipynb
+ 1_exploratory_analysis.ipynb
+ 1_exploratory_analysis.py
+ 1_exploratory_analysis.html
+ 2_topic_modeling_ag_2019-02-20.ipynb
+ 2_topic_modeling.ipynb
+ 2_topic_modeling.py
+ 2_topic_modeling.html
+ dev_2019-02-15.ipynb
+ dev_2019-02-18.ipynb
+ dev.ipynb
+ dev.py
+ dev.html
Here I've got all the notebooks in a folder called jupyter-notebooks. Files and script outputs would generally live outside of this folder.
If applicable, notebooks are numbered in a logical order e.g. date first created. In many cases it will not make sense to number the files (e.g. this repo of mine).
Notebooks are versioned with timestamps and (optionally) initials of the most recent author. This can be done automatically with a post-save hook (see below).
Non timestamped versions of the notebooks have .py and .html versions. By committing the .py files to git, you can get some benefits of version control. These files can also be generated with a post-save hook.
Miscellaneous development work can be put in dev... files.
I have a post-save hooks set up to automate this. In my configuration file (~/.jupyter/jupyter_notebook_config.py) I've got:
import os
from subprocess import check_call
import glob
import datetime
import re
def timestamped_file(fname):
return bool(re.match('.*\d{4}-\d{2}-\d{2}\.ipynb', fname))
def post_save(model, os_path, contents_manager):
if model['type'] != 'notebook':
return # only do this for notebooks
# Post-save hook for converting notebooks to .py scripts
d, fname = os.path.split(os_path)
if not timestamped_file(fname):
check_call(['jupyter', 'nbconvert', '--to', 'script', fname], cwd=d)
check_call(['jupyter', 'nbconvert', '--to', 'html', fname], cwd=d)
# Post-save hook for saving datestamped versions of the notebook
notebooks = glob.glob('*.ipynb') + glob.glob('jupyter-notebooks/*.ipynb')
if notebooks:
latest_mod_file = max(notebooks, key=os.path.getctime)
# Don't do this for datestamped notebooks
if not timestamped_file(latest_mod_file):
date = datetime.datetime.now().strftime('%Y-%m-%d')
fname_timestamped = '{}_{}.ipynb'.format(os.path.splitext(latest_mod_file)[0], date)
check_call(['cp', latest_mod_file, fname_timestamped])
c.FileContentsManager.post_save_hook = post_save
If saving a non-timestamped file, this will automatically convert to .py and .html, and make a timestamped version.
Another Approach
My convention was heavily inspired by this blog post. They describe conventions that I began using a couple years ago before adopting my own variation.
Here's the example they include:
- develop
+ [ISO 8601 date]-[DS-initials]-[2-4 word description].ipynb
+ 2015-06-28-jw-initial-data-clean.html
+ 2015-06-28-jw-initial-data-clean.ipynb
+ 2015-06-28-jw-initial-data-clean.py
+ 2015-07-02-jw-coal-productivity-factors.html
+ 2015-07-02-jw-coal-productivity-factors.ipynb
+ 2015-07-02-jw-coal-productivity-factors.py
- deliver
+ Coal-mine-productivity.ipynb
+ Coal-mine-productivity.html
+ Coal-mine-productivity.py
As you can see, there are separate folders (and naming conventions) for the development and delivery notebooks.

Answer 2

I found myself searching for this answer as well...
I scoured through some popular GitHub repositories involving .ipynb files, under the pretense of the work being reputably standardized. I found that there was no standard between utilizing dashes and underscores; however, I didn't see any notebooks using spaces - so don't do that.
Sources:
https://github.com/IRkernel/IRkernel/tree/master/example-notebooks
https://github.com/rlabbe/Kalman-and-Bayesian-Filters-in-Python/tree/master/Supporting_Notebooks