neuprint_connection_table: Get the upstream and downstream connectivity of a neuron

In natverse/neuprintr: R Client Utilities for Interacting with the neuPrint Connectome Analysis Service

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

Usage

neuprint_connection_table(
  bodyids,
  partners = c("inputs", "outputs"),
  prepost = c("PRE", "POST"),
  roi = NULL,
  by.roi = FALSE,
  threshold = 1L,
  summary = FALSE,
  details = FALSE,
  superLevel = FALSE,
  progress = FALSE,
  dataset = NULL,
  chunk = TRUE,
  all_segments = FALSE,
  conn = NULL,
  ...
)

Arguments

bodyids	the body IDs for neurons/segments (bodies) you wish to query. This can be in any form understood by neuprint_ids.
partners	inputs looks for upstream inputs (presynaptic) whereas outputs looks for downstream outputs (postsynaptic) to the given bodyids.
prepost	PRE: look for partners presynaptic (i.e upstream inputs) or POST: postsynaptic (downstream outputs) to the given bodyids. NB this is redundant to the partners argument and you should only use one.
roi	a single ROI. Use neuprint_ROIs to see what is available.
by.roi	logical, whether or not to break neurons' connectivity down by region of interest (ROI)
threshold	Only return partners >= to an integer value. Default of 1 returns all partners. This threshold will be applied to the ROI weight when the roi argument is specified, otherwise to the whole neuron.
summary	When TRUE and more than one query neuron is given, summarises connectivity grouped by partner.
details	When TRUE returns adds a name and type column for partners. Alternatively a character vector of column names can be provided (but see details for details about details). Default details=FALSE.
superLevel	When by.roi=TRUE, should we look at low-level ROIs (superLevel=FALSE) or only super-level ROIs (superLevel=TRUE). A super-level ROIs can contain multiple lower-level ROIs. If set to 'NULL', both are returned.
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 bodyid, that bodyid is ignored
dataset	optional, a dataset you want to query. If NULL, the default specified by your R environ file is used or, failing that the current connection, is used. See neuprint_login for details.
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 chunk=TRUE).
all_segments	if TRUE, all bodies are considered, if FALSE, only 'Neurons', i.e. bodies with a status roughly traced status.
conn	optional, a neuprintr connection object, which also specifies the neuPrint server. If NULL, the defaults set in your .Rprofile or .Renviron are used. See neuprint_login for details.
...	methods passed to neuprint_login

Details

Note that by default neuprint_connection_table only returns upstream or downstream connections with objects that were large enough to be designated as "Neurons". Smaller objects (Segments) can be included when all_segments=TRUE. When this is done then the total counts will match what is reported by neuprint_get_meta.

The user must ensure that any columns named in the details argument are correct (non-existent columns will be filled with NA). For historical reasons the column displayed by neuprintr as name must be referred to as instance in this argument (but will be renamed to name). File an issue if this bothers you and I will try to do something smarter.

Value

a data frame with one row for each unique combination of query neuron, partner neuron and (where specified) ROI.

• bodyid query neuron identifier

• partner neuron identifier

• prepost 0 for upstream/input partners; 1 for downstream/output partners.

• weight total number of connections between the query and partner neuron.

. When by.roi=TRUE

• roi the name of the ROI

• ROIweight the number of connections within that ROI

Note that when by.roi=TRUE there may be multiple rows for each unique pair of neurons and connections may appear in more than one row when some ROIs are contained within larger ROIs. For example the CA(R) is contained within the MB(R) ROI. Therefore you cannot sum the ROIweight to match the total connection strength (which is available as the weight column).

See Also

neuprint_fetch_custom, neuprint_simple_connectivity, neuprint_common_connectivity, neuprint_ROIs

Examples

## Unitary connection strengths between two chosen neurons,
## and their downstream targets
c1 = neuprint_connection_table(c(818983130, 1796818119), prepost = "POST")
head(c1)

# query of regex against cell type
# summarised per partner with additional details column
c1s = neuprint_connection_table("/DA2.*lPN", partners='out', summary=TRUE, details=TRUE)
head(c1s)
# Kenyon cells typically receive fewer multiple inputs than other partners
table(n=c1s$n, KC=grepl("^KC", c1s$type))

## The same connections broken down by ROI
c2 = neuprint_connection_table(c(818983130, 1796818119), prepost = "POST",
                               by.roi = TRUE)
head(c2)

## 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 only the connections within a specific ROI
c4 = neuprint_connection_table(c(818983130, 1796818119), prepost = "POST",
                               by.roi = TRUE, roi = "LH(R)")




# compare pre/post/upstream/downstream when all_segments=TRUE or FALSE
neuprint_get_meta('/DP1m.*vPN')
sum(neuprint_connection_table('/DP1m.*vPN', partners = 'in')$weight)
sum(neuprint_connection_table('/DP1m.*vPN', partners = 'in', all_segments = TRUE)$weight)
sum(neuprint_connection_table('/DP1m.*vPN', partners = 'out')$weight)
sum(neuprint_connection_table('/DP1m.*vPN', partners = 'out', all_segments = TRUE)$weight)

natverse/neuprintr documentation built on Sept. 15, 2023, 6:59 a.m.