React to what happens in an open Cellucid viewer

The viewer sends its events back over its channel: a selection (every selected cell, however many), the cell under the pointer, a click, the data mapping it applied, an action's answer, a command it could not carry out. cellucid_on() runs a handler for each event of a kind, whenever R is idle; a handler that fails gives a warning and the others still run. cellucid_request_session() asks the viewer for its session, the file the viewer's Save session writes: the history of every step taken in it (what you highlighted, coloured, annotated and arranged, and what R and agents did), every tracker and branch.

Usage

cellucid_on(viewer, event, handler)

cellucid_off(viewer, event = NULL)

cellucid_selection(viewer)

cellucid_wait_ready(viewer, timeout = 30)

cellucid_request_session(viewer)

cellucid_session_result(request, file = NULL, timeout = 60)

Arguments

viewer: A viewer cellucid_view() or cellucid_serve() returned.
event: One of "selection", "hover", "click", "ready", "data_mapping", "command_error", "action_result", "pong", "debug_snapshot", "session_bundle", "result" (a result made or changed, as cellucid_results() lists them), "result_removed", "results" (every result the viewer holds), "history_changed" (every change of the viewer's history: kind, tracker, head, step, branch; see cellucid_last_history_change()), "session_loaded" (a session cellucid_load_session() pushed in, loaded) and "color_by" (the field it colours by: field, a gene by its identifier, the var index; source, "obs" or "var"; symbol, the name the viewer shows for a gene when it differs from its identifier, else NULL; and cells_read, for a gene read for a sample of the open cells of a large dataset stored cell by cell, how many of them it is read for, the first in their order, else NULL; sent again when that grows). An action the viewer carried out arrives as "action_result" (requestId, the history step it made, list(id, label) or NULL, and its outcome); one it refused, or another command it could not carry out, as "command_error" (command, requestId, reason): with no handler for it, and no cellucid_action_result() or cellucid_session_result() waiting for it, R warns. For cellucid_off(), NULL removes every handler.
handler: A function of one argument, the event: a list of its fields. Cells are 1-based positions in every event, as the actions take them: selection gives cells and (for an object) cell_names; hover and click give cell (NULL for no cell under the pointer) and cell_name. cellucid-python's events are 0-based, as Python indexes. The pong and debug_snapshot events answer cellucid_debug_connection(); the channel's own keep-alive pings are answered without an event.
timeout: Seconds to wait for the viewer.
request: What cellucid_request_session() returned.
file: Where to save the session file; a temporary file when NULL.

Value

cellucid_on() and cellucid_off() return the viewer invisibly. cellucid_selection() returns the last selection, list(cells, cell_names, source): the selected cells' 1-based positions, their names (for an object), and the tool that made it; NULL before the first. cellucid_wait_ready() returns the viewer's ready event, list(n_cells, n_obs, dimensions): the cells open (fewer than n_obs when the viewer opened a subsample), the cells in the dataset, and the dimensions shown. cellucid_request_session() returns the request (printed as waiting, answered or failed); cellucid_session_result() the session the viewer sent, read and checked (cellucid_read_session(): its history, every tracker and every step), its .cellucid-session file kept at file (or a temporary file). A session is always asked for, then collected – the one way, in a notebook and outside one (cellucid-python's viewer.request_session() and request.result()). In a Jupyter notebook the viewer answers between cells, so collect it in a later cell (cellucid_session_result() says so at once before then), or apply it there with cellucid_apply_session(object, request); where R can wait (a browser or RStudio viewer) cellucid_session_result() waits for it.

Details

Handlers run on R's main thread while R is idle, so an RStudio or Positron console stays usable. cellucid_wait_ready() and cellucid_session_result() wait by running R's event loop (outside a notebook), and stop with what to do when the viewer does not answer in time.

Examples

if (interactive() && requireNamespace("SeuratObject", quietly = TRUE)) {
  data("pbmc_small", package = "SeuratObject")
  object <- SeuratObject::UpdateSeuratObject(pbmc_small)
  viewer <- cellucid_view(object)
  cellucid_on(viewer, "selection", function(event) {
    message(length(event$cells), " cells selected with the ", event$source)
  })
  # Select cells in the viewer, then:
  selected <- cellucid_selection(viewer)
  if (!is.null(selected)) subset(object, cells = selected$cell_names)
  cellucid_stop(viewer)
}