"""The viewer's methods, one per action of the catalogue: generated, do not edit.
Written by ``scripts/generate_actions.py`` from ``cellucid/action_catalog.json``
(the web app's action catalogue, digest a805685f10d2625d). Each method sends one
``action`` command through :meth:`AnnDataViewer.act`, which checks and converts
its parameters by the catalogue, and returns its :class:`ActionRequest`.
"""
from __future__ import annotations
from collections.abc import Mapping, Sequence
from typing import TYPE_CHECKING, Any, Literal
from ._actions import OMIT, CellsLike, Omit, ValuesLike
if TYPE_CHECKING:
from ._viewer import ActionRequest
[docs]
class ViewerActions:
"""Every action of the catalogue as a method (mixed into the viewer)."""
__slots__ = ()
if TYPE_CHECKING:
def act(self, action: str, /, **params: Any) -> ActionRequest: ...
[docs]
def analysis_cancel(
self,
*,
analysis: Literal['markers', 'differential', 'dotplot', 'signature', 'composition', 'correlation'],
in_: Literal['panel'] | int = 'panel',
) -> ActionRequest:
r"""Stop an analysis.
Stop a running analysis; what it was showing stays, nothing else changes.
Action ``analysis.cancel``. It reads only and changes nothing; ``request.result()`` is what it
reads.
Parameters
----------
analysis : {"markers", "differential", "dotplot", "signature", "composition", "correlation"}
An analysis with a Run button.
in_ : "panel" or int
Default ``'panel'``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.cancel', analysis=analysis, **{'in': in_})
[docs]
def analysis_close(
self,
) -> ActionRequest:
r"""Close the open analysis.
Close the analysis open in the Analysis panel (its settings and result stay).
Action ``analysis.close``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.close')
[docs]
def analysis_composition_get(
self,
*,
in_: Literal['panel'] | int = 'panel',
) -> ActionRequest:
r"""Read composition options.
The composition analysis's options, pages and result state.
Action ``analysis.composition.get``. It reads only and changes nothing; ``request.result()`` is
what it reads.
Parameters
----------
in_ : "panel" or int
Default ``'panel'``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.composition.get', **{'in': in_})
[docs]
def analysis_composition_set(
self,
*,
options: Mapping[str, Any],
in_: Literal['panel'] | int = 'panel',
show: bool = False,
) -> ActionRequest:
r"""Set composition options.
Change options of the composition analysis (only those given); nothing runs.
Action ``analysis.composition.set``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
options : dict
Keys: ``barsBy`` (optional), ``cellTypes`` (optional), ``cells`` (optional), ``condition``
(optional), ``correction`` (optional), ``method`` (optional), ``onlyTypes`` (optional),
``order`` (optional), ``samples`` (optional), ``values`` (optional).
in_ : "panel" or int
Default ``'panel'``.
show : bool
Also open it in the Analysis panel (with in "panel"), as another analysis's "send to" does.
Default ``False``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.composition.set', options=options, **{'in': in_}, show=show)
[docs]
def analysis_correlation_get(
self,
*,
in_: Literal['panel'] | int = 'panel',
) -> ActionRequest:
r"""Read correlation options.
The correlation analysis's options, pages and result state.
Action ``analysis.correlation.get``. It reads only and changes nothing; ``request.result()`` is
what it reads.
Parameters
----------
in_ : "panel" or int
Default ``'panel'``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.correlation.get', **{'in': in_})
[docs]
def analysis_correlation_set(
self,
*,
options: Mapping[str, Any],
in_: Literal['panel'] | int = 'panel',
show: bool = False,
) -> ActionRequest:
r"""Set correlation options.
Change options of the correlation analysis (only those given); nothing runs.
Action ``analysis.correlation.set``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
options : dict
Keys: ``colorBy`` (optional), ``method`` (optional), ``variableX`` (optional), ``variableY``
(optional).
in_ : "panel" or int
Default ``'panel'``.
show : bool
Also open it in the Analysis panel (with in "panel"), as another analysis's "send to" does.
Default ``False``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.correlation.set', options=options, **{'in': in_}, show=show)
[docs]
def analysis_detailed_set(
self,
*,
in_: Literal['panel'] | int = 'panel',
plot: str | Omit = OMIT,
plot_options: Sequence[Mapping[str, Any]] | Omit = OMIT,
variable: None | Mapping[str, Any] | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``analysis.detailed.set``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
in_ : "panel" or int
Default ``'panel'``.
plot : str
The plot, by its id as the Plot select offers it for the variable's kind. Optional: left
out, the viewer decides.
plot_options : list
Options of the plot, each by its name and value. Optional: left out, the viewer decides.
variable : None or dict
What to plot: a column of the cells (categorical_obs, continuous_obs) or a gene
(gene_expression) by name, or null for nothing. Keys: ``key``, ``type``. Optional: left out,
the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.detailed.set', **{'in': in_}, plot=plot, plot_options=plot_options, variable=variable)
[docs]
def analysis_differential_get(
self,
*,
in_: Literal['panel'] | int = 'panel',
) -> ActionRequest:
r"""Read differential expression options.
The differential expression analysis's options, pages and result state.
Action ``analysis.differential.get``. It reads only and changes nothing; ``request.result()`` is
what it reads.
Parameters
----------
in_ : "panel" or int
Default ``'panel'``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.differential.get', **{'in': in_})
[docs]
def analysis_differential_set(
self,
*,
options: Mapping[str, Any],
in_: Literal['panel'] | int = 'panel',
show: bool = False,
) -> ActionRequest:
r"""Set differential expression options.
Change options of the differential expression analysis (only those given); nothing runs.
Action ``analysis.differential.set``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
options : dict
Keys: ``categoriesA`` (optional), ``categoriesB`` (optional), ``compare`` (optional),
``correction`` (optional), ``excludeGenes`` (optional), ``excludePattern`` (optional),
``field`` (optional), ``foldChange`` (optional), ``labels`` (optional), ``matrix``
(optional), ``maxAdjP`` (optional), ``method`` (optional), ``minCells`` (optional),
``minCellsPerSample`` (optional), ``minLog2FC`` (optional), ``minPct`` (optional),
``onlyGenes`` (optional), ``onlyGenesList`` (optional), ``pConvention`` (optional),
``pageA`` (optional), ``pageB`` (optional), ``replicates`` (optional), ``within``
(optional), ``withinCategories`` (optional), ``withinField`` (optional).
in_ : "panel" or int
Default ``'panel'``.
show : bool
Also open it in the Analysis panel (with in "panel"), as another analysis's "send to" does.
Default ``False``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.differential.set', options=options, **{'in': in_}, show=show)
[docs]
def analysis_dotplot_get(
self,
*,
in_: Literal['panel'] | int = 'panel',
) -> ActionRequest:
r"""Read dot plot options.
The dot plot analysis's options, pages and result state.
Action ``analysis.dotplot.get``. It reads only and changes nothing; ``request.result()`` is what
it reads.
Parameters
----------
in_ : "panel" or int
Default ``'panel'``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.dotplot.get', **{'in': in_})
[docs]
def analysis_dotplot_set(
self,
*,
options: Mapping[str, Any],
in_: Literal['panel'] | int = 'panel',
show: bool = False,
) -> ActionRequest:
r"""Set dot plot options.
Change options of the dot plot analysis (only those given); nothing runs.
Action ``analysis.dotplot.set``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
options : dict
Keys: ``cells`` (optional), ``colorMap`` (optional), ``cutoff`` (optional), ``geneSets``
(optional), ``groupBy`` (optional), ``groupOrder`` (optional), ``groups`` (optional),
``matrix`` (optional), ``maxDotSize`` (optional), ``meanOnlyExpressing`` (optional),
``plot`` (optional), ``scale`` (optional), ``swapAxes`` (optional).
in_ : "panel" or int
Default ``'panel'``.
show : bool
Also open it in the Analysis panel (with in "panel"), as another analysis's "send to" does.
Default ``False``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.dotplot.set', options=options, **{'in': in_}, show=show)
[docs]
def analysis_list(
self,
) -> ActionRequest:
r"""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.
Action ``analysis.list``. It reads only and changes nothing; ``request.result()`` is what it
reads.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.list')
[docs]
def analysis_markers_get(
self,
*,
in_: Literal['panel'] | int = 'panel',
) -> ActionRequest:
r"""Read marker genes options.
The marker genes analysis's options, pages and result state.
Action ``analysis.markers.get``. It reads only and changes nothing; ``request.result()`` is what
it reads.
Parameters
----------
in_ : "panel" or int
Default ``'panel'``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.markers.get', **{'in': in_})
[docs]
def analysis_markers_set(
self,
*,
options: Mapping[str, Any],
in_: Literal['panel'] | int = 'panel',
show: bool = False,
) -> ActionRequest:
r"""Set marker genes options.
Change options of the marker genes analysis (only those given); nothing runs.
Action ``analysis.markers.set``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
options : dict
Keys: ``cells`` (optional), ``compareAgainst`` (optional), ``correction`` (optional),
``direction`` (optional), ``excludeGenes`` (optional), ``excludePattern`` (optional),
``foldChange`` (optional), ``groupBy`` (optional), ``matrix`` (optional), ``maxAdjP``
(optional), ``maxPctRef`` (optional), ``method`` (optional), ``minCells`` (optional),
``minLog2FC`` (optional), ``minPctIn`` (optional), ``onlyGenes`` (optional),
``onlyGenesList`` (optional), ``pConvention`` (optional), ``rankBy`` (optional),
``referenceGroup`` (optional), ``restIncludes`` (optional), ``smallGroups`` (optional),
``testGroups`` (optional), ``topN`` (optional).
in_ : "panel" or int
Default ``'panel'``.
show : bool
Also open it in the Analysis panel (with in "panel"), as another analysis's "send to" does.
Default ``False``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.markers.set', options=options, **{'in': in_}, show=show)
[docs]
def analysis_open(
self,
*,
analysis: Literal['markers', 'differential', 'dotplot', 'signature', 'composition', 'quick', 'detailed', 'correlation'],
window: bool = False,
) -> ActionRequest:
r"""Open an analysis.
Show an analysis in the Analysis panel, or open it in a new floating window with the panel's
settings.
Action ``analysis.open``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Parameters
----------
analysis : {"markers", "differential", "dotplot", "signature", "composition", "quick", "detailed", "correlation"}
The analysis: markers (marker genes), differential (differential expression), dotplot,
signature (gene signature), composition, quick, detailed, correlation.
window : bool
Open it in a new floating window. Default ``False``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.open', analysis=analysis, window=window)
[docs]
def analysis_pages_set(
self,
*,
analysis: Literal['markers', 'differential', 'dotplot', 'signature', 'composition', 'quick', 'detailed', 'correlation'],
pages: Sequence[str],
in_: Literal['panel'] | int = 'panel',
) -> ActionRequest:
r"""Choose the pages of an analysis.
The highlight pages an analysis compares (by name, "Rest of <page>" for the rest of a page's
cells); nothing runs.
Action ``analysis.pages.set``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
analysis : {"markers", "differential", "dotplot", "signature", "composition", "quick", "detailed", "correlation"}
The analysis: markers (marker genes), differential (differential expression), dotplot,
signature (gene signature), composition, quick, detailed, correlation.
pages : list
See the action's summary.
in_ : "panel" or int
Default ``'panel'``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.pages.set', analysis=analysis, pages=pages, **{'in': in_})
[docs]
def analysis_quick_set(
self,
*,
categorical: Sequence[str] | Omit = OMIT,
continuous: Sequence[str] | Omit = OMIT,
in_: Literal['panel'] | int = 'panel',
) -> ActionRequest:
r"""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.
Action ``analysis.quick.set``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
categorical : list
Categorical columns of the cells, by name (their composition). Optional: left out, the
viewer decides.
continuous : list
Continuous columns of the cells, by name (their statistics). Optional: left out, the viewer
decides.
in_ : "panel" or int
Default ``'panel'``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.quick.set', categorical=categorical, continuous=continuous, **{'in': in_})
[docs]
def analysis_result(
self,
*,
analysis: Literal['markers', 'differential', 'dotplot', 'signature', 'composition', 'correlation'],
in_: Literal['panel'] | int = 'panel',
top: int = 20,
) -> ActionRequest:
r"""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.
Action ``analysis.result``. It reads only and changes nothing; ``request.result()`` is what it
reads.
Parameters
----------
analysis : {"markers", "differential", "dotplot", "signature", "composition", "correlation"}
An analysis with a Run button.
in_ : "panel" or int
Default ``'panel'``.
top : int
At most this many rows (per group, where the result has groups). Default ``20``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.result', analysis=analysis, **{'in': in_}, top=top)
[docs]
def analysis_run(
self,
*,
analysis: Literal['markers', 'differential', 'dotplot', 'signature', 'composition', 'correlation'],
in_: Literal['panel'] | int = 'panel',
) -> ActionRequest:
r"""Run an analysis.
Run an analysis with its options and pages, and wait for its result.
Action ``analysis.run``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Parameters
----------
analysis : {"markers", "differential", "dotplot", "signature", "composition", "correlation"}
An analysis with a Run button.
in_ : "panel" or int
Default ``'panel'``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.run', analysis=analysis, **{'in': in_})
[docs]
def analysis_signature_get(
self,
*,
in_: Literal['panel'] | int = 'panel',
) -> ActionRequest:
r"""Read gene signature options.
The gene signature analysis's options, pages and result state.
Action ``analysis.signature.get``. It reads only and changes nothing; ``request.result()`` is
what it reads.
Parameters
----------
in_ : "panel" or int
Default ``'panel'``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.signature.get', **{'in': in_})
[docs]
def analysis_signature_set(
self,
*,
options: Mapping[str, Any],
in_: Literal['panel'] | int = 'panel',
show: bool = False,
) -> ActionRequest:
r"""Set gene signature options.
Change options of the gene signature analysis (only those given); nothing runs.
Action ``analysis.signature.set``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
options : dict
Keys: ``bins`` (optional), ``controlSize`` (optional), ``geneSets`` (optional), ``layout``
(optional), ``maxRank`` (optional), ``method`` (optional), ``plotType`` (optional),
``rescale`` (optional), ``seed`` (optional).
in_ : "panel" or int
Default ``'panel'``.
show : bool
Also open it in the Analysis panel (with in "panel"), as another analysis's "send to" does.
Default ``False``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.signature.set', options=options, **{'in': in_}, show=show)
[docs]
def analysis_size_set(
self,
*,
analysis: Literal['markers', 'differential', 'dotplot', 'signature', 'composition', 'quick', 'detailed', 'correlation'],
expanded: Mapping[str, Any],
) -> ActionRequest:
r"""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.
Action ``analysis.size.set``. It changes the viewer's layout, as one step of the viewer's
history, which the person can undo; ``request.result()`` is its outcome and ``request.step`` the
step.
Parameters
----------
analysis : {"markers", "differential", "dotplot", "signature", "composition", "quick", "detailed", "correlation"}
The analysis: markers (marker genes), differential (differential expression), dotplot,
signature (gene signature), composition, quick, detailed, correlation.
expanded : dict
The expanded view's box and its splits, in CSS pixels. Keys: ``footerHeight``, ``height``,
``optionsWidth``, ``statsWidth``, ``width``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.size.set', analysis=analysis, expanded=expanded)
[docs]
def analysis_view_set(
self,
*,
analysis: Literal['markers', 'differential', 'dotplot', 'signature', 'composition', 'correlation'],
view: Mapping[str, Any],
in_: Literal['panel'] | int = 'panel',
) -> ActionRequest:
r"""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.
Action ``analysis.view.set``. It changes how the cells are shown, as one step of the viewer's
history, which the person can undo; ``request.result()`` is its outcome and ``request.step`` the
step.
Parameters
----------
analysis : {"markers", "differential", "dotplot", "signature", "composition", "correlation"}
An analysis with an options form.
view : dict
What to change of how the analysis is shown (only the keys given). Keys: ``group``
(optional), ``groups`` (optional), ``heatmap`` (optional), ``more`` (optional), ``plot``
(optional), ``set`` (optional), ``show`` (optional).
in_ : "panel" or int
Default ``'panel'``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.view.set', analysis=analysis, view=view, **{'in': in_})
[docs]
def analysis_window_close(
self,
*,
window: int,
) -> ActionRequest:
r"""Close an analysis window.
Close a floating analysis window (its settings and result go with it; undo brings it back).
Action ``analysis.window.close``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
window : int
A floating analysis window, by its number (1 is the first open).
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.window.close', window=window)
[docs]
def analysis_window_collapse(
self,
*,
window: int,
collapsed: bool,
) -> ActionRequest:
r"""Collapse or expand an analysis window.
Fold a floating analysis window to its title bar, or unfold it again; its analysis is kept.
Action ``analysis.window.collapse``. It changes the viewer's layout, as one step of the viewer's
history, which the person can undo; ``request.result()`` is its outcome and ``request.step`` the
step.
Parameters
----------
window : int
A floating analysis window, by its number (1 is the first open).
collapsed : bool
True folds it to its title bar, false unfolds it.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.window.collapse', window=window, collapsed=collapsed)
[docs]
def analysis_window_copy(
self,
*,
window: int,
) -> ActionRequest:
r"""Copy an analysis window.
Open a new floating window with a window's analysis and settings.
Action ``analysis.window.copy``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
window : int
A floating analysis window, by its number (1 is the first open).
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.window.copy', window=window)
[docs]
def analysis_window_place(
self,
*,
window: int,
left: float,
top: float,
width: float,
height: float,
) -> ActionRequest:
r"""Move or resize an analysis window.
Give a floating analysis window a place and size; it is kept inside the window.
Action ``analysis.window.place``. It changes the viewer's layout, as one step of the viewer's
history, which the person can undo; ``request.result()`` is its outcome and ``request.step`` the
step.
Parameters
----------
window : int
A floating analysis window, by its number (1 is the first open).
left : float
See the action's summary.
top : float
See the action's summary.
width : float
See the action's summary.
height : float
See the action's summary.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('analysis.window.place', window=window, left=left, top=top, width=width, height=height)
[docs]
def annotation_suggest(
self,
*,
field: Mapping[str, Any],
category: str,
label: str,
evidence: str | Omit = OMIT,
ontology_id: str | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``annotation.suggest``. It acts outside the viewer's state and history (a file the person
receives in the browser, a publication, or what the browser keeps for later visits), which Undo
does not take back, and records no step; ``request.result()`` is its outcome. It publishes for
others to see, so the viewer asks the person first, from Python too, as when an agent runs it;
``request.result()`` waits for their answer (call it again if its timeout passes first).
Parameters
----------
field : dict
A categorical column of the cells by name (source "obs"). Keys: ``key``, ``source``.
category : str
A category label as the legend shows it.
label : str
The label suggested.
evidence : str
Why: the markers or reasoning behind it. Optional: left out, the viewer decides.
ontology_id : str
Its ontology term, when known. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('annotation.suggest', field=field, category=category, label=label, evidence=evidence, ontology_id=ontology_id)
[docs]
def annotation_suggestions(
self,
*,
field: Mapping[str, Any],
category: str | Omit = OMIT,
cursor: int | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``annotation.suggestions``. It reads only and changes nothing; ``request.result()`` is
what it reads.
Parameters
----------
field : dict
A categorical column of the cells by name (source "obs"). Keys: ``key``, ``source``.
category : str
One category; every category of the field when left out. Optional: left out, the viewer
decides.
cursor : int
Where the page starts: the next of the last page; the first page when left out. Optional:
left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('annotation.suggestions', field=field, category=category, cursor=cursor)
[docs]
def annotation_vote(
self,
*,
field: Mapping[str, Any],
category: str,
suggestion: str,
vote: Literal['up', 'down', 'none'],
) -> ActionRequest:
r"""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.
Action ``annotation.vote``. It acts outside the viewer's state and history (a file the person
receives in the browser, a publication, or what the browser keeps for later visits), which Undo
does not take back, and records no step; ``request.result()`` is its outcome. It publishes for
others to see, so the viewer asks the person first, from Python too, as when an agent runs it;
``request.result()`` waits for their answer (call it again if its timeout passes first).
Parameters
----------
field : dict
A categorical column of the cells by name (source "obs"). Keys: ``key``, ``source``.
category : str
A category label as the legend shows it.
suggestion : str
The suggestion, by its id or its label (annotation_suggestions); suggestions with the same
label are one suggestion.
vote : {"up", "down", "none"}
up, down, or none to take the person's vote back.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('annotation.vote', field=field, category=category, suggestion=suggestion, vote=vote)
[docs]
def camera_navigation_set(
self,
*,
view: str,
mode: Literal['orbit', 'planar', 'free'],
) -> ActionRequest:
r"""Set the navigation mode.
Navigate a view by orbit, planar or free-fly (O, P and G); views with linked cameras share one
mode.
Action ``camera.navigation.set``. It changes how the cells are shown, as one step of the
viewer's history, which the person can undo; ``request.result()`` is its outcome and
``request.step`` the step.
Parameters
----------
view : str
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 : {"orbit", "planar", "free"}
"orbit", "planar" or "free" (free-fly).
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('camera.navigation.set', view=view, mode=mode)
[docs]
def camera_path_clear(
self,
) -> ActionRequest:
r"""Clear the camera path.
Delete every keyframe of the camera path; playback stops where the camera is.
Action ``camera-path.clear``. It changes how the cells are shown, as one step of the viewer's
history, which the person can undo; ``request.result()`` is its outcome and ``request.step`` the
step.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('camera-path.clear')
[docs]
def camera_path_duration_set(
self,
*,
seconds: float | None,
keyframe: str | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``camera-path.duration.set``. It changes how the cells are shown, as one step of the
viewer's history, which the person can undo; ``request.result()`` is its outcome and
``request.step`` the step.
Parameters
----------
seconds : float or None
Seconds of the transition to the next keyframe, at least 0.1; null paces it automatically.
keyframe : str
The keyframe the transition starts at; omitted, every keyframe. Optional: left out, the
viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('camera-path.duration.set', seconds=seconds, keyframe=keyframe)
[docs]
def camera_path_keyframe_add(
self,
*,
camera: Mapping[str, Any] | Omit = OMIT,
embedding: Mapping[str, Any] | None | Omit = OMIT,
label: str | Omit = OMIT,
) -> ActionRequest:
r"""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).
Action ``camera-path.keyframe.add``. It changes how the cells are shown, as one step of the
viewer's history, which the person can undo; ``request.result()`` is its outcome and
``request.step`` the step.
Parameters
----------
camera : dict
The camera to save; omitted, the selected view's camera now. Keys: ``freefly``,
``navigationMode``, ``orbit``. Optional: left out, the viewer decides.
embedding : dict or None
The embedding the keyframe was recorded on; omitted, the one the selected view shows. Keys:
``columns``, ``key``. Optional: left out, the viewer decides.
label : str
The keyframe's label; omitted, "KF n". Unique among the keyframes. Optional: left out, the
viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('camera-path.keyframe.add', camera=camera, embedding=embedding, label=label)
[docs]
def camera_path_keyframe_move(
self,
*,
keyframe: str,
direction: Literal['up', 'down'],
) -> ActionRequest:
r"""Move a camera path keyframe.
Move a keyframe one place earlier (up) or later (down) in the camera path.
Action ``camera-path.keyframe.move``. It changes how the cells are shown, as one step of the
viewer's history, which the person can undo; ``request.result()`` is its outcome and
``request.step`` the step.
Parameters
----------
keyframe : str
A keyframe, by its label as the Camera path list shows it.
direction : {"up", "down"}
"up" one place earlier, "down" one place later.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('camera-path.keyframe.move', keyframe=keyframe, direction=direction)
[docs]
def camera_path_keyframe_remove(
self,
*,
keyframe: str,
) -> ActionRequest:
r"""Delete a camera path keyframe.
Delete one keyframe of the camera path.
Action ``camera-path.keyframe.remove``. It changes how the cells are shown, as one step of the
viewer's history, which the person can undo; ``request.result()`` is its outcome and
``request.step`` the step.
Parameters
----------
keyframe : str
A keyframe, by its label as the Camera path list shows it.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('camera-path.keyframe.remove', keyframe=keyframe)
[docs]
def camera_path_keyframe_rename(
self,
*,
keyframe: str,
label: str,
) -> ActionRequest:
r"""Rename a camera path keyframe.
Give a keyframe another label, unique among the keyframes.
Action ``camera-path.keyframe.rename``. It changes how the cells are shown, as one step of the
viewer's history, which the person can undo; ``request.result()`` is its outcome and
``request.step`` the step.
Parameters
----------
keyframe : str
A keyframe, by its label as the Camera path list shows it.
label : str
The new label.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('camera-path.keyframe.rename', keyframe=keyframe, label=label)
[docs]
def camera_path_loop_back_set(
self,
*,
enabled: bool,
) -> ActionRequest:
r"""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).
Action ``camera-path.loop-back.set``. It changes how the cells are shown, as one step of the
viewer's history, which the person can undo; ``request.result()`` is its outcome and
``request.step`` the step.
Parameters
----------
enabled : bool
true to end with the return, false to remove it.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('camera-path.loop-back.set', enabled=enabled)
[docs]
def camera_path_playback_set(
self,
*,
autoplay: bool | Omit = OMIT,
easing: Literal['linear', 'ease-in-out', 'ease-in', 'ease-out'] | Omit = OMIT,
loop: bool | Omit = OMIT,
position_interpolation: Literal['catmull-rom', 'linear', 'bezier'] | Omit = OMIT,
rotation_interpolation: Literal['slerp', 'linear'] | Omit = OMIT,
speed: int | Omit = OMIT,
) -> ActionRequest:
r"""Set camera path playback.
Set how the camera path plays: interpolation, easing, speed of automatic transitions, loop and
autoplay.
Action ``camera-path.playback.set``. It changes how the cells are shown, as one step of the
viewer's history, which the person can undo; ``request.result()`` is its outcome and
``request.step`` the step.
Parameters
----------
autoplay : bool
Start playing as soon as the path has two keyframes. Optional: left out, the viewer decides.
easing : {"linear", "ease-in-out", "ease-in", "ease-out"}
How each transition speeds up and slows down. Optional: left out, the viewer decides.
loop : bool
Play the path again from its start when it ends. Optional: left out, the viewer decides.
position_interpolation : {"catmull-rom", "linear", "bezier"}
How positions between keyframes are drawn. Optional: left out, the viewer decides.
rotation_interpolation : {"slerp", "linear"}
How the view direction turns between keyframes. Optional: left out, the viewer decides.
speed : int
Speed of automatic transitions, 1 (very slow) to 100 (very fast). Optional: left out, the
viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('camera-path.playback.set', autoplay=autoplay, easing=easing, loop=loop, position_interpolation=position_interpolation, rotation_interpolation=rotation_interpolation, speed=speed)
[docs]
def camera_reset(
self,
*,
view: str,
) -> ActionRequest:
r"""Reset the camera.
Put a view's camera back to its starting place, keeping its navigation mode (the R key).
Action ``camera.reset``. It changes how the cells are shown, as one step of the viewer's
history, which the person can undo; ``request.result()`` is its outcome and ``request.step`` the
step.
Parameters
----------
view : str
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).
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('camera.reset', view=view)
[docs]
def camera_set(
self,
*,
view: str,
camera: Mapping[str, Any],
) -> ActionRequest:
r"""Place the camera.
Set the camera of a view (views with linked cameras follow); a camera gesture records one of
these.
Action ``camera.set``. It changes how the cells are shown, as one step of the viewer's history,
which the person can undo; ``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
view : str
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 : dict
A camera: its navigation mode, and its orbit and free-fly poses (the one the mode drives is
used). Keys: ``freefly``, ``navigationMode``, ``orbit``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('camera.set', view=view, camera=camera)
[docs]
def category_delete(
self,
*,
field: Mapping[str, Any],
category: str,
unassigned_label: str = 'unassigned',
) -> ActionRequest:
r"""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.
Action ``category.delete``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Parameters
----------
field : dict
A categorical column of the cells by name (source "obs"). Keys: ``key``, ``source``.
category : str
A category label as the legend shows it.
unassigned_label : str
The category the cells move into, made when missing. Default ``'unassigned'``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('category.delete', field=field, category=category, unassigned_label=unassigned_label)
[docs]
def category_merge(
self,
*,
field: Mapping[str, Any],
category: str,
into: str,
) -> ActionRequest:
r"""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.
Action ``category.merge``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Parameters
----------
field : dict
A categorical column of the cells by name (source "obs"). Keys: ``key``, ``source``.
category : str
The category whose cells move.
into : str
The category they join.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('category.merge', field=field, category=category, into=into)
[docs]
def category_rename(
self,
*,
field: Mapping[str, Any],
category: str,
name: str,
) -> ActionRequest:
r"""Rename a category.
Give one category of a categorical column another label; its original label stays known.
Action ``category.rename``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Parameters
----------
field : dict
A categorical column of the cells by name (source "obs"). Keys: ``key``, ``source``.
category : str
A category label as the legend shows it.
name : str
The new label, unique in the column.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('category.rename', field=field, category=category, name=name)
[docs]
def cells_export(
self,
*,
format: Literal['csv', 'h5ad'] = 'csv',
page: str | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``cells.export``. It acts outside the viewer's state and history (a file the person
receives in the browser, a publication, or what the browser keeps for later visits), which Undo
does not take back, and records no step; ``request.result()`` is its outcome.
Parameters
----------
format : {"csv", "h5ad"}
csv: the obs-column CSV; h5ad: an AnnData file of the highlighted cells. Default ``'csv'``.
page : str
The highlight page; the page shown when left out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('cells.export', format=format, page=page)
[docs]
def cells_open(
self,
*,
mode: Literal['all', 'subsample'],
allocation: Literal['proportional', 'balanced'] = 'proportional',
count: int | Omit = OMIT,
embedding: str | Omit = OMIT,
field: str | Omit = OMIT,
method: Literal['uniform', 'blocks', 'stratified', 'spatial'] | None = None,
seed: int | None = None,
) -> ActionRequest:
r"""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.
Action ``cells.open``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Parameters
----------
mode : {"all", "subsample"}
See the action's summary.
allocation : {"proportional", "balanced"}
Stratified: how the cells are split over the categories. Default ``'proportional'``.
count : int
Subsample: how many cells. Optional: left out, the viewer decides.
embedding : str
Spatial: the obsm embedding it thins. Optional: left out, the viewer decides.
field : str
Stratified: the categorical column it is stratified by. Optional: left out, the viewer
decides.
method : {"uniform", "blocks", "stratified", "spatial", null}
Subsample: how the cells are chosen; null for the file's default. Default ``None``.
seed : int or None
Subsample: its seed; null for the file's. Default ``None``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('cells.open', mode=mode, allocation=allocation, count=count, embedding=embedding, field=field, method=method, seed=seed)
[docs]
def cells_read_genes(
self,
*,
cells: int,
) -> ActionRequest:
r"""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.
Action ``cells.read-genes``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Parameters
----------
cells : int
How many of the open cells; more than are open reads every one.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('cells.read-genes', cells=cells)
[docs]
def cells_values(
self,
*,
cells: CellsLike,
fields: Sequence[Mapping[str, Any]],
) -> ActionRequest:
r"""Read values of cells.
The values of named cells (original positions) in each field or gene asked for.
Action ``cells.values``. It reads only and changes nothing; ``request.result()`` is what it
reads.
Parameters
----------
cells : cells (rows, a boolean mask or obs names)
Cells by original position (their row in the file's obs).
fields : list
See the action's summary.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('cells.values', cells=cells, fields=fields)
[docs]
def cells_visibility_set(
self,
*,
cells: CellsLike | None,
visible: bool,
) -> ActionRequest:
r"""Hide or show cells.
Hide or show cells one by one in the selected view, on top of every filter.
Action ``cells.visibility.set``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
cells : cells (rows, a boolean mask or obs names)
Cells by original position, or null for every cell.
visible : bool
true to show them, false to hide them.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('cells.visibility.set', cells=cells, visible=visible)
[docs]
def color_by(
self,
*,
field: Mapping[str, Any] | None,
) -> ActionRequest:
r"""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.
Action ``color.by``. It changes how the cells are shown, as one step of the viewer's history,
which the person can undo; ``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
field : dict or None
The field or gene by name; null colours the cells by nothing. Keys: ``key``, ``source``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('color.by', field=field)
[docs]
def color_category(
self,
*,
field: Mapping[str, Any],
category: str,
color: str,
) -> ActionRequest:
r"""Colour one category.
Give one category of a categorical column another colour.
Action ``color.category``. It changes how the cells are shown, as one step of the viewer's
history, which the person can undo; ``request.result()`` is its outcome and ``request.step`` the
step.
Parameters
----------
field : dict
A categorical column of the cells by name (source "obs"). Keys: ``key``, ``source``.
category : str
A category label as the legend shows it.
color : str
A colour as six hex digits, "#e41a1c".
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('color.category', field=field, category=category, color=color)
[docs]
def color_continuous_colormap(
self,
*,
field: Mapping[str, Any],
colormap: Literal['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'],
) -> ActionRequest:
r"""Choose a colour map.
The colour map a continuous field or gene is drawn with.
Action ``color.continuous.colormap``. It changes how the cells are shown, as one step of the
viewer's history, which the person can undo; ``request.result()`` is its outcome and
``request.step`` the step.
Parameters
----------
field : dict
The continuous field or gene the view in focus is coloured by, by name. Keys: ``key``,
``source``.
colormap : {"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"}
The colour map by its id (viridis, magma, coolwarm, …).
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('color.continuous.colormap', field=field, colormap=colormap)
[docs]
def color_continuous_log(
self,
*,
field: Mapping[str, Any],
enabled: bool,
) -> ActionRequest:
r"""Log colour scale.
Colour a continuous field or gene on a log scale, or a linear one.
Action ``color.continuous.log``. It changes how the cells are shown, as one step of the viewer's
history, which the person can undo; ``request.result()`` is its outcome and ``request.step`` the
step.
Parameters
----------
field : dict
The continuous field or gene the view in focus is coloured by, by name. Keys: ``key``,
``source``.
enabled : bool
See the action's summary.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('color.continuous.log', field=field, enabled=enabled)
[docs]
def color_continuous_range(
self,
*,
field: Mapping[str, Any],
min: float,
max: float,
) -> ActionRequest:
r"""Set the colour range.
The values the colour map spans for a continuous field or gene that is rescaled to a range.
Action ``color.continuous.range``. It changes how the cells are shown, as one step of the
viewer's history, which the person can undo; ``request.result()`` is its outcome and
``request.step`` the step.
Parameters
----------
field : dict
The continuous field or gene the view in focus is coloured by, by name. Keys: ``key``,
``source``.
min : float
See the action's summary.
max : float
See the action's summary.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('color.continuous.range', field=field, min=min, max=max)
[docs]
def color_continuous_rescale(
self,
*,
field: Mapping[str, Any],
enabled: bool,
) -> ActionRequest:
r"""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.
Action ``color.continuous.rescale``. It changes how the cells are shown, as one step of the
viewer's history, which the person can undo; ``request.result()`` is its outcome and
``request.step`` the step.
Parameters
----------
field : dict
The continuous field or gene the view in focus is coloured by, by name. Keys: ``key``,
``source``.
enabled : bool
See the action's summary.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('color.continuous.rescale', field=field, enabled=enabled)
[docs]
def color_continuous_zero_gray(
self,
*,
field: Mapping[str, Any],
enabled: bool,
) -> ActionRequest:
r"""Gray for zero.
Draw a gene's zeros in gray beneath the expressing cells, or in the colour map's lowest colour.
Action ``color.continuous.zero-gray``. It changes how the cells are shown, as one step of the
viewer's history, which the person can undo; ``request.result()`` is its outcome and
``request.step`` the step.
Parameters
----------
field : dict
The continuous field or gene the view in focus is coloured by, by name. Keys: ``key``,
``source``.
enabled : bool
See the action's summary.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('color.continuous.zero-gray', field=field, enabled=enabled)
[docs]
def dataset_open(
self,
*,
name: str,
kind: Literal['any', 'sample', 'my-datasets', 'link'] = 'any',
) -> ActionRequest:
r"""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.
Action ``dataset.open``. It opens another dataset in place of the one the viewer shows, as an
agent in the viewer does. A notebook's viewer shows the dataset its notebook serves, so the
viewer refuses it from Python: show another dataset with :func:`cellucid.show_anndata` or
:func:`cellucid.serve_anndata`.
Parameters
----------
name : str
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).
kind : {"any", "sample", "my-datasets", "link"}
Where to look for the name: any (samples, then My datasets, then as a link), sample,
my-datasets or link. Default ``'any'``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('dataset.open', name=name, kind=kind)
[docs]
def dataset_share_link(
self,
) -> ActionRequest:
r"""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).
Action ``dataset.share-link``. It acts outside the viewer's state and history (a file the person
receives in the browser, a publication, or what the browser keeps for later visits), which Undo
does not take back, and records no step; ``request.result()`` is its outcome. It publishes for
others to see, so the viewer asks the person first, from Python too, as when an agent runs it;
``request.result()`` waits for their answer (call it again if its timeout passes first).
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('dataset.share-link')
[docs]
def dataset_summary(
self,
) -> ActionRequest:
r"""Read the dataset summary.
The open dataset: its name, citation, how many cells (and how many are open), genes, embeddings
and fields.
Action ``dataset.summary``. It reads only and changes nothing; ``request.result()`` is what it
reads.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('dataset.summary')
[docs]
def datasets_list(
self,
) -> ActionRequest:
r"""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.
Action ``datasets.list``. It reads only and changes nothing; ``request.result()`` is what it
reads.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('datasets.list')
[docs]
def display_reset(
self,
) -> ActionRequest:
r"""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.
Action ``display.reset``. It changes how the cells are shown, as one step of the viewer's
history, which the person can undo; ``request.result()`` is its outcome and ``request.step`` the
step.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('display.reset')
[docs]
def field_categories(
self,
*,
field: Mapping[str, Any],
) -> ActionRequest:
r"""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.
Action ``field.categories``. It reads only and changes nothing; ``request.result()`` is what it
reads.
Parameters
----------
field : dict
A field by name: source "obs" for a column of the cells, "var" for a gene; key is the name
as shown. Keys: ``key``, ``source``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('field.categories', field=field)
[docs]
def field_consensus(
self,
*,
key: str,
field: Mapping[str, Any],
mapping: Sequence[Mapping[str, Any]],
settings: Mapping[str, Any],
provenance: Mapping[str, Any],
) -> ActionRequest:
r"""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.
Action ``field.consensus``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Parameters
----------
key : str
The consensus column's name.
field : dict
The annotated column the consensus is of. Keys: ``key``, ``source``.
mapping : list
The outcome of each category of the column (a category left out is pending).
settings : dict
The consensus rule it was built with. Keys: ``minAnnotators``, ``threshold``.
provenance : dict
Where the votes came from. Keys: ``branch``, ``commit``, ``pulledAt``, ``repository``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('field.consensus', key=key, field=field, mapping=mapping, settings=settings, provenance=provenance)
[docs]
def field_create_from_pages(
self,
*,
key: str,
pages: Sequence[Mapping[str, Any]],
intersection_labels: Sequence[Mapping[str, Any]] | Omit = OMIT,
overlap: Literal['first', 'last', 'overlap-label', 'intersections'] = 'first',
overlap_label: str = 'Overlap',
uncovered_label: str = 'Unassigned',
) -> ActionRequest:
r"""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.
Action ``field.create-from-pages``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
key : str
The new column's name.
pages : list
The pages, in order (first and last refer to it), each with its category label.
intersection_labels : list
With overlap "intersections": the label of each combination of pages that has cells.
Optional: left out, the viewer decides.
overlap : {"first", "last", "overlap-label", "intersections"}
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 : str
The label of cells on several pages when overlap is "overlap-label". Default ``'Overlap'``.
uncovered_label : str
The category of cells on no page; empty leaves them without one. Default ``'Unassigned'``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('field.create-from-pages', key=key, pages=pages, intersection_labels=intersection_labels, overlap=overlap, overlap_label=overlap_label, uncovered_label=uncovered_label)
[docs]
def field_delete(
self,
*,
field: Mapping[str, Any],
) -> ActionRequest:
r"""Delete a field.
Remove a column of the cells or a gene from the lists; it can be restored from Deleted fields
until purged.
Action ``field.delete``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Parameters
----------
field : dict
A field by name: source "obs" for a column of the cells, "var" for a gene; key is the name
as shown. Keys: ``key``, ``source``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('field.delete', field=field)
[docs]
def field_duplicate(
self,
*,
field: Mapping[str, Any],
name: str | Omit = OMIT,
) -> ActionRequest:
r"""Duplicate a field.
Copy a column of the cells or a gene as a new field (named "<name> (copy)" unless a name is
given) and colour by the copy.
Action ``field.duplicate``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Parameters
----------
field : dict
A field by name: source "obs" for a column of the cells, "var" for a gene; key is the name
as shown. Keys: ``key``, ``source``.
name : str
The copy's name; by default "<name> (copy)", numbered when taken. Optional: left out, the
viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('field.duplicate', field=field, name=name)
[docs]
def field_export(
self,
*,
field: Mapping[str, Any],
) -> ActionRequest:
r"""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.
Action ``field.export``. It acts outside the viewer's state and history (a file the person
receives in the browser, a publication, or what the browser keeps for later visits), which Undo
does not take back, and records no step; ``request.result()`` is its outcome.
Parameters
----------
field : dict
A column of the cells by name (source "obs"), categorical or continuous. Keys: ``key``,
``source``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('field.export', field=field)
[docs]
def field_purge(
self,
*,
field: Mapping[str, Any],
) -> ActionRequest:
r"""Purge a deleted field.
Confirm a deletion: the field leaves Deleted fields and can no longer be restored there (undo
still brings it back).
Action ``field.purge``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Parameters
----------
field : dict
The deleted field by the name it had when deleted. Keys: ``key``, ``source``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('field.purge', field=field)
[docs]
def field_push(
self,
*,
key: str,
kind: Literal['categorical', 'continuous'],
categories: Sequence[str] | None,
n_obs: int,
cells: CellsLike | None,
values: ValuesLike,
) -> ActionRequest:
r"""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.
Action ``field.push``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Parameters
----------
key : str
The column's name.
kind : {"categorical", "continuous"}
See the action's summary.
categories : list or None
A categorical column's categories (its values are codes into them; the largest code is "no
category"); null for a continuous one.
n_obs : int
The cells of the dataset the column belongs to.
cells : cells (rows, a boolean mask or obs names)
The cells the values are of, as original positions; null for every cell in order.
values : array of numbers, one per cell
One value per cell named: a code (categorical) or a number (continuous).
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('field.push', key=key, kind=kind, categories=categories, n_obs=n_obs, cells=cells, values=values)
[docs]
def field_rename(
self,
*,
field: Mapping[str, Any],
name: str,
) -> ActionRequest:
r"""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.
Action ``field.rename``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Parameters
----------
field : dict
A field by name: source "obs" for a column of the cells, "var" for a gene; key is the name
as shown. Keys: ``key``, ``source``.
name : str
A field name: not empty, unique among the fields shown.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('field.rename', field=field, name=name)
[docs]
def field_restore(
self,
*,
field: Mapping[str, Any],
) -> ActionRequest:
r"""Restore a deleted field.
Bring back a deleted field under its name, as it was when deleted.
Action ``field.restore``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Parameters
----------
field : dict
The deleted field by the name it had when deleted. Keys: ``key``, ``source``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('field.restore', field=field)
[docs]
def field_revert_name(
self,
*,
field: Mapping[str, Any],
) -> ActionRequest:
r"""Restore a field's original name.
Give a renamed field back the name it has in the file.
Action ``field.revert-name``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
field : dict
A field by name: source "obs" for a column of the cells, "var" for a gene; key is the name
as shown. Keys: ``key``, ``source``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('field.revert-name', field=field)
[docs]
def field_summary(
self,
*,
field: Mapping[str, Any],
by: Mapping[str, Any],
top: int = 50,
visible_only: bool = False,
) -> ActionRequest:
r"""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.
Action ``field.summary``. It reads only and changes nothing; ``request.result()`` is what it
reads.
Parameters
----------
field : dict
A field by name: source "obs" for a column of the cells, "var" for a gene; key is the name
as shown. Keys: ``key``, ``source``.
by : dict
The categorical obs field to group the cells by. Keys: ``key``, ``source``.
top : int
For a categorical field: at most this many of its categories per group. Default ``50``.
visible_only : bool
Only the cells the active view shows. Default ``False``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('field.summary', field=field, by=by, top=top, visible_only=visible_only)
[docs]
def fields_list(
self,
*,
kind: Literal['categorical', 'continuous'] | Omit = OMIT,
query: str | Omit = OMIT,
) -> ActionRequest:
r"""List the fields.
The cell annotations (obs fields) with their kind and, for a categorical one, how many
categories it has.
Action ``fields.list``. It reads only and changes nothing; ``request.result()`` is what it
reads.
Parameters
----------
kind : {"categorical", "continuous"}
Only fields of this kind. Optional: left out, the viewer decides.
query : str
Only fields whose key contains this text (any case). Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('fields.list', kind=kind, query=query)
[docs]
def filter_category_all(
self,
*,
field: Mapping[str, Any],
visible: bool,
) -> ActionRequest:
r"""Show or hide every category.
Show or hide every category of a categorical column that has open cells, and the cells without a
category.
Action ``filter.category.all``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
field : dict
A categorical column of the cells by name (source "obs"). Keys: ``key``, ``source``.
visible : bool
See the action's summary.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('filter.category.all', field=field, visible=visible)
[docs]
def filter_category_cell_count(
self,
*,
field: Mapping[str, Any],
category: str,
count: int | None,
seed: int = 0,
) -> ActionRequest:
r"""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.
Action ``filter.category.cell-count``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
field : dict
A categorical column of the cells by name (source "obs"). Keys: ``key``, ``source``.
category : str
A category label as the legend shows it.
count : int or None
How many of its cells stay shown; null for all of them.
seed : int
The sample's seed. Default ``0``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('filter.category.cell-count', field=field, category=category, count=count, seed=seed)
[docs]
def filter_category_missing(
self,
*,
field: Mapping[str, Any],
visible: bool,
) -> ActionRequest:
r"""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).
Action ``filter.category.missing``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
field : dict
A categorical column of the cells by name (source "obs"). Keys: ``key``, ``source``.
visible : bool
See the action's summary.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('filter.category.missing', field=field, visible=visible)
[docs]
def filter_category_visibility(
self,
*,
field: Mapping[str, Any],
categories: Sequence[str],
visible: bool,
) -> ActionRequest:
r"""Show or hide categories.
Show or hide the cells of one or more categories of a categorical column.
Action ``filter.category.visibility``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
field : dict
A categorical column of the cells by name (source "obs"). Keys: ``key``, ``source``.
categories : list
Category labels as the legend shows them.
visible : bool
See the action's summary.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('filter.category.visibility', field=field, categories=categories, visible=visible)
[docs]
def filter_continuous_range(
self,
*,
field: Mapping[str, Any],
min: float,
max: float,
) -> ActionRequest:
r"""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.
Action ``filter.continuous.range``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
field : dict
The continuous field or gene the view in focus is coloured by, by name. Keys: ``key``,
``source``.
min : float
See the action's summary.
max : float
See the action's summary.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('filter.continuous.range', field=field, min=min, max=max)
[docs]
def filter_continuous_reset(
self,
*,
field: Mapping[str, Any],
) -> ActionRequest:
r"""Reset a visible range.
Show every value of a continuous field or gene again.
Action ``filter.continuous.reset``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
field : dict
The continuous field or gene the view in focus is coloured by, by name. Keys: ``key``,
``source``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('filter.continuous.reset', field=field)
[docs]
def filter_enable(
self,
*,
field: Mapping[str, Any],
kind: Literal['category', 'continuous', 'outlier'],
enabled: bool,
) -> ActionRequest:
r"""Turn a filter on or off.
Turn a field's category, range or outlier filter off (its settings kept) or on again.
Action ``filter.enable``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Parameters
----------
field : dict
The field or gene whose filter it is, by name. Keys: ``key``, ``source``.
kind : {"category", "continuous", "outlier"}
See the action's summary.
enabled : bool
See the action's summary.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('filter.enable', field=field, kind=kind, enabled=enabled)
[docs]
def filter_outlier(
self,
*,
field: Mapping[str, Any],
threshold: float,
) -> ActionRequest:
r"""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).
Action ``filter.outlier``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Parameters
----------
field : dict
The categorical column the view in focus is coloured by, by name. Keys: ``key``, ``source``.
threshold : float
The quantile above which cells are hidden; 1 hides none.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('filter.outlier', field=field, threshold=threshold)
[docs]
def filter_remove(
self,
*,
field: Mapping[str, Any],
kind: Literal['category', 'continuous', 'outlier'],
) -> ActionRequest:
r"""Remove a filter.
Remove a field's category, range or outlier filter: every cell it hid is shown again.
Action ``filter.remove``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Parameters
----------
field : dict
The field or gene whose filter it is, by name. Keys: ``key``, ``source``.
kind : {"category", "continuous", "outlier"}
See the action's summary.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('filter.remove', field=field, kind=kind)
[docs]
def gene_set_save(
self,
*,
name: str,
genes: Sequence[str],
description: str = '',
) -> ActionRequest:
r"""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.
Action ``gene-set.save``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Parameters
----------
name : str
The set's name.
genes : list
Gene names.
description : str
What the set is. Default ``''``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('gene-set.save', name=name, genes=genes, description=description)
[docs]
def genes_search(
self,
*,
query: str,
limit: int = 20,
) -> ActionRequest:
r"""Search the genes.
Gene names matching what is typed, best first, as the gene search box ranks them.
Action ``genes.search``. It reads only and changes nothing; ``request.result()`` is what it
reads.
Parameters
----------
query : str
See the action's summary.
limit : int
At most this many names. Default ``20``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('genes.search', query=query, limit=limit)
[docs]
def highlight_category(
self,
*,
field: Mapping[str, Any],
category: str | float | bool,
color: str | Omit = OMIT,
page: str | Omit = OMIT,
) -> ActionRequest:
r"""Highlight a category.
Add the cells of one category of a field, as the selected view shows them, as a group.
Action ``highlight.category``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
field : dict
A categorical field, by name. Keys: ``key``, ``source``.
category : str or float or bool
The category, by its label as the legend shows it.
color : str
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. Optional: left out, the viewer decides.
page : str
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. Optional: left out, the
viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('highlight.category', field=field, category=category, color=color, page=page)
[docs]
def highlight_cells(
self,
*,
cells: CellsLike,
color: str | Omit = OMIT,
label: str | Omit = OMIT,
page: str | Omit = OMIT,
tool: Literal['annotation', 'lasso', 'proximity', 'knn'] = 'annotation',
) -> ActionRequest:
r"""Highlight cells.
Add a group of cells to a highlight page: a confirmed selection, or cells an agent or notebook
names.
Action ``highlight.cells``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Parameters
----------
cells : cells (rows, a boolean mask or obs names)
Cells by original position (0-based row of obs), each once, in any order.
color : str
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. Optional: left out, the viewer decides.
label : str
The group's label; omitted, "Highlight (N cells)". A label already on the page gets " (2)",
" (3)", …. Optional: left out, the viewer decides.
page : str
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. Optional: left out, the
viewer decides.
tool : {"annotation", "lasso", "proximity", "knn"}
The selection tool that made the cells (annotation for cells named directly). Default
``'annotation'``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('highlight.cells', cells=cells, color=color, label=label, page=page, tool=tool)
[docs]
def highlight_clear_all(
self,
) -> ActionRequest:
r"""Clear every highlight.
Remove every group of every highlight page; the pages stay.
Action ``highlight.clear-all``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('highlight.clear-all')
[docs]
def highlight_group_remove(
self,
*,
group: str,
page: str | Omit = OMIT,
) -> ActionRequest:
r"""Remove a highlight group.
Remove one group from a highlight page.
Action ``highlight.group.remove``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
group : str
A highlight group, by its label as the group list shows it (without the cell count).
page : str
The group's page, by name; omitted, the page shown. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('highlight.group.remove', group=group, page=page)
[docs]
def highlight_group_toggle(
self,
*,
group: str,
enabled: bool,
page: str | Omit = OMIT,
) -> ActionRequest:
r"""Show or hide a highlight group.
Turn one group of a page on or off; a group that is off highlights nothing.
Action ``highlight.group.toggle``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
group : str
A highlight group, by its label as the group list shows it (without the cell count).
enabled : bool
true to show the group, false to hide it.
page : str
The group's page, by name; omitted, the page shown. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('highlight.group.toggle', group=group, enabled=enabled, page=page)
[docs]
def highlight_page_clear(
self,
*,
page: str | Omit = OMIT,
) -> ActionRequest:
r"""Clear a highlight page.
Remove every group of one highlight page; the page stays.
Action ``highlight.page.clear``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
page : str
The page, by name; omitted, the page shown. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('highlight.page.clear', page=page)
[docs]
def highlight_page_combine(
self,
*,
pages: Sequence[str],
operation: Literal['intersection', 'union'],
name: str | Omit = OMIT,
) -> ActionRequest:
r"""Combine two highlight pages.
Make a page of the cells in both pages (intersection) or in either (union), and show it.
Action ``highlight.page.combine``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
pages : list
The two pages, by name.
operation : {"intersection", "union"}
Cells in both pages, or in either.
name : str
The new page's name; omitted, "A ∩ B" or "A ∪ B". Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('highlight.page.combine', pages=pages, operation=operation, name=name)
[docs]
def highlight_page_create(
self,
*,
color: str | Omit = OMIT,
name: str | Omit = OMIT,
) -> ActionRequest:
r"""Make a highlight page.
Add an empty highlight page and show it.
Action ``highlight.page.create``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
color : str
The new page's colour; omitted, the next colour of the page palette. Optional: left out, the
viewer decides.
name : str
The new page's name; omitted, the first free "Page N". Optional: left out, the viewer
decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('highlight.page.create', color=color, name=name)
[docs]
def highlight_page_delete(
self,
*,
page: str,
) -> ActionRequest:
r"""Delete a highlight page.
Delete a highlight page and its groups; the last page cannot be deleted.
Action ``highlight.page.delete``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
page : str
A highlight page, by its name as its tab shows it.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('highlight.page.delete', page=page)
[docs]
def highlight_page_recolor(
self,
*,
page: str,
color: str,
) -> ActionRequest:
r"""Recolour a highlight page.
Set the colour a highlight page has in its tab, the analyses and the category builder.
Action ``highlight.page.recolor``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
page : str
A highlight page, by its name as its tab shows it.
color : str
A colour as six hex digits, "#e41a1c".
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('highlight.page.recolor', page=page, color=color)
[docs]
def highlight_page_rename(
self,
*,
page: str,
name: str,
) -> ActionRequest:
r"""Rename a highlight page.
Give a highlight page another name, unique among the pages.
Action ``highlight.page.rename``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
page : str
A highlight page, by its name as its tab shows it.
name : str
The new name.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('highlight.page.rename', page=page, name=name)
[docs]
def highlight_page_switch(
self,
*,
page: str,
) -> ActionRequest:
r"""Show a highlight page.
Show another highlight page: its groups are the highlighted cells.
Action ``highlight.page.switch``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
page : str
A highlight page, by its name as its tab shows it.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('highlight.page.switch', page=page)
[docs]
def highlight_range(
self,
*,
field: Mapping[str, Any],
min: float,
max: float,
color: str | Omit = OMIT,
page: str | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``highlight.range``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Parameters
----------
field : dict
A continuous field or a gene, by name. Keys: ``key``, ``source``.
min : float
The smallest value included.
max : float
The largest value included.
color : str
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. Optional: left out, the viewer decides.
page : str
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. Optional: left out, the
viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('highlight.range', field=field, min=min, max=max, color=color, page=page)
[docs]
def history_anndata_save(
self,
*,
file: str | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``history.anndata.save``. It acts outside the viewer's state and history (a file the
person receives in the browser, a publication, or what the browser keeps for later visits),
which Undo does not take back, and records no step; ``request.result()`` is its outcome.
Parameters
----------
file : str
The new file's name (.zarr.zip is added when it does not end so); "<dataset> with this
state.zarr.zip" when left out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.anndata.save', file=file)
[docs]
def history_bookmark_set(
self,
*,
step: str,
name: str | None,
) -> ActionRequest:
r"""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.
Action ``history.bookmark.set``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
step : str
A step of the tracker in use, by its id (history_get lists the steps).
name : str or None
The bookmark, or null to remove it.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.bookmark.set', step=step, name=name)
[docs]
def history_branch_apply(
self,
*,
branch: str,
name: str | Omit = OMIT,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""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).
Action ``history.branch.apply``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
branch : str
A branch by its name or its id (history_summary lists them).
name : str
A name, unique among its kind (compared without case and extra spaces); no length limit.
Optional: left out, the viewer decides.
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.branch.apply', branch=branch, name=name, tracker=tracker)
[docs]
def history_branch_archive(
self,
*,
branch: str,
archived: bool,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``history.branch.archive``. It moves the viewer's history, as the person's Undo, Redo or
a click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
branch : str
A branch by its name or its id (history_summary lists them).
archived : bool
See the action's summary.
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.branch.archive', branch=branch, archived=archived, tracker=tracker)
[docs]
def history_branch_cancel(
self,
) -> ActionRequest:
r"""Cancel a new branch.
Forget the branch "Branch here" set to start with the next change.
Action ``history.branch.cancel``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.branch.cancel')
[docs]
def history_branch_create(
self,
*,
step: str,
name: str | Omit = OMIT,
) -> ActionRequest:
r"""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".
Action ``history.branch.create``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
step : str
A step of the tracker in use, by its id (history_get lists the steps).
name : str
A name, unique among its kind (compared without case and extra spaces); no length limit.
Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.branch.create', step=step, name=name)
[docs]
def history_branch_delete(
self,
*,
branch: str,
tracker: str | Omit = OMIT,
with_sub_branches: bool = False,
) -> ActionRequest:
r"""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.
Action ``history.branch.delete``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
branch : str
A branch by its name or its id (history_summary lists them).
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
with_sub_branches : bool
Also delete every branch that starts from it. Default ``False``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.branch.delete', branch=branch, tracker=tracker, with_sub_branches=with_sub_branches)
[docs]
def history_branch_lock(
self,
*,
branch: str,
locked: bool,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``history.branch.lock``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
branch : str
A branch by its name or its id (history_summary lists them).
locked : bool
See the action's summary.
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.branch.lock', branch=branch, locked=locked, tracker=tracker)
[docs]
def history_branch_rename(
self,
*,
branch: str,
name: str,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""Rename a branch.
Give a branch another name, unique in its tracker.
Action ``history.branch.rename``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
branch : str
A branch by its name or its id (history_summary lists them).
name : str
A name, unique among its kind (compared without case and extra spaces); no length limit.
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.branch.rename', branch=branch, name=name, tracker=tracker)
[docs]
def history_branch_set_main(
self,
*,
branch: str,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""Make a branch main.
Make a branch the tracker's main one, what sharing, replay and loading default to.
Action ``history.branch.set-main``. It moves the viewer's history, as the person's Undo, Redo or
a click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
branch : str
A branch by its name or its id (history_summary lists them).
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.branch.set-main', branch=branch, tracker=tracker)
[docs]
def history_branch_switch(
self,
*,
branch: str,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""Switch branch.
Show a branch's last step and continue on it; an agent's turn continues on it too.
Action ``history.branch.switch``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
branch : str
A branch by its name or its id (history_summary lists them).
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.branch.switch', branch=branch, tracker=tracker)
[docs]
def history_branch_without(
self,
*,
step: str,
name: str | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``history.branch.without``. It moves the viewer's history, as the person's Undo, Redo or
a click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
step : str
A step of the tracker in use, by its id (history_get lists the steps).
name : str
A name, unique among its kind (compared without case and extra spaces); no length limit.
Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.branch.without', step=step, name=name)
[docs]
def history_clear(
self,
*,
keep_state: bool,
) -> ActionRequest:
r"""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.
Action ``history.clear``. It moves the viewer's history, as the person's Undo, Redo or a click
on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
keep_state : bool
True keeps the state shown as one step; false starts over from the dataset as opened.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.clear', keep_state=keep_state)
[docs]
def history_diff(
self,
*,
a: Mapping[str, Any],
b: Mapping[str, Any],
) -> ActionRequest:
r"""Compare two steps.
What differs between the state after two steps, part by part (filters, labels, highlights, …);
the steps may be of two trackers.
Action ``history.diff``. It reads only and changes nothing; ``request.result()`` is what it
reads.
Parameters
----------
a : dict
The first step. Keys: ``step``, ``tracker`` (optional).
b : dict
The second step. Keys: ``step``, ``tracker`` (optional).
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.diff', a=a, b=b)
[docs]
def history_get(
self,
*,
all_branches: bool = False,
branch: str | Omit = OMIT,
cursor: str | Omit = OMIT,
fields: Sequence[Literal['params', 'notes', 'bookmark']] | Omit = OMIT,
limit: int = 200,
since: float | Omit = OMIT,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""Read the history.
The steps taken on this dataset, who took each (person, agent, notebook), branches and the step
shown.
Action ``history.get``. It reads only and changes nothing; ``request.result()`` is what it
reads.
Parameters
----------
all_branches : bool
Every branch, not only the path to the step shown. Default ``False``.
branch : str
The path to this branch's tip (by its name or id) instead of the path to the step shown; not
with all_branches. Optional: left out, the viewer decides.
cursor : str
Where the page starts: the next of the last page (its last step's id); the first page when
left out. Optional: left out, the viewer decides.
fields : list
What to add to each step: params (each parameter in words), notes, bookmark. Optional: left
out, the viewer decides.
limit : int
The steps of one page (200 when left out: well under what a tool result carries). Default
``200``.
since : float
Only the steps recorded at or after this time (milliseconds since 1970: a step's "at"), so a
second read lists what came since. Optional: left out, the viewer decides.
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.get', all_branches=all_branches, branch=branch, cursor=cursor, fields=fields, limit=limit, since=since, tracker=tracker)
[docs]
def history_group_create(
self,
*,
from_: str,
to: str,
name: str,
) -> ActionRequest:
r"""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.
Action ``history.group.create``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
from_ : str
Its first step.
to : str
Its last step.
name : str
A name, unique among its kind (compared without case and extra spaces); no length limit.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.group.create', **{'from': from_}, to=to, name=name)
[docs]
def history_group_extend(
self,
*,
group: str,
to: str,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""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).
Action ``history.group.extend``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
group : str
A group by its name or its id (history_summary lists them).
to : str
Its new last step.
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.group.extend', group=group, to=to, tracker=tracker)
[docs]
def history_group_remove(
self,
*,
group: str,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""Ungroup.
Remove a group; its steps stay as they are.
Action ``history.group.remove``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
group : str
A group by its name or its id (history_summary lists them).
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.group.remove', group=group, tracker=tracker)
[docs]
def history_group_rename(
self,
*,
group: str,
name: str,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""Rename a group.
Give a group another name, unique in its tracker.
Action ``history.group.rename``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
group : str
A group by its name or its id (history_summary lists them).
name : str
A name, unique among its kind (compared without case and extra spaces); no length limit.
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.group.rename', group=group, name=name, tracker=tracker)
[docs]
def history_journal_empty(
self,
*,
entry: str | Omit = OMIT,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``history.journal.empty``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
entry : str
An entry of Recently deleted, by its id (history_summary counts them). Optional: left out,
the viewer decides.
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.journal.empty', entry=entry, tracker=tracker)
[docs]
def history_journal_undo(
self,
*,
entry: str,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``history.journal.undo``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
entry : str
An entry of Recently deleted, by its id (history_summary counts them).
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.journal.undo', entry=entry, tracker=tracker)
[docs]
def history_jump(
self,
*,
at: float | Omit = OMIT,
bookmark: str | Omit = OMIT,
step: str | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``history.jump``. It moves the viewer's history, as the person's Undo, Redo or a click on
a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
at : float
A time (milliseconds since 1970): show the last step at or before it on the branch shown.
Optional: left out, the viewer decides.
bookmark : str
A bookmark's name (any case): show the step it marks. Optional: left out, the viewer
decides.
step : str
A step of the tracker in use, by its id (history_get lists the steps). Optional: left out,
the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.jump', at=at, bookmark=bookmark, step=step)
[docs]
def history_methods(
self,
*,
branch: str | Omit = OMIT,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``history.methods``. It reads only and changes nothing; ``request.result()`` is what it
reads.
Parameters
----------
branch : str
A branch by its name or its id (history_summary lists them). Optional: left out, the viewer
decides.
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.methods', branch=branch, tracker=tracker)
[docs]
def history_note_add(
self,
*,
target: Mapping[str, Any],
text: str,
from_reply: bool = False,
) -> ActionRequest:
r"""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.
Action ``history.note.add``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
target : dict or dict or dict or dict or dict
What the note is on: a step, a branch, a group, a turn, or a tracker itself.
text : str
Markdown: emphasis, inline code and http(s) links; shown without HTML.
from_reply : bool
Taken from the agent's final reply (the turn summary written for an agent that wrote none).
Default ``False``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.note.add', target=target, text=text, from_reply=from_reply)
[docs]
def history_note_edit(
self,
*,
note: str,
text: str,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""Edit a note.
Change a note's text. An agent edits only its own notes; the person edits any.
Action ``history.note.edit``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
note : str
A note, by its id (history_step and history_summary list them).
text : str
Markdown: emphasis, inline code and http(s) links; shown without HTML.
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.note.edit', note=note, text=text, tracker=tracker)
[docs]
def history_note_remove(
self,
*,
note: str,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""Remove a note.
Remove a note. An agent removes only its own notes; the person removes any.
Action ``history.note.remove``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
note : str
A note, by its id (history_step and history_summary list them).
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.note.remove', note=note, tracker=tracker)
[docs]
def history_pseudocode(
self,
*,
branch: str | Omit = OMIT,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""Write the pseudocode.
A branch's steps (main when left out) as pseudocode, one line each, as recorded.
Action ``history.pseudocode``. It reads only and changes nothing; ``request.result()`` is what
it reads.
Parameters
----------
branch : str
A branch by its name or its id (history_summary lists them). Optional: left out, the viewer
decides.
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.pseudocode', branch=branch, tracker=tracker)
[docs]
def history_recording_pause(
self,
*,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``history.recording.pause``. It moves the viewer's history, as the person's Undo, Redo or
a click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.recording.pause', tracker=tracker)
[docs]
def history_recording_resume(
self,
*,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``history.recording.resume``. It moves the viewer's history, as the person's Undo, Redo
or a click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.recording.resume', tracker=tracker)
[docs]
def history_redo(
self,
) -> ActionRequest:
r"""Redo.
Show the step after the one shown now on the branch last taken, as the State panel's Redo does.
Action ``history.redo``. It moves the viewer's history, as the person's Undo, Redo or a click on
a step does, and records no step; ``request.result()`` is its outcome.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.redo')
[docs]
def history_replay(
self,
*,
saved: str,
branch: str | Omit = OMIT,
mapping: Mapping[str, Any] | Omit = OMIT,
name: str | Omit = OMIT,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``history.replay``. It moves the viewer's history, as the person's Undo, Redo or a click
on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
saved : str
A saved state of this browser (history_saved_list).
branch : str
Its branch; its main branch when left out. Optional: left out, the viewer decides.
mapping : dict
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. Keys: ``categories``, ``fields``, ``genes``. Optional: left out, the
viewer decides.
name : str
A name, unique among its kind (compared without case and extra spaces); no length limit.
Optional: left out, the viewer decides.
tracker : str
Its tracker, by name or id; its tracker shown when left out. Optional: left out, the viewer
decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.replay', saved=saved, branch=branch, mapping=mapping, name=name, tracker=tracker)
[docs]
def history_report(
self,
*,
as_: Literal['file', 'text'] = 'file',
file: str | Omit = OMIT,
pictures: Literal['none', 'default'] | Sequence[str] = 'none',
) -> ActionRequest:
r"""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).
Action ``history.report``. It acts outside the viewer's state and history (a file the person
receives in the browser, a publication, or what the browser keeps for later visits), which Undo
does not take back, and records no step; ``request.result()`` is its outcome.
Parameters
----------
as_ : {"file", "text"}
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'``.
file : str
The file's name; the dataset's name and "history report" when left out. Optional: left out,
the viewer decides.
pictures : {"none", "default"} or list
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'``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.report', **{'as': as_}, file=file, pictures=pictures)
[docs]
def history_save(
self,
*,
content: Literal['history', 'state', 'steps'] = 'history',
name: str | Omit = OMIT,
results: Literal['include', 'recompute'] = 'include',
) -> ActionRequest:
r"""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).
Action ``history.save``. It acts outside the viewer's state and history (a file the person
receives in the browser, a publication, or what the browser keeps for later visits), which Undo
does not take back, and records no step; ``request.result()`` is its outcome.
Parameters
----------
content : {"history", "state", "steps"}
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'``.
name : str
Its name; the dataset's name and the time when left out. Optional: left out, the viewer
decides.
results : {"include", "recompute"}
Analysis results: include them, or leave them out to compute again on open from their
recorded inputs (smaller; always so for steps). Default ``'include'``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.save', content=content, name=name, results=results)
[docs]
def history_saved_delete(
self,
*,
saved: str,
) -> ActionRequest:
r"""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.
Action ``history.saved.delete``. It acts outside the viewer's state and history (a file the
person receives in the browser, a publication, or what the browser keeps for later visits),
which Undo does not take back, and records no step; ``request.result()`` is its outcome.
Parameters
----------
saved : str
Its id (history_saved_list).
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.saved.delete', saved=saved)
[docs]
def history_saved_list(
self,
) -> ActionRequest:
r"""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.
Action ``history.saved.list``. It reads only and changes nothing; ``request.result()`` is what
it reads.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.saved.list')
[docs]
def history_search(
self,
*,
bookmarked: bool | Omit = OMIT,
by: Literal['person', 'agent', 'python', 'r', 'replay', 'outside'] | Omit = OMIT,
domain: Literal['cells', 'mapping', 'field-overlays', 'gene-sets', 'views', 'active-field', 'filters', 'colors', 'visibility', 'highlights', 'camera', 'camera-path', 'settings', 'analysis', 'layout'] | Omit = OMIT,
flagged: bool | Omit = OMIT,
has_note: bool | Omit = OMIT,
kind: Literal['state', 'view', 'layout'] | Omit = OMIT,
step_kind: Literal['root', 'action', 'outside', 'squashed'] | Omit = OMIT,
text: str | Omit = OMIT,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``history.search``. It reads only and changes nothing; ``request.result()`` is what it
reads.
Parameters
----------
bookmarked : bool
Optional: left out, the viewer decides.
by : {"person", "agent", "python", "r", "replay", "outside"}
Who took them. Optional: left out, the viewer decides.
domain : {"cells", "mapping", "field-overlays", "gene-sets", "views", "active-field", "filters", "colors", "visibility", "highlights", "camera", "camera-path", "settings", "analysis", "layout"}
The part of the state they changed. Optional: left out, the viewer decides.
flagged : bool
Stale, or no longer applying. Optional: left out, the viewer decides.
has_note : bool
Optional: left out, the viewer decides.
kind : {"state", "view", "layout"}
What their action changes. Optional: left out, the viewer decides.
step_kind : {"root", "action", "outside", "squashed"}
What they are: root, action, outside (changed outside an action) or squashed. Optional: left
out, the viewer decides.
text : str
Words to find (any case). Optional: left out, the viewer decides.
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.search', bookmarked=bookmarked, by=by, domain=domain, flagged=flagged, has_note=has_note, kind=kind, step_kind=step_kind, text=text, tracker=tracker)
[docs]
def history_share(
self,
*,
chats: bool = False,
content: Literal['history', 'state', 'steps'] = 'history',
file: str | Omit = OMIT,
include: Sequence[Mapping[str, Any]] | Omit = OMIT,
journal: bool = False,
notes: bool = True,
results: Literal['include', 'recompute'] = 'include',
source: Literal['full', 'name'] = 'full',
times: Literal['exact', 'dates', 'none'] | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``history.share``. It acts outside the viewer's state and history (a file the person
receives in the browser, a publication, or what the browser keeps for later visits), which Undo
does not take back, and records no step; ``request.result()`` is its outcome.
Parameters
----------
chats : bool
Conversations kept with the trackers (never with a state). Default ``False``.
content : {"history", "state", "steps"}
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'``.
file : str
The file's name; the dataset's name when left out. Optional: left out, the viewer decides.
include : list
The trackers to include, each with its branches (its main and shown branches when left out);
the tracker in use when left out. Optional: left out, the viewer decides.
journal : bool
Recently deleted (never with a state). Default ``False``.
notes : bool
Notes and bookmarks (never with a state). Default ``True``.
results : {"include", "recompute"}
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'``.
source : {"full", "name"}
full: the dataset's name and where it opens from; name: its name only. Default ``'full'``.
times : {"exact", "dates", "none"}
exact; dates (each rounded down to its day); none. When left out: exact for a history or
steps, none for a state. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.share', chats=chats, content=content, file=file, include=include, journal=journal, notes=notes, results=results, source=source, times=times)
[docs]
def history_squash(
self,
*,
from_: str,
to: str,
) -> ActionRequest:
r"""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.
Action ``history.squash``. It moves the viewer's history, as the person's Undo, Redo or a click
on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
from_ : str
The first step to merge.
to : str
The last step to merge.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.squash', **{'from': from_}, to=to)
[docs]
def history_stale(
self,
*,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``history.stale``. It reads only and changes nothing; ``request.result()`` is what it
reads.
Parameters
----------
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.stale', tracker=tracker)
[docs]
def history_step(
self,
*,
step: str,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``history.step``. It reads only and changes nothing; ``request.result()`` is what it
reads.
Parameters
----------
step : str
A step, by its id (history_get lists the steps).
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.step', step=step, tracker=tracker)
[docs]
def history_step_delete(
self,
*,
step: str,
) -> ActionRequest:
r"""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.
Action ``history.step.delete``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
step : str
A step of the tracker in use, by its id (history_get lists the steps).
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.step.delete', step=step)
[docs]
def history_step_revert(
self,
*,
step: str,
) -> ActionRequest:
r"""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).
Action ``history.step.revert``. It changes the data's meaning (fields, labels, filters,
highlights, results), as one step of the viewer's history, which the person can undo;
``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
step : str
A step of the tracker in use, by its id (history_get lists the steps).
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.step.revert', step=step)
[docs]
def history_summary(
self,
*,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``history.summary``. It reads only and changes nothing; ``request.result()`` is what it
reads.
Parameters
----------
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.summary', tracker=tracker)
[docs]
def history_tour_start(
self,
) -> ActionRequest:
r"""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.
Action ``history.tour.start``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.tour.start')
[docs]
def history_tour_stop(
self,
) -> ActionRequest:
r"""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).
Action ``history.tour.stop``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.tour.stop')
[docs]
def history_tracker_remove(
self,
*,
tracker: str,
) -> ActionRequest:
r"""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.
Action ``history.tracker.remove``. It moves the viewer's history, as the person's Undo, Redo or
a click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
tracker : str
A tracker by its name or its id (history_summary lists them).
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.tracker.remove', tracker=tracker)
[docs]
def history_tracker_rename(
self,
*,
tracker: str,
name: str,
) -> ActionRequest:
r"""Rename a tracker.
Give a tracker another name, unique among this dataset's trackers.
Action ``history.tracker.rename``. It moves the viewer's history, as the person's Undo, Redo or
a click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
tracker : str
A tracker by its name or its id (history_summary lists them).
name : str
A name, unique among its kind (compared without case and extra spaces); no length limit.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.tracker.rename', tracker=tracker, name=name)
[docs]
def history_tracker_start(
self,
*,
name: str | Omit = OMIT,
start: Literal['opened', 'shown'] = 'opened',
) -> ActionRequest:
r"""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.
Action ``history.tracker.start``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
name : str
A name, unique among its kind (compared without case and extra spaces); no length limit.
Optional: left out, the viewer decides.
start : {"opened", "shown"}
opened: the dataset as it was opened; shown: what is shown now. Default ``'opened'``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.tracker.start', name=name, start=start)
[docs]
def history_tracker_use(
self,
*,
tracker: str,
) -> ActionRequest:
r"""Use another tracker.
Show another tracker's step shown and record into it.
Action ``history.tracker.use``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
tracker : str
A tracker by its name or its id (history_summary lists them).
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.tracker.use', tracker=tracker)
[docs]
def history_turn_undo(
self,
*,
turn: str,
only_own: bool = False,
) -> ActionRequest:
r"""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.
Action ``history.turn.undo``. It moves the viewer's history, as the person's Undo, Redo or a
click on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
turn : str
A turn, by its id (history_summary lists them).
only_own : bool
Delete only the turn's own steps, keeping the others (to Recently deleted). Default
``False``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.turn.undo', turn=turn, only_own=only_own)
[docs]
def history_undo(
self,
) -> ActionRequest:
r"""Undo.
Show the state before the step shown now, as the State panel's Undo does; the step stays in the
history, to redo.
Action ``history.undo``. It moves the viewer's history, as the person's Undo, Redo or a click on
a step does, and records no step; ``request.result()`` is its outcome.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.undo')
[docs]
def history_verify(
self,
*,
branch: str,
keep: bool = False,
tracker: str | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``history.verify``. It moves the viewer's history, as the person's Undo, Redo or a click
on a step does, and records no step; ``request.result()`` is its outcome.
Parameters
----------
branch : str
A branch by its name or its id (history_summary lists them).
keep : bool
Keep the scratch tracker afterwards. Default ``False``.
tracker : str
A tracker by its name or its id (history_summary lists them); the tracker in use when left
out. Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('history.verify', branch=branch, keep=keep, tracker=tracker)
[docs]
def layout_get(
self,
) -> ActionRequest:
r"""Read the layout.
The sidebar's sections (docked or floating, where, open or closed), whether the sidebar shows
and how wide, and the theme.
Action ``layout.get``. It reads only and changes nothing; ``request.result()`` is what it reads.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('layout.get')
[docs]
def layout_panel_dock(
self,
*,
panel: str,
) -> ActionRequest:
r"""Dock a section.
Put a floating sidebar section back into the sidebar, where it was.
Action ``layout.panel.dock``. It changes the viewer's layout, as one step of the viewer's
history, which the person can undo; ``request.result()`` is its outcome and ``request.step`` the
step.
Parameters
----------
panel : str
A sidebar section by its title (Visualization, Navigation, …) or its id.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('layout.panel.dock', panel=panel)
[docs]
def layout_panel_float(
self,
*,
panel: str,
height: float | Omit = OMIT,
left: float | Omit = OMIT,
top: float | Omit = OMIT,
width: float | Omit = OMIT,
) -> ActionRequest:
r"""Undock a section.
Tear a sidebar section off into a floating window, at a given place and size or beside the
sidebar.
Action ``layout.panel.float``. It changes the viewer's layout, as one step of the viewer's
history, which the person can undo; ``request.result()`` is its outcome and ``request.step`` the
step.
Parameters
----------
panel : str
A sidebar section by its title (Visualization, Navigation, …) or its id.
height : float
Height in CSS pixels (kept at least its header and first row). Optional: left out, the
viewer decides.
left : float
Distance of its left edge from the left of the window, in CSS pixels. Optional: left out,
the viewer decides.
top : float
Distance of its top edge from the top of the window, in CSS pixels. Optional: left out, the
viewer decides.
width : float
Width in CSS pixels (kept at least its smallest working width). Optional: left out, the
viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('layout.panel.float', panel=panel, height=height, left=left, top=top, width=width)
[docs]
def layout_panel_place(
self,
*,
panel: str,
left: float,
top: float,
width: float,
height: float,
) -> ActionRequest:
r"""Move or resize a floating section.
Give a floating sidebar section a place and size; it is kept inside the window.
Action ``layout.panel.place``. It changes the viewer's layout, as one step of the viewer's
history, which the person can undo; ``request.result()`` is its outcome and ``request.step`` the
step.
Parameters
----------
panel : str
A sidebar section by its title (Visualization, Navigation, …) or its id.
left : float
Distance of its left edge from the left of the window, in CSS pixels.
top : float
Distance of its top edge from the top of the window, in CSS pixels.
width : float
Width in CSS pixels (kept at least its smallest working width).
height : float
Height in CSS pixels (kept at least its header and first row).
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('layout.panel.place', panel=panel, left=left, top=top, width=width, height=height)
[docs]
def layout_section_open(
self,
*,
section: str,
open: bool,
) -> ActionRequest:
r"""Open or close a section.
Open or close a section of the sidebar (docked or floating).
Action ``layout.section.open``. It changes the viewer's layout, as one step of the viewer's
history, which the person can undo; ``request.result()`` is its outcome and ``request.step`` the
step.
Parameters
----------
section : str
A sidebar section by its title (Visualization, Navigation, …) or its id.
open : bool
True opens it, false closes it.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('layout.section.open', section=section, open=open)
[docs]
def layout_theme_set(
self,
*,
theme: Literal['light', 'dark'],
) -> ActionRequest:
r"""Choose the theme.
Show the app light or dark.
Action ``layout.theme.set``. It changes the viewer's layout, as one step of the viewer's
history, which the person can undo; ``request.result()`` is its outcome and ``request.step`` the
step.
Parameters
----------
theme : {"light", "dark"}
See the action's summary.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('layout.theme.set', theme=theme)
[docs]
def mapping_set(
self,
*,
embeddings: Mapping[str, Any] | Omit = OMIT,
expression: str | None | Omit = OMIT,
gene_names: str | Omit = OMIT,
highly_variable: str | None | Omit = OMIT,
knn: str | None | Omit = OMIT,
latent: str | None | Omit = OMIT,
log1p: Sequence[Mapping[str, Any]] | Omit = OMIT,
modality: str | Omit = OMIT,
vector_fields: Sequence[Mapping[str, Any]] | Omit = OMIT,
) -> ActionRequest:
r"""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.
Action ``mapping.set``. It changes the data's meaning (fields, labels, filters, highlights,
results), as one step of the viewer's history, which the person can undo; ``request.result()``
is its outcome and ``request.step`` the step.
Parameters
----------
embeddings : dict
The embeddings views can show, sorted by key then columns, and the default of each
dimension. Keys: ``defaults``, ``enabled``. Optional: left out, the viewer decides.
expression : str or None
"X", "raw", "layer:<name>", or null for no genes. Optional: left out, the viewer decides.
gene_names : str
"index", or "column:<var column>". Optional: left out, the viewer decides.
highly_variable : str or None
The boolean var column marking highly variable genes, or null. Optional: left out, the
viewer decides.
knn : str or None
The obsp neighbour graph, or null for none. Optional: left out, the viewer decides.
latent : str or None
The obsm latent space outlier filters use, or null. Optional: left out, the viewer decides.
log1p : list
Each expression matrix that holds log1p values, with its base (null: e). Optional: left out,
the viewer decides.
modality : str
The modality genes are read from (a dataset of several). Optional: left out, the viewer
decides.
vector_fields : list
Vector fields bound to enabled embeddings, sorted by embedding then key. Optional: left out,
the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('mapping.set', embeddings=embeddings, expression=expression, gene_names=gene_names, highly_variable=highly_variable, knn=knn, latent=latent, log1p=log1p, modality=modality, vector_fields=vector_fields)
[docs]
def my_datasets_forget(
self,
*,
name: str,
saved_states: bool = False,
) -> ActionRequest:
r"""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.
Action ``my-datasets.forget``. It acts outside the viewer's state and history (a file the person
receives in the browser, a publication, or what the browser keeps for later visits), which Undo
does not take back, and records no step; ``request.result()`` is its outcome.
Parameters
----------
name : str
Its name in My datasets (datasets_list).
saved_states : bool
Also delete its saved states (histories kept in this browser). Default ``False``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('my-datasets.forget', name=name, saved_states=saved_states)
[docs]
def setting_set(
self,
*,
setting: str,
value: str | float | bool,
) -> ActionRequest:
r"""Change a setting.
Set one render, navigation, overlay or tool setting of the sidebar; settings.list names each,
with its kind, range and choices.
Action ``setting.set``. It changes how the cells are shown, as one step of the viewer's history,
which the person can undo; ``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
setting : str
The setting's id, as settings.list gives it.
value : str or float or bool
A number for a slider, true or false for a switch, an option value for a choice, #rrggbb for
a colour.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('setting.set', setting=setting, value=value)
[docs]
def settings_list(
self,
*,
section: str | Omit = OMIT,
) -> ActionRequest:
r"""List the settings.
Every setting of the sidebar with its label, section, kind, value, range or choices, and whether
it can be changed now.
Action ``settings.list``. It reads only and changes nothing; ``request.result()`` is what it
reads.
Parameters
----------
section : str
Only the settings of the sidebar section with this title (Visualization, Navigation, …).
Optional: left out, the viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('settings.list', section=section)
[docs]
def stored_list(
self,
) -> ActionRequest:
r"""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.
Action ``stored.list``. It reads only and changes nothing; ``request.result()`` is what it
reads.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('stored.list')
[docs]
def stored_remove(
self,
*,
connection_speeds: bool = False,
dataset: str | Omit = OMIT,
decoder_choices: bool = False,
everything: bool = False,
items: Sequence[str] | Omit = OMIT,
my_datasets: bool = False,
saved_states: bool = False,
) -> ActionRequest:
r"""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.
Action ``stored.remove``. It acts outside the viewer's state and history (a file the person
receives in the browser, a publication, or what the browser keeps for later visits), which Undo
does not take back, and records no step; ``request.result()`` is its outcome.
Parameters
----------
connection_speeds : bool
The connection speeds remembered per host. Default ``False``.
dataset : str
Every kept item of the dataset with this file name (stored_list). Optional: left out, the
viewer decides.
decoder_choices : bool
The decoder choices measured in this browser. Default ``False``.
everything : bool
Everything no open tab uses, as Remove all. Default ``False``.
items : list
Kept items by id (stored_list). Optional: left out, the viewer decides.
my_datasets : bool
My datasets: the list and the handles of its files (my_datasets_forget forgets one). Default
``False``.
saved_states : bool
Every saved state of this browser (history_saved_delete deletes one). Default ``False``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('stored.remove', connection_speeds=connection_speeds, dataset=dataset, decoder_choices=decoder_choices, everything=everything, items=items, my_datasets=my_datasets, saved_states=saved_states)
[docs]
def view_cameras_link(
self,
*,
linked: bool,
) -> ActionRequest:
r"""Link cameras.
Let views that show the same embedding share one camera, or give each view its own.
Action ``view.cameras.link``. It changes how the cells are shown, as one step of the viewer's
history, which the person can undo; ``request.result()`` is its outcome and ``request.step`` the
step.
Parameters
----------
linked : bool
true to link, false to unlink.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('view.cameras.link', linked=linked)
[docs]
def view_clear(
self,
) -> ActionRequest:
r"""Remove every kept view.
Remove every kept view and show the live view alone (as View 1).
Action ``view.clear``. It changes how the cells are shown, as one step of the viewer's history,
which the person can undo; ``request.result()`` is its outcome and ``request.step`` the step.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('view.clear')
[docs]
def view_embedding_cycle(
self,
*,
view: str,
dimension: Literal[1, 2, 3],
) -> ActionRequest:
r"""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.
Action ``view.embedding.cycle``. It changes how the cells are shown, as one step of the viewer's
history, which the person can undo; ``request.result()`` is its outcome and ``request.step`` the
step.
Parameters
----------
view : str
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 : {1, 2, 3}
The dimension: 1, 2 or 3.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('view.embedding.cycle', view=view, dimension=dimension)
[docs]
def view_embedding_default(
self,
*,
view: str,
dimension: Literal[1, 2, 3],
) -> ActionRequest:
r"""Show the default embedding.
Show the dataset's default embedding of one dimension in a view; the view follows that default
from then on.
Action ``view.embedding.default``. It changes how the cells are shown, as one step of the
viewer's history, which the person can undo; ``request.result()`` is its outcome and
``request.step`` the step.
Parameters
----------
view : str
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 : {1, 2, 3}
The dimension: 1, 2 or 3.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('view.embedding.default', view=view, dimension=dimension)
[docs]
def view_embedding_set(
self,
*,
view: str,
embedding: Mapping[str, Any],
) -> ActionRequest:
r"""Show an embedding.
Show one enabled embedding in a view; the view keeps it when the data mapping changes its
defaults.
Action ``view.embedding.set``. It changes how the cells are shown, as one step of the viewer's
history, which the person can undo; ``request.result()`` is its outcome and ``request.step`` the
step.
Parameters
----------
view : str
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 : dict
An embedding: the obsm array and the columns of it plotted. Keys: ``columns``, ``key``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('view.embedding.set', view=view, embedding=embedding)
[docs]
def view_focus(
self,
*,
view: str,
) -> ActionRequest:
r"""Select a view.
Select the view the sidebar edits and the camera controls drive.
Action ``view.focus``. It changes how the cells are shown, as one step of the viewer's history,
which the person can undo; ``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
view : str
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).
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('view.focus', view=view)
[docs]
def view_keep(
self,
*,
branch: str | Omit = OMIT,
) -> ActionRequest:
r"""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).
Action ``view.keep``. It changes how the cells are shown, as one step of the viewer's history,
which the person can undo; ``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
branch : str
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). Optional: left out, the
viewer decides.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('view.keep', branch=branch)
[docs]
def view_layout_set(
self,
*,
layout: Literal['grid', 'single'],
) -> ActionRequest:
r"""Set the view layout.
Show every view side by side (grid) or the selected view alone (single).
Action ``view.layout.set``. It changes how the cells are shown, as one step of the viewer's
history, which the person can undo; ``request.result()`` is its outcome and ``request.step`` the
step.
Parameters
----------
layout : {"grid", "single"}
"grid" or "single".
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('view.layout.set', layout=layout)
[docs]
def view_picture(
self,
*,
height: int = 480,
legend: bool = True,
view: str | Omit = OMIT,
width: int = 640,
) -> ActionRequest:
r"""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.
Action ``view.picture``. It reads only and changes nothing; ``request.result()`` is what it
reads.
Parameters
----------
height : int
The plot's height in pixels. Default ``480``.
legend : bool
Draw the colour legend beside the plot. Default ``True``.
view : str
The view: "View N" as the Compare views list numbers it; the selected view when left out.
Optional: left out, the viewer decides.
width : int
The plot's width in pixels (the picture adds its margins and the legend). Default ``640``.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('view.picture', height=height, legend=legend, view=view, width=width)
[docs]
def view_remove(
self,
*,
view: str,
) -> ActionRequest:
r"""Remove a view.
Remove a view; removing the live view (View 1) hides it while two or more kept views remain.
Action ``view.remove``. It changes how the cells are shown, as one step of the viewer's history,
which the person can undo; ``request.result()`` is its outcome and ``request.step`` the step.
Parameters
----------
view : str
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).
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('view.remove', view=view)
[docs]
def views_state(
self,
) -> ActionRequest:
r"""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.
Action ``views.state``. It reads only and changes nothing; ``request.result()`` is what it
reads.
Returns
-------
ActionRequest
The request, sent at once (or as soon as the viewer connects). In a notebook widget its
answer arrives once the cell has finished: collect it in a later cell.
"""
return self.act('views.state')
