Action reference#

This page answers: “What can be done to an open dataset, by name, and what does each step change?” Every change a person makes with a control, and every change or read an agent, a Python or R viewer, a session or a replay makes, is one of these actions, checked against the same parameters and recorded as one history step with the same label. The catalogue is assets/js/app/actions/definitions/ in the cellucid repository (app/actions/README.md there); this page is generated from it. How the action layer, the state domains and the history work is Action layer, state domains and history.

The catalogue holds 177 actions: 96 that change the state or open a dataset, 37 that move or edit the history, 13 that act outside the state (a file written, a publication, what this browser keeps), and 31 reads. Parameters name things, never positions: a field as {source, key} (obs for a column of the cells, var for a gene), a category by its label, a gene by its name, a highlight page by its name, a view as "live" or "View N", and cells by their original position (the 0-based row of obs). A step therefore replays on another dataset with the same names. An agent calls an action by its tool name (the type with dots and dashes as underscores).

State domains#

An action names the parts of the state it changes (“Changes”). The history keeps their values before and after each step; undo puts the before-values back. It also names the parts its result depends on besides its parameters (“Depends on”: the cells, mapping or pages it computes from, the state a name it is given resolves in); a step keeps their value hashes, which say when its result is stale.

Domain	Name	Holds
`cells`	Open cells	Which cells are open (every cell, or a subsample) and how many of them genes are read for.
`mapping`	Data mapping	Which stored arrays are plotted and read (the data mapping).
`field-overlays`	Fields and labels	Field and category renames, deleted fields, user-defined fields with their values.
`gene-sets`	Gene sets	Gene sets pushed by a notebook or made in the app.
`views`	Views	Kept views, their layout, the focused view, camera lock, the representation each view shows.
`active-field`	Active field	What each view is coloured by (a field or a gene).
`filters`	Filters	Category visibility, continuous ranges, outlier and missing-value filters, per view.
`colors`	Colors	Category colours, colour maps, colour ranges, log scale, zero grey, per view.
`visibility`	Hidden cells	Cells hidden one by one (the cell visibility mask), per view.
`highlights`	Highlights	Highlight pages and their groups of cells.
`camera`	Camera	The camera of each view and the navigation mode.
`camera-path`	Camera path	Camera path keyframes and their playback settings.
`settings`	Settings	Render, navigation and overlay settings (every stable control of the sidebar).
`analysis`	Analysis	The analyses of the panel and of each window: their settings and results.
`layout`	Layout	Docked and floating panels, analysis windows’ places and sizes, open sections, sidebar, theme.

History#

`history.anndata.save`#

Save AnnData with this state. Write a new Cellucid-ready AnnData file (.zarr.zip) of the whole open dataset with the state shown applied, as Python and R apply a session: renamed labels, user-defined fields and highlight groups as obs columns, gene sets in uns and var, and a record of what was applied; never over the dataset’s own file.

Agent tool: history_anndata_save
Effect: outside: it acts outside the dataset’s state and history (writes a file the person receives, publishes, or keeps or removes something in this browser for later visits), which the history cannot take back, and records no step
Asks the person first when an agent takes it: it writes a file (writes-file)

Parameter	Type	Required	Notes
`file`	string	no	The new file’s name (.zarr.zip is added when it does not end so); “<dataset> with this state.zarr.zip” when left out. Not empty.

Example:

{}

It returns:

Field	Type	Notes
`file`	string	The file’s name.
`to`	one of `"file"`, `"download"`	file: a file the person chose in the save dialog; download: the browser’s downloads.
`bytes`	integer
`layout`	one of `"anndata"`, `"mudata"`	A Cellucid-ready AnnData, or a MuData for a dataset of several modalities.
`cells`	integer	Cells written: every cell of the dataset, whichever were open.
`tracker`	object (`id`, `name`)
`branch`	object (`id`, `name`)
`step`	string	The step applied: the one shown.
`applied`	boolean	False when every change was in the dataset already (no record added).
`rows`	list of object (`kind`, `name`, `status`, `cells`, `note`)	Every change of the apply plan, in domain order, as Python and R plan it.
`left_out`	list of string	What the copy does not hold of the state, or of the dataset, one sentence each.

Timeline label: Saved an AnnData copy with this state

Pseudocode: save_anndata()

`history.bookmark.set`#

Bookmark a step. Give a step a bookmark name, unique in its tracker (jump to it by name), or remove it with null. Bookmark before destructive or heavy work.

Agent tool: history_bookmark_set
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`step`	string	yes	A step of the tracker in use, by its id (history_get lists the steps).
`name`	string or null	yes	The bookmark, or null to remove it. Not empty.

Example:

{"step":"s3","name":"Before reclustering"}

It returns:

Field	Type	Notes
`step`	string
`bookmark`	string or null
`journal`	string

Timeline label: Bookmarked step s3 “Before reclustering”

Pseudocode: bookmark("s3", "Before reclustering")

`history.branch.apply`#

Apply a branch’s steps here. Apply a branch’s own steps again, by name, on top of the step shown, as a new branch (no values are merged; a step that does not apply here is flagged).

Agent tool: history_branch_apply
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`branch`	string	yes	A branch by its name or its id (history_summary lists them). Not empty.
`name`	string	no	A name, unique among its kind (compared without case and extra spaces); no length limit. Not empty.
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{"branch":"Main"}

It returns:

Field	Type	Notes
`branch`	object (`id`, `name`) or null
`head`	string	The step shown now.
`report`	list of object (`source`, `label`, `outcome`, `step`, `reason`, `missing`)	Every step replayed and what became of it.

Timeline label: Applied the steps of branch “Main” here

Pseudocode: apply_branch(branch="Main")

`history.branch.archive`#

Archive a branch. Hide a branch from the graph and the pickers, or show it again; it is kept and can be shared. Main cannot be archived.

Agent tool: history_branch_archive
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`branch`	string	yes	A branch by its name or its id (history_summary lists them). Not empty.
`archived`	boolean	yes
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{"branch":"Main","archived":true}

It returns:

Field	Type	Notes
`branch`	object (`id`, `name`)
`archived`	boolean
`journal`	string

Timeline label: Archived branch “Main”

Pseudocode: archive_branch(branch="Main", archived=true)

`history.branch.cancel`#

Cancel a new branch. Forget the branch “Branch here” set to start with the next change.

Agent tool: history_branch_cancel
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

It takes no parameters.

Example:

{}

It returns:

Field	Type	Notes
`cancelled`	string or null	The name forgotten; null when none was set.

Timeline label: Cancelled the new branch

Pseudocode: cancel_branch()

`history.branch.create`#

Branch here. Show a step and start a new branch from it with the next change (a branch exists from its first step); the name defaults to the next “Branch n”.

Agent tool: history_branch_create
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`step`	string	yes	A step of the tracker in use, by its id (history_get lists the steps).
`name`	string	no	A name, unique among its kind (compared without case and extra spaces); no length limit. Not empty.

Example:

{"step":"s3"}

It returns:

Field	Type	Notes
`pending`	string	The name the next change’s branch takes.
`from`	string
`head`	string	The step shown now.

Timeline label: Branched from step s3

Pseudocode: branch_here(step="s3")

`history.branch.delete`#

Delete a branch. Move a branch’s own steps (those no other branch starts from) to Recently deleted, where they can be restored; with with_sub_branches, the branches that start from it too. Main and locked branches cannot be deleted.

Agent tool: history_branch_delete
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)
Asks the person first when an agent takes it: it deletes something saved (deletes-saved)

Parameter	Type	Required	Notes
`branch`	string	yes	A branch by its name or its id (history_summary lists them). Not empty.
`with_sub_branches`	boolean	no	Also delete every branch that starts from it. Default `false`.
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{"branch":"Main"}

It returns:

Field	Type	Notes
`branches`	list of object (`id`, `name`)	The branches deleted.
`steps`	integer	Steps moved to Recently deleted.
`results`	integer	Results computed on them.
`kept_views`	integer	Kept views elsewhere made from it (they keep their picture).
`replays`	integer	Trackers replayed from it.
`absorbed_by`	object (`id`, `name`) or null	The branch that keeps its shared steps.
`head`	string	The step shown now.
`journal`	string	Its Recently deleted entry.

Timeline label: Deleted branch “Main”

Pseudocode: delete_branch(branch="Main")

`history.branch.lock`#

Lock a branch. Lock a branch (no new step, rename, delete or compaction until unlocked; a change at its tip starts a new branch), or unlock it.

Agent tool: history_branch_lock
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`branch`	string	yes	A branch by its name or its id (history_summary lists them). Not empty.
`locked`	boolean	yes
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{"branch":"Main","locked":true}

It returns:

Field	Type	Notes
`branch`	object (`id`, `name`)
`locked`	boolean
`journal`	string

Timeline label: Locked branch “Main”

Pseudocode: lock_branch(branch="Main", locked=true)

`history.branch.rename`#

Rename a branch. Give a branch another name, unique in its tracker.

Agent tool: history_branch_rename
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`branch`	string	yes	A branch by its name or its id (history_summary lists them). Not empty.
`name`	string	yes	A name, unique among its kind (compared without case and extra spaces); no length limit. Not empty.
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{"branch":"Main","name":"Without alpha"}

It returns:

Field	Type	Notes
`branch`	object (`id`, `name`)
`journal`	string	Its Recently changed entry.

Timeline label: Renamed branch “Main” to “Without alpha”

Pseudocode: rename_branch(branch="Main", name="Without alpha")

`history.branch.set-main`#

Make a branch main. Make a branch the tracker’s main one, what sharing, replay and loading default to.

Agent tool: history_branch_set_main
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`branch`	string	yes	A branch by its name or its id (history_summary lists them). Not empty.
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{"branch":"Main"}

It returns:

Field	Type	Notes
`branch`	object (`id`, `name`)
`journal`	string

Timeline label: Made branch “Main” main

Pseudocode: set_main_branch(branch="Main")

`history.branch.switch`#

Switch branch. Show a branch’s last step and continue on it; an agent’s turn continues on it too.

Agent tool: history_branch_switch
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`branch`	string	yes	A branch by its name or its id (history_summary lists them). Not empty.
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{"branch":"Main"}

It returns:

Field	Type	Notes
`branch`	object (`id`, `name`)
`head`	string	The step shown now.

Timeline label: Switched to branch “Main”

Pseudocode: switch_branch(branch="Main")

`history.branch.without`#

Branch without a step. Make a new branch from a step’s parent that applies the later steps of the path again without it, by name; nothing existing changes. The report says what did not apply.

Agent tool: history_branch_without
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`step`	string	yes	A step of the tracker in use, by its id (history_get lists the steps).
`name`	string	no	A name, unique among its kind (compared without case and extra spaces); no length limit. Not empty.

Example:

{"step":"s3"}

It returns:

Field	Type	Notes
`branch`	object (`id`, `name`) or null
`head`	string	The step shown now.
`report`	list of object (`source`, `label`, `outcome`, `step`, `reason`, `missing`)	Every step replayed and what became of it.

Timeline label: Branched without step s3

Pseudocode: branch_without(step="s3")

`history.clear`#

Clear the history. Start the branch “Fresh start” from the opening step with nothing behind it: keeping the state shown (one squashed step from the dataset as opened to it), or from the dataset as opened (the branch starts with the next change). Every branch stays, archivable; either way it is kept in Recently changed and can be undone there.

Agent tool: history_clear
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)
Asks the person first when an agent takes it: it deletes something saved (deletes-saved)

Parameter	Type	Required	Notes
`keep_state`	boolean	yes	True keeps the state shown as one step; false starts over from the dataset as opened.

Example:

{"keep_state":true}

It returns:

Field	Type	Notes
`branch`	object (`id`, `name`) or null
`head`	string	The step shown now.
`journal`	string	Its Recently changed entry.

Timeline label: Cleared the history, keeping the state

Pseudocode: clear_history(keep_state=True)

`history.diff`#

Compare two steps. What differs between the state after two steps, part by part (filters, labels, highlights, …); the steps may be of two trackers.

Agent tool: history_diff
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`a`	object (`step`, `tracker`)	yes	The first step.
`b`	object (`step`, `tracker`)	yes	The second step.

Example:

{"a":{"step":"s1"},"b":{"step":"s2"}}

It returns:

Field	Type	Notes
`a`	object (`tracker`, `step`)
`b`	object (`tracker`, `step`)
`common`	string or null	Their last common step (null across trackers).
`domains`	list of object (`domain`, `name`, `lines`)

`history.get`#

Read the history. The steps taken on this dataset, who took each (person, agent, notebook), branches and the step shown.

Agent tool: history_get
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.
`branch`	string	no	The path to this branch’s tip (by its name or id) instead of the path to the step shown; not with all_branches. Not empty.
`all_branches`	boolean	no	Every branch, not only the path to the step shown. Default `false`.
`since`	number	no	Only the steps recorded at or after this time (milliseconds since 1970: a step’s “at”), so a second read lists what came since.
`limit`	integer	no	The steps of one page (200 when left out: well under what a tool result carries). At least 1. Default `200`.
`cursor`	string	no	Where the page starts: the next of the last page (its last step’s id); the first page when left out. Not empty.
`fields`	list of one of `"params"`, `"notes"`, `"bookmark"`	no	What to add to each step: params (each parameter in words), notes, bookmark. Each once.

Example:

{}

It returns:

Field	Type	Notes
`tracker`	object (`id`, `name`)
`trackers`	list of object (`id`, `name`, `active`)
`head`	string	The step shown now.
`branches`	list of object (`name`, `tip`, `active`)
`steps`	list of object (`id`, `parent`, `kind`, `squash`, `label`, `type`, `v`, `code`, `origin`, `agent`, `host`, `turn`, `at`, `status`, `note`, `touches`, `group`, `shown`, `params`, `notes`, `bookmark`)	One page: root first; parents before children.
`total`	integer	Steps on every page (the path to the step shown, or every branch).
`next`	string or null	The cursor of the next page; null on the last.

`history.group.create`#

Group steps. Name a run of consecutive steps of one branch as a group (a folder; nothing is changed or merged). It holds whole turns; a step is in one group at most. Group a multi-step analysis under a short name.

Agent tool: history_group_create
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`from`	string	yes	Its first step.
`to`	string	yes	Its last step.
`name`	string	yes	A name, unique among its kind (compared without case and extra spaces); no length limit. Not empty.

Example:

{"from":"s4","to":"s9","name":"QC"}

It returns:

Field	Type	Notes
`group`	object (`id`, `name`)
`steps`	integer	Steps in it.
`journal`	string	Its Recently changed entry.

Timeline label: Grouped steps s4 to s9 as “QC”

Pseudocode: group_steps("s4", "s9", "QC")

`history.group.extend`#

Add steps to a group. Extend a group to a later step of its branch, taking in every step between (whole turns, none of another group).

Agent tool: history_group_extend
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`group`	string	yes	A group by its name or its id (history_summary lists them). Not empty.
`to`	string	yes	Its new last step.
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{"group":"QC","to":"s12"}

It returns:

Field	Type	Notes
`group`	object (`id`, `name`)
`steps`	integer	Steps in it now.
`journal`	string

Timeline label: Extended the group “QC” to step s12

Pseudocode: extend_group(group="QC", to="s12")

`history.group.remove`#

Ungroup. Remove a group; its steps stay as they are.

Agent tool: history_group_remove
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`group`	string	yes	A group by its name or its id (history_summary lists them). Not empty.
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{"group":"QC"}

It returns:

Field	Type	Notes
`group`	object (`id`, `name`)
`journal`	string

Timeline label: Ungrouped “QC”

Pseudocode: ungroup(group="QC")

`history.group.rename`#

Rename a group. Give a group another name, unique in its tracker.

Agent tool: history_group_rename
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`group`	string	yes	A group by its name or its id (history_summary lists them). Not empty.
`name`	string	yes	A name, unique among its kind (compared without case and extra spaces); no length limit. Not empty.
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{"group":"QC","name":"Without alpha"}

It returns:

Field	Type	Notes
`group`	object (`id`, `name`)
`journal`	string

Timeline label: Renamed the group “QC” to “Without alpha”

Pseudocode: rename_group(group="QC", name="Without alpha")

`history.journal.empty`#

Empty Recently deleted. Drop what Recently deleted keeps (one entry, or all of them) so its values can be freed; it can no longer be restored.

Agent tool: history_journal_empty
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)
Asks the person first when an agent takes it: it deletes something saved (deletes-saved)

Parameter	Type	Required	Notes
`entry`	string	no	An entry of Recently deleted, by its id (history_summary counts them).
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{}

It returns:

Field	Type	Notes
`purged`	integer
`bytes`	integer	Memory freed.

Timeline label: Emptied Recently deleted

Pseudocode: empty_recently_deleted()

`history.journal.undo`#

Restore from Recently deleted. Undo an edit of the history (a delete, a rename, a note, …) from Recently deleted: exactly as it was when nothing changed it since, else as new objects (“X (restored)”, removed steps applied again as a branch). Undoing a rename whose old name was taken since is refused, naming the name to use instead.

Agent tool: history_journal_undo
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`entry`	string	yes	An entry of Recently deleted, by its id (history_summary counts them).
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{"entry":"j0"}

It returns:

Field	Type	Notes
`entry`	string
`restored`	one of `"exact"`, `"as-new"`
`journal`	string	The entry the restore itself made (undoable).
`branch`	object (`id`, `name`) or null	The first branch a restore as new made of the steps it applied again.
`report`	list of object (`source`, `label`, `outcome`, `step`, `reason`, `missing`)	The steps a restore as new applied again and what became of each (empty for an exact restore).

