R/connectivity.R
neuprint_connection_table.RdGet the upstream and downstream connectivity of a body, restricted to within an ROI if specified
the body IDs for neurons/segments (bodies) you wish to query.
This can be in any form understood by neuprint_ids.
inputs looks for upstream inputs (presynaptic) whereas
outputs looks for downstream outputs (postsynaptic) to the given
bodyids.
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.
a single ROI. Use neuprint_ROIs to see what is available.
logical, whether or not to break neurons' connectivity down by region of interest (ROI)
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.
When TRUE and more than one query neuron is given,
summarises connectivity grouped by partner.
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.
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.
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
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.
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).
if TRUE, all bodies are considered, if FALSE, only 'Neurons', i.e. bodies with a status roughly traced status.
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
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).
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.
# \donttest{
## Unitary connection strengths between two chosen neurons,
## and their downstream targets
c1 = neuprint_connection_table(c(818983130, 1796818119), prepost = "POST")
head(c1)
#> bodyid partner prepost weight
#> 1 1796818119 632402333 1 26
#> 2 818983130 785914742 1 24
#> 3 1796818119 5813080766 1 24
#> 4 818983130 754870859 1 23
#> 5 818983130 798869986 1 23
#> 6 818983130 1143677310 1 23
# 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)
#> # A tibble: 6 × 6
#> partner prepost weight name type n
#> <dbl> <dbl> <int> <chr> <chr> <int>
#> 1 5813055865 1 85 LHAD1f2_R LHAD1f2 5
#> 2 1671608112 1 67 M_ilPNm90_R M_ilPNm90 5
#> 3 573695941 1 66 LHPV4b3_R LHPV4b3 5
#> 4 574377562 1 62 LHAV2d1_R LHAV2d1 5
#> 5 574377845 1 61 LHAV3f1_R LHAV3f1 5
#> 6 5813012083 1 55 LHAV4d1_R LHAV4d1 5
# Kenyon cells typically receive fewer multiple inputs than other partners
table(n=c1s$n, KC=grepl("^KC", c1s$type))
#> KC
#> n FALSE TRUE
#> 1 224 124
#> 2 97 28
#> 3 66 5
#> 4 57 0
#> 5 99 0
## The same connections broken down by ROI
c2 = neuprint_connection_table(c(818983130, 1796818119), prepost = "POST",
by.roi = TRUE)
head(c2)
#> bodyid partner prepost weight ROIweight roi
#> 1 1796818119 632402333 1 26 26 MB(+ACA)(R)
#> 2 1796818119 632402333 1 26 26 MB(R)
#> 3 1796818119 632402333 1 26 26 CA(R)
#> 4 818983130 785914742 1 24 23 MB(+ACA)(R)
#> 5 818983130 785914742 1 24 23 MB(R)
#> 6 818983130 785914742 1 24 1 mALT(R)
## 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)
#> [1] 660
nrow(c2)
#> [1] 1186
## Find only the connections within a specific ROI
c4 = neuprint_connection_table(c(818983130, 1796818119), prepost = "POST",
by.roi = TRUE, roi = "LH(R)")
# }
# \donttest{
# compare pre/post/upstream/downstream when all_segments=TRUE or FALSE
neuprint_get_meta('/DP1m.*vPN')
#> bodyid pre post upstream downstream status statusLabel voxels
#> 1 635048729 180 273 273 1868 Traced Roughly traced 617533058
#> cropped name type cellBodyFiber notes soma
#> 1 FALSE DP1m_vPN_R DP1m_vPN AVM04 <NA> TRUE
sum(neuprint_connection_table('/DP1m.*vPN', partners = 'in')$weight)
#> [1] 252
sum(neuprint_connection_table('/DP1m.*vPN', partners = 'in', all_segments = TRUE)$weight)
#> [1] 273
sum(neuprint_connection_table('/DP1m.*vPN', partners = 'out')$weight)
#> [1] 373
sum(neuprint_connection_table('/DP1m.*vPN', partners = 'out', all_segments = TRUE)$weight)
#> [1] 1868
# }