Vote on a suggested label

Vote a suggested label of a category up or down (none takes the person's vote back) and publish that vote alone: the person's own file in the community annotation repository is written as published now plus this vote (a pull request when they cannot write to the repository), which others see on their next Pull. Nothing else of the person's is published, and a vote that changes nothing publishes nothing. 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_vote(viewer, field, category, suggestion, vote)

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.

suggestion

The suggestion, by its id or its label (annotation_suggestions); suggestions with the same label are one suggestion. Text (at least 1 character). Required.

vote

up, down, or none to take the person's vote back. One of "up", "down", "none". Required.

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 down (Its downvotes now), not_published (The person's other changes still not published (null when not known)), published (Where the vote went: written to the repository, in a pull request its authors merge, or nowhere (it was already so)), pull_request (The pull request, when it went to one), repository (The GitHub repository of the community annotation), suggestion (The label voted on), up (Its upvotes now), vote (The person's vote on it now).

Details

The viewer's action annotation.vote (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_vote(viewer, category = "T cells",
      field = list(key = "cell_type", source = "obs"),
      suggestion = "CD4+ T cell", vote = "up")
  print(request)
  # cellucid_action_result(request) waits for its outcome.
  cellucid_stop(viewer)
}