Timeline label: Restored j0

Pseudocode: restore(entry="j0")

`history.jump`#

Show a step. Show the state after any step of the tracker in use, on any branch, as clicking it in the timeline does; nothing is undone or lost. Name exactly one of step, bookmark or at.

Agent tool: history_jump
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`step`	string	no	A step of the tracker in use, by its id (history_get lists the steps).
`bookmark`	string	no	A bookmark’s name (any case): show the step it marks. Not empty.
`at`	number	no	A time (milliseconds since 1970): show the last step at or before it on the branch shown.

Example:

{}

It returns:

Field	Type	Notes
`head`	string	The step shown now.

Timeline label: Showed the step at a time

Pseudocode: jump()

`history.methods`#

Write the methods paragraph. The methods paragraph of a branch (main when left out): the dataset and its citation, the cells used, each step that changed the analysis, the tracker’s notes as its opening, and the Cellucid version.

Agent tool: history_methods
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`branch`	string	no	A branch by its name or its id (history_summary lists them). Not empty.
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{}

It returns:

Field	Type	Notes
`tracker`	object (`id`, `name`)
`branch`	object (`id`, `name`)
`text`	string

`history.note.add`#

Add a note. Write a note on a step, a branch, a turn or a tracker. End each turn that changed something with a one-line summary note on the turn.

Agent tool: history_note_add
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`target`	object (`step`, `tracker`) or object (`branch`, `tracker`) or object (`group`, `tracker`) or object (`turn`, `tracker`) or object (`tracker`)	yes	What the note is on: a step, a branch, a group, a turn, or a tracker itself.
`text`	string	yes	Markdown: emphasis, inline code and http(s) links; shown without HTML. Not empty.
`from_reply`	boolean	no	Taken from the agent’s final reply (the turn summary written for an agent that wrote none). Default `false`.

Example:

{"target":{"step":"s3"},"text":"Top hits match the paper."}

It returns:

Field	Type	Notes
`note`	string
`journal`	string

Timeline label: Added a note on step s3

Pseudocode: add_note({"step":"s3"}, "Top hits match the paper.")

`history.note.edit`#

Edit a note. Change a note’s text. An agent edits only its own notes; the person edits any.

Agent tool: history_note_edit
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`note`	string	yes	A note, by its id (history_step and history_summary list them).
`text`	string	yes	Markdown: emphasis, inline code and http(s) links; shown without HTML. Not empty.
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{"note":"n0","text":"Top hits match the paper."}

It returns:

Field	Type	Notes
`note`	string
`journal`	string

Timeline label: Edited note n0

Pseudocode: edit_note(note="n0", text="Top hits match the paper.")

`history.note.remove`#

Remove a note. Remove a note. An agent removes only its own notes; the person removes any.

Agent tool: history_note_remove
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`note`	string	yes	A note, by its id (history_step and history_summary list them).
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{"note":"n0"}

It returns:

Field	Type	Notes
`note`	string
`journal`	string

Timeline label: Removed note n0

Pseudocode: remove_note(note="n0")

`history.pseudocode`#

Write the pseudocode. A branch’s steps (main when left out) as pseudocode, one line each, as recorded.

Agent tool: history_pseudocode
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`branch`	string	no	A branch by its name or its id (history_summary lists them). Not empty.
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{}

It returns:

Field	Type	Notes
`tracker`	object (`id`, `name`)
`branch`	object (`id`, `name`)
`text`	string

`history.recording.pause`#

Pause recording. Pause the history of a tracker: changes still apply but make no step until it is resumed, and an agent’s change cannot be undone on its own meanwhile. Ask the person first.

Agent tool: history_recording_pause
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)
Asks the person first when an agent takes it: it pauses the recording (while paused, a change cannot be undone on its own) (pauses-recording)

Parameter	Type	Required	Notes
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{}

It returns:

Field	Type	Notes
`since`	number or null	When it was paused (milliseconds since 1970).
`head`	string	The step shown now.

Timeline label: Paused recording

Pseudocode: pause_history()

`history.recording.resume`#

Resume recording. Record again: what differs from the step shown becomes one squashed step (“While paused: …”), by everyone who acted meanwhile; nothing when nothing differs.

Agent tool: history_recording_resume
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{}

It returns:

Field	Type	Notes
`squashed`	string or null	The squashed step resuming made; null when nothing differed.
`head`	string	The step shown now.

Timeline label: Resumed recording

Pseudocode: resume_history()

`history.redo`#

Redo. Show the step after the one shown now on the branch last taken, as the State panel’s Redo does.

Agent tool: history_redo
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

It takes no parameters.

Example:

{}

It returns:

Field	Type	Notes
`moved`	boolean	Whether the history moved: not when there was no step to move to (nothing to undo, or nothing to redo).
`head`	string	The step shown now.

Timeline label: Redid a step

Pseudocode: redo()

`history.replay`#

Replay a saved history. Apply a saved state’s branch (its main branch when left out) again here, step by step by name, in a new tracker linked to it; with a mapping, other names are used for fields, categories and genes. The report says what did not match.

Agent tool: history_replay
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`saved`	string	yes	A saved state of this browser (history_saved_list). Not empty.
`tracker`	string	no	Its tracker, by name or id; its tracker shown when left out. Not empty.
`branch`	string	no	Its branch; its main branch when left out. Not empty.
`mapping`	object (`fields`, `categories`, `genes`)	no	Names to use in place of the recorded ones, each from its recorded name (the replay report offers them: a step’s missing names what matched nothing here). A category is named by its field’s recorded key.
`name`	string	no	A name, unique among its kind (compared without case and extra spaces); no length limit. Not empty.

Example:

{"saved":"state-1"}

It returns:

Field	Type	Notes
`tracker`	object (`id`, `name`)
`report`	list of object (`source`, `label`, `outcome`, `step`, `reason`, `missing`)	Every step replayed and what became of it.

Timeline label: Replayed the saved state “state-1”

Pseudocode: replay(saved="state-1")

`history.report`#

Make the printable report. The State panel’s printable report of the branch shown up to the step shown (the dataset, the methods text, every step with who took it, its parameters, what it changed and its notes, then the pseudocode), as an .html file the person receives (asked first) or as its text; with pictures of the views after the steps chosen (a file only).

Agent tool: history_report
Effect: outside: it acts outside the dataset’s state and history (writes a file the person receives, publishes, or keeps or removes something in this browser for later visits), which the history cannot take back, and records no step
Asks the person first when an agent takes it: it writes a file (writes-file)

Parameter	Type	Required	Notes
`as`	one of `"file"`, `"text"`	no	file: an .html file downloaded to the person’s computer, which they open, print or save as PDF; text: the same HTML document in the result (no pictures). Default `"file"`.
`pictures`	one of `"none"`, `"default"` or list of string	no	The steps that get a picture of the views after them (each is shown in turn and drawn, then the history returns to the step shown). A file only. Default `"none"`.
`file`	string	no	The file’s name; the dataset’s name and “history report” when left out. Not empty.

Example:

{}

It returns:

Field	Type	Notes
`as`	one of `"file"`, `"text"`
`tracker`	object (`id`, `name`)
`branch`	object (`id`, `name`)
`to`	string or null	The last step it covers, or null at the branch’s tip.
`steps`	integer	Steps in it.
`pictures`	integer	Pictures in it.
`file`	string or null	The file written (as file).
`bytes`	integer	Its size.
`html`	string or null	The report as one HTML document (as text).

Timeline label: Wrote the printable report as a file

Pseudocode: history_report()

`history.save`#

Save the history in this browser. Keep the history (every tracker), the current state only, or the steps only as a named saved state of this browser (history_saved_list lists them; replay or load it later).

Agent tool: history_save
Effect: outside: it acts outside the dataset’s state and history (writes a file the person receives, publishes, or keeps or removes something in this browser for later visits), which the history cannot take back, and records no step

Parameter	Type	Required	Notes
`name`	string	no	Its name; the dataset’s name and the time when left out. Not empty.
`content`	one of `"history"`, `"state"`, `"steps"`	no	history: the trackers and branches with their values; state: the current state only, without its history (one squashed step “Shared state”); steps: the steps only, no cells or values (a replay plan for any dataset). Default `"history"`.
`results`	one of `"include"`, `"recompute"`	no	Analysis results: include them, or leave them out to compute again on open from their recorded inputs (smaller; always so for steps). Default `"include"`.

Example:

{}

It returns:

Field	Type	Notes
`saved`	string	Its id (history_saved_list).
`name`	string
`content`	one of `"history"`, `"state"`, `"steps"`
`bytes`	integer
`steps`	integer

Timeline label: Saved the history in this browser

Pseudocode: save_history()

`history.saved.delete`#

Delete a saved state. Remove one saved state of this browser (an autosave or a named save, by its id from history_saved_list) with every value only it held; it cannot be brought back. The history shown stays open.

Agent tool: history_saved_delete
Effect: outside: it acts outside the dataset’s state and history (writes a file the person receives, publishes, or keeps or removes something in this browser for later visits), which the history cannot take back, and records no step
Asks the person first when an agent takes it: it deletes something saved (deletes-saved)

Parameter	Type	Required	Notes
`saved`	string	yes	Its id (history_saved_list). Not empty.

Example:

{"saved":"state-1"}

It returns:

Field	Type	Notes
`saved`	string
`name`	string or null
`dataset`	string or null	The name of its dataset.
`steps`	integer

Timeline label: Deleted the saved state state-1

Pseudocode: history_saved_delete("state-1")

`history.saved.list`#

List saved states. The histories kept in this browser (each dataset’s autosave and the named saves): name, dataset, trackers, steps, size, and whether this version opens them.

Agent tool: history_saved_list
Effect: read: it reads, changes nothing and records no step

It takes no parameters.

Example:

{}

It returns:

Field	Type	Notes
`saved`	list of object (`id`, `kind`, `name`, `dataset`, `this_dataset`, `created_at`, `updated_at`, `steps`, `trackers`, `bytes`, `openable`)	Most recently written first.

`history.search`#

Search the history. The steps whose label, parameters, notes or bookmark match, filtered by who took them, their kind, the part of the state they changed, notes, bookmarks and flags.

Agent tool: history_search
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`text`	string	no	Words to find (any case). Not empty.
`by`	one of `"person"`, `"agent"`, `"python"`, `"r"`, `"replay"`, `"outside"`	no	Who took them.
`kind`	one of `"state"`, `"view"`, `"layout"`	no	What their action changes.
`step_kind`	one of `"root"`, `"action"`, `"outside"`, `"squashed"`	no	What they are: root, action, outside (changed outside an action) or squashed.
`domain`	one of `"cells"`, `"mapping"`, `"field-overlays"`, `"gene-sets"`, `"views"`, `"active-field"`, `"filters"`, `"colors"`, `"visibility"`, `"highlights"`, `"camera"`, `"camera-path"`, `"settings"`, `"analysis"`, `"layout"`	no	The part of the state they changed.
`has_note`	boolean	no
`bookmarked`	boolean	no
`flagged`	boolean	no	Stale, or no longer applying.
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{}

It returns:

Field	Type	Notes
`tracker`	object (`id`, `name`)
`steps`	list of string	The matching steps, in step order.
`total`	integer	Steps in the tracker.

`history.share`#

Share the history as a file. Write a session file to share: the history (trackers and branches chosen; the tracker in use, its main and shown branches by default), the current state only, or the steps only; with or without notes, conversations, Recently deleted, times and where the dataset opens from.

Agent tool: history_share
Effect: outside: it acts outside the dataset’s state and history (writes a file the person receives, publishes, or keeps or removes something in this browser for later visits), which the history cannot take back, and records no step
Asks the person first when an agent takes it: it writes a file (writes-file)

Parameter	Type	Required	Notes
`include`	list of object (`tracker`, `branches`)	no	The trackers to include, each with its branches (its main and shown branches when left out); the tracker in use when left out. At least 1 item.
`content`	one of `"history"`, `"state"`, `"steps"`	no	history: the trackers and branches with their values; state: the current state only, without its history (one squashed step “Shared state”); steps: the steps only, no cells or values (a replay plan for any dataset). Default `"history"`.
`results`	one of `"include"`, `"recompute"`	no	Analysis results: include them, or leave them out to compute again on open from their recorded inputs (smaller; always so for steps). Steps only always recompute, whatever is given. Default `"include"`.
`notes`	boolean	no	Notes and bookmarks (never with a state). Default `true`.
`chats`	boolean	no	Conversations kept with the trackers (never with a state). Default `false`.
`journal`	boolean	no	Recently deleted (never with a state). Default `false`.
`times`	one of `"exact"`, `"dates"`, `"none"`	no	exact; dates (each rounded down to its day); none. When left out: exact for a history or steps, none for a state.
`source`	one of `"full"`, `"name"`	no	full: the dataset’s name and where it opens from; name: its name only. Default `"full"`.
`file`	string	no	The file’s name; the dataset’s name when left out. Not empty.

Example:

{}

It returns:

Field	Type	Notes
`file`	string
`bytes`	integer
`content`	one of `"history"`, `"state"`, `"steps"`
`trackers`	list of object (`id`, `name`)
`steps`	integer	Steps written.

Timeline label: Shared the history as a file

Pseudocode: share_history()

`history.squash`#

Merge steps into one. Replace consecutive steps of one branch (from first to last, whole turns; a group’s are its steps) with one squashed step from the first one’s state to the last one’s; elsewhere it replays as values only. Refused when another branch starts inside; the steps go to Recently deleted. An agent squashes only its own turn’s steps.

Agent tool: history_squash
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)
Asks the person first when an agent takes it: it deletes something saved (deletes-saved)

Parameter	Type	Required	Notes
`from`	string	yes	The first step to merge.
`to`	string	yes	The last step to merge.

Example:

{"from":"s4","to":"s9"}

It returns:

Field	Type	Notes
`step`	string	The squashed step.
`squashed`	integer	Steps it replaced.
`groups_removed`	list of object (`id`, `name`)	Groups that held only these steps, removed with them.
`head`	string	The step shown now.
`journal`	string	Its Recently deleted entry.

Timeline label: Merged steps s4 to s9 into one

Pseudocode: squash("s4", "s9")

`history.stale`#

List stale results. Steps whose result no longer matches its inputs (the cells, the mapping, a highlight changed since), each with the step that made it stale and why.

Agent tool: history_stale
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{}

It returns:

Field	Type	Notes
`tracker`	object (`id`, `name`)
`stale`	list of object (`step`, `label`, `cause`, `reasons`)

`history.step`#

Read a step. One step in full: its parameters, pseudocode, who took it and when, what it changed and read, its notes and bookmark, and why it is stale.

Agent tool: history_step
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`step`	string	yes	A step, by its id (history_get lists the steps).
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{"step":"s3"}

It returns:

Field	Type	Notes
`tracker`	object (`id`, `name`)
`id`	string
`parent`	string or null
`children`	list of string
`branch`	object (`id`, `name`)
`kind`	one of `"root"`, `"action"`, `"outside"`, `"squashed"`
`type`	string or null
`v`	integer or null
`label`	string
`code`	string or null
`params`	list of object (`label`, `value`)	Its parameters as the details show them (cells as counts).
`by`	object (`origin`, `agent`, `model`, `host`, `person`, `turn`)	Who acted.
`at`	number or null
`until`	number or null
`merged`	integer	Changes merged into it (a drag, a gesture).
`ms`	number or null	How long its action took.
`touches`	list of one of `"cells"`, `"mapping"`, `"field-overlays"`, `"gene-sets"`, `"views"`, `"active-field"`, `"filters"`, `"colors"`, `"visibility"`, `"highlights"`, `"camera"`, `"camera-path"`, `"settings"`, `"analysis"`, `"layout"`
`reads`	list of string	The inputs its result depends on.
`status`	one of `"applied"`, `"unapplicable"`
`reason`	string or null
`squashed`	object (`cause`, `count`, `by`, `carried`) or null
`notes`	list of object (`id`, `text`, `by`, `at`, `edited_at`, `from_reply`)
`bookmark`	string or null
`group`	object (`id`, `name`) or null
`replay_of`	object (`tracker`, `step`) or null
`stale`	object (`cause`, `reasons`) or null
`shown`	boolean	On the path to the step shown now.

`history.step.delete`#

Delete a step. Move one step to Recently deleted; only the later steps that changed or read what it changed are applied again, and one that no longer applies is kept, flagged.

Agent tool: history_step_delete
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)
Asks the person first when an agent takes it: it deletes something saved (deletes-saved)

Parameter	Type	Required	Notes
`step`	string	yes	A step of the tracker in use, by its id (history_get lists the steps).

Example:

{"step":"s3"}

It returns:

Field	Type	Notes
`reapplied`	list of string	Steps applied again.
`flagged`	list of object (`step`, `reason`)	Steps that no longer apply.
`head`	string	The step shown now.
`journal`	string	Its Recently deleted entry.

Timeline label: Deleted step s3

Pseudocode: delete_step("s3")

`history.step.revert`#

Revert a step. Add a step that puts back exactly what a step changed, when no later step on the path changed the same parts (else use Branch without a step).

Agent tool: history_step_revert
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Open cells (cells), Data mapping (mapping), Fields and labels (field-overlays), Gene sets (gene-sets), Views (views), Active field (active-field), Filters (filters), Colors (colors), Hidden cells (visibility), Highlights (highlights), Camera (camera), Camera path (camera-path), Settings (settings), Analysis (analysis), Layout (layout)

Parameter	Type	Required	Notes
`step`	string	yes	A step of the tracker in use, by its id (history_get lists the steps).

