Bring what was made in Cellucid back onto the object, in one call

Everything a person made in the viewer – every highlight group, every user-defined categorical field (labels, annotations, clusters), every continuous field and score, every gene set – written onto the object as metadata columns in one call, from a live viewer or from the web app's exports. cellucid-python's viewer.pull(adata) and cellucid.pull(adata, source) write the same columns.

Usage

cellucid_pull(
  data,
  source,
  ...,
  highlights = TRUE,
  fields = TRUE,
  scores = TRUE,
  visibility = FALSE,
  gene_sets = TRUE,
  include_pushed = FALSE,
  highlight_prefix = "cellucid_highlight__",
  field_prefix = "",
  on_conflict = "error",
  prune = TRUE,
  return_summary = FALSE
)

cellucid_results(viewer)

cellucid_subset(data, viewer, which = NULL)

cellucid_gene_sets(viewer, symbols = FALSE)

Arguments

data: The object the viewer shows, cells in the same order: a Seurat object (columns go to meta.data), a SingleCellExperiment or SummarizedExperiment (colData), or a data frame with one row per cell named by cell. From a viewer, an object holding the viewer's cells in another order is refused (nothing is written), as is one in a Cellucid-ready file's stored order (its cellucid$priority record describes its cells; cellucid_restore_original_order() puts it back).
source: An open viewer (cellucid_view()): what it holds, as it last sent it – every result as it is made, and all of them whenever its dataset opens – so nothing is waited for, and in a Jupyter notebook a lasso drawn and cellucid_pull() run in the next cell finds the lasso; or what the web app exports with no R session at all: obs-column .csv files (a header row, obs_name then each column's name; a kind row, kind then each column's kind, highlight, categorical or continuous; a row per cell; each column written as named and as its kind says, never guessed from its values, and a cell the file does not list NA), .gmt gene sets and .cellucid-session files; one file, several, or a folder of them.
...: For a session file: the arguments cellucid_view() was given that choose what is shown (as cellucid_apply_session() takes them).
highlights: Write the highlight groups.
fields: Write the user-defined fields (labels, annotations, clusters).
scores: Write the scores an analysis made (a gene signature's).
visibility: Write the cells the filters leave visible, as cellucid_visible (off by default).
gene_sets: Write the gene sets.
include_pushed: Also write the fields this R session pushed (cellucid_push()), which the object holds already.
highlight_prefix: A highlight group's column is <highlight_prefix><group id>.
field_prefix: A field's or score's column is <field_prefix><key>.
on_conflict: What a column the object has already does, when no pull from the same source (the viewer, or the same file) wrote it: "error" (nothing is written), "replace", or "suffix" (written as <name>_2 beside it). A result an earlier pull wrote is written to the same column again, suffix and all. Session files follow the same rule.
prune: For a viewer: remove the columns, and the gene sets, an earlier viewer pull wrote whose result the viewer no longer holds (a highlight deleted since). A result left out of this pull (highlights = FALSE, a pushed field) keeps its column, and files never remove anything.
return_summary: TRUE returns list(data, summary): the columns written (columns) and removed (removed), the gene sets brought (gene_sets) and removed (removed_gene_sets), and the results left out (skipped).
viewer: A viewer cellucid_view() or cellucid_serve() returned.
which: A highlight group, by id ("highlight_3") or by its label; "visible" for the visible cells; NULL for the last selection.
symbols: FALSE names each gene set's genes by identifier – the var index, rownames(object); TRUE by the names the viewer shows for them: those of the var column its data mapping names the genes by (such as feature_name), else the identifiers themselves.

Value

cellucid_pull(): the object with the columns added (R copies on change: the object passed in is not changed); highlight groups are TRUE/FALSE, categorical fields factors with the viewer's categories, continuous fields and scores numbers (NA where a cell has none). When the viewer opened a subsample, a cell it did not open is NA: unknown, not "not selected". The gene sets go to misc$cellucid$gene_sets (Seurat), metadata(x)$cellucid$gene_sets, or the cellucid attribute of a data frame – each its genes by identifier (the var index), and from a viewer whose data mapping names the genes by a var column the symbols shown – beside pulled, the record of each column written: where it came from (pulled_from: "viewer" or the file's name) and the result it holds (kind, id). A gene set name used twice is "name (2)", as the web app and cellucid-python name it.

cellucid_results(): every result the viewer holds, as of the last event it sent – one epoch's: a reloaded page, or the viewer shown again, replaces what an older page sent – (it stops with what to do before the viewer sent them all once, and while the viewer shows a dataset this viewer did not serve, opened in it instead), each a list of kind ("highlight", "categorical", "continuous", "geneSet", "visibility", "subset"), id, revision, n_obs, meta, cells (1-based, NULL for every cell), values and, for an object, cell_names.

cellucid_subset(): those cells of data. cellucid_gene_sets(): a named list of character vectors, one per gene set (the R session's, the shown marker genes', the shown gene signature's), by identifier or by symbol (symbols).

Details

cellucid_apply_session() writes a saved session's highlight groups and fields with the same column rules; cellucid_pull() of a .cellucid-session file writes the highlight groups and user-defined fields of the state it shows (its active tracker's head), checked against the object as an apply checks it (the dataset, the cells and their order, the fields that state uses), keeps its gene sets, and names the columns with every other column of the pull (the labels a session renames are cellucid_apply_session()'s to write).

Examples

if (interactive() && requireNamespace("SeuratObject", quietly = TRUE)) {
  data("pbmc_small", package = "SeuratObject")
  object <- SeuratObject::UpdateSeuratObject(pbmc_small)
  viewer <- cellucid_view(object)
  # Lasso some cells, label a few clusters, score a gene signature, then:
  object <- cellucid_pull(object, viewer)
  head(object[[]])
  # From the web app's exports, without a viewer:
  # object <- cellucid_pull(object, "~/Downloads/cellucid-exports")
  cellucid_stop(viewer)
}