doc additions/tweaks for manc_set_lrgroup

Author: jefferis

R/dvidtools.R

@@ -99,16 +99,16 @@ manc_set_dvid_instance <- function(bodyid, instance, user=getOption("malevnc.dvi
 
 #' Check if group is complete
 #'
-#' In other words in all neurons from group are represented in \code{body_ids}
-#' vector.
+#' In other words if the \code{body_ids} argument contains all neurons in the
+#' group.
 #'
 #' @param group_id numeric/character with group id
 #' @param body_ids vector with body ids to compare
 #' @param conn Optional, a \code{\link{neuprint_connection}} object, which also
 #'   specifies the neuPrint server. Defaults to \code{\link{manc_neuprint}()} to
 #'   ensure that query is against the VNC dataset.
 #'
-#' @return logical with \code{TRUE} if group is complete
+#' @return logical \code{TRUE} if group is complete, \code{FALSE} otherwise.
 #'
 #' @importFrom glue glue
 manc_check_group_complete <- function(group_id, body_ids,
@@ -123,15 +123,60 @@ manc_check_group_complete <- function(group_id, body_ids,
 
 #' Set LR matching groups for neurons in DVID and optionally Clio
 #'
-#' @param ids A set of ids belonging to the same group
-#' @param dryrun When \code{TRUE}, the default, show what will
-#'   happen rather than applying the annotations.
+#' @details One important process in reviewing and annotating neurons is to
+#'   compare neurons on the left and right side of the malevnc dataset. This can
+#'   identify neurons that need further proof-reading fixes as well as grouping
+#'   neurons that may eventually form agreed cell types. At the time of writing
+#'   (21 Aug 2021) group information is stored in two locations: the DVID
+#'   instance field and the Clio group field. DVID instance information is being
+#'   periodically copied to Clio, but for the time being this is not automated.
+#'   Furthermore it is not trivial to reconcile the two locations if they get
+#'   out of sync. Therefore we have agreed that DVID will remain the master
+#'   source of information for the time being.
+#'
+#'   DVID left-right groupings are stored in the instance field (for the
+#'   hemibrain this was more specific than the type field and typically included
+#'   side of brain information). The convention has been to store the lowest
+#'   body id in a group followed by an underscore and then the side (L or R) or
+#'   a letter U to indicate that the neuron is unpaired (sometimes this is UNP).
+#'   In contrast the Clio group column just contains the lowest bodyid. At this
+#'   point we assume that the selected bodyid will \emph{not} change if neurons
+#'   are added to the group. \code{manc_set_lrgroup} will choose the lowest
+#'   bodyid as the default when setting the group for a set of ids unless a
+#'   specific \code{group} argument is passed.
+#'
+#'   Grouping neurons remains a subjective process: while many cases are
+#'   obvious, there are always edge cases where experts disagree. Therefore it
+#'   is not necessarily productive to spend extensive amounts of discussion once
+#'   a designation has been made. Therefore \code{manc_set_lrgroup} tries to
+#'   avoid overriding previous designations unless the user insists. This
+#'   behaviour can be changed using the \code{Force} or \code{Partial}. As you
+#'   might expect \code{Force=TRUE} just does what you ask regardless of any
+#'   existing annotations. Use this sparingly and with caution.
+#'
+#'   \code{Partial=TRUE} is more nuanced and tries to do the right thing when
+#'   extending a group for which some members already have annotations. The main
+#'   limitation is that you must pass \emph{all} the members of the group in
+#'   your call so that \code{manc_set_lrgroup} knows that you are trying to make
+#'   a compatible annotation.
+#'
+#'   Here are some examples of group annotations: \itemize{
+#'
+#'   \item \code{10000_R}, \code{10000_L} for bodyids \code{10000, 10002} (the
+#'   giant fibers)
+#'
+#'   \item \code{13083_U} an unpaired neuron.
+#'
+#'   }
+#' @param ids A set of body ids belonging to the same group
+#' @param dryrun When \code{TRUE}, the default, show what will happen rather
+#'   than applying the annotations.
 #' @param Force Whether to update DVID instances (and clio group) even when
 #'   there is existing DVID instance information.
-#' @param Partial Assigns only partial annotations to DVID instances
+#' @param Partial Assigns group annotations (via DVID instances) only to neurons
 #'   that do not yet have annotation.
-#' @param group Set a specific group id.
-#' @param clio Whether push to Clio or not.
+#' @param group Set a specific group id rather than accepting the default.
+#' @param clio Whether to set the Clio group field in addition to DVID.
 #'
 #' @export
 #' @examples