Example:

{"step":"s3"}

Timeline label: Reverted step s3

Pseudocode: revert_step("s3")

`history.summary`#

Summarise the history. The history at a glance: trackers, branches (fork step, tip, steps, main, locked, archived), bookmarks, turns with their summaries, stale results and Recently deleted, without the steps. Read it before acting on the history.

Agent tool: history_summary
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.

Example:

{}

It returns:

Field	Type	Notes
`tracker`	object (`id`, `name`)
`trackers`	list of object (`id`, `name`, `active`, `steps`, `start`)	Every tracker not removed.
`head`	string	The step shown now.
`active_branch`	string
`main_branch`	string
`recording`	object (`on`, `since`)
`pending`	object (`name`, `from`) or null
`steps`	integer	Steps of the tracker, the root included.
`branches`	list of object (`id`, `name`, `base`, `tip`, `steps`, `main`, `locked`, `archived`, `active`, `notes`)	Every branch, in id order (archived ones flagged).
`groups`	list of object (`id`, `name`, `branch`, `first`, `last`, `steps`, `notes`)	Every group, in id order: a named run of consecutive steps of one branch.
`bookmarks`	list of object (`name`, `step`)
`turns`	list of object (`id`, `label`, `by`, `steps`, `branch`, `summary`)
`stale`	integer	Results whose inputs changed since (history_stale lists them).
`recently_deleted`	integer	Entries that can be undone.

`history.tour.start`#

Start the guided tour. Play the State panel’s guided tour of the branch shown, from the opening to the step shown: each step is shown in turn with its caption and notes (a camera step is flown to), for a talk or a class. It returns once the tour plays; the person pauses, steps or stops it, or history_tour_stop does.

Agent tool: history_tour_start
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

It takes no parameters.

Example:

{}

It returns:

Field	Type	Notes
`tracker`	object (`id`, `name`)
`branch`	object (`id`, `name`)
`steps`	integer	Steps the tour shows after the opening.
`returns_to`	string	The step shown again when the tour ends.

Timeline label: Started the guided tour

Pseudocode: tour_start()

`history.tour.stop`#

Stop the guided tour. Stop the guided tour, as its Stop button does: the history returns to the step shown before it began (unless the person made a step meanwhile).

Agent tool: history_tour_stop
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

It takes no parameters.

Example:

{}

It returns:

Field	Type	Notes
`stopped`	boolean	False when no tour was playing.
`head`	string or null	The step shown now.

Timeline label: Stopped the guided tour

Pseudocode: tour_stop()

`history.tracker.remove`#

Remove a tracker. Move a tracker to Recently deleted, where it can be restored; when it is the one in use, the one used before it is shown first.

Agent tool: history_tracker_remove
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)
Asks the person first when an agent takes it: it deletes something saved (deletes-saved)

Parameter	Type	Required	Notes
`tracker`	string	yes	A tracker by its name or its id (history_summary lists them). Not empty.

Example:

{"tracker":"Tracker 1"}

It returns:

Field	Type	Notes
`tracker`	object (`id`, `name`)
`shown`	object (`id`, `name`)
`journal`	string

Timeline label: Removed the tracker “Tracker 1”

Pseudocode: remove_tracker("Tracker 1")

`history.tracker.rename`#

Rename a tracker. Give a tracker another name, unique among this dataset’s trackers.

Agent tool: history_tracker_rename
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`tracker`	string	yes	A tracker by its name or its id (history_summary lists them). Not empty.
`name`	string	yes	A name, unique among its kind (compared without case and extra spaces); no length limit. Not empty.

Example:

{"tracker":"Tracker 1","name":"Without alpha"}

It returns:

Field	Type	Notes
`tracker`	object (`id`, `name`)
`journal`	string

Timeline label: Renamed the tracker “Tracker 1” to “Without alpha”

Pseudocode: rename_tracker("Tracker 1", "Without alpha")

`history.tracker.start`#

Start another tracker. Start a new tracker, an independent tree of steps on this dataset: from the dataset as opened (the default), or from what is shown.

Agent tool: history_tracker_start
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`start`	one of `"opened"`, `"shown"`	no	opened: the dataset as it was opened; shown: what is shown now. Default `"opened"`.
`name`	string	no	A name, unique among its kind (compared without case and extra spaces); no length limit. Not empty.

Example:

{}

It returns:

Field	Type	Notes
`tracker`	object (`id`, `name`)
`head`	string	The step shown now.

Timeline label: Started another tracker

Pseudocode: start_tracker()

`history.tracker.use`#

Use another tracker. Show another tracker’s step shown and record into it.

Agent tool: history_tracker_use
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`tracker`	string	yes	A tracker by its name or its id (history_summary lists them). Not empty.

Example:

{"tracker":"Tracker 1"}

It returns:

Field	Type	Notes
`tracker`	object (`id`, `name`)
`head`	string	The step shown now.

Timeline label: Used the tracker “Tracker 1”

Pseudocode: use_tracker("Tracker 1")

`history.turn.undo`#

Undo a turn. Take back one agent or notebook turn on the branch shown: show the step before it, or, with only_own, delete only the turn’s own steps (applying the others again) when someone else’s steps came in between.

Agent tool: history_turn_undo
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`turn`	string	yes	A turn, by its id (history_summary lists them). Not empty.
`only_own`	boolean	no	Delete only the turn’s own steps, keeping the others (to Recently deleted). Default `false`.

Example:

{"turn":"turn-1"}

It returns:

Field	Type	Notes
`head`	string	The step shown now.
`removed`	integer	Steps deleted (only_own).
`other_branches`	list of object (`id`, `name`)	Branches holding more of its steps, undone there separately.
`journal`	string or null

Timeline label: Undid a turn

Pseudocode: undo_turn(turn="turn-1")

`history.undo`#

Undo. Show the state before the step shown now, as the State panel’s Undo does; the step stays in the history, to redo.

Agent tool: history_undo
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

It takes no parameters.

Example:

{}

It returns:

Field	Type	Notes
`moved`	boolean	Whether the history moved: not when there was no step to move to (nothing to undo, or nothing to redo).
`head`	string	The step shown now.

Timeline label: Undid a step

Pseudocode: undo()

`history.verify`#

Verify a branch. Replay a branch on this dataset into a scratch tracker and compare every part of the state at the end with its last step: reproduced exactly, or the first step whose values differ.

Agent tool: history_verify
Effect: history: it moves or edits the history itself and records no step of the state (an edit is kept in the history’s journal, undone from Recently deleted)

Parameter	Type	Required	Notes
`branch`	string	yes	A branch by its name or its id (history_summary lists them). Not empty.
`tracker`	string	no	A tracker by its name or its id (history_summary lists them); the tracker in use when left out. Not empty.
`keep`	boolean	no	Keep the scratch tracker afterwards. Default `false`.

Example:

{"branch":"Main"}

It returns:

Field	Type	Notes
`reproduced`	boolean
`steps`	integer	Steps replayed.
`domains`	list of object (`domain`, `first_step`, `lines`)	Each part of the state that differs.
`scratch`	object (`id`, `name`) or null

Timeline label: Verified branch “Main”

Pseudocode: verify_branch(branch="Main")

Fields#

`category.delete`#

Delete a category. Move every cell of one category into the unassigned category. A column from the file becomes a new column (the original moves to Deleted fields); a column made in the app is edited in place.

Agent tool: category_delete
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Fields and labels (field-overlays), Active field (active-field), Filters (filters), Colors (colors), Highlights (highlights), Views (views)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	A categorical column of the cells by name (source “obs”).
`category`	string	yes	A category label as the legend shows it. Not empty.
`unassigned_label`	string	no	The category the cells move into, made when missing. Not empty. Default `"unassigned"`.

Example:

{"field":{"source":"obs","key":"cell_type"},"category":"T cells"}

Timeline label: Deleted the category T cells of cell_type

Pseudocode: delete_category("cell_type", "T cells")

`category.merge`#

Merge two categories. Move every cell of one category into another. A column from the file becomes a new column (the original moves to Deleted fields); a column made in the app is edited in place.

Agent tool: category_merge
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Fields and labels (field-overlays), Active field (active-field), Filters (filters), Colors (colors), Highlights (highlights), Views (views)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	A categorical column of the cells by name (source “obs”).
`category`	string	yes	The category whose cells move. Not empty.
`into`	string	yes	The category they join. Not empty.

Example:

{"field":{"source":"obs","key":"cell_type"},"category":"T cells","into":"T cells"}

Timeline label: Merged T cells into T cells in cell_type

Pseudocode: merge_categories("cell_type", "T cells", into="T cells")

`category.rename`#

Rename a category. Give one category of a categorical column another label; its original label stays known.

Agent tool: category_rename
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Fields and labels (field-overlays), Filters (filters), Colors (colors), Highlights (highlights), Views (views)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	A categorical column of the cells by name (source “obs”).
`category`	string	yes	A category label as the legend shows it. Not empty.
`name`	string	yes	The new label, unique in the column. Not empty.

Example:

{"field":{"source":"obs","key":"cell_type"},"category":"T cells","name":"T cells"}

Timeline label: Renamed T cells to T cells in cell_type

Pseudocode: rename_category("cell_type", "T cells", "T cells")

`field.consensus`#

Build the consensus column. The community annotation’s consensus for a categorical column as a column of its own: each cell gets the agreed label of its category, or the status of a category without one (disputed, pending); built again under the same name, it is replaced. The outcome of each category is named in the parameters, so it replays by name on any dataset with the same column and categories.

Agent tool: field_consensus
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Fields and labels (field-overlays), Active field (active-field), Filters (filters), Colors (colors)

Parameter	Type	Required	Notes
`key`	string	yes	The consensus column’s name. Not empty.
`field`	object (`source`, `key`)	yes	The annotated column the consensus is of.
`mapping`	list of object (`category`, `status`, `label`, `voters`)	yes	The outcome of each category of the column (a category left out is pending). At least 1 item.
`settings`	object (`minAnnotators`, `threshold`)	yes	The consensus rule it was built with.
`provenance`	object (`repository`, `branch`, `commit`, `pulledAt`)	yes	Where the votes came from.

Example:

{"key":"x","field":{"source":"obs","key":"cell_type"},"mapping":[{"category":"T cells","status":"consensus","label":"x","voters":0}],"settings":{"minAnnotators":0,"threshold":-1},"provenance":{"repository":"x","branch":"x","commit":"x","pulledAt":"x"}}

Timeline label: Built the consensus column x of cell_type

Pseudocode: consensus_column("x", of="cell_type", mapping={"T cells": "x"})

`field.create-from-pages`#

Make a field from highlight pages. A new categorical column whose categories are highlight pages: each page’s cells take its label; cells on several pages follow the overlap rule.

Agent tool: field_create_from_pages
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Fields and labels (field-overlays)
Depends on: Highlights (highlights), Open cells (cells)

Parameter	Type	Required	Notes
`key`	string	yes	The new column’s name. Not empty.
`pages`	list of object (`page`, `label`)	yes	The pages, in order (first and last refer to it), each with its category label. At least 1 item.
`uncovered_label`	string	no	The category of cells on no page; empty leaves them without one. Default `"Unassigned"`.
`overlap`	one of `"first"`, `"last"`, `"overlap-label"`, `"intersections"`	no	Cells on several pages: the first page’s label, the last’s, the overlap label, or one label per combination of pages. Default `"first"`.
`overlap_label`	string	no	The label of cells on several pages when overlap is “overlap-label”. Default `"Overlap"`.
`intersection_labels`	list of object (`pages`, `label`)	no	With overlap “intersections”: the label of each combination of pages that has cells. Default `[]`.

Example:

{"key":"x","pages":[{"page":"x","label":"T cells"}]}

Timeline label: Made x from 1 highlight page

Pseudocode: field_from_pages("x", {"x": "T cells"})

`field.delete`#

Delete a field. Remove a column of the cells or a gene from the lists; it can be restored from Deleted fields until purged.

Agent tool: field_delete
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Fields and labels (field-overlays), Active field (active-field), Filters (filters), Colors (colors), Highlights (highlights), Views (views)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	A field by name: source “obs” for a column of the cells, “var” for a gene; key is the name as shown.

Example:

{"field":{"source":"obs","key":"cell_type"}}

Timeline label: Deleted cell_type

Pseudocode: delete_field("cell_type")

`field.duplicate`#

Duplicate a field. Copy a column of the cells or a gene as a new field (named “ (copy)” unless a name is given) and colour by the copy.

Agent tool: field_duplicate
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Fields and labels (field-overlays), Active field (active-field), Filters (filters), Colors (colors), Highlights (highlights), Views (views)
Depends on: Data mapping (mapping), Open cells (cells)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	A field by name: source “obs” for a column of the cells, “var” for a gene; key is the name as shown.
`name`	string	no	The copy’s name; by default “<name> (copy)”, numbered when taken. Not empty.

Example:

{"field":{"source":"obs","key":"cell_type"}}

Timeline label: Duplicated cell_type as cell_type (copy)

Pseudocode: duplicate_field("cell_type")

`field.purge`#

Purge a deleted field. Confirm a deletion: the field leaves Deleted fields and can no longer be restored there (undo still brings it back).

Agent tool: field_purge
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Fields and labels (field-overlays), Filters (filters)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	The deleted field by the name it had when deleted.

Example:

{"field":{"source":"obs","key":"cell_type"}}

Timeline label: Purged cell_type

Pseudocode: purge_field("cell_type")

`field.push`#

Add a column of values. A notebook’s column as a field of the cells: categorical (codes into its categories) or continuous; a later push of the same name replaces it.

Agent tool: field_push
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Fields and labels (field-overlays), Active field (active-field), Filters (filters), Colors (colors)

Parameter	Type	Required	Notes
`key`	string	yes	The column’s name. Not empty.
`kind`	one of `"categorical"`, `"continuous"`	yes
`categories`	list of string or null	yes	A categorical column’s categories (its values are codes into them; the largest code is “no category”); null for a continuous one.
`n_obs`	integer	yes	The cells of the dataset the column belongs to. At least 0.
`cells`	cells (original positions)	yes	The cells the values are of, as original positions; null for every cell in order.
`values`	one number per cell	yes	One value per cell named: a code (categorical) or a number (continuous).

Example:

{"key":"x","kind":"categorical","categories":[],"n_obs":0,"cells":[],"values":[]}

Timeline label: Added the categorical column x

Pseudocode: push_column("x", kind="categorical")

`field.rename`#

Rename a field. Give a column of the cells or a gene another name; its original name stays known, and renaming it back to that name restores it.

Agent tool: field_rename
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Fields and labels (field-overlays), Active field (active-field), Filters (filters), Colors (colors), Highlights (highlights), Views (views)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	A field by name: source “obs” for a column of the cells, “var” for a gene; key is the name as shown.
`name`	string	yes	A field name: not empty, unique among the fields shown. Not empty.

Example:

{"field":{"source":"obs","key":"cell_type"},"name":"x"}

Timeline label: Renamed cell_type to x

Pseudocode: rename_field("cell_type", "x")

`field.restore`#

Restore a deleted field. Bring back a deleted field under its name, as it was when deleted.

Agent tool: field_restore
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Fields and labels (field-overlays), Active field (active-field), Filters (filters), Colors (colors), Highlights (highlights), Views (views)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	The deleted field by the name it had when deleted.

Example:

{"field":{"source":"obs","key":"cell_type"}}

Timeline label: Restored cell_type

Pseudocode: restore_field("cell_type")

`field.revert-name`#

Restore a field’s original name. Give a renamed field back the name it has in the file.

Agent tool: field_revert_name
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Fields and labels (field-overlays), Active field (active-field), Filters (filters), Colors (colors), Highlights (highlights), Views (views)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	A field by name: source “obs” for a column of the cells, “var” for a gene; key is the name as shown.

Example:

{"field":{"source":"obs","key":"cell_type"}}

Timeline label: Restored the original name of cell_type

Pseudocode: revert_field_name("cell_type")

Genes#

`gene-set.save`#

Keep a gene set. A named list of genes, kept with the dataset for analyses and sessions; a later set of the same name replaces it.

Agent tool: gene_set_save
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Gene sets (gene-sets)

Parameter	Type	Required	Notes
`name`	string	yes	The set’s name. Not empty.
`description`	string	no	What the set is. Default `""`.
`genes`	list of string	yes	Gene names. At least 1 item.

Example:

{"name":"x","genes":["x"]}

Timeline label: Kept the gene set x (1 gene)

Pseudocode: gene_set("x", ["x"])

Colours#

`color.by`#

Colour the cells by a field or gene. Colour the view in focus by a column of the cells (source “obs”) or a gene (source “var”), reading it first when needed; null clears the colouring.

Agent tool: color_by
Effect: view: it changes how the data is shown
Changes: Active field (active-field), Filters (filters), Colors (colors)
A newer one replaces one still running

Parameter	Type	Required	Notes
`field`	object (`source`, `key`) or null	yes	The field or gene by name; null colours the cells by nothing.

Example:

{"field":{"source":"obs","key":"cell_type"}}

Timeline label: Coloured by cell_type

Pseudocode: color_by("cell_type")

`color.category`#

Colour one category. Give one category of a categorical column another colour.

Agent tool: color_category
Effect: view: it changes how the data is shown
Changes: Colors (colors)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	A categorical column of the cells by name (source “obs”).
`category`	string	yes	A category label as the legend shows it. Not empty.
`color`	string	yes	A colour as six hex digits, “#e41a1c”.

Example:

{"field":{"source":"obs","key":"cell_type"},"category":"T cells","color":"#e41a1c"}

