nbparameterise Library

Common errors

• ModuleNotFoundError: No module named 'nbparameterise'

  cause The nbparameterise library is not installed or not available in the current Python environment.
  fix Run `pip install nbparameterise` to install the package.

• FileNotFoundError: [Errno 2] No such file or directory: 'your_notebook.ipynb'

  cause The input notebook file path provided to `execute_notebook` does not exist or is incorrect.
  fix Verify the path to your input notebook (`your_notebook.ipynb` in the example). Ensure the file exists and the path is absolute, or correct relative to your current working directory.

• NotebookExecutionError: Kernel died during execution.

  cause The Jupyter kernel used to execute the notebook crashed. This often indicates an unhandled error within the notebook's code, excessive memory usage, or a missing dependency required by the notebook itself.
  fix Debug the notebook interactively in a Jupyter environment (e.g., Jupyter Lab or Notebook) to identify the specific cell or error causing the crash. Ensure all dependencies required by the notebook's code are installed and available in the execution environment where `nbparameterise` is run.

Warnings

• breaking Dropped Python 3.7 support.
  Fix: Upgrade your Python environment to 3.8 or newer to use nbparameterise versions 0.6.0 and above.
• deprecated The direct function `run_notebook_dir` was removed and replaced by methods within the `parameterise` object.
  Fix: Update your code to use `from nbparameterise import parameterise, execute_notebook` and then call `execute_notebook(notebook, path)` instead.
• gotcha Parameters are only reliably recognized if defined in the first *code* cell of the notebook.
  Fix: Ensure all variables intended as parameters are assigned in the very first executable code cell. While not strictly required by the library, adding `# Parameters` as a comment in that cell helps for readability and tool recognition.
• gotcha Notebook execution requires an active Jupyter kernel in the environment.
  Fix: Ensure 'ipykernel' is installed (`pip install ipykernel`) in the Python environment where `nbparameterise` is being run. If using virtual environments or different kernels, verify the correct kernel is available and registered.

Install

• pip install nbparameterise Install latest version

Imports

• parameterise
  wrong:

  from nbparameterise import run_notebook

  correct:

  from nbparameterise import parameterise

  'run_notebook' was an older entry point and has been deprecated/removed in favor of 'parameterise.execute_notebook'.
• execute_notebook
  wrong:

  from nbparameterise import run_notebook_dir

  correct:

  from nbparameterise import execute_notebook

  'run_notebook_dir' was an older function that has been replaced by 'execute_notebook'.

Quickstart

This quickstart demonstrates how to programmatically define, parameterise, and execute a Jupyter notebook using `nbparameterise`. It creates a dummy notebook, overrides its initial parameters, executes it, and then prints the output, finally cleaning up generated files. Ensure `ipykernel` is installed for successful execution.

import os
from nbparameterise import parameterise, execute_notebook
import nbformat

# 1. Define the input notebook content (as a string) that includes parameters
input_notebook_content = """
{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Parameters\n",
    "x = 10\n",
    "y = 'hello'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(f'Original x: {x}')\n",
    "print(f'Original y: {y}')\n",
    "result = x * 2\n",
    "print(f'Result: {result}')"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.x.x"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
"""
# Define file paths
input_path = "quickstart_input.ipynb"
output_path = "quickstart_output.ipynb"

# Save the dummy input notebook file
with open(input_path, "w") as f:
    f.write(input_notebook_content)
print(f"Created input notebook: {input_path}")

try:
    # Load the notebook object
    with open(input_path) as f:
        nb = nbformat.read(f, as_version=4)

    # Extract current parameters and define new values to override them
    params = parameterise.extract_parameters(nb)
    new_params = parameterise.parameter_values(params, x=25, y="world!") # Override x and y
    parameterised_nb = parameterise.replace_definitions(nb, new_params)

    # Execute the modified notebook and save the output
    # Requires 'ipykernel' to be installed in the environment.
    execute_notebook(parameterised_nb, output_path)
    print(f"Notebook executed and saved to {output_path}")

    # Optionally, verify the output from the executed notebook
    with open(output_path) as f:
        output_nb = nbformat.read(f, as_version=4)
        print("\n--- Output Notebook Cells ---")
        for cell in output_nb.cells:
            if cell.cell_type == 'code':
                for output in cell.outputs:
                    if output.output_type == 'stream':
                        print(output.text.strip())

except Exception as e:
    print(f"Error during quickstart execution: {e}")
    print("Hint: Ensure 'ipykernel' is installed (`pip install ipykernel`) for notebook execution.")
finally:
    # Clean up generated files
    if os.path.exists(input_path):
        os.remove(input_path)
    if os.path.exists(output_path):
        os.remove(output_path)
    print("\nCleaned up generated files.")