Skip to content

Clerk

Experimental

The Clerk module (celldega.clerk and the celldega.viz.Clerk widget) is experimental. It is a proof of concept: its features, API and saved formats may change between releases, without deprecation. Check what it tells you against the data, as you would any draft.

Clerk is Celldega's AI tool for exploring and interpreting its visualizations. It isn't a separate service or an MCP server. It's a set of prompts, actions and light interface components that let Anthropic's Claude read and drive the visualizations you link to it (a Landscape, Clustergram or Enrich panel) and consult outside tools: Enrichr for gene-set enrichment and PubMed for the literature.

Clerk gathers the evidence (marker genes, enrichment, literature, the tissue image) and makes a case for a cell-type label, or answers your question, that you rule on. The name reads as both a law clerk (gathers evidence and drafts the reasoning; you decide) and a bodega clerk (fetches what you ask for).

Genes, clusters and cited views can be clicked to inspect the evidence in your widgets. The conversation can be exported with Snapshots: screenshots of the linked views, memos and reproducibility metadata, including observed evidence and supported replay settings. Full view restoration is not implemented yet. Clerk runs through your own Claude account, using the claude command-line tool on the machine running your notebook.

What Clerk can do

  • Read the visualizations. With each question, Clerk receives what the linked widgets show: the Landscape's image and state (camera, selection, cells and genes in view), the Clustergram's rows, columns, values and dendrogram groups, and the Enrich panel's results.
  • Drive the visualizations. It can highlight clusters, color cells by genes, zoom, move the Clustergram's marker level, and cite views you open with a click, returning to your own view with Return.
  • Look things up. Ranked marker genes and expression values from the Clustergram, enrichment from Enrichr, and the literature from PubMed.
  • Look at single cells. With a linked Yearbook, Clerk sees its cell portraits and can choose which cells it shows. Its main evidence stays the cluster signatures; single cells are small samples it looks at.
  • Answer questions from several kinds of evidence at once: the tissue image, gene expression, enrichment and papers, with the evidence behind each claim.
  • Annotate. It records tentative cell types, offers to label the Clustergram with them, and keeps the views it was shown as Snapshots (clerk.snapshots): images with the state to return to them.
  • Draft analysis notebooks. When you ask for new analysis, Clerk writes a Jupyter notebook for it (Scanpy, Squidpy, Celldega); when it thinks one would help, it suggests one and drafts it if you agree. You inspect and run it, or have Claude Code run it in a separate process; its results come back to Clerk to interpret. See Analysis notebooks.
  • Keep the record. Save and reopen a conversation, export it as a report, and start later work from an earlier one with a briefing.

So you and Clerk work on the same data with the same tools and leave the same kinds of artifacts: Snapshots for what you saw, notebooks for what you computed. Clerk's own role stays interpretation; it never runs code in your notebook, and you decide what to keep.

Requirements and logging in

Clerk sends your questions to Claude through the claude command-line tool (Claude Code), running on the same machine as your kernel and using your own Claude account. You need:

  • Claude Code installed on the machine running the kernel; see the setup guide.
  • A Claude plan that includes Claude Code (Pro or higher), or an Anthropic Console account billed per use. The free plan doesn't include Claude Code.

Log in once:

  1. Open a terminal on the machine running the kernel (JupyterLab: File → New → Terminal; VS Code: Terminal → New Terminal).
  2. Run claude auth login (add --console to use a Console account instead of a Claude plan).
  3. Sign in on the page that opens. If no browser opens, open the link it prints, sign in, and paste the code it shows back into the terminal.

The CLI remembers the login (in the macOS keychain, or its own credentials file on Linux), so no terminal needs to stay open afterwards. Celldega never sees or stores it. If the kernel runs on a remote server (e.g. JupyterHub), log in from a terminal on that server.

Check from Python, without calling the model:

import celldega as dega

dega.clerk.claude_auth_status()
# {'logged_in': True, 'auth_method': 'claude.ai', 'subscription_type': 'pro'}