Timeline label: Coloured T cells of cell_type #e41a1c

Pseudocode: color_category("cell_type", "T cells", "#e41a1c")

`color.continuous.colormap`#

Choose a colour map. The colour map a continuous field or gene is drawn with.

Agent tool: color_continuous_colormap
Effect: view: it changes how the data is shown
Changes: Colors (colors)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	The continuous field or gene the view in focus is coloured by, by name.
`colormap`	one of `"viridis"`, `"plasma"`, `"inferno"`, `"magma"`, `"cividis"`, `"turbo"`, `"twilight"`, `"coolwarm"`, `"bluered"`, `"spectral"`, `"rdylbu"`, `"rdbu"`, `"piyg"`, `"prgn"`, `"brbg"`, `"seismic"`, `"ylgnbu"`, `"ylorrd"`, `"ylorbr"`, `"gnbu"`, `"bupu"`, `"rdpu"`, `"purd"`, `"orrd"`, `"blues"`, `"greens"`, `"reds"`, `"purples"`, `"oranges"`, `"greys"`, `"heat"`, `"hot"`, `"cool"`, `"jet"`, `"rainbow"`, `"ocean"`, `"terrain"`, `"spring"`, `"summer"`, `"autumn"`, `"winter"`, `"bone"`, `"copper"`, `"pink"`	yes	The colour map by its id (viridis, magma, coolwarm, …).

Example:

{"field":{"source":"obs","key":"cell_type"},"colormap":"viridis"}

Timeline label: Drew cell_type in viridis

Pseudocode: colormap("cell_type", "viridis")

`color.continuous.log`#

Log colour scale. Colour a continuous field or gene on a log scale, or a linear one.

Agent tool: color_continuous_log
Effect: view: it changes how the data is shown
Changes: Colors (colors)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	The continuous field or gene the view in focus is coloured by, by name.
`enabled`	boolean	yes

Example:

{"field":{"source":"obs","key":"cell_type"},"enabled":false}

Timeline label: Turned the log colour scale off for cell_type

Pseudocode: log_color_scale("cell_type", False)

`color.continuous.range`#

Set the colour range. The values the colour map spans for a continuous field or gene that is rescaled to a range.

Agent tool: color_continuous_range
Effect: view: it changes how the data is shown
Changes: Colors (colors)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	The continuous field or gene the view in focus is coloured by, by name.
`min`	number	yes
`max`	number	yes

Example:

{"field":{"source":"obs","key":"cell_type"},"min":0,"max":0}

Timeline label: Spanned the colours of cell_type over 0–0

Pseudocode: color_range("cell_type", 0, 0)

`color.continuous.rescale`#

Rescale colours to the visible range. Stretch the colour map over the visible range of a continuous field or gene, or over all its values.

Agent tool: color_continuous_rescale
Effect: view: it changes how the data is shown
Changes: Colors (colors)
Depends on: Filters (filters), Open cells (cells)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	The continuous field or gene the view in focus is coloured by, by name.
`enabled`	boolean	yes

Example:

{"field":{"source":"obs","key":"cell_type"},"enabled":false}

Timeline label: Turned rescaling to the visible range off for cell_type

Pseudocode: rescale_colors("cell_type", False)

`color.continuous.zero-gray`#

Gray for zero. Draw a gene’s zeros in gray beneath the expressing cells, or in the colour map’s lowest colour.

Agent tool: color_continuous_zero_gray
Effect: view: it changes how the data is shown
Changes: Colors (colors)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	The continuous field or gene the view in focus is coloured by, by name.
`enabled`	boolean	yes

Example:

{"field":{"source":"obs","key":"cell_type"},"enabled":false}

Timeline label: Turned gray for zero off for cell_type

Pseudocode: gray_for_zero("cell_type", False)

Filters#

`filter.category.all`#

Show or hide every category. Show or hide every category of a categorical column that has open cells, and the cells without a category.

Agent tool: filter_category_all
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Filters (filters)
Depends on: Open cells (cells), Data mapping (mapping), Fields and labels (field-overlays), Hidden cells (visibility), Views (views)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	A categorical column of the cells by name (source “obs”).
`visible`	boolean	yes

Example:

{"field":{"source":"obs","key":"cell_type"},"visible":false}

Timeline label: Hid every category of cell_type

Pseudocode: hide_all_categories("cell_type")

`filter.category.cell-count`#

Keep N cells of a category. Show only count cells of one category, a random sample drawn with seed (the same seed and count show the same cells; a larger count adds cells); null shows all its cells again.

Agent tool: filter_category_cell_count
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Filters (filters)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	A categorical column of the cells by name (source “obs”).
`category`	string	yes	A category label as the legend shows it. Not empty.
`count`	integer or null	yes	How many of its cells stay shown; null for all of them. At least 0.
`seed`	integer	no	The sample’s seed. At least 0, at most 4294967295. Default `0`.

Example:

{"field":{"source":"obs","key":"cell_type"},"category":"T cells","count":0}

Timeline label: Kept 0 cells of T cells in cell_type

Pseudocode: keep_cells("cell_type", "T cells", 0)

`filter.category.missing`#

Show or hide cells without a category. Show or hide the cells of a categorical column that have no category (the legend’s Missing row).

Agent tool: filter_category_missing
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Filters (filters)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	A categorical column of the cells by name (source “obs”).
`visible`	boolean	yes

Example:

{"field":{"source":"obs","key":"cell_type"},"visible":false}

Timeline label: Hid the cells of cell_type without a category

Pseudocode: hide_missing("cell_type")

`filter.category.visibility`#

Show or hide categories. Show or hide the cells of one or more categories of a categorical column.

Agent tool: filter_category_visibility
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Filters (filters)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	A categorical column of the cells by name (source “obs”).
`categories`	list of string	yes	Category labels as the legend shows them. At least 1 item, each once.
`visible`	boolean	yes

Example:

{"field":{"source":"obs","key":"cell_type"},"categories":["T cells"],"visible":false}

Timeline label: Hid T cells of cell_type

Pseudocode: hide_categories("cell_type", ["T cells"])

`filter.continuous.range`#

Set a visible range. Show only the cells whose value of a continuous field or gene lies in [min, max]; the colours follow when they are rescaled to the range.

Agent tool: filter_continuous_range
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Filters (filters), Colors (colors)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	The continuous field or gene the view in focus is coloured by, by name.
`min`	number	yes
`max`	number	yes

Example:

{"field":{"source":"obs","key":"cell_type"},"min":0,"max":0}

Timeline label: Showed cell_type from 0 to 0

Pseudocode: visible_range("cell_type", 0, 0)

`filter.continuous.reset`#

Reset a visible range. Show every value of a continuous field or gene again.

Agent tool: filter_continuous_reset
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Filters (filters), Colors (colors)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	The continuous field or gene the view in focus is coloured by, by name.

Example:

{"field":{"source":"obs","key":"cell_type"}}

Timeline label: Reset the visible range of cell_type

Pseudocode: reset_range("cell_type")

`filter.enable`#

Turn a filter on or off. Turn a field’s category, range or outlier filter off (its settings kept) or on again.

Agent tool: filter_enable
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Filters (filters)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	The field or gene whose filter it is, by name.
`kind`	one of `"category"`, `"continuous"`, `"outlier"`	yes
`enabled`	boolean	yes

Example:

{"field":{"source":"obs","key":"cell_type"},"kind":"category","enabled":false}

Timeline label: Turned the category filter of cell_type off

Pseudocode: enable_filter("cell_type", "category", False)

`filter.outlier`#

Filter outliers. Hide the cells of each category that lie furthest from it in the latent space: those above the threshold quantile (1 hides none).

Agent tool: filter_outlier
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Filters (filters)
Depends on: Open cells (cells), Fields and labels (field-overlays), Data mapping (mapping)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	The categorical column the view in focus is coloured by, by name.
`threshold`	number	yes	The quantile above which cells are hidden; 1 hides none. At least 0, at most 1.

Example:

{"field":{"source":"obs","key":"cell_type"},"threshold":0}

Timeline label: Hid outliers of cell_type above 0 %

Pseudocode: outlier_filter("cell_type", 0)

`filter.remove`#

Remove a filter. Remove a field’s category, range or outlier filter: every cell it hid is shown again.

Agent tool: filter_remove
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Filters (filters), Colors (colors)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	The field or gene whose filter it is, by name.
`kind`	one of `"category"`, `"continuous"`, `"outlier"`	yes

Example:

{"field":{"source":"obs","key":"cell_type"},"kind":"category"}

Timeline label: Removed the category filter of cell_type

Pseudocode: remove_filter("cell_type", "category")

Data#

`cells.open`#

Open a share of the cells. Read the dataset again with every cell, or with exactly count cells chosen by a subsample method; highlights, labels, views and filters are kept for the cells still open.

Agent tool: cells_open
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Open cells (cells), Data mapping (mapping), Fields and labels (field-overlays), Gene sets (gene-sets), Views (views), Active field (active-field), Filters (filters), Colors (colors), Hidden cells (visibility), Highlights (highlights), Camera (camera), Settings (settings), Analysis (analysis)
A newer one replaces one still running

Parameter	Type	Required	Notes
`mode`	one of `"all"`, `"subsample"`	yes
`count`	integer	no	Subsample: how many cells. At least 1.
`method`	one of `"uniform"`, `"blocks"`, `"stratified"`, `"spatial"`, `null`	no	Subsample: how the cells are chosen; null for the file’s default. Default `null`.
`seed`	integer or null	no	Subsample: its seed; null for the file’s. At least 0, at most 4294967295. Default `null`.
`field`	string	no	Stratified: the categorical column it is stratified by. Not empty.
`allocation`	one of `"proportional"`, `"balanced"`	no	Stratified: how the cells are split over the categories. Default `"proportional"`.
`embedding`	string	no	Spatial: the obsm embedding it thins. Not empty.

Example:

{"mode":"all"}

Timeline label: Opened every cell

Pseudocode: open_cells("all")

`cells.read-genes`#

Read genes for more cells. Read every gene for the first cells open cells (a dataset stored cell by cell reads genes for a sample of the open cells); stopping keeps what was read.

Agent tool: cells_read_genes
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Open cells (cells)

Parameter	Type	Required	Notes
`cells`	integer	yes	How many of the open cells; more than are open reads every one. At least 1.

Example:

{"cells":1}

Timeline label: Read genes for 1 cell

Pseudocode: read_genes_for(1)

`mapping.set`#

Change the data mapping. Choose which stored arrays are the embeddings, neighbour graph, genes (modality, expression matrix, gene names, log1p, highly variable), latent space and vector fields; groups not named stay as they are. Applied as one change: refused, nothing changes.

Agent tool: mapping_set
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Data mapping (mapping), Views (views), Active field (active-field), Filters (filters), Colors (colors), Camera (camera), Analysis (analysis)

Parameter	Type	Required	Notes
`embeddings`	object (`enabled`, `defaults`)	no	The embeddings views can show, sorted by key then columns, and the default of each dimension.
`knn`	string or null	no	The obsp neighbour graph, or null for none. Not empty.
`modality`	string	no	The modality genes are read from (a dataset of several). Not empty.
`gene_names`	string	no	“index”, or “column:<var column>”. Not empty.
`expression`	string or null	no	“X”, “raw”, “layer:<name>”, or null for no genes. Not empty.
`log1p`	list of object (`matrix`, `base`)	no	Each expression matrix that holds log1p values, with its base (null: e).
`highly_variable`	string or null	no	The boolean var column marking highly variable genes, or null. Not empty.
`latent`	string or null	no	The obsm latent space outlier filters use, or null. Not empty.
`vector_fields`	list of object (`key`, `embedding`)	no	Vector fields bound to enabled embeddings, sorted by embedding then key.

Example:

{}

Timeline label: Applied the data mapping

Pseudocode: set_data_mapping()

Highlights#

`highlight.category`#

Highlight a category. Add the cells of one category of a field, as the selected view shows them, as a group.

Agent tool: highlight_category
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Highlights (highlights)
Depends on: Open cells (cells), Data mapping (mapping), Fields and labels (field-overlays), Filters (filters), Hidden cells (visibility), Views (views)
Run again on a stale step (the State panel) brings its result up to date

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	A categorical field, by name.
`category`	string or number or boolean	yes	The category, by its label as the legend shows it.
`page`	string	no	The page the group goes on, by name; a page of that name is made when there is none. Omitted: the page shown, or with `color`, a page of that colour. Not empty.
`color`	string	no	The colour of the page the group goes on. With `page`, the colour of the page made (an existing page must already have it). Without, the page shown when it has this colour, else the first page that has it, else a new page of it.

Example:

{"field":{"source":"obs","key":"cell_type"},"category":"T cells"}

Timeline label: Highlighted “T cells” of cell_type

Pseudocode: highlight_category("cell_type", "T cells")

`highlight.cells`#

Highlight cells. Add a group of cells to a highlight page: a confirmed selection, or cells an agent or notebook names.

Agent tool: highlight_cells
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Highlights (highlights)

Parameter	Type	Required	Notes
`cells`	cells (original positions)	yes	Cells by original position (0-based row of obs), each once, in any order. At least 1 item.
`label`	string	no	The group’s label; omitted, “Highlight (N cells)”. A label already on the page gets “ (2)”, “ (3)”, …. Not empty.
`tool`	one of `"annotation"`, `"lasso"`, `"proximity"`, `"knn"`	no	The selection tool that made the cells (annotation for cells named directly). Default `"annotation"`.
`page`	string	no	The page the group goes on, by name; a page of that name is made when there is none. Omitted: the page shown, or with `color`, a page of that colour. Not empty.
`color`	string	no	The colour of the page the group goes on. With `page`, the colour of the page made (an existing page must already have it). Without, the page shown when it has this colour, else the first page that has it, else a new page of it.

Example:

{"cells":[0,1,2]}

Timeline label: Highlighted 3 cells

Pseudocode: highlight_cells(<3 cells>)

`highlight.clear-all`#

Clear every highlight. Remove every group of every highlight page; the pages stay.

Agent tool: highlight_clear_all
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Highlights (highlights)

It takes no parameters.

Example:

{}

Timeline label: Cleared every highlight

Pseudocode: clear_highlights()

`highlight.group.remove`#

Remove a highlight group. Remove one group from a highlight page.

Agent tool: highlight_group_remove
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Highlights (highlights)

Parameter	Type	Required	Notes
`group`	string	yes	A highlight group, by its label as the group list shows it (without the cell count). Not empty.
`page`	string	no	The group’s page, by name; omitted, the page shown. Not empty.

Example:

{"group":"x"}

Timeline label: Removed highlight “x”

Pseudocode: remove_highlight("x")

`highlight.group.toggle`#

Show or hide a highlight group. Turn one group of a page on or off; a group that is off highlights nothing.

Agent tool: highlight_group_toggle
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Highlights (highlights)

Parameter	Type	Required	Notes
`group`	string	yes	A highlight group, by its label as the group list shows it (without the cell count). Not empty.
`enabled`	boolean	yes	true to show the group, false to hide it.
`page`	string	no	The group’s page, by name; omitted, the page shown. Not empty.

Example:

{"group":"x","enabled":false}

Timeline label: Hid highlight “x”

Pseudocode: set_highlight_enabled("x", False)

`highlight.page.clear`#

Clear a highlight page. Remove every group of one highlight page; the page stays.

Agent tool: highlight_page_clear
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Highlights (highlights)

Parameter	Type	Required	Notes
`page`	string	no	The page, by name; omitted, the page shown. Not empty.

Example:

{}

Timeline label: Cleared highlight page

Pseudocode: clear_highlight_page()

`highlight.page.combine`#

Combine two highlight pages. Make a page of the cells in both pages (intersection) or in either (union), and show it.

Agent tool: highlight_page_combine
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Highlights (highlights)

Parameter	Type	Required	Notes
`pages`	list of string	yes	The two pages, by name. At least 2 items, at most 2 items, each once.
`operation`	one of `"intersection"`, `"union"`	yes	Cells in both pages, or in either.
`name`	string	no	The new page’s name; omitted, “A ∩ B” or “A ∪ B”. Not empty.

Example:

{"pages":["Page 1","Page 2"],"operation":"intersection"}

Timeline label: Intersected highlight pages “Page 1” and “Page 2”

Pseudocode: combine_highlight_pages("Page 1", "Page 2", "intersection")

`highlight.page.create`#

Make a highlight page. Add an empty highlight page and show it.

Agent tool: highlight_page_create
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Highlights (highlights)

Parameter	Type	Required	Notes
`name`	string	no	The new page’s name; omitted, the first free “Page N”. Not empty.
`color`	string	no	The new page’s colour; omitted, the next colour of the page palette.

Example:

{}

Timeline label: Made highlight page “new”

Pseudocode: create_highlight_page()

`highlight.page.delete`#

Delete a highlight page. Delete a highlight page and its groups; the last page cannot be deleted.

Agent tool: highlight_page_delete
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Highlights (highlights)

Parameter	Type	Required	Notes
`page`	string	yes	A highlight page, by its name as its tab shows it. Not empty.

Example:

{"page":"Page 1"}

Timeline label: Deleted highlight page “Page 1”

Pseudocode: delete_highlight_page("Page 1")

`highlight.page.recolor`#

Recolour a highlight page. Set the colour a highlight page has in its tab, the analyses and the category builder.

Agent tool: highlight_page_recolor
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Highlights (highlights)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`page`	string	yes	A highlight page, by its name as its tab shows it. Not empty.
`color`	string	yes	A colour as six hex digits, “#e41a1c”.

Example:

{"page":"Page 1","color":"#e41a1c"}

