Session Saving, Restoring, and Sharing#

A Cellucid session file (.cellucid-session) holds the history of the dataset you are looking at: every tracker, every step of each, the branches, and the step that is shown. Loading it puts that history back, at the step it showed, with every step still there to undo to. Share… chooses what it holds: the history of the trackers and branches you tick, the current state only, or the steps only (a plan to replay on another dataset). It is how you keep your work outside this browser and how you send it to someone else.

This section is written for mixed audiences:

Wet lab / non-technical collaborators: click-by-click “save my work and send it to someone”.
Computational users: exact semantics (what is saved, what is left out, and why a load is all or nothing).
Power users / demo builders: the file format, starting views for a catalog, and strict dataset identity.

Important

A session file does not contain your dataset.

Share… and Load… sit in the sidebar’s State section, under Session. To reopen a session you saved yourself:

choose Load… › Open a session file… and pick the .cellucid-session file;
a session saved on a sample, a data link or a Cellucid server opens its dataset first; one saved on a file from your computer needs that file (in Chrome and Edge, the handle this browser kept of it opens it again with one click; elsewhere you choose the file again).

A dataset opened from a catalog (the built-in samples included) can come with a starting view the catalog names: Cellucid puts it back by itself after the dataset is published and the session’s bytes are verified, and the history starts from it.

Tip

If you’re here because “I loaded a session but it looks different”, start with:

Current format and dataset identity (exact identity and refusal rules)
Troubleshooting sessions (symptom → diagnosis → fix)

The history itself (steps, undo, branches, trackers, the copy kept in this browser) has its own chapter: State and History.

Fast path (choose your goal)#

You want to…	Do this	Why it’s the right choice	Start here
Reopen your work later on this computer	Nothing: every step is kept in this browser, and reopening the dataset offers Continue where you left off?	The history is saved as you work	Saved states and autosave
Keep your work as a file, or move it to another computer	State › Session › Share… → Save file, keep the `.cellucid-session` file	The file holds the history you chose and opens in any browser	Save/restore UX (manual save + restore)
Run the same steps on another dataset	Open the other dataset, then Load… › Replay a session file here…	Steps are applied again by name; what does not match is flagged, never dropped	Sharing, loading and replaying
Start a sample in its reviewed view	Choose the dataset from its catalog; the starting view the catalog names is put back by itself	The data is published first, then the view is integrity-verified	Starting views named by a catalog
Send someone your work	Send the `.cellucid-session` file, and the dataset file when it was opened from your computer	Sessions don’t include data; a sample, link or server opens by itself	Share workflows (links, session files and data files)
Collaborate on labels with many people	Use Community annotation (GitHub-backed)	Sessions are single-user files; annotation is multi-user	Community Annotation (Voting + Consensus; GitHub Sync)

What to read (recommended order)#

Session mental model (what a session file is and how to reason about it)
What gets saved and restored (exact list of what is and is not saved)
Save/restore UX (manual save + restore) (Share… / Load… step by step)
Starting views named by a catalog (starting views a catalog names, put back by themselves)
Share workflows (links, session files and data files) (how to share with humans)
Troubleshooting sessions (the big “why did this fail?” map)

From Python and R: read a session file’s history – its trackers, branches, steps, notes and turns, and the state at any step – with cellucid.read_session() (Sessions (.cellucid-session files)); apply the labels, highlight groups, fields and gene sets of one step to an AnnData with apply_cellucid_session_to_anndata(adata, session, tracker=..., branch=..., step=...), a plan first, then the change, each apply recorded (Sessions: apply to AnnData (apply_session_to_anndata)); ask a notebook viewer for its session (Sessions: capture from the browser (request_session)), or push a file into it with viewer.load_session(path). In R the same is cellucid_read_session(), cellucid_trackers() and its companions, cellucid_apply_session() with cellucid_apply_plan(), and cellucid_load_session() (Hooks, Selections and Sessions). Results come back to an AnnData with viewer.pull(adata) (Round trip (results back from the viewer, columns and gene sets into it)).

Interface reference#

State › Session: Share… (chooses what the file holds, then downloads the .cellucid-session file; Sharing, loading and replaying) and Load… (every history this browser keeps, Open a session file… and Replay a session file here…; see Saved states and autosave).
State › History: the steps a session file holds, as a graph with its branches and trackers, shown and changed in place (The history, Branches, trackers and comparing).
Session (the panel above State): Open data, Subsampling (Cells to open, Genes read for) and Data mapping. A change of the cells to open or of the data mapping is a step of the history, so a session file keeps it; opening a dataset is not a step.