If you ask a question while logged out, Clerk replies with these instructions instead of the CLI's raw error.

Quickstart (standalone)

Ask a question directly, passing whatever evidence you have:

import celldega as dega

answer = dega.clerk.ask(
    "What cell type is this cluster?",
    gene_list=["CD3D", "CD8A", "CD2", "TRAC"],
    info="Cluster 5, Xenium human lung",
)
print(answer)

Or use the widget for an interactive chat panel:

clerk = dega.viz.Clerk(gene_list=["CD3D", "CD8A", "CD2", "TRAC"])
clerk

Clerk pre-gathers Enrichr enrichment terms for the gene list (reusing Celldega's existing Enrichr integration) and folds them into the prompt as evidence — the model itself uses no tools, so results are fast and predictable.

Each question also carries the recent conversation, so follow-up questions keep their context: the last clerk.history_questions questions (default 10) with Clerk's replies and actions, within clerk.history_chars characters (default 40,000, about 10k tokens). It's sent once per question, so a longer memory costs little; screenshots and lookup results from earlier questions aren't included, only the text. Questions run in the background: the notebook stays usable while Clerk thinks.

What Clerk knows

Clerk only knows what each question sends it, so you can tell where an answer came from:

  • its instructions (dega.clerk.SYSTEM_PROMPT), whose examples use placeholders (cluster "A", GENE1) rather than real tissues or genes, so they can't hint at an answer;
  • the evidence gathered for the question (the linked views, your gene list and context, and the lookups Clerk asks for);
  • the recent conversation in this panel (see history_questions above). A new Clerk starts with none;
  • a briefing, if you load one (below).

Briefings: starting from earlier work

To give Clerk earlier conclusions to build on, load a briefing. It goes with every question under "Earlier work", introduced as claims to check rather than evidence, and the panel shows a "Briefing: …" line so it's always clear what Clerk was told:

clerk.load_briefing("clerk_files/kidney-exploration")  # an exported report folder
clerk.load_briefing("case1/record.json", "notes.md")     # several sources
clerk.load_briefing(other_clerk, append=True)            # another panel's conversation
clerk.load_briefing("celldega_files/snapshots")        # manual Snapshots
clerk.load_briefing("clerk_files/screenshots", append=True) # Clerk's Snapshots
clerk.briefing = "Cluster 7 looked mixed last time."     # or plain text
clerk.briefing = ""                                      # clear it

A record is summarized as each question with Clerk's final answer and the latest cell types; screenshots and lookup results are left out. Exported reports show the briefing Clerk was given. To carry over the visible conversation itself instead, copy it: clerk.messages = other_clerk.messages.

Every call is isolated from your own Claude Code setup: Clerk uses its own system prompt, no tools or MCP servers, none of your settings or hooks, the CLI's switches that turn off memory and CLAUDE.md files, and a throwaway working directory. Nothing from your other Claude Code sessions, memory or projects reaches it; only the CLI login is shared. The CLI itself adds your account's email address and today's date to each call.

The model's general training knowledge is the one thing you can't switch off. It may know public datasets and papers, so for a fair test of Clerk's reasoning use unpublished data, or leave dataset names out of context_info.

Efficiency

A conversation runs in one CLI session. The first question sends all the evidence. Each later call resumes the session and sends only what is new:

  • A follow-up round (after a lookup, or a view change Clerk asked to see) sends the lookup results, any view that changed, and a screenshot only if the view moved.
  • A new question sends only the linked views whose state changed since Clerk last saw them, and names the others as unchanged. It also sends what happened in the panel in between, such as labels applied or an analysis that ran. The Landscape's screenshot goes only with a changed Landscape. "Sent with" under your question marks the views that weren't resent "(unchanged)".

The API caches the conversation so far, so each later call re-reads it at about a tenth of the price. In a test with a 34k-token prompt, a follow-up cost $0.008 instead of $0.12. After clerk.max_session_questions questions (default 10), or when the context or briefing changes, the next question starts a new session. It sends everything again, with a text summary of the conversation so far. Reopening a saved conversation also starts a new session. Set clerk.continue_conversation = False to start a new session for every question.

The CLI saves the session's transcript so it can be resumed. Clerk deletes it when the conversation's session ends: a new session, a reopened conversation, or closing the widget. Transcripts left by a crashed kernel are removed after an hour.

Token use per question (and the CLI's cost estimate, which is notional on a Claude plan) is recorded in clerk.record[i]["usage"] and shown in exported reports.

Pick a model by alias ("opus", "sonnet", "haiku") or full id; a smaller model is cheaper and faster for routine questions:

clerk = dega.viz.Clerk(model="haiku")   # "" (default) inherits the CLI default

Reasoning effort is a separate setting ("low", "medium", "high", "xhigh", "max"): higher effort is slower and uses more tokens. Both have pickers next to the Ask button, or set them from Python:

clerk.model = "opus"
clerk.effort = "high"

Linking to other widgets

Clerk is standalone and wide by default, and you link it to whatever widgets you have — they can live in other notebook cells. Widgets are modular and swappable; the usual case is Landscape + Clustergram (optionally Enrich). Link from the constructor:

landscape = dega.viz.Landscape(base_url="...", adata=adata)
cgm       = dega.viz.Clustergram(adata=adata)

clerk = dega.viz.Clerk(landscape=landscape, clustergram=cgm)
clerk   # display the wide Clerk panel wherever you like

or after the fact with link_clerk:

clerk = dega.viz.Clerk()
dega.viz.link_clerk(clerk, landscape=landscape, clustergram=cgm)

Sidecar or wide

To lay Clerk out with the views, linked, pass it to spatial_clustergram. By default it becomes a sidecar: a narrow column at the end of the row, the row's height, the way an Enrich panel sits beside the Clustergram. clerk_layout="wide" puts it full width under the row instead.

dega.viz.spatial_clustergram(landscape, cgm, clerk=True)                 # sidecar
dega.viz.spatial_clustergram(landscape, cgm, enrich=True, clerk=True)    # with Enrich
dega.viz.spatial_clustergram(landscape, cgm, clerk=clerk, clerk_layout="wide")

clerk=True creates a Clerk (pass its options as clerk_kwargs), or pass one you made. A sidecar sizes itself: it takes the room the row leaves, between 240 and 300 px, and the Landscape, Clustergram and Enrich keep their full widths. A row wider than the notebook scrolls sideways, with room under it for the scrollbar. A Clerk with its own width keeps it. When the panel is narrow, the question box takes its own line, with the model and effort pickers below.

Once linked:

  • selecting a cluster/gene set in the Clustergram flows the genes into clerk.gene_list;
  • each time you ask a question, the current Landscape view is captured and sent as image evidence, including the exact zoom/pan (see below). Pan and zoom, then ask "what's in this field of view?"

Clerk only sees the widgets you link. In the conversation, each question shows the Landscape and Clustergram Snapshot previews, side by side, and a "Sent with" line listing the rest, so you can see exactly what Clerk received. If a linked widget doesn't reply (for example, it isn't displayed), Clerk is told so and says it rather than guessing.

With a linked Enrich panel, each question carries the enrichment results on screen: the library, input genes and their source, the top terms with combined score, adjusted p-value, odds ratio and overlapping genes, the selected term, and the Enrichr link. Clerk then stops running its own Enrichr query.

With a linked Clustergram, each question also carries a state summary of what the Clustergram shows: the clusters and genes on screen (with their attributes, such as leiden, cell_type or leiden_marker), each axis's order, the marker level (DIM slider), the dendrogram groups at the current cut, the selection, and a capped table of values and dot sizes for what's on screen. Genes you name in a question, or that Clerk named in its previous answer, are added to that table when the Clustergram has them, so "check MUC2 and TFF3 across clusters" works even if they're off screen. Choose what it describes with clerk.clustergram_options, e.g. {"rows": "ranked", "max_rows": 25} for the top of the current order instead of what's on screen.

The same state summary is available on its own:

cgm.request_state()                       # rows/cols on screen
cgm.request_state(rows="ranked", cols=["4", "5"], max_rows=25)
# ...in a later cell, once the browser has replied:
cgm.latest_state                          # plain dict; never saved into the notebook

In JavaScript (e.g. a web app embedding Celldega), the Clustergram instance returned by matrix_viz exposes the same state summary synchronously as matrix.get_state(options).

How Clerk answers

Clerk is instructed to be very brief: the answer in a sentence or two, then an optional Evidence list of at most five bullets, which the panel shows collapsed. It is also conservative: before naming a cell type it checks each relevant cluster's top ~25 ranked markers, canonical markers for the candidate type and its alternatives, and enrichment in more than one library, and it states a confidence. It starts from morphology and anatomy, treats the sample's diagnosis (e.g. "colorectal cancer") as a description of the whole sample rather than of the region in view, does not call a region abnormal without evidence specific to that, and says when a canonical marker isn't in the panel (unmeasured is not absent). The instructions are in celldega/clerk/prompts.py (dega.clerk.SYSTEM_PROMPT).

The conversation panel

Each question is a collapsible turn:

  • the question, with Landscape and Clustergram Snapshot previews and a "Sent with" line;
  • Work · N steps (collapsed): the lookups and view changes Clerk made and any interim replies; open while Clerk is working;
  • Clerk's answer, with its Evidence collapsed;
  • Enrichr results, each folded under a title such as "Enrichr · Cluster 4 upregulated";
  • what Clerk recorded or changed alongside the answer (one short ↻ line each, with the details, such as each cluster's cell type, in the turn's Evidence), and any errors.

Genes selected in the linked views still go with your next question. Enrichr results appear in the conversation alongside Clerk's answer.

If the answer ends with a yes/no question ("Check cluster 7's top 25 markers?"), Yes and No buttons answer it. Expand / Collapse open or close every turn, work log and evidence section at once (handy before searching the page), and the panel remembers the ones you opened or closed. Report saves the conversation as a report (see Taking the record with you).

Evidence you can click

Everything Clerk cites can be replayed in the linked widgets, right away and even while it's still answering:

  • Snapshot previews: Show this view below a preview returns that widget (the Landscape or the Clustergram) to the view Clerk was sent, and Show both views restores both. You can navigate elsewhere and use these links to revisit the images' state. Return returns to where you were before following the link. These links are kept when saving and reopening the conversation; older images without a saved state have no link.
  • Genes (blue, dotted underline): hover for the UniProt name and description, as in the other widgets; click to color the Landscape by the gene, mark it in the Clustergram (blue row label) and zoom the Clustergram to it. Shift-click adds or removes genes, to compare several; clicking the only gene shown again returns to cluster colors.
  • Clusters ("cluster 4", "clusters 4, 5 and 12"): hover for the label you or Clerk gave it; click to highlight it in the Landscape, shift-click to add more.
  • Gene lists in Clerk's work log ("Looked up 16 genes"): hover to list them, click to show them in the Landscape (up to 20).
  • Cited views ("[Fig 1A]"): for a point that needs a particular view (a zoom, genes together, a marker level, a dendrogram group), Clerk defines the view and links it like a figure. Hover for its caption and what it shows; click to apply it to the Landscape and Clustergram. Nothing changes until you click. Genes and clusters named inside a cited view's link are still links of their own.
  • Dendrogram groups: when Clerk discusses a group ("group 39"), it can cite a view that selects it again. The view keeps the dendrogram cut the group was seen at, so the group's name and members still match when you click it later.

Before the first link, Clerk saves the supported Landscape and Clustergram settings. Return reapplies them, including Clustergram pan/zoom, crop and order, and Landscape layers, channels and sliders. See the remaining replay limitations. In an exported report, each cited view becomes a numbered figure under the answer with the apply_state code that applies its settings, and the "[Fig 1A]" link jumps to it. Cited views do not yet get their own rendered images on export.

Back now validates the saved view's data fingerprint and waits for browser completion. If a dataset has changed or restoration fails, Clerk keeps the saved view for retry. Within the same session it checks loaded data without re-downloading remote assets. Conversation captures include portable Snapshot envelopes, so reports can use restore_snapshot when reopening evidence on compatible, freshly constructed widgets. The host contract describes the widget-independent loop and celldega-app integration points.

Lookups

While answering, Clerk can look things up without changing anything you see; each lookup appears in the conversation as a "↻" line:

  • Ranked markers: a cluster's top-N up-regulated genes (rank_genes_groups) with their value and dot size, whatever the DIM slider shows. The Matrix sends each cluster's ranked markers to the Clustergram front end for this.
  • Genes: specific genes' values and dot sizes across all clusters.
  • Enrichr: a cluster's top markers, or any gene list, against Enrichr libraries (CellMarker_2024 and PanglaoDB_Augmented_2021 by default). This calls the Enrichr web service directly; the Enrich panel is not changed.
  • PubMed: literature searches through NCBI's public E-utilities (titles and abstract excerpts); Clerk cites PMIDs as links.

From Python, cgm.request_state(markers={"clusters": ["4"], "n": 25}) reads the same ranked markers, and dega.clerk.lookups.enrichr(...) / dega.clerk.lookups.pubmed(...) run the web lookups.

Enrichr results in the conversation

Enrichr results are drawn in the conversation, under the answer, like the Enrich panel and folded under a title ("Cluster 4 upregulated", "6 selected genes"): a library picker, a scrolling bar graph of the top 20 terms by combined score, a paragraph of the genes tested, and a View full results on Enrichr link to the same list on the Enrichr website. Hover a bar for its statistics; click it to color the paragraph as Enrich does (the term's genes blue, the rest dark gray) and show the term's genes on the Landscape and Clustergram, and click again to clear. Picking another library asks Enrichr from the browser. Genes in the paragraph work like Clerk's other gene links. This covers both Clerk's own Enrichr lookups and the panel's Enrichr results for the selected genes, shown once per gene list. The model reads the top 8 terms as text, with the Enrichr link, which it can cite; the drawing is for you.

Enrichr and PubMed results are cached. Later questions see earlier Enrichr results in the conversation's history, so Clerk reuses them rather than asking again, and every result is kept on disk in <output_dir>/lookup_cache (clerk_files/lookup_cache by default). A lookup made in an earlier session is read from there instead of sent to Enrichr or PubMed again. Set clerk.lookup_cache = None to keep results for the session only.

Recording cell types

When Clerk proposes cell types (for example when you ask what a cluster might be), it records them, together with the marker genes it relied on: "↻ Recorded tentative cell types for 3 clusters", with each cluster's cell type in the turn's Evidence. With a Clustergram linked, Clerk then asks Label these clusters in the Clustergram (cell_type)?; Label makes the cell types tentative column labels (in the manual column category, or clerk_cell_type if none is set up) and marks the marker genes with their cell type on the rows (the manual row category, or clerk_marker), in the same color as the column. If you asked Clerk to label the clusters, it labels them right away. Labels you set yourself are never overwritten, and when Clerk relabels a cluster it clears the marks it made for the old label. clerk.label_clustergram = True always labels right away, and False never labels.

Get the cell types as a table or write them to an AnnData (cell-level, or the cluster-level signature AnnData behind a Clustergram):

clerk.findings_df()          # cluster, label, confidence, markers, notes, question, time
clerk.write_cell_types(adata, groupby="leiden", key="clerk_cell_type")

write_cell_types only adds a column (pass overwrite=True to replace one), fills clusters without a proposal with Unassigned, and records the labels used in adata.uns["clerk_cell_types"].

Looking at single cells in a Yearbook

Link a Yearbook and each question also sends Clerk its portraits: the query, page, the cells on screen and an image of them, shown under your question. Clerk can choose which cells the Yearbook shows, in one of two ways:

  • The Yearbook's own query: a cluster's cells, ranked by a gene's expression. The Yearbook runs it in the browser, so no AnnData is needed.
  • A celldega.select selection, from a single-cell AnnData you give Clerk: any combination of cell attributes and genes, sampled at random, ranked, by quantile bin, or evenly across categories.
clerk = dega.viz.Clerk(adata="data/cells.h5ad")   # or a .zarr path or URL, or an AnnData
dega.viz.link_clerk(clerk, landscape=landscape, clustergram=cgm, yearbook=yearbook)

Clerk works mainly from the cluster signatures (the Clustergram's pseudo-bulk expression) and uses selections to look at small samples of single cells: 60 by default, at most 200. It never sees the AnnData's values. It gets a short description (its size, gene names, and each obs column's categories or range) and writes the query and sampler as JSON. The Clerk widget rebuilds them in the kernel (dega.select.query_from_dict, sampler_from_dict; no code Clerk writes is run) and runs them. Clerk then learns how many cells matched and sees the chosen ones in the Yearbook. The selection is stored with the Yearbook (yearbook.selection), so the report records how its cells were chosen.

An AnnData link is read the first time Clerk needs it (a local .h5ad in backed mode). It also tells the analysis notebooks Clerk drafts where the data is. Without one, Clerk uses a linked Landscape's AnnData if it has one.

Letting Clerk change the views

Clerk can show you its evidence: highlight the clusters it is discussing in the Landscape, color it by genes, zoom to a cluster, or move the Clustergram's DIM slider. It uses the same setters you can call yourself (landscape.apply_state, cgm.apply_state; see the Landscape and Clustergram pages), and each change appears in the conversation as a "↻ Changed …" line. Cell types Clerk records can also be written to the Clustergram's manual column category, when you accept its offer to (see Recording cell types); labels you set yourself are never overwritten.

Reading and changing are separate. Clerk can look up any gene in the Clustergram (values and dot sizes across clusters) without changing what you see, even genes hidden by the DIM slider or off screen; the browser holds the whole matrix, and DIM, crop and zoom only filter what's displayed. Such lookups appear as "↻ Looked up EPCAM, PTPRC in the Clustergram (view unchanged)".

Clerk cites views rather than changing them (see above), and changes the linked views directly only when you ask it to show something now, for example "show more marker genes" moves the DIM slider. A view change ends Clerk's reply, unless Clerk asked to look at the result and continue ("continue": true in its actions); lookups always continue with their results. Lookup results add up over a question, so Clerk remembers what it already checked, and an action identical to the previous one is not repeated.

Each lookup or change is one round, and Clerk makes at most clerk.max_action_rounds (default 6) per question. At that point it pauses with a Continue button rather than stopping: click it to let Clerk carry on with a fresh budget, or ask something else.

The same changes are available from Python:

cgm.apply_state({"marker_level": 10})         # DIM slider; "all" for every row
cgm.apply_state({"mode": "dotplot", "size": "unit"})
cgm.apply_state({"focus_gene": "MUC2"})        # zoom to a gene, like the search box
cgm.apply_state({"order": {"row": "rank"}, "crop": {"col": ["4", "5"]}})
cgm.apply_state({"view": {"target": [250, 250], "zoom": [1, 2]}})
landscape.apply_state({"layers": {"image": True, "cells": False}})

Landscape also exposes image channels, layer sliders and the image source selector. See Viz API for the complete shapes. Dendrogram cut and linked selections remain future controls.

For a simple side-by-side layout of one Landscape + Clerk:

dega.viz.landscape_clerk(landscape, clerk)

Analysis notebooks

Clerk interprets; it doesn't run analysis. When a question needs new analysis (scoring a cell-type signature, a differential expression test, a neighborhood statistic), Clerk can draft a Jupyter notebook for it instead of guessing. The notebook is the analysis counterpart of a Snapshot: an artifact you can inspect, change, rerun and share.

  1. Clerk drafts it, when you want it. If you asked for the analysis ("write a notebook that scores…"), Clerk drafts it right away. Otherwise Clerk only suggests one: "↻ Suggested an analysis notebook", with what it would do and a Draft notebook button; nothing is written until you click it. Once drafted, the line shows the file's path (under clerk_files/analyses/). The notebook opens with who drafted it, the question it answers, where its data lives, and a reminder to inspect it. Its cells use Scanpy, Squidpy or Celldega; they read the inputs and write any new results (for example an AnnData with new columns) as new files next to the notebook.
  2. You inspect it, in Jupyter like any notebook, and edit it if you like.
  3. You run it, yourself, or with Run with Claude Code on its line. Claude Code runs it in a separate process with jupyter nbconvert, saving the outputs in the notebook. It may fix a small, clear error (a typo, a misspelled column) and rerun, and it writes a short summary next to the notebook. It can do nothing else: other tools and commands are refused, and your Claude Code settings, hooks and MCP servers aren't loaded.
  4. Clerk interprets the results. Claude Code's summary appears in the conversation, so your next question can ask what it means.

Tell Clerk where the data lives when the linked widgets don't say (for example an AnnData file behind an in-memory Landscape):

clerk.analysis_data = {"adata": "data/cells.h5ad"}

clerk.draft_notebook()        # draft the latest suggestion (the panel's Draft notebook)
clerk.analyses                # the notebooks Clerk drafted: title, path, status, summary
clerk.run_analysis()          # the latest, with Claude Code (in the background)
clerk.run_analysis(path, wait=True)  # one in particular; wait for its result

clerk.draft_notebooks = True   # draft suggestions too, without asking ("ask" by default)
clerk.draft_notebooks = False  # never draft notebooks

Clerk never runs a notebook: drafting one you didn't ask for, and running any, is always your choice.

Landscape raster capture (a reusable feature)

Clerk needed to see the view, so Landscape gained a general raster capture: the screenshot component of a Snapshot. Request a capture; when the browser replies, the image and the exact view state are set on the widget (in memory only — captures are never saved into the notebook):

landscape.request_raster()      # asks the browser to capture the current view
# ...in a later cell, once the browser has replied:
landscape.raster_png            # base64 PNG (no data: prefix), longest side <= 1024 px
landscape.raster_thumb          # small preview
landscape.raster_view_state     # {"target": [...], "zoom": ..., ...} for reproducibility

The reply arrives asynchronously, so read these in a later cell or observe them; a cell that requests a capture can't wait for it.

Snapshots

Ask Clerk to save evidence ("save a Snapshot of this for the report") and it takes a Snapshot of the linked views after any requested changes. The screenshot, Clerk's memo and reproducibility metadata are saved together. Snapshots are written to clerk_files/screenshots/ (or clerk.screenshot_dir), marked as made by Clerk, listed in clerk.screenshots, and recorded in the conversation. Manual exports from SNAP or widget.snapshot() default to celldega_files/snapshots/. Either folder can be loaded as a briefing or configured to use a shared location. Clerk's screenshot_dir and screenshots attributes and its screenshots/ folder retain their existing names.

Taking the record with you

Clerk writes exported reports to clerk_files/<report name>/ and Snapshots to clerk_files/screenshots/; change the parent folder with clerk.output_dir. Manual visualization exports use celldega_files/snapshots/ and the widget's snapshot_dir. Both default output directories are ignored by Git.

A law clerk who brings evidence also says how it was found and how to check it. clerk.export() (or the panel's Report button) writes the conversation to a folder. The button opens an optional Report name field. The name becomes the report's heading and its folder name (Kidney exploration -> clerk_files/kidney-exploration/); leave it blank to use report. The date is recorded in record.json. An existing report is never overwritten: if the name is taken, the new one is saved as kidney-exploration-2 (then -3...), and the panel says so.

clerk.export("hcrc_clerk")                               # into the folder hcrc_clerk
clerk.export("hcrc_clerk", adata=adata, groupby="leiden")  # also annotate an AnnData
clerk.export(title="Kidney exploration")                 # named report under clerk_files/
  • report.html: the whole conversation as one self-contained page with static images. Each Landscape and Clustergram Snapshot sits under code to replay its supported settings on widgets with the same data loaded, e.g. landscape.apply_state({"space": "spatial", "view": {...}, "clusters": ["4"]}) and cgm.apply_state({"marker_level": 25}); Clerk's work and evidence are collapsed.
  • report.ipynb: the same as a notebook, to re-run the reproduction code against your own widgets.
  • record.json: every question with its model, effort, what was sent, each step (lookups and their results, view changes, replies), each capture's observed evidence (observations), available widget sources and partial replay settings.
  • screenshots/: each capture as a Snapshot, one per widget (q1_1.png for the Landscape, q1_1_clustergram.png for the Clustergram). Like SNAP's, each PNG carries the record to reopen its view, e.g. dega.viz.from_png("report/screenshots/q1_1.png").
  • findings.csv: the cell types Clerk proposed.
  • With adata= and groupby=: the latest cell types written into adata.obs["clerk_cell_type"] (a column Clerk wrote earlier is replaced) and cell_types.csv; add write_h5ad=True to save the AnnData too.

The record is also available as clerk.record (a list of dicts, one per question). The HTML needs nbconvert; without it the other files are still written.

Saving and reopening a conversation

The panel's Save button (or clerk.save_conversation()) saves the conversation to reopen later, the way SNAP saves a view. It writes one JSON file to clerk_files/conversations/, holding:

  • the messages, with their gene, cluster and view links and Enrichr results;
  • the record of each question, with the replay settings of its captures;
  • Clerk's proposed cell types and the context;
  • links to the data the linked widgets show.

Each question's Snapshot preview is kept, but full-size captures are left out to keep the file light; Write report keeps those.

Open (or clerk.load_conversation(path)) puts a saved conversation back in the panel, replacing the current one. It also opens an exported report folder. Saved conversations are named after their title (kidney-walkthrough.json), with -2 and so on when the name is taken.

saved = clerk.save_conversation(title="kidney walkthrough")
# ...later, in a notebook with the same data linked:
clerk.load_conversation(saved)          # or the panel's Open button

Reading a saved conversation needs no Claude, so it shows what a session looked like: click through the genes, clusters and cited views ([Fig 1A]) and they change the linked widgets, as they did when Clerk answered. The links need the same data loaded in those widgets. A new question continues the conversation, with the loaded one as its history.

Reopening a case

Clerk(clerk_files=...) (or clerk.open_case(...)) reopens a saved case: a report folder, a saved conversation, or a folder of them such as clerk_files, which opens the most recent. Use it to read back through a case, like a record you scroll through, or to keep working on it:

clerk = dega.viz.Clerk(
    clerk_files="clerk_files",   # the most recent case; or "clerk_files/kidney-exploration"
    landscape=landscape, clustergram=cgm, yearbook=yearbook,
)

It needs no Claude. The panel shows the conversation, findings and evidence; their genes, clusters and cited views change the linked widgets, and the case's views become pins on the Landscape (PINS: hover a pin for its question and a preview, click it to return to that view). Asking a question continues the case (that needs Claude), and new reports are saved beside it.

Saved views, evidence and reports

The Viz API preserves an interactive observation as a Snapshot. A Snapshot becomes an evidence artifact when Clerk cites it to support or contradict a claim. The report collects those artifacts with questions, lookups, reasoning and findings; that organization belongs to Clerk, not the visualization API.

Use clerk.export(...) and clerk.load_briefing(...) to save and reuse this record. Manual exports use the same underlying saved-view contract without constructing a Clerk. See Portable Snapshots.

Roadmap

Planned next steps include a one-click "label my clusters" pass (evidence gathered by code, one model call), counting the cell types in view at mid zoom without loading transcripts, and running Clerk on the Claude Agent SDK so lookups are real tools. See celldega/clerk/ROADMAP.md for the full plan.