Timeline label: Recoloured highlight page “Page 1” #e41a1c

Pseudocode: set_highlight_page_color("Page 1", "#e41a1c")

`highlight.page.rename`#

Rename a highlight page. Give a highlight page another name, unique among the pages.

Agent tool: highlight_page_rename
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Highlights (highlights)

Parameter	Type	Required	Notes
`page`	string	yes	A highlight page, by its name as its tab shows it. Not empty.
`name`	string	yes	The new name. Not empty.

Example:

{"page":"Page 1","name":"Page 1"}

Timeline label: Renamed highlight page “Page 1” to “Page 1”

Pseudocode: rename_highlight_page("Page 1", "Page 1")

`highlight.page.switch`#

Show a highlight page. Show another highlight page: its groups are the highlighted cells.

Agent tool: highlight_page_switch
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Highlights (highlights)

Parameter	Type	Required	Notes
`page`	string	yes	A highlight page, by its name as its tab shows it. Not empty.

Example:

{"page":"Page 1"}

Timeline label: Showed highlight page “Page 1”

Pseudocode: show_highlight_page("Page 1")

`highlight.range`#

Highlight a range of values. Add the cells whose value of a continuous field or gene lies in a range, as the selected view shows them, as a group.

Agent tool: highlight_range
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Highlights (highlights)
Depends on: Open cells (cells), Data mapping (mapping), Fields and labels (field-overlays), Filters (filters), Hidden cells (visibility), Views (views)
Run again on a stale step (the State panel) brings its result up to date

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	A continuous field or a gene, by name.
`min`	number	yes	The smallest value included.
`max`	number	yes	The largest value included.
`page`	string	no	The page the group goes on, by name; a page of that name is made when there is none. Omitted: the page shown, or with `color`, a page of that colour. Not empty.
`color`	string	no	The colour of the page the group goes on. With `page`, the colour of the page made (an existing page must already have it). Without, the page shown when it has this colour, else the first page that has it, else a new page of it.

Example:

{"field":{"source":"obs","key":"cell_type"},"min":0,"max":0}

Timeline label: Highlighted cell_type from 0 to 0

Pseudocode: highlight_range("cell_type", 0, 0)

Views#

`view.cameras.link`#

Link cameras. Let views that show the same embedding share one camera, or give each view its own.

Agent tool: view_cameras_link
Effect: view: it changes how the data is shown
Changes: Views (views), Camera (camera)

Parameter	Type	Required	Notes
`linked`	boolean	yes	true to link, false to unlink.

Example:

{"linked":false}

Timeline label: Gave each view its own camera

Pseudocode: link_cameras(False)

`view.clear`#

Remove every kept view. Remove every kept view and show the live view alone (as View 1).

Agent tool: view_clear
Effect: view: it changes how the data is shown
Changes: Views (views), Active field (active-field), Filters (filters), Colors (colors), Hidden cells (visibility), Camera (camera)

It takes no parameters.

Example:

{}

Timeline label: Removed every kept view

Pseudocode: clear_views()

`view.embedding.cycle`#

Next embedding of a dimension. The 1, 2 and 3 keys: a view showing another dimension shows this dimension’s default; one already showing it moves to the next enabled embedding.

Agent tool: view_embedding_cycle
Effect: view: it changes how the data is shown
Changes: Views (views), Camera (camera)

Parameter	Type	Required	Notes
`view`	string	yes	A view: “View N” as the Compare views list numbers its rows (the live view is View 1 while it is shown, the kept views follow in the order they were kept).
`dimension`	one of `1`, `2`, `3`	yes	The dimension: 1, 2 or 3.

Example:

{"view":"View 1","dimension":1}

Timeline label: Showed the next 1D embedding in View 1

Pseudocode: next_embedding("View 1", 1)

`view.embedding.default`#

Show the default embedding. Show the dataset’s default embedding of one dimension in a view; the view follows that default from then on.

Agent tool: view_embedding_default
Effect: view: it changes how the data is shown
Changes: Views (views), Camera (camera)
A newer one replaces one still running

Parameter	Type	Required	Notes
`view`	string	yes	A view: “View N” as the Compare views list numbers its rows (the live view is View 1 while it is shown, the kept views follow in the order they were kept).
`dimension`	one of `1`, `2`, `3`	yes	The dimension: 1, 2 or 3.

Example:

{"view":"View 1","dimension":1}

Timeline label: Showed the 1D default in View 1

Pseudocode: show_default_embedding("View 1", 1)

`view.embedding.set`#

Show an embedding. Show one enabled embedding in a view; the view keeps it when the data mapping changes its defaults.

Agent tool: view_embedding_set
Effect: view: it changes how the data is shown
Changes: Views (views), Camera (camera)
A newer one replaces one still running

Parameter	Type	Required	Notes
`view`	string	yes	A view: “View N” as the Compare views list numbers its rows (the live view is View 1 while it is shown, the kept views follow in the order they were kept).
`embedding`	object (`key`, `columns`)	yes	An embedding: the obsm array and the columns of it plotted.

Example:

{"view":"View 1","embedding":{"key":"X_umap","columns":[0,1]}}

Timeline label: Showed obsm[“X_umap”] [0, 1] in View 1

Pseudocode: show_embedding("View 1", "X_umap", [0, 1])

`view.focus`#

Select a view. Select the view the sidebar edits and the camera controls drive.

Agent tool: view_focus
Effect: view: it changes how the data is shown
Changes: Views (views), Camera (camera)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`view`	string	yes	A view: “View N” as the Compare views list numbers its rows (the live view is View 1 while it is shown, the kept views follow in the order they were kept).

Example:

{"view":"View 1"}

Timeline label: Selected View 1

Pseudocode: select_view("View 1")

`view.keep`#

Keep the view. Freeze the selected view as a panel of the multiview, with its colouring, filters and camera, and select it; with a branch, the view as it is at the last step of that branch of the history (to compare branches side by side).

Agent tool: view_keep
Effect: view: it changes how the data is shown
Changes: Views (views), Active field (active-field), Filters (filters), Colors (colors), Hidden cells (visibility), Camera (camera)
Depends on: the history (history)

Parameter	Type	Required	Notes
`branch`	string	no	A branch of the tracker in use, by its name: the kept view shows what the selected view shows at its last step (colouring, filters, hidden cells, camera). Not empty.

Example:

{}

Timeline label: Kept the view

Pseudocode: keep_view()

`view.layout.set`#

Set the view layout. Show every view side by side (grid) or the selected view alone (single).

Agent tool: view_layout_set
Effect: view: it changes how the data is shown
Changes: Views (views)

Parameter	Type	Required	Notes
`layout`	one of `"grid"`, `"single"`	yes	“grid” or “single”.

Example:

{"layout":"grid"}

Timeline label: Showed the views side by side

Pseudocode: set_view_layout("grid")

`view.picture`#

Take a picture of a view. A PNG of a view as the figure export draws it (points, legend), returned as base64; nothing is downloaded.

Agent tool: view_picture
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`view`	string	no	The view: “View N” as the Compare views list numbers it; the selected view when left out.
`width`	integer	no	The plot’s width in pixels (the picture adds its margins and the legend). At least 100, at most 20000. Default `640`.
`height`	integer	no	The plot’s height in pixels. At least 100, at most 20000. Default `480`.
`legend`	boolean	no	Draw the colour legend beside the plot. Default `true`.

Example:

{}

It returns:

Field	Type	Notes
`png`	string	The image, base64-encoded PNG bytes (an agent receives it as an image).
`width`	integer	The image’s width in pixels.
`height`	integer	The image’s height in pixels.
`plot`	object (`width`, `height`)	The plot’s size in the image, as asked for.
`view`	string	The view drawn, by its name.
`notes`	list of string	What the picture leaves out of what the view shows (an overlay it cannot draw).

`view.remove`#

Remove a view. Remove a view; removing the live view (View 1) hides it while two or more kept views remain.

Agent tool: view_remove
Effect: view: it changes how the data is shown
Changes: Views (views), Active field (active-field), Filters (filters), Colors (colors), Hidden cells (visibility), Camera (camera)

Parameter	Type	Required	Notes
`view`	string	yes	A view: “View N” as the Compare views list numbers its rows (the live view is View 1 while it is shown, the kept views follow in the order they were kept).

Example:

{"view":"View 1"}

Timeline label: Removed View 1

Pseudocode: remove_view("View 1")

`views.state`#

Read the views. Each open view: its name (what actions name it by), its title, the representation it shows, what it is coloured by, its filters and camera; the layout; the highlight pages with their groups.

Agent tool: views_state
Effect: read: it reads, changes nothing and records no step

It takes no parameters.

Example:

{}

It returns:

Field	Type	Notes
`active`	string	The name of the view the controls act on (“View N”).
`layout`	one of `"single"`, `"grid"`
`cameras_locked`	boolean
`views`	list of object (`name`, `title`, `live`, `active`, `representation`, `colored_by`, `filters`, `camera`)
`highlights`	object (`active_page`, `pages`)

Cells#

`cells.visibility.set`#

Hide or show cells. Hide or show cells one by one in the selected view, on top of every filter.

Agent tool: cells_visibility_set
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Hidden cells (visibility)

Parameter	Type	Required	Notes
`cells`	cells (original positions) or null	yes	Cells by original position, or null for every cell.
`visible`	boolean	yes	true to show them, false to hide them.

Example:

{"cells":[0,1,2],"visible":false}

Timeline label: Hid 3 cells

Pseudocode: set_visibility(<3 cells>, visible=False)

Camera#

`camera.navigation.set`#

Set the navigation mode. Navigate a view by orbit, planar or free-fly (O, P and G); views with linked cameras share one mode.

Agent tool: camera_navigation_set
Effect: view: it changes how the data is shown
Changes: Camera (camera)

Parameter	Type	Required	Notes
`view`	string	yes	A view: “View N” as the Compare views list numbers its rows (the live view is View 1 while it is shown, the kept views follow in the order they were kept).
`mode`	one of `"orbit"`, `"planar"`, `"free"`	yes	“orbit”, “planar” or “free” (free-fly).

Example:

{"view":"View 1","mode":"orbit"}

Timeline label: Navigated View 1 by orbit

Pseudocode: set_navigation_mode("View 1", "orbit")

`camera.reset`#

Reset the camera. Put a view’s camera back to its starting place, keeping its navigation mode (the R key).

Agent tool: camera_reset
Effect: view: it changes how the data is shown
Changes: Camera (camera)

Parameter	Type	Required	Notes
`view`	string	yes	A view: “View N” as the Compare views list numbers its rows (the live view is View 1 while it is shown, the kept views follow in the order they were kept).

Example:

{"view":"View 1"}

Timeline label: Reset the camera of View 1

Pseudocode: reset_camera("View 1")

`camera.set`#

Place the camera. Set the camera of a view (views with linked cameras follow); a camera gesture records one of these.

Agent tool: camera_set
Effect: view: it changes how the data is shown
Changes: Camera (camera)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`view`	string	yes	A view: “View N” as the Compare views list numbers its rows (the live view is View 1 while it is shown, the kept views follow in the order they were kept).
`camera`	object (`navigationMode`, `orbit`, `freefly`)	yes	A camera: its navigation mode, and its orbit and free-fly poses (the one the mode drives is used).

Example:

{"view":"View 1","camera":{"navigationMode":"orbit","orbit":{"radius":1,"targetRadius":1,"theta":0,"phi":0,"target":[0,0,0]},"freefly":{"position":[0,0,0],"yaw":0,"pitch":0}}}

Timeline label: Moved the camera of View 1

Pseudocode: set_camera("View 1", <camera>)

`display.reset`#

Reset the camera and display. The Reset camera button: the selected view’s camera, its dimension’s navigation mode, the background, the render mode and the smoke resolutions back to their defaults.

Agent tool: display_reset
Effect: view: it changes how the data is shown
Changes: Camera (camera), Settings (settings)

It takes no parameters.

Example:

{}

Timeline label: Reset the camera and display

Pseudocode: reset_display()

Camera path#

`camera-path.clear`#

Clear the camera path. Delete every keyframe of the camera path; playback stops where the camera is.

Agent tool: camera_path_clear
Effect: view: it changes how the data is shown
Changes: Camera path (camera-path)

It takes no parameters.

Example:

{}

Timeline label: Cleared the camera path

Pseudocode: clear_camera_path()

`camera-path.duration.set`#

Set a camera path transition time. Set how long the camera takes from one keyframe to the next, or from every keyframe to its next.

Agent tool: camera_path_duration_set
Effect: view: it changes how the data is shown
Changes: Camera path (camera-path)

Parameter	Type	Required	Notes
`keyframe`	string	no	The keyframe the transition starts at; omitted, every keyframe. Not empty.
`seconds`	number or null	yes	Seconds of the transition to the next keyframe, at least 0.1; null paces it automatically. At least 0.1.

Example:

{"seconds":0.1}

Timeline label: Set every camera path transition to 0.1 s

Pseudocode: set_keyframe_duration(None, 0.1)

`camera-path.keyframe.add`#

Add a camera path keyframe. Save a camera as the next keyframe of the camera path (before the return to start, when there is one).

Agent tool: camera_path_keyframe_add
Effect: view: it changes how the data is shown
Changes: Camera path (camera-path)
Depends on: Camera (camera)

Parameter	Type	Required	Notes
`camera`	object (`navigationMode`, `orbit`, `freefly`)	no	The camera to save; omitted, the selected view’s camera now.
`label`	string	no	The keyframe’s label; omitted, “KF n”. Unique among the keyframes. Not empty.
`embedding`	object (`key`, `columns`) or null	no	The embedding the keyframe was recorded on; omitted, the one the selected view shows.

Example:

{}

Timeline label: Saved camera path keyframe “new”

Pseudocode: add_keyframe()

`camera-path.keyframe.move`#

Move a camera path keyframe. Move a keyframe one place earlier (up) or later (down) in the camera path.

Agent tool: camera_path_keyframe_move
Effect: view: it changes how the data is shown
Changes: Camera path (camera-path)

Parameter	Type	Required	Notes
`keyframe`	string	yes	A keyframe, by its label as the Camera path list shows it. Not empty.
`direction`	one of `"up"`, `"down"`	yes	“up” one place earlier, “down” one place later.

Example:

{"keyframe":"x","direction":"up"}

Timeline label: Moved camera path keyframe “x” earlier

Pseudocode: move_keyframe("x", "up")

`camera-path.keyframe.remove`#

Delete a camera path keyframe. Delete one keyframe of the camera path.

Agent tool: camera_path_keyframe_remove
Effect: view: it changes how the data is shown
Changes: Camera path (camera-path)

Parameter	Type	Required	Notes
`keyframe`	string	yes	A keyframe, by its label as the Camera path list shows it. Not empty.

Example:

{"keyframe":"x"}

Timeline label: Deleted camera path keyframe “x”

Pseudocode: remove_keyframe("x")

`camera-path.keyframe.rename`#

Rename a camera path keyframe. Give a keyframe another label, unique among the keyframes.

Agent tool: camera_path_keyframe_rename
Effect: view: it changes how the data is shown
Changes: Camera path (camera-path)

Parameter	Type	Required	Notes
`keyframe`	string	yes	A keyframe, by its label as the Camera path list shows it. Not empty.
`label`	string	yes	The new label. Not empty.

Example:

{"keyframe":"x","label":"x"}

Timeline label: Renamed camera path keyframe “x” to “x”

Pseudocode: rename_keyframe("x", "x")

`camera-path.loop-back.set`#

End the camera path at its start. Add or remove a last keyframe that returns the camera to the first one (two keyframes or more).

Agent tool: camera_path_loop_back_set
Effect: view: it changes how the data is shown
Changes: Camera path (camera-path)

Parameter	Type	Required	Notes
`enabled`	boolean	yes	true to end with the return, false to remove it.

Example:

{"enabled":false}

Timeline label: Removed the camera path’s return to its start

Pseudocode: set_keyframe_loop_back(False)

`camera-path.playback.set`#

Set camera path playback. Set how the camera path plays: interpolation, easing, speed of automatic transitions, loop and autoplay.

Agent tool: camera_path_playback_set
Effect: view: it changes how the data is shown
Changes: Camera path (camera-path)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`position_interpolation`	one of `"catmull-rom"`, `"linear"`, `"bezier"`	no	How positions between keyframes are drawn.
`rotation_interpolation`	one of `"slerp"`, `"linear"`	no	How the view direction turns between keyframes.
`easing`	one of `"linear"`, `"ease-in-out"`, `"ease-in"`, `"ease-out"`	no	How each transition speeds up and slows down.
`speed`	integer	no	Speed of automatic transitions, 1 (very slow) to 100 (very fast). At least 1, at most 100.
`loop`	boolean	no	Play the path again from its start when it ends.
`autoplay`	boolean	no	Start playing as soon as the path has two keyframes.

Example:

{}

Timeline label: Set camera path playback: unchanged

Pseudocode: set_camera_path_playback()

Settings#

`figure-export.set`#

Change figure export settings. Set Figure export options: size, frame, background, fonts, title and axis labels, axes, legend, preview, what Export downloads; only those given change, nothing is exported.

