Do anything in an open Cellucid viewer: send an action, collect its answer

Everything a person can do in the viewer is an action of its catalogue – colouring, filtering, highlighting, renaming and merging categories, views and the camera, the layout, every analysis – and so is everything an agent or a notebook does there: cellucid_act() sends one, by its type, with its parameters. Each action has its own function as well, cellucid_<tool>(), generated from the catalogue with its own help page (cellucid_color_by(), cellucid_highlight_cells(), cellucid_history_get(), ...). An action that changes the viewer is one step of its history, labelled as R's, undone like any other step; a read changes nothing.

Nothing waits for the viewer: an action is sent and its request returned at once. cellucid_action_result() collects the answer – where R can wait (a browser or the RStudio viewer) it waits for it; in a Jupyter notebook the viewer answers between cells, so collect it in a later cell (it says so at once before then). An action the viewer refused and that nobody collects is said as a warning, unless a cellucid_on() handler of "command_error" takes it.

cellucid_freeze() tells the page to keep its last complete view because R stops serving it (cellucid_stop() sends it first); it is a command, not an action.

Usage

cellucid_act(.viewer, .action, ...)

cellucid_action_result(request, timeout = 60)

cellucid_freeze(viewer)

Arguments

.viewer: A viewer cellucid_view() or cellucid_serve() returned.
.action: The action, by its dotted type, such as "color.by" or "highlight.cells": one of the viewer's action catalogue (each has its own function, below), or one a viewer newer than this package knows.
...: The action's parameters, by name, as its function takes them: field = list(source = "obs", key = "cell_type"). A parameter named as an R reserved word is written with a trailing underscore (in_ = 2 sends in). NULL sends JSON null; a parameter not given is left out.
request: What cellucid_act(), an action's function or cellucid_push() returned.
timeout: Seconds to wait for the viewer's answer.
viewer: A viewer cellucid_view() or cellucid_serve() returned.

Value

cellucid_act() returns the request at once, invisibly (a cellucid_action_request), the action sent now or, before the viewer's page has connected, as soon as it does, in order with every other command. It prints its action and state (waiting for the viewer, sent, answered with the step it made, refused with why); request$done says whether the viewer answered, request$step the history step the action made (list(id, label), or NULL for a read or a change that changed nothing), request$state the state.

cellucid_action_result() returns the action's outcome: for a read, what it read; for a change, what it did (names, counts and ids), or NULL when it had nothing to report. Outcomes are lists as jsonlite reads JSON (simplifyVector = FALSE); cells in them are original positions, the 0-based rows of the dataset's obs. It stops with the viewer's reason when the viewer refused the action, and when the viewer was stopped before it answered. The answer is kept while the request is: call it again for the same outcome.

cellucid_freeze() returns the viewer invisibly.

Details

Parameters are converted to each action's parameter schema by its annotations, never one action at a time. Cells (an x-cells parameter, such as highlight.cells' cells) are given as R gives them: 1-based positions, TRUE/FALSE for every cell, or the cell names of the object the viewer shows; each cell once, in any order. They are sent as 0-based original positions in one binary frame, four bytes a cell, so a million cells is four megabytes written in one pass. A column of values (an x-values parameter) is sent in its value type: a factor as its codes (NA: no category), TRUE/FALSE as 1/0, whole numbers from 0 in the smallest unsigned type that holds them, other numbers as float64 (NA: no value). A vector given for an array parameter is sent as an array whatever its length, and a named list as an object.

Whether the parameters fit is the viewer's to say: its schema is the authority, and a refusal names what is wrong ("There is no category ... in ...; its categories are ...").

Examples

if (interactive() && requireNamespace("SeuratObject", quietly = TRUE)) {
  data("pbmc_small", package = "SeuratObject")
  object <- SeuratObject::UpdateSeuratObject(pbmc_small)
  viewer <- cellucid_view(object)
  cellucid_act(viewer, "color.by", field = list(source = "obs", key = "groups"))
  # The same, by the action's own function:
  cellucid_color_by(viewer, field = list(source = "obs", key = "groups"))
  request <- cellucid_highlight_cells(viewer, object$groups == "g2", label = "g2")
  cellucid_action_result(request)
  history <- cellucid_action_result(cellucid_history_get(viewer))
  length(history$steps)
  cellucid_stop(viewer)
}