Apply one step of a saved Cellucid history to an object: a plan first

What was made in the viewer, as it stood at one step of its history – renamed fields and categories, user-defined fields (labels, annotations, merged categories, pushed columns, copies of a column or a gene), gene sets and highlight groups – written onto the object it was saved on, after a plan says what would change. The rules are cellucid-python's apply_cellucid_session_to_anndata() and the web app's “Save AnnData with this state...” copy (app/history/exports/anndata-copy.js), row for row: the three are held to one shared expected plan, the feature-metadata columns each writes included.

Usage

cellucid_apply_session(
  data,
  session,
  tracker = NULL,
  branch = NULL,
  step = NULL,
  ...,
  dry_run = TRUE,
  overwrite = FALSE,
  keep_session = FALSE,
  timeout = 60
)

cellucid_apply_plan(plan)

cellucid_history_applied(data)

Arguments

data: The Seurat, SingleCellExperiment or SummarizedExperiment object the session was saved on, its cells in their original order: a session names every cell by its original position. An object read from a Cellucid-ready store in its stored priority order is refused; cellucid_restore_original_order() puts it back.
session: A session cellucid_read_session() read, a .cellucid-session file (what the viewer's Save session writes), or what cellucid_request_session() returned: the session is then collected first (in a Jupyter notebook in a later cell, since the viewer answers between cells; elsewhere this waits for it).
tracker: The tracker, by its name or id; NULL for the one the viewer showed (the active tracker).
branch: A branch of the tracker, by its name or id: its last step, or, with step, the branch that step must be on.
step: A step of the tracker, by its id ("s4"; cellucid_steps() lists them). With neither branch nor step: the step the viewer showed (the tracker's head).
...: The arguments cellucid_view() was given that choose what is shown (embeddings, obs, modalities, ...), so the object is checked against what the viewer showed.
dry_run: TRUE (the default) returns the plan and changes nothing; FALSE applies it at once.
overwrite: Replace a column or gene set an earlier apply wrote with other values. A column or gene set the person made is never replaced, whatever this says.
keep_session: Keep the whole session file, base64, in the apply's record, so the history can be rebuilt from the object alone.
timeout: Seconds to wait for a viewer's session, when session is a request.
plan: What cellucid_apply_session(dry_run = TRUE) returned.

Value

cellucid_apply_session(dry_run = TRUE): a cellucid_apply_plan, a list of session_sha256, tracker, branch and step (the ids chosen), requires (the obs columns and genes the step's state uses: obs, var) and rows, a data frame of one row per change, in domain order: kind ("column-renamed", "categories-renamed", "categories-merged", "field-deleted", "user-field", "gene-set", "highlight", "presentation"), domain, name (the column, category or gene set it writes), column (the column a category is in), from (a list column: the old name or category), cells (the cells it labels), status ("write"; "unchanged": the object holds it already; "replace": an earlier apply's, with overwrite = TRUE; "not-applied") and note (why, in a sentence). Printing it shows the rows.

cellucid_apply_plan(), and cellucid_apply_session(dry_run = FALSE): the object with the plan written – its labels renamed in place, each user-defined field and highlight group a column of its cell metadata (Seurat meta.data; colData), its gene sets in cellucid$gene_sets (origin "session") and as columns of the feature metadata the data mapping reads (see Details) – and a record of the apply appended to cellucid$history_applied (Seurat misc$cellucid; metadata(x)$cellucid). Its attribute "cellucid_apply_report" is list(plan, applied, provenance): applied is FALSE when nothing was written (applying the same step again), and provenance the record. R copies on change: the object passed in is not changed. A plan whose object changed since it was made is refused: make it again.

cellucid_history_applied(): every apply recorded on the object, oldest first, each a list: session_sha256, tracker, branch, step, applied_at, cellucid_version, package ("r"), columns (the columns it wrote), renamed (each rename it applied: kind, column, from, to), skipped (each change not applied: kind, name, note) and session (the file, base64, with keep_session = TRUE). cellucid-python's uns['cellucid']['history_applied'] holds the same records. A record holds no source (where the viewer opened the dataset, which may be a private link); with keep_session = TRUE it keeps the whole file, its source included unless the file was shared without one.

Details

Only what the chosen step needs is checked, before anything is written: the dataset (its cell count, its id when the object's cellucid record names one, the data mapping the session was saved with and its gene count, and the cells' order when the object has the embedding the session names: a cell-order digest of its stored values), the obs columns and genes the step's state uses, and every value of the state against the keys this version reads (a value it does not understand is refused, never applied in part).

Applying the same step again changes nothing and says so (every row "unchanged" or "not-applied"). A column the person made is never replaced: its row says so and the rest applies. Presentation (filters, colours, views, the camera, analyses) is reported, one row per domain that differs from the tracker's opening, never applied. A session shared as its steps only (without the values they leave behind) cannot be applied.

A highlight group's column is cellucid_highlight__<page>__<group>, from the page's name and the group's label (each run of characters other than letters and digits one underscore); a user-defined field's is its name. A step's state knows the cells the viewer had open then: a cell outside them is NA in a highlight column and in a field's, never "not selected".

A gene set written or replaced is also a TRUE/FALSE column of the feature metadata of the genes the session's data mapping reads: the modality it reads (a Seurat assay's meta.features, or an Assay5's meta.data; rowData of the main experiment, or of altExp(x, name) when the mapping reads that alternative experiment). The column is cellucid_gene_set__<name> (the highlight columns' rule; gene_set when nothing of the name is left; _2, _3 on clashes among the step's gene sets, named in their order), TRUE on each feature whose gene name, as the mapping names genes, the set lists; genes the object does not have are left out, with a warning. A new column is added after the existing ones, and an earlier apply's ("replace") is replaced in place; a column of that name beside a gene set no apply wrote is the object's own and is never replaced (a warning says so). A mapping that reads no expression matrix has no features to mark: the gene sets stay in cellucid$gene_sets only (a warning says so). A gene set the step no longer holds has no row: its record and its column stay. These columns are not rows of the plan, and columns in the apply's record lists cell-metadata columns only.

obs['cellucid_original_position'] (a Cellucid-ready store's record of each cell's original position in priority order) is never written, renamed or replaced: a plan that would is refused before anything is written, a dry run included.

Examples

path <- system.file("extdata", "history_golden.cellucid-session", package = "cellucid")
session <- cellucid_read_session(path)
cellucid_steps(cellucid_tracker(session))[, c("id", "branch", "label")]
#>     id branch                                                         label
#> 1   s0     b0                                                        Opened
#> 2   s1     b0                            Renamed NK cell to NK in cell_type
#> 3   s2     b0               Highlighted 40 cells as "Doublets" on page "QC"
#> 4   s3     b0                             Added the continuous column score
#> 5   s4     b0                                              Ran Marker genes
#> 6   s5     b0                    Kept the gene set T cell markers (2 genes)
#> 7   s6     b0                                         Coloured by gene CD3E
#> 8   s7     b1                                     Renamed leiden to cluster
#> 9   s8     b1 Highlighted "T cell" of cell_type (250 cells) on page "Types"
#> 10  s9     b2                                   Renamed 0 to Zero in leiden
#> 11 s10     b3                                    Moved the camera of View 1
#> 12 s12     b0                             Hid highlight "Gate" on page "QC"
#> 13 s13     b0                        Merged B cell into T cell in cell_type
#> 14 s14     b3                                While paused: Colors, Settings
#> 15 s16     b3                          Merged 2 steps: Active field, Camera
#> 16 s17     b3                                    Moved the camera of View 1
#> 17 s18     b4                                         Coloured by gene NKG7
if (FALSE) { # \dontrun{
# The object the session was saved on:
plan <- cellucid_apply_session(sce, session)
plan
sce <- cellucid_apply_plan(plan)
# A bookmarked step, or a branch's last step:
sce <- cellucid_apply_session(sce, session, step = "s5", dry_run = FALSE)
sce <- cellucid_apply_session(sce, session, branch = "Without score", dry_run = FALSE)
cellucid_history_applied(sce)

# From the viewer:
request <- cellucid_request_session(v)
sce <- cellucid_apply_session(sce, request, dry_run = FALSE)
} # }