Agent tool: figure_export_set
Effect: view: it changes how the data is shown
Changes: Settings (settings)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`size_preset`	one of `"screen-half"`, `"screen"`, `"1200x900"`, `"1600x1200"`, `"1920x1080"`	no	The size preset shown in the panel.
`width`	integer	no	Plot width in CSS pixels. At least 100, at most 20000.
`height`	integer	no	Plot height in CSS pixels. At least 100, at most 20000.
`frame`	object (`lock_aspect`, `rect`) or null	no	The part of the view exported (needs the preview on), or null for the whole view.
`background`	one of `"viewer"`, `"white"`, `"transparent"`, `"custom"`	no	The background: the viewer’s, white, transparent or custom.
`background_color`	string	no	The custom background colour, lowercase #rrggbb.
`font_family`	one of `"Arial, Helvetica, sans-serif"`, `"Helvetica, Arial, sans-serif"`, `"\"Times New Roman\", Times, serif"`	no	The font of every text.
`auto_text_size`	boolean	no	Size the text from the figure’s size (font_sizes is then null).
`font_sizes`	object (`base`, `legend`, `ticks`, `axis_label`, `title`, `centroid_label`) or null	no	Text sizes in pixels while auto_text_size is off, else null.
`title_follows_dataset`	boolean	no	The title is the dataset’s name (title is then null).
`title`	string or null	no	The figure title while it does not follow the dataset, else null.
`x_label`	string	no	The x axis label.
`y_label`	string	no	The y axis label.
`include_axes`	boolean	no	Draw the axes.
`include_legend`	boolean	no	Draw the legend.
`reference_grid`	boolean	no	Draw a reference grid.
`show_orientation`	boolean	no	Draw the 3D orientation indicator.
`depth_sort`	boolean	no	Draw 3D points back to front.
`legend_position`	one of `"right"`, `"bottom"`	no	Where the legend goes.
`emphasize_selection`	boolean	no	Fade the cells that are not highlighted.
`selection_muted_opacity`	number	no	The opacity of the faded cells, 0 to 1. At least 0, at most 1.
`preview`	object (`enabled`, `colorblind_mode`)	no	The preview in the panel and the colour-vision deficiency it simulates.
`download`	one of `"svg"`, `"png"`, `"svg+png"`, `"png-multi"`, `"all"`	no	What Export downloads.
`dpi`	one of `150`, `300`, `600`	no	The resolution of a PNG.
`svg_strategy`	one of `"full-vector"`, `"optimized-vector"`, `"hybrid"`, `null`	no	How an SVG draws many points, or null until chosen.
`optimized_target_count`	integer	no	How many points an optimized SVG keeps. At least 1000, at most 5000000.
`export_all_views`	boolean	no	Export every view of the multiview, side by side.

Example:

{"width":1200,"height":900,"include_axes":false}

Timeline label: Figure export: width 1200, height 900, include axes off

Pseudocode: set_figure_export(width=1200, height=900, include_axes=false)

`setting.set`#

Change a setting. Set one render, navigation, overlay or tool setting of the sidebar; settings.list names each, with its kind, range and choices.

Agent tool: setting_set
Effect: view: it changes how the data is shown
Changes: Settings (settings), Views (views)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`setting`	string	yes	The setting’s id, as settings.list gives it. Not empty.
`value`	string or number or boolean	yes	A number for a slider, true or false for a switch, an option value for a choice, #rrggbb for a colour.

Example:

{"setting":"point-size","value":20}

Timeline label: point-size: set to 20

Pseudocode: set_setting("point-size", 20)

`settings.list`#

List the settings. Every setting of the sidebar with its label, section, kind, value, range or choices, and whether it can be changed now.

Agent tool: settings_list
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`section`	string	no	Only the settings of the sidebar section with this title (Visualization, Navigation, …). Not empty.

Example:

{}

It returns:

Field	Type	Notes
`settings`	list of object (`id`, `label`, `section`, `kind`, `value`, `shown`, `min`, `max`, `step`, `options`, `available`)

Layout#

`layout.get`#

Read the layout. The sidebar’s sections (docked or floating, where, open or closed), whether the sidebar shows and how wide, and the theme.

Agent tool: layout_get
Effect: read: it reads, changes nothing and records no step

It takes no parameters.

Example:

{}

It returns:

Field	Type	Notes
`panels`	list of object (`id`, `title`, `floating`, `open`, `left`, `top`, `width`, `height`)
`sidebar`	object (`shown`, `width`)
`theme`	one of `"light"`, `"dark"`

`layout.panel.dock`#

Dock a section. Put a floating sidebar section back into the sidebar, where it was.

Agent tool: layout_panel_dock
Effect: layout: it changes the panels, sections or theme
Changes: Layout (layout)

Parameter	Type	Required	Notes
`panel`	string	yes	A sidebar section by its title (Visualization, Navigation, …) or its id. Not empty.

Example:

{"panel":"Visualization"}

Timeline label: Docked Visualization

Pseudocode: dock_panel("Visualization")

`layout.panel.float`#

Undock a section. Tear a sidebar section off into a floating window, at a given place and size or beside the sidebar.

Agent tool: layout_panel_float
Effect: layout: it changes the panels, sections or theme
Changes: Layout (layout)

Parameter	Type	Required	Notes
`panel`	string	yes	A sidebar section by its title (Visualization, Navigation, …) or its id. Not empty.
`left`	number	no	Distance of its left edge from the left of the window, in CSS pixels.
`top`	number	no	Distance of its top edge from the top of the window, in CSS pixels.
`width`	number	no	Width in CSS pixels (kept at least its smallest working width). More than 0.
`height`	number	no	Height in CSS pixels (kept at least its header and first row). More than 0.

Example:

{"panel":"Visualization"}

Timeline label: Undocked Visualization

Pseudocode: float_panel("Visualization")

`layout.panel.place`#

Move or resize a floating section. Give a floating sidebar section a place and size; it is kept inside the window.

Agent tool: layout_panel_place
Effect: layout: it changes the panels, sections or theme
Changes: Layout (layout)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`panel`	string	yes	A sidebar section by its title (Visualization, Navigation, …) or its id. Not empty.
`left`	number	yes	Distance of its left edge from the left of the window, in CSS pixels.
`top`	number	yes	Distance of its top edge from the top of the window, in CSS pixels.
`width`	number	yes	Width in CSS pixels (kept at least its smallest working width). More than 0.
`height`	number	yes	Height in CSS pixels (kept at least its header and first row). More than 0.

Example:

{"panel":"Visualization","left":0,"top":0,"width":1,"height":1}

Timeline label: Moved Visualization to 1 × 1 at 0, 0

Pseudocode: place_panel("Visualization", left=0, top=0, width=1, height=1)

`layout.section.open`#

Open or close a section. Open or close a section of the sidebar (docked or floating).

Agent tool: layout_section_open
Effect: layout: it changes the panels, sections or theme
Changes: Layout (layout)

Parameter	Type	Required	Notes
`section`	string	yes	A sidebar section by its title (Visualization, Navigation, …) or its id. Not empty.
`open`	boolean	yes	True opens it, false closes it.

Example:

{"section":"Visualization","open":false}

Timeline label: Closed Visualization

Pseudocode: open_section("Visualization", False)

`layout.sidebar.show`#

Show or hide the sidebar. Show the sidebar beside the plot, or hide it to give the plot the whole window.

Agent tool: layout_sidebar_show
Effect: layout: it changes the panels, sections or theme
Changes: Layout (layout)

Parameter	Type	Required	Notes
`shown`	boolean	yes	True shows the sidebar, false hides it.

Example:

{"shown":false}

Timeline label: Hid the sidebar

Pseudocode: show_sidebar(False)

`layout.sidebar.width`#

Resize the sidebar. Set the sidebar’s width (kept between its narrowest and widest).

Agent tool: layout_sidebar_width
Effect: layout: it changes the panels, sections or theme
Changes: Layout (layout)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`width`	number	yes	Width in CSS pixels. More than 0.

Example:

{"width":1}

Timeline label: Made the sidebar 1 pixel wide

Pseudocode: sidebar_width(1)

`layout.theme.set`#

Choose the theme. Show the app light or dark.

Agent tool: layout_theme_set
Effect: layout: it changes the panels, sections or theme
Changes: Layout (layout)

Parameter	Type	Required	Notes
`theme`	one of `"light"`, `"dark"`	yes

Example:

{"theme":"light"}

Timeline label: Chose the light theme

Pseudocode: set_theme("light")

Dataset#

`cells.values`#

Read values of cells. The values of named cells (original positions) in each field or gene asked for.

Agent tool: cells_values
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`cells`	cells (original positions)	yes	Cells by original position (their row in the file’s obs). At least 1 item.
`fields`	list of object (`source`, `key`)	yes	At least 1 item.

Example:

{"cells":[0],"fields":[{"source":"obs","key":"cell_type"}]}

It returns:

Field	Type	Notes
`cells`	list of integer	The cells asked for that are open, in the order asked.
`columns`	list of object (`field`, `values`)
`not_open`	list of integer	Cells asked for that are not open (a subsample).

`dataset.summary`#

Read the dataset summary. The open dataset: its name, citation, how many cells (and how many are open), genes, embeddings and fields.

Agent tool: dataset_summary
Effect: read: it reads, changes nothing and records no step

It takes no parameters.

Example:

{}

It returns:

Field	Type	Notes
`name`	string or null
`id`	string or null	The dataset’s id where it has one.
`source`	string or null	Where it was opened from (a sample, a link, a local file, a notebook).
`citation`	string or null
`cells`	object (`total`, `open`, `share`, `subsample`, `digest`)
`genes`	object (`count`, `read_for`)
`embeddings`	list of object (`name`, `dimension`)
`fields`	object (`categorical`, `continuous`, `user_defined`)

`field.categories`#

Read the categories of a field. Each category of a categorical field with its cells, the cells shown in the active view, its colour and whether it is shown.

Agent tool: field_categories
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	A field by name: source “obs” for a column of the cells, “var” for a gene; key is the name as shown.

Example:

{"field":{"source":"obs","key":"cell_type"}}

It returns:

Field	Type	Notes
`field`	string
`view`	string	The view the colours and shown counts are of (the selected one), named as actions name views (“View N”).
`categories`	list of object (`label`, `cells`, `visible`, `color`, `shown`)
`missing`	integer	Open cells without a category. At least 0.

`field.summary`#

Summarise a field per category. A continuous field or a gene per category of a categorical field (cells, mean, median, range, share above zero), or a categorical field’s top categories per category.

Agent tool: field_summary
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	A field by name: source “obs” for a column of the cells, “var” for a gene; key is the name as shown.
`by`	object (`source`, `key`)	yes	The categorical obs field to group the cells by.
`top`	integer	no	For a categorical field: at most this many of its categories per group. At least 1. Default `50`.
`visible_only`	boolean	no	Only the cells the active view shows. Default `false`.

Example:

{"field":{"source":"obs","key":"cell_type"},"by":{"source":"obs","key":"cell_type"}}

It returns:

Field	Type	Notes
`field`	object (`source`, `key`, `kind`)
`by`	string
`read_for`	object (`cells`, `of`) or null	For a gene read for a sample of the open cells: the cells its statistics are of.
`groups`	list of object (`label`, `cells`, `mean`, `median`, `min`, `max`, `above_zero`, `top`)

`fields.list`#

List the fields. The cell annotations (obs fields) with their kind and, for a categorical one, how many categories it has.

Agent tool: fields_list
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`kind`	one of `"categorical"`, `"continuous"`	no	Only fields of this kind.
`query`	string	no	Only fields whose key contains this text (any case). Not empty.

Example:

{}

It returns:

Field	Type	Notes
`fields`	list of object (`key`, `kind`, `categories`, `user_defined`)

`genes.search`#

Search the genes. Gene names matching what is typed, best first, as the gene search box ranks them.

Agent tool: genes_search
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`query`	string	yes	Not empty.
`limit`	integer	no	At most this many names. At least 1. Default `20`.

Example:

{"query":"CD3"}

It returns:

Field	Type	Notes
`genes`	list of string
`matches`	integer	How many genes match in all. At least 0.
`total`	integer	How many genes the dataset has. At least 0.

Analysis#

`analysis.cancel`#

Stop an analysis. Stop a running analysis; what it was showing stays, nothing else changes.

Agent tool: analysis_cancel
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`analysis`	one of `"markers"`, `"differential"`, `"dotplot"`, `"signature"`, `"composition"`, `"correlation"`	yes	An analysis with a Run button.
`in`	`"panel"` or integer	no	Default `"panel"`.

Example:

{"analysis":"markers"}

It returns:

Field	Type	Notes
`stopped`	boolean	False when it was not running.

`analysis.close`#

Close the open analysis. Close the analysis open in the Analysis panel (its settings and result stay).

Agent tool: analysis_close
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Analysis (analysis)

It takes no parameters.

Example:

{}

Timeline label: Closed the analysis

Pseudocode: close_analysis()

`analysis.composition.get`#

Read composition options. The composition analysis’s options, pages and result state.

Agent tool: analysis_composition_get
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`in`	`"panel"` or integer	no	Default `"panel"`.

Example:

{}

It returns:

Field	Type	Notes
`analysis`	`"composition"`
`in`	`"panel"` or integer	Default `"panel"`.
`options`	object (`cellTypes`, `samples`, `condition`, `cells`, `onlyTypes`, `method`, `correction`, `barsBy`, `order`, `values`)
`pages`	list of string
`has_result`	boolean
`running`	boolean
`stale`	boolean	The result no longer matches its inputs (the reasons say what changed).
`stale_reasons`	list of string
`computed_on`	object (`dataset`, `cells`, `genes_read_for`, `mapping`, `pages`, `visible_only`) or null	What the result was computed on.

`analysis.composition.set`#

Set composition options. Change options of the composition analysis (only those given); nothing runs.

Agent tool: analysis_composition_set
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Analysis (analysis)
Depends on: Active field (active-field), Fields and labels (field-overlays), Data mapping (mapping), Highlights (highlights)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`in`	`"panel"` or integer	no	Default `"panel"`.
`options`	object (`cellTypes`, `samples`, `condition`, `cells`, `onlyTypes`, `method`, `correction`, `barsBy`, `order`, `values`)	yes
`show`	boolean	no	Also open it in the Analysis panel (with in “panel”), as another analysis’s “send to” does. Default `false`.

Example:

{"options":{}}

Timeline label: Set no options of Composition

Pseudocode: analysis_set("composition", {})

`analysis.correlation.get`#

Read correlation options. The correlation analysis’s options, pages and result state.

Agent tool: analysis_correlation_get
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`in`	`"panel"` or integer	no	Default `"panel"`.

Example:

{}

It returns:

Field	Type	Notes
`analysis`	`"correlation"`
`in`	`"panel"` or integer	Default `"panel"`.
`options`	object (`variableX`, `variableY`, `method`, `colorBy`)
`pages`	list of string
`has_result`	boolean
`running`	boolean
`stale`	boolean	The result no longer matches its inputs (the reasons say what changed).
`stale_reasons`	list of string
`computed_on`	object (`dataset`, `cells`, `genes_read_for`, `mapping`, `pages`, `visible_only`) or null	What the result was computed on.

`analysis.correlation.set`#

Set correlation options. Change options of the correlation analysis (only those given); nothing runs.

Agent tool: analysis_correlation_set
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Analysis (analysis)
Depends on: Active field (active-field), Fields and labels (field-overlays), Data mapping (mapping), Highlights (highlights)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`in`	`"panel"` or integer	no	Default `"panel"`.
`options`	object (`variableX`, `variableY`, `method`, `colorBy`)	yes
`show`	boolean	no	Also open it in the Analysis panel (with in “panel”), as another analysis’s “send to” does. Default `false`.

Example:

{"options":{}}

Timeline label: Set no options of Correlation

Pseudocode: analysis_set("correlation", {})

`analysis.detailed.set`#

Choose what the detailed analysis plots. The variable the detailed analysis plots (a field or a gene, by name, or none), the plot, and options of that plot (only those given); it updates by itself.

Agent tool: analysis_detailed_set
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Analysis (analysis)
Depends on: Open cells (cells), Data mapping (mapping), Fields and labels (field-overlays), Filters (filters), Hidden cells (visibility), Views (views), Highlights (highlights)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`in`	`"panel"` or integer	no	Default `"panel"`.
`variable`	null or object (`type`, `key`)	no	What to plot: a column of the cells (categorical_obs, continuous_obs) or a gene (gene_expression) by name, or null for nothing.
`plot`	string	no	The plot, by its id as the Plot select offers it for the variable’s kind. Not empty.
`plot_options`	list of object (`option`, `value`)	no	Options of the plot, each by its name and value. At least 1 item.

Example:

{"variable":{"type":"categorical_obs","key":"cell_type"}}

Timeline label: Plotted cell_type in Detailed

Pseudocode: analysis_detailed({"variable":{"type":"categorical_obs","key":"cell_type"}})

`analysis.differential.get`#

Read differential expression options. The differential expression analysis’s options, pages and result state.

Agent tool: analysis_differential_get
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`in`	`"panel"` or integer	no	Default `"panel"`.

Example:

{}

It returns:

Field	Type	Notes
`analysis`	`"differential"`
`in`	`"panel"` or integer	Default `"panel"`.
`options`	object (`compare`, `pageA`, `pageB`, `field`, `categoriesA`, `categoriesB`, `within`, `withinField`, `withinCategories`, `minCells`, `replicates`, `minCellsPerSample`, `method`, `pConvention`, `correction`, `matrix`, `foldChange`, `maxAdjP`, `minLog2FC`, `minPct`, `excludeGenes`, `excludePattern`, `onlyGenes`, `onlyGenesList`, `labels`)
`pages`	list of string
`has_result`	boolean
`running`	boolean
`stale`	boolean	The result no longer matches its inputs (the reasons say what changed).
`stale_reasons`	list of string
`computed_on`	object (`dataset`, `cells`, `genes_read_for`, `mapping`, `pages`, `visible_only`) or null	What the result was computed on.

