VeraTracer vs notebooks
Notebooks are the default tool for exploratory analysis, and deservedly so. This page is about the one thing they are genuinely bad at — and it happens to be the thing VeraTracer is built around.
What notebooks are better at
Worth saying first, because it is true and because a comparison that pretends otherwise is not worth reading:
- Narrative. Prose, maths and code interleaved is a genuinely good way to explain a result to a person. VeraTracer has no answer to that.
- Plots inline. Seeing a chart next to the code that produced it is hard to beat for exploration.
- The ecosystem. Any Python library, immediately. VeraScript has four statements.
- Teaching and reporting. A notebook is a document. A VeraScript file is a pipeline.
If your work is mostly explaining, a notebook is the right tool and this page is not an argument against it.
The problem: hidden state
A notebook has two orders — the order cells appear on screen, and the order you actually ran them. Nothing keeps those in sync. The variables in memory are the product of whatever sequence of executions happened to occur, including cells you have since edited or deleted.
This produces a specific, familiar failure:
- You run cells 1 through 8 and get a number you like.
- You go back and fix a filter in cell 3.
- Cells 4 to 8 still hold values computed from the old filter.
- You either re-run everything from the top — paying full cost for a one-line change — or you re-run selectively and quietly carry a mixture of old and new state.
The second option is the dangerous one, because nothing about the notebook looks wrong afterwards.
What VeraTracer does instead
The script is the single order of execution. Steps become checkpoints derived from the file itself, so there is no second source of truth to fall out of sync. Re-running means selecting a range, and everything outside that range keeps state it already computed.
The trade is real and worth stating plainly: you give up a general purpose language and inline plots, and you get history that cannot lie to you.
Side by side
| Task | Notebook | VeraTracer |
|---|---|---|
| Re-running one step | Re-run the cell — but every downstream cell now holds stale values until you remember to re-run those too. | Pick a checkpoint range. Steps outside it keep their computed state; nothing goes stale. |
| Trying a second approach | Duplicate the notebook, or comment out the old cell and hope you can reconstruct it. | Branch from a checkpoint. Both versions keep their own results, side by side. |
| Going back | Restart the kernel and re-run from the top. | Rewind. Recorded state is restored, so it costs the same whether the step took 20ms or 20 minutes. |
| What ran, in what order | Execution counts, if nobody has cleared them. Cell order on screen need not match order of execution. | The file is the order. Checkpoints are derived from it, so they cannot disagree. |
| Reviewing a change | A JSON diff containing outputs, metadata and base64 images. | A text diff of a .verascript file. |
| Handing it to someone else | Works if they have the same environment, the same data paths and run the cells in the right order. | A script plus a project folder. |
When to stay where you are
Do not switch if:
- You need libraries. VeraScript does not have
scikit-learn, and pretending otherwise would waste your afternoon. - Your output is a document for humans rather than a dataset.
- Charts are the point of the work.
Consider it if:
- You have re-run an expensive pipeline because you changed its last step.
- You keep several near-identical copies of the same analysis to compare approaches.
- You have ever shipped a number and been unable to reconstruct exactly how it was produced.
The clearest way to see the difference is the worked example, where the first hypothesis turns out to be wrong and the branch is what saves the afternoon.