Jupyter notebook automation

The hera_stats.automate module contains functions to replace placeholder variables in template Jupyter notebooks (jupyter_replace_tags) and run them programmatically (jupyter_run_notebook).

hera_stats.automate.jupyter_replace_tags(fname_tmpl, replace, outfile=None, overwrite=False, verbose=False)[source]

Search through a Jupyter notebook file for tagged lines, replace them with new values, and then save into a new Jupyter notebook.

Tags work in a simple way: If any line in the notebook has an in-line comment of the form ‘# @tag’, and a key ‘tag’ exists in the ‘replace’ dict, the entire line will be replaced with ‘tag = value’, where ‘value’ is the value of ‘replace[key]’, which is assumed to be a string. Any expression that was on that line will be completely replaced.

Parameters:
  • fname_tmpl (str) – Filename of input notebook that contains tags to be replaced.
  • replace (dict) – Dictionary of tag:value pairs. The values will all be inserted as Python strings, and so the code in the Jupyter notebook should be prepared to do a type conversion if necessary.
  • outfile (str, optional) – Filename to save the tag-replaced notebook to. If not specified, the updated JSON dict will be returned from this function. Default: None.
  • overwrite (bool, optional) – If outfile is not None, whether to overwrite a notebook file if one with the same filename already exists. Default: False.
  • verbose (bool, optional) – If True, print out tags as they are found. Default: False.
Returns:

new_tree – If outfile=None, a dict containing the updated JSON data for the notebook is returned.
Return type:

JSON dict, optional
hera_stats.automate.jupyter_run_notebook(tree=None, fname=None, outfile=None, rundir='.', version=4, kernel='python3')[source]

Run a Jupyter notebook programatically. The notebook to run can be passed as either a filename or a dict derived from JSON data.

If the notebook experiences an error, a CellExecutionError will be raised. The notebook will still be saved to disk even if it errors though.

Parameters:
  • tree (dict, optional) – Dict containing JSON tree representing a Jupyter notebook.
  • fname (str, optional) – Filename of Jupyter notebook to load. Only one of ‘tree’ and ‘fname’ should be specified.
  • outfile (str, optional) – File to store Jupyter notebook into after it has run. Default: None (no notebook file will be saved).
  • rundir (str, optional) – Directory to run the script from. Default: ‘.’ (current directory).
  • version (int, optional) – Version of Jupyter notebooks to use.
  • kernel (str, optional) – Name of Jupyter Python kernel to use. Default: ‘python3’.