`analysis.differential.set`#

Set differential expression options. Change options of the differential expression analysis (only those given); nothing runs.

Agent tool: analysis_differential_set
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Analysis (analysis)
Depends on: Active field (active-field), Fields and labels (field-overlays), Data mapping (mapping), Highlights (highlights)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`in`	`"panel"` or integer	no	Default `"panel"`.
`options`	object (`compare`, `pageA`, `pageB`, `field`, `categoriesA`, `categoriesB`, `within`, `withinField`, `withinCategories`, `minCells`, `replicates`, `minCellsPerSample`, `method`, `pConvention`, `correction`, `matrix`, `foldChange`, `maxAdjP`, `minLog2FC`, `minPct`, `excludeGenes`, `excludePattern`, `onlyGenes`, `onlyGenesList`, `labels`)	yes
`show`	boolean	no	Also open it in the Analysis panel (with in “panel”), as another analysis’s “send to” does. Default `false`.

Example:

{"options":{}}

Timeline label: Set no options of Differential expression

Pseudocode: analysis_set("differential", {})

`analysis.dotplot.get`#

Read dot plot options. The dot plot analysis’s options, pages and result state.

Agent tool: analysis_dotplot_get
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`in`	`"panel"` or integer	no	Default `"panel"`.

Example:

{}

It returns:

Field	Type	Notes
`analysis`	`"dotplot"`
`in`	`"panel"` or integer	Default `"panel"`.
`options`	object (`groupBy`, `geneSets`, `groups`, `cells`, `matrix`, `scale`, `cutoff`, `meanOnlyExpressing`, `plot`, `swapAxes`, `groupOrder`, `colorMap`, `maxDotSize`)
`pages`	list of string
`has_result`	boolean
`running`	boolean
`stale`	boolean	The result no longer matches its inputs (the reasons say what changed).
`stale_reasons`	list of string
`computed_on`	object (`dataset`, `cells`, `genes_read_for`, `mapping`, `pages`, `visible_only`) or null	What the result was computed on.

`analysis.dotplot.set`#

Set dot plot options. Change options of the dot plot analysis (only those given); nothing runs.

Agent tool: analysis_dotplot_set
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Analysis (analysis)
Depends on: Active field (active-field), Fields and labels (field-overlays), Data mapping (mapping), Highlights (highlights)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`in`	`"panel"` or integer	no	Default `"panel"`.
`options`	object (`groupBy`, `geneSets`, `groups`, `cells`, `matrix`, `scale`, `cutoff`, `meanOnlyExpressing`, `plot`, `swapAxes`, `groupOrder`, `colorMap`, `maxDotSize`)	yes
`show`	boolean	no	Also open it in the Analysis panel (with in “panel”), as another analysis’s “send to” does. Default `false`.

Example:

{"options":{}}

Timeline label: Set no options of Dot plot

Pseudocode: analysis_set("dotplot", {})

`analysis.list`#

List the analyses. Each analysis of the panel and each analysis window: which is open, its pages, whether it has a result, is running, or is stale and why.

Agent tool: analysis_list
Effect: read: it reads, changes nothing and records no step

It takes no parameters.

Example:

{}

It returns:

Field	Type	Notes
`open`	string or null	The analysis open in the panel.
`analyses`	list of object (`analysis`, `title`, `in`, `pages`, `has_result`, `running`, `stale`, `stale_reasons`, `computed_on`)

`analysis.markers.get`#

Read marker genes options. The marker genes analysis’s options, pages and result state.

Agent tool: analysis_markers_get
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`in`	`"panel"` or integer	no	Default `"panel"`.

Example:

{}

It returns:

Field	Type	Notes
`analysis`	`"markers"`
`in`	`"panel"` or integer	Default `"panel"`.
`options`	object (`groupBy`, `compareAgainst`, `referenceGroup`, `testGroups`, `cells`, `restIncludes`, `minCells`, `smallGroups`, `method`, `pConvention`, `correction`, `matrix`, `foldChange`, `direction`, `maxAdjP`, `minLog2FC`, `minPctIn`, `maxPctRef`, `excludeGenes`, `excludePattern`, `onlyGenes`, `onlyGenesList`, `rankBy`, `topN`)
`pages`	list of string
`has_result`	boolean
`running`	boolean
`stale`	boolean	The result no longer matches its inputs (the reasons say what changed).
`stale_reasons`	list of string
`computed_on`	object (`dataset`, `cells`, `genes_read_for`, `mapping`, `pages`, `visible_only`) or null	What the result was computed on.

`analysis.markers.set`#

Set marker genes options. Change options of the marker genes analysis (only those given); nothing runs.

Agent tool: analysis_markers_set
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Analysis (analysis)
Depends on: Active field (active-field), Fields and labels (field-overlays), Data mapping (mapping), Highlights (highlights)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`in`	`"panel"` or integer	no	Default `"panel"`.
`options`	object (`groupBy`, `compareAgainst`, `referenceGroup`, `testGroups`, `cells`, `restIncludes`, `minCells`, `smallGroups`, `method`, `pConvention`, `correction`, `matrix`, `foldChange`, `direction`, `maxAdjP`, `minLog2FC`, `minPctIn`, `maxPctRef`, `excludeGenes`, `excludePattern`, `onlyGenes`, `onlyGenesList`, `rankBy`, `topN`)	yes
`show`	boolean	no	Also open it in the Analysis panel (with in “panel”), as another analysis’s “send to” does. Default `false`.

Example:

{"options":{}}

Timeline label: Set no options of Marker genes

Pseudocode: analysis_set("markers", {})

`analysis.open`#

Open an analysis. Show an analysis in the Analysis panel, or open it in a new floating window with the panel’s settings.

Agent tool: analysis_open
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Analysis (analysis), Layout (layout)
Depends on: Open cells (cells), Data mapping (mapping), Fields and labels (field-overlays), Filters (filters), Hidden cells (visibility), Views (views), Highlights (highlights), Active field (active-field)

Parameter	Type	Required	Notes
`analysis`	one of `"markers"`, `"differential"`, `"dotplot"`, `"signature"`, `"composition"`, `"quick"`, `"detailed"`, `"correlation"`	yes	The analysis: markers (marker genes), differential (differential expression), dotplot, signature (gene signature), composition, quick, detailed, correlation.
`window`	boolean	no	Open it in a new floating window. Default `false`.

Example:

{"analysis":"markers"}

Timeline label: Opened Marker genes

Pseudocode: open_analysis("markers")

`analysis.pages.set`#

Choose the pages of an analysis. The highlight pages an analysis compares (by name, “Rest of ” for the rest of a page’s cells); nothing runs.

Agent tool: analysis_pages_set
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Analysis (analysis)
Depends on: Open cells (cells), Data mapping (mapping), Fields and labels (field-overlays), Filters (filters), Hidden cells (visibility), Views (views), Highlights (highlights)

Parameter	Type	Required	Notes
`analysis`	one of `"markers"`, `"differential"`, `"dotplot"`, `"signature"`, `"composition"`, `"quick"`, `"detailed"`, `"correlation"`	yes	The analysis: markers (marker genes), differential (differential expression), dotplot, signature (gene signature), composition, quick, detailed, correlation.
`in`	`"panel"` or integer	no	Default `"panel"`.
`pages`	list of string	yes	Each once.

Example:

{"analysis":"markers","pages":[]}

Timeline label: Chose no pages for Marker genes

Pseudocode: analysis_pages("markers", [])

`analysis.quick.set`#

Choose the fields of the quick analysis. The categorical columns whose composition and the continuous columns whose statistics the quick analysis shows (only the kinds given; before a choice it shows the first two of each); it updates by itself.

Agent tool: analysis_quick_set
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Analysis (analysis)
Depends on: Open cells (cells), Data mapping (mapping), Fields and labels (field-overlays), Filters (filters), Hidden cells (visibility), Views (views), Highlights (highlights)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`in`	`"panel"` or integer	no	Default `"panel"`.
`categorical`	list of string	no	Categorical columns of the cells, by name (their composition). Each once.
`continuous`	list of string	no	Continuous columns of the cells, by name (their statistics). Each once.

Example:

{"categorical":["cell_type"]}

Timeline label: Showed composition of cell_type in Quick

Pseudocode: analysis_quick({"categorical":["cell_type"]})

`analysis.result`#

Read an analysis result. The top rows of an analysis’s result table (N a parameter), with what it was computed on and whether it is stale.

Agent tool: analysis_result
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`analysis`	one of `"markers"`, `"differential"`, `"dotplot"`, `"signature"`, `"composition"`, `"correlation"`	yes	An analysis with a Run button.
`in`	`"panel"` or integer	no	Default `"panel"`.
`top`	integer	no	At most this many rows (per group, where the result has groups). At least 1. Default `20`.

Example:

{"analysis":"markers"}

It returns:

Field	Type	Notes
`analysis`	string
`columns`	list of string
`rows`	list of list of string or number or boolean or null
`total_rows`	integer	Rows in the whole result.
`stale`	boolean
`stale_reasons`	list of string
`computed_on`	object (`dataset`, `cells`, `genes_read_for`, `mapping`, `pages`, `visible_only`) or null	What the result was computed on.

`analysis.run`#

Run an analysis. Run an analysis with its options and pages, and wait for its result.

Agent tool: analysis_run
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Analysis (analysis)
Depends on: Open cells (cells), Data mapping (mapping), Fields and labels (field-overlays), Filters (filters), Hidden cells (visibility), Views (views), Highlights (highlights)
Run again on a stale step (the State panel) brings its result up to date

Parameter	Type	Required	Notes
`analysis`	one of `"markers"`, `"differential"`, `"dotplot"`, `"signature"`, `"composition"`, `"correlation"`	yes	An analysis with a Run button.
`in`	`"panel"` or integer	no	Default `"panel"`.

Example:

{"analysis":"markers"}

Timeline label: Ran Marker genes

Pseudocode: run_analysis("markers")

`analysis.signature.get`#

Read gene signature options. The gene signature analysis’s options, pages and result state.

Agent tool: analysis_signature_get
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`in`	`"panel"` or integer	no	Default `"panel"`.

Example:

{}

It returns:

Field	Type	Notes
`analysis`	`"signature"`
`in`	`"panel"` or integer	Default `"panel"`.
`options`	object (`geneSets`, `method`, `controlSize`, `bins`, `seed`, `maxRank`, `plotType`, `rescale`, `layout`)
`pages`	list of string
`has_result`	boolean
`running`	boolean
`stale`	boolean	The result no longer matches its inputs (the reasons say what changed).
`stale_reasons`	list of string
`computed_on`	object (`dataset`, `cells`, `genes_read_for`, `mapping`, `pages`, `visible_only`) or null	What the result was computed on.

`analysis.signature.set`#

Set gene signature options. Change options of the gene signature analysis (only those given); nothing runs.

Agent tool: analysis_signature_set
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Analysis (analysis)
Depends on: Active field (active-field), Fields and labels (field-overlays), Data mapping (mapping), Highlights (highlights)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`in`	`"panel"` or integer	no	Default `"panel"`.
`options`	object (`geneSets`, `method`, `controlSize`, `bins`, `seed`, `maxRank`, `plotType`, `rescale`, `layout`)	yes
`show`	boolean	no	Also open it in the Analysis panel (with in “panel”), as another analysis’s “send to” does. Default `false`.

Example:

{"options":{}}

Timeline label: Set no options of Gene signature

Pseudocode: analysis_set("signature", {})

`analysis.size.set`#

Size an analysis’s expanded view. The size and splits an analysis’s expanded view opens at, remembered per analysis; a person sets them by resizing it.

Agent tool: analysis_size_set
Effect: layout: it changes the panels, sections or theme
Changes: Layout (layout)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`analysis`	one of `"markers"`, `"differential"`, `"dotplot"`, `"signature"`, `"composition"`, `"quick"`, `"detailed"`, `"correlation"`	yes	The analysis: markers (marker genes), differential (differential expression), dotplot, signature (gene signature), composition, quick, detailed, correlation.
`expanded`	object (`width`, `height`, `optionsWidth`, `footerHeight`, `statsWidth`)	yes	The expanded view’s box and its splits, in CSS pixels.

Example:

{"analysis":"markers","expanded":{"width":900,"height":600,"optionsWidth":260,"footerHeight":180,"statsWidth":320}}

Timeline label: Resized the expanded view of Marker genes

Pseudocode: size_analysis_view("markers", width=900, height=600)

`analysis.view.set`#

Change how an analysis is shown. Open or close its option groups, and choose what its result shows (marker genes: list or heatmap, the group listed, the heatmap’s look; gene signature: the set shown; the options of the plot its expanded view draws); nothing runs.

Agent tool: analysis_view_set
Effect: view: it changes how the data is shown
Changes: Analysis (analysis)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`analysis`	one of `"markers"`, `"differential"`, `"dotplot"`, `"signature"`, `"composition"`, `"correlation"`	yes	An analysis with an options form.
`in`	`"panel"` or integer	no	Default `"panel"`.
`view`	object (`more`, `groups`, `show`, `group`, `heatmap`, `set`, `plot`)	yes	What to change of how the analysis is shown (only the keys given).

Example:

{"analysis":"markers","view":{"show":"list"}}

Timeline label: Showed Marker genes as a list

Pseudocode: analysis_view("markers", {"show":"list"})

`analysis.window.close`#

Close an analysis window. Close a floating analysis window (its settings and result go with it; undo brings it back).

Agent tool: analysis_window_close
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Analysis (analysis), Layout (layout)

Parameter	Type	Required	Notes
`window`	integer	yes	A floating analysis window, by its number (1 is the first open). At least 1.

Example:

{"window":1}

Timeline label: Closed analysis window 1

Pseudocode: close_analysis_window(1)

`analysis.window.collapse`#

Collapse or expand an analysis window. Fold a floating analysis window to its title bar, or unfold it again; its analysis is kept.

Agent tool: analysis_window_collapse
Effect: layout: it changes the panels, sections or theme
Changes: Layout (layout)

Parameter	Type	Required	Notes
`window`	integer	yes	A floating analysis window, by its number (1 is the first open). At least 1.
`collapsed`	boolean	yes	True folds it to its title bar, false unfolds it.

Example:

{"window":1,"collapsed":false}

Timeline label: Expanded analysis window 1

Pseudocode: collapse_analysis_window(1, False)

`analysis.window.copy`#

Copy an analysis window. Open a new floating window with a window’s analysis and settings.

Agent tool: analysis_window_copy
Effect: state: it changes what the data says (fields, labels, filters, highlights, results)
Changes: Analysis (analysis), Layout (layout)
Depends on: Open cells (cells), Data mapping (mapping), Fields and labels (field-overlays), Filters (filters), Hidden cells (visibility), Views (views), Highlights (highlights)

Parameter	Type	Required	Notes
`window`	integer	yes	A floating analysis window, by its number (1 is the first open). At least 1.

Example:

{"window":1}

Timeline label: Copied window 1

Pseudocode: copy_analysis_window(1)

`analysis.window.place`#

Move or resize an analysis window. Give a floating analysis window a place and size; it is kept inside the window.

Agent tool: analysis_window_place
Effect: layout: it changes the panels, sections or theme
Changes: Layout (layout)
Repeated at once (a drag, a gesture), it is one step

Parameter	Type	Required	Notes
`window`	integer	yes	A floating analysis window, by its number (1 is the first open). At least 1.
`left`	number	yes
`top`	number	yes
`width`	number	yes	More than 0.
`height`	number	yes	More than 0.

Example:

{"window":1,"left":0,"top":0,"width":1,"height":1}

Timeline label: Moved analysis window 1

Pseudocode: place_analysis_window(1, left=0, top=0, width=1, height=1)

Datasets#

`dataset.open`#

Open a dataset. Open a dataset by the name the person gives: a built-in sample, one of their datasets (My datasets), a link, or an accession the link box takes. It replaces the open dataset; that one’s history stays kept in this browser and the new one starts its own. A whole-file download is asked about first.

Agent tool: dataset_open
Effect: dataset: it opens another dataset, whose history starts anew (the open one’s stays kept in this browser), and records no step
Asks the person first when an agent takes it: it downloads a lot (large-download)

Parameter	Type	Required	Notes
`name`	string	yes	A sample’s name or id, a name from My datasets, a link to a dataset (a file, a Zarr store, a dataset folder, a CELLxGENE, Zenodo, Figshare or GitHub address), an accession (GSE123456, a DOI), or a Cellucid server (localhost:8765). Not empty.
`kind`	one of `"any"`, `"sample"`, `"my-datasets"`, `"link"`	no	Where to look for the name: any (samples, then My datasets, then as a link), sample, my-datasets or link. Default `"any"`.

Example:

{"name":"Pancreatic endocrinogenesis (scVelo)"}

It returns:

Field	Type	Notes
`name`	string	The dataset now open, as Cellucid names it.
`kind`	one of `"sample"`, `"link"`, `"server"`, `"file"`, `"folder"`, `"notebook"`	Where it opens from: a built-in sample, a link, a Cellucid server, a file or folder of the person’s computer, or a notebook (Python, R) that serves it.
`cells`	integer	The cells open (a share of the dataset when it is subsampled). At least 0.
`total_cells`	integer	At least 0.
`genes`	integer or null	At least 0.
`saved_states`	integer	Histories of this dataset kept in this browser from earlier visits; the person was offered to continue the latest. At least 0.
`already_open`	boolean	It was open already, so nothing was opened again and its history goes on.

Timeline label: Opened Pancreatic endocrinogenesis (scVelo)

