`jellycell.api`¶

The jc.* API — what notebook cells import (spec §2.4).

Every call has two modes:

Inside a run (jellycell.run.context.get_context() returns a non-None): resolves paths relative to the project root, and side effects (artifacts, declared deps, caption/notes/tags metadata) are picked up by the runner.
Standalone (no run context): falls back to a plain file op, no manifest side effect.

Module Contents¶

Functions¶

`save`	Write `obj` to `path`. Format inferred from suffix unless overridden.
`figure`	Save a matplotlib figure, or register a pre-rendered image at `path`.
`table`	Save a tabular (pandas DataFrame) to a parquet artifact.
`load`	Load an object from `path`. Format inferred from suffix.
`path`	Resolve a named artifact path.
`deps`	Declare explicit deps for this cell (spec §2.4).
`cache`	Memoize an expensive function via the cache store (spec §2.4).

Data¶

ctx

Singleton for jc.ctx access from cell code.

API¶

Write obj to path. Format inferred from suffix unless overridden.

Supported formats: parquet, csv, json, pkl, png. Duck-typed — the caller’s object must support the corresponding method (e.g., to_parquet for pandas DataFrames).

caption / notes / tags are optional metadata — inside a run they’re attached to the produced artifact’s :class:ArtifactRecord and surfaced in tearsheets. Standalone: ignored (no manifest to write to).

Save a matplotlib figure, or register a pre-rendered image at path.

Two modes:

Render — fig= given, or omitted with plt.gcf() available: the figure is saved to path (or a sensible default if path is None, honoring [artifacts] layout).
Path-only — fig omitted and path points to an existing image file: no matplotlib re-encode. The file is registered as an artifact (metadata attached) and displayed inline via IPython. This is the idiomatic form for verbatim-mirror analyses where figures are pre-rendered on disk.

caption / notes / tags flow into the artifact’s

Class:: ArtifactRecord and show up in tearsheets alongside the image.

jellycell.api.table(df: Any, *, caption: str | None = None, notes: str | None = None, tags: list[str] | None = None, name: str | None = None) → pathlib.Path¶

Save a tabular (pandas DataFrame) to a parquet artifact.

Like :func:figure, the default path honors [artifacts] layout and caption / notes / tags flow into the artifact’s manifest record.

Object columns with mixed types (e.g., a p-value column holding both "<.001" strings and numeric floats) are automatically cast to string before serialization — pyarrow rejects mixed dtypes with a cryptic error deep in the parquet writer, and the information loss of treating everything-as-string is minimal for the common regression-output case. Pure-string and pure-numeric object columns are left untouched.

jellycell.api.load(path: str | pathlib.Path) → Any¶

Load an object from path. Format inferred from suffix.

Inside a run, also registers a dep edge on the producing cell (looked up via :meth:CacheIndex.find_producer) so the caller’s cache key incorporates the producer’s state. Best-effort: if the artifact has no recorded producer yet, the load still succeeds without a dep edge.

jellycell.api.path(name: str) → pathlib.Path¶

Resolve a named artifact path.

If name matches a known cell’s name (via the artifact lineage index), returns the path of the artifact that cell produced. Otherwise falls back to <artifacts>/<name>.

jellycell.api.deps(*names: str) → None¶

Declare explicit deps for this cell (spec §2.4).

At runtime this is a no-op — the runner AST-walks cell source statically to find these calls before execution (spec §2.5). Runtime tracking is kept as a fallback for dynamic cases.

jellycell.api.cache(fn: Any) → Any¶

Memoize an expensive function via the cache store (spec §2.4).

Inside a run: keys on (qualname, normalized source, pickled args) and persists the pickled return value alongside cell outputs.

Standalone (no RunContext): identity passthrough — no caching.

jellycell.api.ctx¶

‘_Ctx(…)’