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.

Usage

cellucid_annotation_suggest(viewer, field, category, label, evidence, ontology_id)

Arguments

viewer

A viewer cellucid_view() or cellucid_serve() returned.

field

A categorical column of the cells by name (source "obs"). A named list. Required.

source

Categories belong to columns of the cells. Exactly "obs". Required.

category

A category label as the legend shows it. Text (at least 1 character). Required.

label

The label suggested. Text (at least 1 character). Required.

evidence

Why: the markers or reasoning behind it. Text (at least 1 character). Left out unless given (the viewer then chooses as its own control does).

ontology_id

Its ontology term, when known. Text (at least 1 character). Left out unless given (the viewer then chooses as its own control does).

Value

A cellucid_action_request, at once and invisibly: the action is sent now, or when the viewer's channel opens. cellucid_action_result(request) returns its outcome: a list of id (The suggestion's id (annotation_vote takes it)), label (The label suggested), not_published (The person's other changes still not published (null when not known)), published (Where the suggestion went: written to the repository, or in a pull request its authors merge), pull_request (The pull request, when it went to one), repository (The GitHub repository of the community annotation).

Details

The viewer's action annotation.suggest (Community annotation). 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: it makes no step of the history.

It publishes for others to see, so the viewer asks the person first (publishes), from R too, as when an agent (Claude, ChatGPT) runs it; cellucid_action_result(request) waits for their answer (call it again if its timeout passes first).

See also

cellucid_act() sends any action by its type, and cellucid_action_result() collects its answer.

Examples

if (interactive() && requireNamespace("SeuratObject", quietly = TRUE)) {
  data("pbmc_small", package = "SeuratObject")
  viewer <- cellucid_view(SeuratObject::UpdateSeuratObject(pbmc_small))
  request <- cellucid_annotation_suggest(viewer, category = "T cells",
      field = list(key = "cell_type", source = "obs"),
      label = "CD4+ T cell")
  print(request)
  # cellucid_action_result(request) waits for its outcome.
  cellucid_stop(viewer)
}