Pseudocode: open_dataset("Pancreatic endocrinogenesis (scVelo)")

`dataset.share-link`#

Make a share link. The public link that opens the dataset shown on www.cellucid.com for anyone, with its “Open in Cellucid” badge and an embed snippet, as Share in Session › Open data makes them; what a link carried to grant access is left out. Refused for a dataset no link reopens (a file of this computer, a notebook’s, a server on this computer).

Agent tool: dataset_share_link
Effect: outside: it acts outside the dataset’s state and history (writes a file the person receives, publishes, or keeps or removes something in this browser for later visits), which the history cannot take back, and records no step
Asks the person first when an agent takes it: it publishes (publishes)

It takes no parameters.

Example:

{}

It returns:

Field	Type	Notes
`link`	string	The link.
`badge`	string	The badge as Markdown.
`embed`	string	The embed snippet as HTML.
`access_left_out`	boolean	The dataset’s link carried a key, a signature or a token that was left out: someone without access cannot open it.

Timeline label: Made a share link

Pseudocode: share_link()

`datasets.list`#

List the datasets to open. The datasets this tab can open by name: the built-in samples and the person’s own datasets opened before in this browser (My datasets, each with its size and what this browser keeps of it), with the one open now.

Agent tool: datasets_list
Effect: read: it reads, changes nothing and records no step

It takes no parameters.

Example:

{}

It returns:

Field	Type	Notes
`open`	object (`name`, `kind`) or null	The dataset open now, or null.
`samples`	list of object (`name`, `id`, `cells`, `genes`)
`my_datasets`	list of object (`name`, `kind`, `cells`, `genes`, `last_opened`, `saved_states`, `size`, `saved_states_bytes`, `kept_bytes`, `agent_can_open`)	Most recently opened first.

`my-datasets.forget`#

Forget a dataset of My datasets. Remove one dataset from My datasets, as its Forget in My datasets › All… does: the entry and, for a file or folder of this computer, the browser’s handle of it; its saved states only when asked. The dataset itself is not touched, and nothing brings the entry back but opening it again.

Agent tool: my_datasets_forget
Effect: outside: it acts outside the dataset’s state and history (writes a file the person receives, publishes, or keeps or removes something in this browser for later visits), which the history cannot take back, and records no step
Asks the person first when an agent takes it: it deletes something saved (deletes-saved)

Parameter	Type	Required	Notes
`name`	string	yes	Its name in My datasets (datasets_list). Not empty.
`saved_states`	boolean	no	Also delete its saved states (histories kept in this browser). Default `false`.

Example:

{"name":"Pancreatic endocrinogenesis (scVelo)"}

It returns:

Field	Type	Notes
`name`	string	The dataset forgotten.
`handles`	integer	Handles of files of this computer forgotten with it. At least 0.
`saved_states`	integer	Its saved states deleted. At least 0.

Timeline label: Forgot Pancreatic endocrinogenesis (scVelo) in My datasets

Pseudocode: forget_dataset("Pancreatic endocrinogenesis (scVelo)")

Stored#

`stored.list`#

List what this browser keeps. Everything kept in this browser for later visits, as the Stored dialog lists it: per dataset (its file’s name and host) the converted copies, downloads, downloaded parts and gene indexes with their sizes; then the saved states, My datasets, the connection speeds and the decoder choices; and how much room the browser gives the site.

Agent tool: stored_list
Effect: read: it reads, changes nothing and records no step

It takes no parameters.

Example:

{}

It returns:

Field	Type	Notes
`datasets`	list of object (`name`, `host`, `bytes`, `items`)	Most recently used first.
`saved_states`	object (`count`, `bytes`)	The histories kept in this browser (history_saved_list lists each).
`my_datasets`	object (`count`, `files`)	The datasets opened in this browser (datasets_list lists each) and the files of this computer among them it can reopen.
`connection_speeds`	integer	Hosts whose connection speed is remembered. At least 0.
`decoder_choices`	integer	Decoder choices measured in this browser. At least 0.
`bytes`	integer	What the kept items and saved states take. At least 0.
`room`	object (`usage`, `quota`, `kept_when_space_is_low`)	What the browser says of the site’s storage.

`stored.remove`#

Remove what this browser keeps. Remove what the Stored dialog removes: kept items by id, all a dataset’s kept items, every saved state, My datasets (the list and the files’ handles), the connection speeds, the decoder choices, or everything (Remove all). An item an open tab uses stays until that tab closes. Nothing brings it back; the dataset opens again more slowly the first time.

Agent tool: stored_remove
Effect: outside: it acts outside the dataset’s state and history (writes a file the person receives, publishes, or keeps or removes something in this browser for later visits), which the history cannot take back, and records no step
Asks the person first when an agent takes it: it deletes something saved (deletes-saved)

Parameter	Type	Required	Notes
`items`	list of string	no	Kept items by id (stored_list). At least 1 item, each once.
`dataset`	string	no	Every kept item of the dataset with this file name (stored_list). Not empty.
`saved_states`	boolean	no	Every saved state of this browser (history_saved_delete deletes one). Default `false`.
`my_datasets`	boolean	no	My datasets: the list and the handles of its files (my_datasets_forget forgets one). Default `false`.
`connection_speeds`	boolean	no	The connection speeds remembered per host. Default `false`.
`decoder_choices`	boolean	no	The decoder choices measured in this browser. Default `false`.
`everything`	boolean	no	Everything no open tab uses, as Remove all. Default `false`.

Example:

{}

It returns:

Field	Type	Notes
`removed`	integer	Kept items removed. At least 0.
`held`	integer	Kept items that stay, in use by an open tab. At least 0.
`saved_states`	integer	Saved states deleted. At least 0.
`my_datasets`	integer	Datasets forgotten from My datasets. At least 0.
`connection_speeds`	integer	Hosts whose connection speed was forgotten. At least 0.
`decoder_choices`	integer	Decoder choices forgotten. At least 0.
`said`	string	What the dialog says of it.

Timeline label: Removed what this browser keeps

Pseudocode: stored_remove()

Exports#

`cells.export`#

Export the highlighted cells. Write the highlighted cells of a highlight page as a file, as the Highlights list’s export buttons do: an obs-column CSV (every open cell, a true/false column per highlight, which cellucid.pull() in Python and cellucid_pull() in R read back) or an .h5ad subset of the highlighted cells with their expression rows. The .h5ad reads the cells’ expression first; its time and bytes are estimated from this connection before it starts.

Agent tool: cells_export
Effect: outside: it acts outside the dataset’s state and history (writes a file the person receives, publishes, or keeps or removes something in this browser for later visits), which the history cannot take back, and records no step
Asks the person first when an agent takes it: it writes a file (writes-file)

Parameter	Type	Required	Notes
`page`	string	no	The highlight page; the page shown when left out. Not empty.
`format`	one of `"csv"`, `"h5ad"`	no	csv: the obs-column CSV; h5ad: an AnnData file of the highlighted cells. Default `"csv"`.

Example:

{}

It returns:

Field	Type	Notes
`file`	string	The file written.
`bytes`	integer	At least 0.
`format`	one of `"csv"`, `"h5ad"`
`page`	string	The highlight page exported.
`cells`	integer	Cells highlighted on it. At least 0.
`renamed`	list of object (`key`, `name`)	Names an .h5ad cannot hold as they are, written under other names.

Timeline label: Exported the highlighted cells as CSV

Pseudocode: export_cells()

`field.export`#

Export a field. Write a column of the cells (categorical or continuous) as an obs-column CSV, as its Export button in Color by does: every open cell and its value, which cellucid.pull() in Python and cellucid_pull() in R read back.

Agent tool: field_export
Effect: outside: it acts outside the dataset’s state and history (writes a file the person receives, publishes, or keeps or removes something in this browser for later visits), which the history cannot take back, and records no step
Asks the person first when an agent takes it: it writes a file (writes-file)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	A column of the cells by name (source “obs”), categorical or continuous.

Example:

{"field":{"source":"obs","key":"cell_type"}}

It returns:

Field	Type	Notes
`file`	string	The file written.
`bytes`	integer	At least 0.
`field`	string	The field exported.
`kind`	one of `"categorical"`, `"continuous"`

Timeline label: Exported cell_type as CSV

Pseudocode: export_field("cell_type")

`figure.export`#

Export the figure. Write the figure of the view shown (every view in a grid when the settings say so) as its Download button does, with the figure export’s settings as they are (figure_export_set changes them: format, size, labels, legend, style): one SVG or PNG file, or several in one ZIP archive. Refused, saying why, when the figure cannot reproduce what the view shows (a render mode other than points, an overlay it cannot draw).

Agent tool: figure_export
Effect: outside: it acts outside the dataset’s state and history (writes a file the person receives, publishes, or keeps or removes something in this browser for later visits), which the history cannot take back, and records no step
Asks the person first when an agent takes it: it writes a file (writes-file)

It takes no parameters.

Example:

{}

It returns:

Field	Type	Notes
`files`	list of object (`format`, `file`, `dpi`)	The figures written: one file, or several in one ZIP archive.
`zip`	boolean	The files were written in one ZIP archive (several formats or resolutions).

Timeline label: Exported the figure

Pseudocode: export_figure()

Community annotation#

`annotation.suggest`#

Suggest a label. Suggest a label for a category in the person’s name, with their upvote, as the voting dialog’s New suggestion does, and publish that suggestion alone: the person’s own file in the community annotation repository is written as published now plus this suggestion (a pull request when they cannot write to the repository), which others see on their next Pull. A label already suggested for the category is refused with its id (vote on it instead). Asked of the person first; the history cannot take it back. Refused until the person has connected the repository and signed in to GitHub.

Agent tool: annotation_suggest
Effect: outside: it acts outside the dataset’s state and history (writes a file the person receives, publishes, or keeps or removes something in this browser for later visits), which the history cannot take back, and records no step
Asks the person first when an agent takes it: it publishes (publishes)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	A categorical column of the cells by name (source “obs”).
`category`	string	yes	A category label as the legend shows it. Not empty.
`label`	string	yes	The label suggested. Not empty.
`ontology_id`	string	no	Its ontology term, when known. Not empty.
`evidence`	string	no	Why: the markers or reasoning behind it. Not empty.

Example:

{"field":{"source":"obs","key":"cell_type"},"category":"T cells","label":"CD4+ T cell"}

It returns:

Field	Type	Notes
`repository`	string	The GitHub repository of the community annotation.
`published`	one of `"repository"`, `"pull-request"`	Where the suggestion went: written to the repository, or in a pull request its authors merge.
`pull_request`	string or null	The pull request, when it went to one.
`id`	string	The suggestion’s id (annotation_vote takes it).
`label`	string	The label suggested.
`not_published`	integer or null	The person’s other changes still not published (null when not known). At least 0.

Timeline label: Suggested “CD4+ T cell” for T cells of cell_type

Pseudocode: annotation_suggest("cell_type", "T cells", "CD4+ T cell")

`annotation.suggestions`#

Read the community annotation. The labels suggested for the categories of a field by the community annotation of the dataset shown (its connected GitHub repository), with their votes, the person’s own vote and each category’s consensus, as the voting dialog and the legend show them; whether the field is open for voting, and when this browser last pulled. One page holds what fits a tool result; next starts the following one.

Agent tool: annotation_suggestions
Effect: read: it reads, changes nothing and records no step

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	A categorical column of the cells by name (source “obs”).
`category`	string	no	One category; every category of the field when left out. Not empty.
`cursor`	integer	no	Where the page starts: the next of the last page; the first page when left out. At least 0.

Example:

{"field":{"source":"obs","key":"cell_type"}}

It returns:

Field	Type	Notes
`repository`	string	The GitHub repository it is kept in.
`pulled_at`	string or null	When this browser last pulled from it (an ISO instant), null before the first Pull: votes made since are not here.
`annotated`	boolean	The field is open to community annotation.
`closed`	boolean	Voting on the field is closed (only its authors still vote).
`repository_field`	string	The field’s name in the repository, when the person renamed it here.
`categories`	list of object (`category`, `repository_category`, `consensus`, `suggestions`)
`total_categories`	integer	Categories on every page. At least 0.
`next`	integer or null	The cursor of the next page; null on the last. At least 0.

`annotation.vote`#

Vote on a suggested label. Vote a suggested label of a category up or down (none takes the person’s vote back) and publish that vote alone: the person’s own file in the community annotation repository is written as published now plus this vote (a pull request when they cannot write to the repository), which others see on their next Pull. Nothing else of the person’s is published, and a vote that changes nothing publishes nothing. Asked of the person first; the history cannot take it back. Refused until the person has connected the repository and signed in to GitHub.

Agent tool: annotation_vote
Effect: outside: it acts outside the dataset’s state and history (writes a file the person receives, publishes, or keeps or removes something in this browser for later visits), which the history cannot take back, and records no step
Asks the person first when an agent takes it: it publishes (publishes)

Parameter	Type	Required	Notes
`field`	object (`source`, `key`)	yes	A categorical column of the cells by name (source “obs”).
`category`	string	yes	A category label as the legend shows it. Not empty.
`suggestion`	string	yes	The suggestion, by its id or its label (annotation_suggestions); suggestions with the same label are one suggestion. Not empty.
`vote`	one of `"up"`, `"down"`, `"none"`	yes	up, down, or none to take the person’s vote back.

Example:

{"field":{"source":"obs","key":"cell_type"},"category":"T cells","suggestion":"CD4+ T cell","vote":"up"}

It returns:

Field	Type	Notes
`repository`	string	The GitHub repository of the community annotation.
`published`	one of `"repository"`, `"pull-request"`, `"unchanged"`	Where the vote went: written to the repository, in a pull request its authors merge, or nowhere (it was already so).
`pull_request`	string or null	The pull request, when it went to one.
`suggestion`	string	The label voted on.
`vote`	one of `"up"`, `"down"`, `"none"`	The person’s vote on it now.
`up`	integer	Its upvotes now. At least 0.
`down`	integer	Its downvotes now. At least 0.
`not_published`	integer or null	The person’s other changes still not published (null when not known). At least 0.

Timeline label: Voted “CD4+ T cell” up for T cells of cell_type

Pseudocode: annotation_vote("cell_type", "T cells", "CD4+ T cell", "up")

Action reference#

State domains#

History#

history.anndata.save#

history.bookmark.set#

history.branch.apply#

history.branch.archive#

history.branch.cancel#

history.branch.create#

history.branch.delete#

history.branch.lock#

history.branch.rename#

history.branch.set-main#

history.branch.switch#

history.branch.without#

history.clear#

history.diff#

history.get#

history.group.create#

history.group.extend#

history.group.remove#

history.group.rename#

history.journal.empty#

history.journal.undo#

history.jump#

history.methods#

history.note.add#

history.note.edit#

history.note.remove#

history.pseudocode#

history.recording.pause#

history.recording.resume#

history.redo#

history.replay#

history.report#

history.save#

history.saved.delete#

history.saved.list#

history.search#

history.share#

history.squash#

history.stale#

history.step#

history.step.delete#

history.step.revert#

history.summary#

history.tour.start#

history.tour.stop#

history.tracker.remove#

history.tracker.rename#

history.tracker.start#

history.tracker.use#

history.turn.undo#

history.undo#

history.verify#

Fields#

category.delete#

category.merge#

category.rename#

field.consensus#

field.create-from-pages#

field.delete#

field.duplicate#

field.purge#

field.push#

field.rename#

field.restore#

field.revert-name#

Genes#

gene-set.save#

Colours#

color.by#

color.category#

color.continuous.colormap#

color.continuous.log#

color.continuous.range#

color.continuous.rescale#

color.continuous.zero-gray#

Filters#

filter.category.all#

`history.anndata.save`#

`history.bookmark.set`#

`history.branch.apply`#

`history.branch.archive`#

`history.branch.cancel`#

`history.branch.create`#

`history.branch.delete`#

`history.branch.lock`#

`history.branch.rename`#

`history.branch.set-main`#

`history.branch.switch`#

`history.branch.without`#

`history.clear`#

`history.diff`#

`history.get`#

`history.group.create`#

`history.group.extend`#

`history.group.remove`#

`history.group.rename`#

`history.journal.empty`#

`history.journal.undo`#

`history.jump`#

`history.methods`#

`history.note.add`#

`history.note.edit`#

`history.note.remove`#

`history.pseudocode`#

`history.recording.pause`#

`history.recording.resume`#

`history.redo`#

`history.replay`#

`history.report`#

`history.save`#

`history.saved.delete`#

`history.saved.list`#

`history.search`#

`history.share`#

`history.squash`#

`history.stale`#

`history.step`#

`history.step.delete`#

`history.step.revert`#

`history.summary`#

`history.tour.start`#

`history.tour.stop`#

`history.tracker.remove`#

`history.tracker.rename`#

`history.tracker.start`#

`history.tracker.use`#

`history.turn.undo`#

`history.undo`#

`history.verify`#

`category.delete`#

`category.merge`#

`category.rename`#

`field.consensus`#

`field.create-from-pages`#

`field.delete`#

`field.duplicate`#

`field.purge`#

`field.push`#

`field.rename`#

`field.restore`#

`field.revert-name`#

`gene-set.save`#

`color.by`#

`color.category`#

`color.continuous.colormap`#

`color.continuous.log`#

`color.continuous.range`#

`color.continuous.rescale`#

`color.continuous.zero-gray`#

`filter.category.all`#

`filter.category.cell-count`#

`filter.category.missing`#

`filter.category.visibility`#

`filter.continuous.range`#

`filter.continuous.reset`#

`filter.enable`#

`filter.outlier`#