Skip to main content

Integration guideSeal API and Scripts

Jupyter Notebook

Link notebook versions and analysis outputs to experimental records.

Illustration of a seal beside a laptop showing a data table and an evidence binder linked by a red thread.

Jupyter Notebook to SealSeal API and Scripts

Seal reads
Exported .ipynb notebooks and their outputs
Writes back
If agreed
Source of truth
Agreed when scoped
Set up
Scoped with your team
Neil › Analysis record
draft

Keep this analysis together with its input records.

Neil

  • Once the connection is configured, I’ll use the records it provides and cite each one. Anything it doesn’t supply stays listed as missing.
Reads
Exported .ipynb notebooks and their outputs
Returns
  • Inputs, analysis outputs and reproducibility context
  • Missing or unmatched information
  • Next steps for your team to review
Illustrative work with Jupyter Notebook: a request to Neil, the source it reads and the draft it returns for your review.

1What’s connected.

Link Jupyter notebooks and their outputs to experimental records in Seal through exported .ipynb files or Seal’s API. Keep the notebook version, inputs and parameters with each result so the analysis can be reproduced.

Connection setup and permissions

Use Seal’s APIs or scripting engine for a connection tailored to your process. Agree the data mapping, access and direction of transfer before implementation.

Related blueprints

2Read what an .ipynb file says about how a result was made.

Route

A notebook is a JSON file with the .ipynb extension, holding text, code, rich output and metadata in cells. As plain text it can be version-controlled.⁠¹²

Record identity

A notebook’s top-level keys are metadata, nbformat, nbformat_minor and cells, and since nbformat 4.5 every cell has an ID unique within the notebook.⁠³ Metadata may name the kernel’s language and its version in language_info, but every metadata field is optional.⁠³

Outputs

A code cell stores its source, the outputs from running it and an execution_count, which may be null. The count comes from the kernel’s counter, which only goes up.⁠³⁴ jupyter nbconvert --to notebook --execute runs a notebook again and writes the new outputs to a separate file, unless --inplace is given.⁠⁵

When it fails

A cell raised an error
By default nbconvert stops when a cell raises, and the saved notebook holds the output up to that cell, with the traceback.⁠⁶ Attach a result only from a run without errors, and keep the failed run with its traceback if the investigation needs it.
The counts are out of order
Since the counter only goes up, counts that do not rise down the page mean cells ran out of order or more than once.⁠⁴ Run the notebook again from the top with nbconvert before attaching it.

Check one record

Take one notebook attached to an experiment in Seal and rerun it with nbconvert into a new file. The outputs, and the input records it names, should match the attached copy, and the execution counts should run 1, 2, 3 down the page.

3Start with the job.

Tell us what Neil needs to do and which records it needs. We’ll confirm the interface, permissions and implementation scope with your team.

Discuss this connection →

4Before it goes live.

Access and any write-back

Define which records are in scope and whose permissions apply. Whether the connection writes back at all is a separate decision, with its own mapping and approval.

Verification and release

Review the configured connection for its intended use. Keep the requirements, checks and evidence with the change, and approve the release through your team’s controls.

Read the assurance detail →

References

  1. 1Jupyter: nbformat.
  2. 2Jupyter Notebook: the notebook.
  3. 3Jupyter: notebook file format.
  4. 4Jupyter: messaging in Jupyter.
  5. 5nbconvert: using the command line.
  6. 6nbconvert: executing notebooks.