Parameterize

Generally, the first workflow step when using papermill is to parameterize the notebook.

To do this, tag notebook cells with parameters. These parameters are later used when the notebook is executed or run.

Designate parameters for a cell

To parameterize a notebook, designate a cell with the tag parameters.

_images/parameters.png

Notebook

If using the Jupyter Notebook interface

  1. Activate the tagging toolbar by navigating to View, Cell Toolbar, and then Tags
  2. Enter parameters into a textbox at the top right of a cell
  3. Click Add tag

Lab

If using the JupyterLab interface

  1. Select the cell to parameterize
  2. Click the cell inspector (wrench icon)
  3. Edit the Cell Metadata field by adding "tags":["parameters"]

Learn more about the jupyter notebook format and metadata fields here. For easier management, consider using an extension such as jupyterlab-celltags.

How parameters work

The parameters cell is assumed to specify default values which may be overridden by values specified at execution time.

  • papermill inserts a new cell tagged injected-parameters immediately after the parameters cell
  • injected-parameters contains only the overridden parameters
  • subsequent cells are treated as normal cells, even if also tagged parameters
  • if no cell is tagged parameters, the injected-parameters cell is inserted at the top of the notebook

One caveat is that a parameters cell may not behave intuitively with inter-dependent parameters. Consider a notebook note.ipynb with two cells:

#parameters
a = 1
twice = a * 2
print("a =", a, "and twice =", twice)

when executed with papermill note.ipynb -p a 9, the output will be a = 9 and twice = 2 (not twice = 18).