Clarify documentation re prepost

* Partly in response to @IsabelDAlessandro in #63
* also a few other small doc fixes while I was at it

R/connectivity.R

@@ -93,46 +93,79 @@ neuprint_get_adjacency_matrix <- function(bodyids=NULL, inputids=NULL,
 
 #' @title Get the upstream and downstream connectivity of a neuron
 #'
-#' @description Get the upstream and downstream connectivity of a body, restricted to within an ROI if specified
+#' @description Get the upstream and downstream connectivity of a body,
+#'   restricted to within an ROI if specified
 #' @inheritParams neuprint_read_neurons
 #' @inheritParams neuprint_find_neurons
-#' @param prepost whether to look for partners presynaptic to postsynaptic
-#' to the given bodyids
+#' @param prepost \code{PRE}: look for partners presynaptic (i.e upstream
+#'   inputs) or \code{POST}: postsynaptic (downstream outputs) to the given
+#'   \code{bodyids}
 #' @param by.roi logical, whether or not to break neurons' connectivity down by
-#'  region of interest (ROI)
-#' @param superLevel When `by.roi` is `TRUE`, should we look at low-level ROIs
-#'  (`FALSE`) or super-level ROIs (`TRUE`). A super-level ROIs can
-#'  contain multiple
-#'  lower-level ROIs. If set to `NULL`, both are returned.
+#'   region of interest (ROI)
+#' @param superLevel When \code{by.roi=TRUE}, should we look at low-level ROIs
+#'   (\code{superLevel=FALSE}) or only super-level ROIs
+#'   (\code{superLevel=TRUE}). A super-level ROIs can contain multiple
+#'   lower-level ROIs. If set to `NULL`, both are returned.
 #' @param chunk A logical specifying whether to split the query into multiple
-#'   chunks or an integer specifying the size of those chunks (which defaults
-#'   to 20 when \code{chunk=TRUE}).
-#' @param progress default FALSE. If TRUE, the API is called separately for
-#' each neuron and you can assess its progress, if an error is thrown by any
-#' one \code{bodyid}, that \code{bodyid} is ignored
-#' @return a data frame giving partners within a set of ROIs, the connection
-#' strength for weights to or from that partner, and the direction, for the
-#' given bodyid
+#'   chunks or an integer specifying the size of those chunks (which defaults to
+#'   20 when \code{chunk=TRUE}).
+#' @param progress default FALSE. If TRUE, the API is called separately for each
+#'   neuron and you can assess its progress, if an error is thrown by any one
+#'   \code{bodyid}, that \code{bodyid} is ignored
+#' @return a data frame with one row for each unique combination of query
+#'   neuron, partner neuron and (where specified) ROI. \itemize{
+#'
+#'   \item bodyid query neuron identifier
+#'
+#'   \item partner neuron identifier
+#'
+#'   \item prepost 0 for downstream/output partners; 1 for upstream/input
+#'   partners
+#'
+#'   \item weight total number of connections between the query and partner
+#'   neuron.
+#'
+#'   }. When \code{by.roi=TRUE}
+#'
+#'   \itemize{
+#'
+#'   \item roi the name of the ROI
+#'
+#'   \item ROIweight the number of connections within that ROI
+#'
+#'   }
+#'
+#'   Note that when \code{by.roi=TRUE} there may be multiple rows for each
+#'   unique pair of neurons \bold{and} connections may appear in more than one
+#'   row when some ROIs are contained within larger ROIs. For example the
+#'   \code{CA(R)} is contained within the \code{MB(R)} ROI. Therefore you cannot
+#'   sum the \code{ROIweight} to match the total connection strength (which is
+#'   available as the \code{weight} column).
+#'
 #' @seealso \code{\link{neuprint_fetch_custom}},
-#' \code{\link{neuprint_simple_connectivity}},
-#' \code{\link{neuprint_common_connectivity}}, \code{\link{neuprint_ROIs}}
+#'   \code{\link{neuprint_simple_connectivity}},
+#'   \code{\link{neuprint_common_connectivity}}, \code{\link{neuprint_ROIs}}
 #' @export
 #' @rdname neuprint_connection_table
 #' @examples
 #' \donttest{
 #' ## Unitary connection strengths between two chosen neurons,
 #' ## and their downstream targets
 #' c1 = neuprint_connection_table(c(818983130, 1796818119), prepost = "POST")
+#' head(c1)
 #'
-#' ## The same connection strength broken down by ROI
+#' ## The same connections broken down by ROI
 #' c2 = neuprint_connection_table(c(818983130, 1796818119), prepost = "POST",
 #'                                by.roi = TRUE)
+#' head(c2)
 #'
-#' ## The same connection strength broken down by super-level ROI
+#' ## The same connections broken down by super-level ROIs only
 #' c3 = neuprint_connection_table(c(818983130, 1796818119), prepost = "POST",
 #'                                by.roi = TRUE, superLevel = TRUE)
+#' nrow(c3)
+#' nrow(c2)
 #'
-#' ## Find connections in a specific ROI
+#' ## Find only the connections within a specific ROI
 #' c4 = neuprint_connection_table(c(818983130, 1796818119), prepost = "POST",
 #'                                by.roi = TRUE, roi = "LH(R)")
 #'

R/synapses.R

@@ -23,11 +23,18 @@
 #'   fetching process for smaller queries (<100 body ids). The default of
 #'   \code{progress=NULL} will only show a progress bar if the query will be
 #'   split into multiple chunks based on the \code{chunk} argument.
-#' @return a data frame, where each entry is a connection between the specified
-#'   bodyid and its partner, either presynaptic to the bodyid (\code{prepost=0})
-#'   or postsynaptic (\code{prepost=1}). Each connection is associated with a
-#'   synapse that has its own unique connector_id, XYZ coordinates and a
-#'   confidence in its existence.
+#' @return a data frame, where each row is a connection between one query
+#'   \code{bodyid} and a single \code{partner} neuron. The \code{prepost} column
+#'   should be interpreted as follows: \itemize{
+#'
+#'   \item{\code{prepost=0}}{ a downstream or \emph{output} partner,
+#'   postsynaptic to the query neuron}
+#'
+#'   \item{\code{prepost=1}}{ an upstream or \emph{input} partner, presynaptic
+#'   to the query neuron}
+#'
+#'   } Each connection is associated with a synapse that has its own unique
+#'   \code{connector_id}, XYZ coordinates and a confidence in its existence.
 #' @seealso \code{\link{neuprint_fetch_custom}},
 #'   \code{\link{neuprint_simple_connectivity}},
 #'   \code{\link{neuprint_common_connectivity}}