notebook-to-script

name	notebook-to-script
description	Refactor an exploratory Jupyter notebook into a single runnable Python script while preserving the scientific "meat". Use when converting an .ipynb to a standalone script for batch/HPC execution.

Notebook to Script

Treat the notebook as a prototype spec. Your job is to extract the scientific logic and wrap it in a standalone script that follows script-opinions.

Prerequisite: load script-opinions for style, logging, run-dir, and skeleton rules. This skill covers only the conversion protocol.

Output contract

• Return one runnable Python script in a single code block.
• Do not output a worker/sbatch shell script unless explicitly requested (see the job-dispatch skill, if needed).
• Preserve scientific logic as-is. Refactor aggressively around it, not through it.

Protocol

1) Ingest

Convert .ipynb to script text via the bundled scripts/notebook_ingest.py or jupyter nbconvert --to script. Read the result into context before reasoning.

2) Audit — objective, I/O, hidden state, hazards

• Objective — one sentence.
• Inputs / outputs — files, dirs, env-vars, formats; what's written and where.
• Hidden state — globals mutated across cells, implicit CWD, sys.path.append, cells that depend on earlier cells being run manually, variables carried from a prior kernel, relative paths assuming the notebook's CWD.
• Hazards — large I/O, multiprocess + HDF5, GPU memory, long loops.

3) Promote parameters

Classify each literal / hardcoded value. When uncertain, expose via CLI.

Category	Destination
Sweepable parameter	argparse argument
Path	argparse argument
True invariant	Module-level constant
Loop index / bookkeeping / intermediate	Local variable

4) Restructure

Fit the extracted code into the script-opinions skeleton. The notebook's meat goes into run_experiment(...) with minimal edits — only change code to eliminate notebook-only constructs, remove reliance on globals, route outputs into the run dir, and expose hyperparameters via argparse. Leave ugly-but-correct scientific logic alone.

Any meaningful refactorings or code changes must be explicitly approved by the user/manager. Ask, if you are unsure. The goal is to preserve the original logic, exactly.

5) Headless conversion

Notebook	Script
print(...)	logger.info(...)
plt.show()	savefig(...) + close(fig) (behind --save-plots if optional)
display(df)	df.to_csv(filepath_out) or logger.info(df.to_string())
inline cell outputs, magics	drop

Tools

Bundled Python helpers live in scripts/ (e.g. notebook_ingest.py). Use them to convert .ipynb to script text before reasoning.