aedes_partner_summary(): Aedes-aware wrapper for flywire_partner_summary

NAMESPACE

@@ -9,6 +9,7 @@ export(aedes_key_point)
 export(aedes_meta)
 export(aedes_mirror)
 export(aedes_nm2raw)
+export(aedes_partner_summary)
 export(aedes_point_side)
 export(aedes_raw2nm)
 export(aedes_set_group)

R/partners.R

@@ -1,4 +1,55 @@
-#' @noRd
+#' Summarise the synaptic partners of one or more Aedes neurons
+#'
+#' Tabulates the up- or downstream partners of a set of query neurons at a
+#' chosen CAVE materialisation, returning one row per partner with the number
+#' of connecting synapses. This is a thin Aedes-aware wrapper around
+#' [fafbseg::flywire_partner_summary()]: it resolves the input via
+#' [aedes_ids()], points fafbseg at the Aedes segmentation, and updates root
+#' ids to the requested `version`/`timestamp` before querying.
+#'
+#' @param rootids Query neurons in any form accepted by [aedes_ids()] (root
+#'   ids or a FlyTable query string).
+#' @param partners Whether to summarise `"outputs"` (downstream partners, the
+#'   default) or `"inputs"` (upstream partners).
+#' @param threshold Only return partners connected by more than `threshold`
+#'   synapses (default `0`, i.e. all partners).
+#' @param version,timestamp Optional CAVE materialisation selectors. When
+#'   supplied, query ids are first updated to the corresponding version /
+#'   timestamp with [fafbseg::flywire_latestid()], and the synapse query is
+#'   run against that materialisation. Give at most one of the two.
+#' @param synapse_table CAVE synapse table to query. Defaults to the
+#'   `coconatfly.aedes.synapses` option (`"synapses_v2"`).
+#' @param ... Additional arguments passed on to
+#'   [fafbseg::flywire_partner_summary()]. Power-user options include
+#'   `remove_autapses` (set `FALSE` to keep self-connections; see examples)
+#'   and `cleft.threshold`.
+#'
+#' @return A `data.frame` with one row per partner neuron. `query` holds the
+#'   query neuron root id and `weight` the synapse count; the partner root id
+#'   is in `post_id` when `partners = "outputs"` and `pre_id` when
+#'   `partners = "inputs"`. See [fafbseg::flywire_partner_summary()] for the
+#'   full column description.
+#'
+#' @seealso [fafbseg::flywire_partner_summary()], [aedes_ids()]
+#' @export
+#' @examples
+#' \dontrun{
+#' # downstream partners of a neuron, keeping only strong connections
+#' aedes_partner_summary("720575940...", threshold = 4)
+#'
+#' # inputs instead of outputs
+#' aedes_partner_summary("720575940...", partners = "inputs")
+#'
+#' # Power-user: query a specific CAVE materialisation rather than 'now'
+#' aedes_partner_summary("720575940...", version = 1000)
+#' aedes_partner_summary("720575940...", timestamp = "2024-01-01")
+#'
+#' # Power-user: include autapses (self-connections). MBON11 is strongly
+#' # autaptic, so its own root id appears among its downstream partners when
+#' # remove_autapses = FALSE (the fafbseg default drops these).
+#' mbon11 <- aedes_ids("cell_type:MBON11")
+#' aedes_partner_summary(mbon11, remove_autapses = FALSE)
+#' }
 aedes_partner_summary <- function(rootids,
                                   partners = c("outputs", "inputs"),
                                   threshold = 0,

_pkgdown.yml

@@ -39,6 +39,11 @@ reference:
   - aedes_set_meta
   - aedes_set_group
 
+- title: Connectivity
+  desc: Summarise synaptic partners.
+  contents:
+  - aedes_partner_summary
+
 - title: Low level CAVE access
   contents:
   - aedes_cave_client

tests/testthat/test-partners.R

@@ -0,0 +1,28 @@
+test_that("aedes_partner_summary summarises downstream partners", {
+  # Pin the query neuron by a stable raw coordinate (root ids drift with
+  # proofreading) and resolve it to the *current* root id at test time. This is
+  # the same stable handle used in test-chunkedgraph.R. The partner query then
+  # runs against the latest materialisation (no version pin), since old
+  # materialisation versions expire for synapse queries.
+  pt <- c(24606, 12450, 5798)
+  id <- try(aedes_xyz2id(pt, rawcoords = TRUE), silent = TRUE)
+  skip_if(inherits(id, "try-error") || identical(id, "0"),
+          "Skipping: transform service unavailable")
+
+  ps <- try(aedes_partner_summary(id, partners = "outputs"), silent = TRUE)
+  skip_if(inherits(ps, "try-error") || !is.data.frame(ps),
+          "Skipping: no CAVE synapse access to aedes materialisation")
+
+  skip_if(nrow(ps) == 0L, "Skipping: no downstream partners returned")
+  expect_true(all(c("query", "post_id", "weight") %in% colnames(ps)))
+  # for outputs every row shares the single query neuron as presynaptic partner
+  expect_equal(unique(as.character(ps$query)), as.character(id))
+  expect_true(all(ps$weight > 0))
+
+  # threshold filters on synapse count
+  strong <- try(aedes_partner_summary(id, partners = "outputs", threshold = 4),
+                silent = TRUE)
+  skip_if(inherits(strong, "try-error"), "Skipping: threshold query failed")
+  expect_true(all(strong$weight > 4))
+  expect_lte(nrow(strong), nrow(ps))
+})