Get the upstream and downstream connectivity of a body, restricted to within an ROI if specified

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.

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

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).

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.

Examples

# \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 1143677310       1     23
#> 5  818983130 5813055865       1     23
#> 6  818983130  798869986       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     82 ADL02oo_pct(ADL02)_R ADL02oo_pct                   5
#> 2 1671608112       1     67 mPNX_R               olfactory multi C PN mALT     5
#> 3  573695941       1     66 PDL16j_pct(PDL16)_R  PDL16j_pct                    5
#> 4  574377845       1     60 ADL24t_pct(ADL24)_R  ADL24t_pct                    5
#> 5  574377562       1     56 ADL24f_pct(ADL24)_R  ADL24f_pct                    5
#> 6  917842566       1     54 PDL09c_pct(PDL09)_R  PDL09c_pct                    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   231  125
#>   2    89   28
#>   3    58    5
#>   4    58    0
#>   5    95    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] 641
nrow(c2)
#> [1] 854

## 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 status    statusLabel cropped    voxels
#> 1 635048729 180  273 Traced Roughly traced   FALSE 615424679
#>                  name     type cellBodyFiber soma
#> 1 mlPN2_DP1m(AVM04)_R DP1m vPN           A14 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] 335
sum(neuprint_connection_table('/DP1m.*vPN', partners = 'out', all_segments = TRUE)$weight)
#> [1] 1871
# }