Search for body IDs based on a given name

Source: R/name.R

neuprint_search searches for bodyids corresponding to a given name. By default performs regex sensitive matches against neuron names and returns a data.frame.

neuprint_ids provides for flexible search / specification of neuprint body ids. Use it at the start of any function that accepts body ids. Queries are by default partial and fixed (i.e. non-regex) against type. Returns a character vector of bodyids.

neuprint_search(
  search,
  field = "name",
  fixed = FALSE,
  exact = NULL,
  meta = TRUE,
  all_segments = FALSE,
  dataset = NULL,
  conn = NULL,
  ...
)

neuprint_ids(
  x,
  mustWork = TRUE,
  unique = TRUE,
  fixed = TRUE,
  conn = NULL,
  dataset = NULL,
  ...
)

Arguments

search

Search query, by default a regular expression that must match the whole of the neuPrint instance name field. See examples and the field, fixed and exact for how this can be modified.

field

the meta data field in which you want a match for your search query. Defaults to name (or instance, as handled by neuprintr:::neuprint_name_field). Other common options include type, status, cellBodyFiber etc.

fixed

if FALSE (the default), search is interpreted as a regular expression (i.e. "Advanced input" in neuPrint Explorer). If TRUE, the string search is interpreted as a simple character string to be matched (the default search behavior in neuPrint explorer). In this case partial matches are fine.

exact

Whether the query must match the whole field. This is always true for regular expression queries while the default (NULL) implies false for fixed queries.

meta

if TRUE, meta data for found bodyids is also pulled

all_segments

if TRUE, all bodies are considered, if FALSE, only 'Neurons', i.e. bodies with a status roughly traced status.

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.

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.

...

Additional arguments passed to neuprint_search

x

A set of bodyids or a query

mustWork

Whether to insist that at least one valid id is returned (default TRUE)

unique

Whether to ensure that only unique ids are returned (default TRUE)

Value

a vector of body ids, or a data frame with their meta information

For neuprint_ids, a character vector of bodyids (of length 0 when there are none and mustWork=FALSE).

Standard query syntax

It is probably best just to look at the examples, but the query syntax is as follows where square brackets denote optional parts:

[!/][<field>:]<query>

Starting with the optional leading character. An exclamation mark denotes an exact, fixed search. The / denotes a regular expression (exact) search. When both are missing, a partial, fixed search is carried out.

The optional field argument terminated by a colon defines a field other than the default one to use for the query.

Finally the query itself is a plain text (fixed) or regular expression query.

Extended query syntax

As a stepping stone to writing full CYPHER queries against Neo4J you can used the special where keyword to introduce your queries:

where:<cypher query>

e.g.

"where:exists(n.somaLocation) AND n.post>30000 AND NOT n.cropped"

Note that properties of individual nodes (i.e. neurons) must be prefixed with n. as would be typical in a CYPHER query. This feature is still experimental and details of the interface may still change. If you have feedback please do so at https://github.com/natverse/neuprintr/pull/153.

Examples

# \donttest{
neuprint_search(".*DA2.*")
#>       bodyid pre post status    statusLabel cropped    voxels              name
#> 1 1796817841 392  512 Traced Roughly traced   FALSE 723036360 mPN1_DA2(AVM02)_R
#> 2 1827516355 391  548 Traced Roughly traced   FALSE 737014743 mPN1_DA2(AVM02)_R
#> 3  818983130 408  562 Traced Roughly traced   FALSE 606338969 mPN1_DA2(AVM02)_R
#> 4 1797505019 339  479 Traced Roughly traced   FALSE 445320106 mPN1_DA2(AVM02)_R
#> 5 1796818119 510  818 Traced Roughly traced   FALSE 907369420 mPN1_DA2(AVM02)_R
#>      type cellBodyFiber  soma
#> 1 DA2 lPN           A12  TRUE
#> 2 DA2 lPN           A12  TRUE
#> 3 DA2 lPN           A12 FALSE
#> 4 DA2 lPN           A12 FALSE
#> 5 DA2 lPN           A12  TRUE
neuprint_search(".*DA2.*", meta=FALSE)
#> [1] 1796817841 1827516355  818983130 1797505019 1796818119

# Search the type field
neuprint_search("MBON.*", field = "type", meta=FALSE)
#>  [1]  612371421  673509195  424789697 5813022341  612738462  487925037
#>  [7]  487925063  613079053  799586652 1386512867 5813061512  422725634
#> [13]  733036127 1234386037  611477605  920470959 1016835041 1048215779
#> [19] 1078693835  672352543  581678043  613719036  673085197  706840303
#> [25]  768555687 5812982924  517518166  424767514  861665641  704466265
#> [31] 1139667240  394225044  300972942 5813068729 5813067721  642664141
#> [37]  673702721  673366098  457196643 5812981264 5812981543 5813020828
#> [43]  457196444  610463953  517854468  423774471  792368888 5813022896
#> [49] 5813042659  423382015  487143497  550081497  612742248  612422902
#> [55] 5813075634  895441451 5813117385 5813061538 5813021291 5813075020
#> [61] 5813052909 5813058048 5813022234  894020730  706948318  642732835
#> [67]  643847447  547552266 5813033000 1173814525
neuprint_search("MBON[0-9]+", field = "type", meta=FALSE)
#>  [1]  612371421  673509195  424789697 5813022341  612738462  487925037
#>  [7]  487925063  613079053  799586652 1386512867 5813061512  422725634
#> [13]  733036127 1234386037  611477605  920470959 1016835041 1048215779
#> [19] 1078693835  672352543  581678043  613719036  673085197  706840303
#> [25]  768555687 5812982924  517518166  424767514  861665641  704466265
#> [31] 1139667240  394225044  300972942 5813068729 5813067721  642664141
#> [37]  673702721  673366098 5812981264 5813020828  457196444  610463953
#> [43]  517854468  423774471  792368888 5813022896 5813042659  423382015
#> [49]  487143497  550081497  612742248  612422902 5813075634  895441451
#> [55] 5813117385 5813061538 5813021291 5813075020 5813052909 5813058048
#> [61] 5813022234  894020730  706948318  642732835  643847447  547552266
#> [67] 5813033000 1173814525

# compact specification of field
neuprint_search("type:MBON[0-9]+", meta=FALSE)
#>  [1]  612371421  673509195  424789697 5813022341  612738462  487925037
#>  [7]  487925063  613079053  799586652 1386512867 5813061512  422725634
#> [13]  733036127 1234386037  611477605  920470959 1016835041 1048215779
#> [19] 1078693835  672352543  581678043  613719036  673085197  706840303
#> [25]  768555687 5812982924  517518166  424767514  861665641  704466265
#> [31] 1139667240  394225044  300972942 5813068729 5813067721  642664141
#> [37]  673702721  673366098 5812981264 5813020828  457196444  610463953
#> [43]  517854468  423774471  792368888 5813022896 5813042659  423382015
#> [49]  487143497  550081497  612742248  612422902 5813075634  895441451
#> [55] 5813117385 5813061538 5813021291 5813075020 5813052909 5813058048
#> [61] 5813022234  894020730  706948318  642732835  643847447  547552266
#> [67] 5813033000 1173814525

# starts with MBON
neuprint_search("type:MBON.*", meta=FALSE)
#>  [1]  612371421  673509195  424789697 5813022341  612738462  487925037
#>  [7]  487925063  613079053  799586652 1386512867 5813061512  422725634
#> [13]  733036127 1234386037  611477605  920470959 1016835041 1048215779
#> [19] 1078693835  672352543  581678043  613719036  673085197  706840303
#> [25]  768555687 5812982924  517518166  424767514  861665641  704466265
#> [31] 1139667240  394225044  300972942 5813068729 5813067721  642664141
#> [37]  673702721  673366098  457196643 5812981264 5812981543 5813020828
#> [43]  457196444  610463953  517854468  423774471  792368888 5813022896
#> [49] 5813042659  423382015  487143497  550081497  612742248  612422902
#> [55] 5813075634  895441451 5813117385 5813061538 5813021291 5813075020
#> [61] 5813052909 5813058048 5813022234  894020730  706948318  642732835
#> [67]  643847447  547552266 5813033000 1173814525

# full access to WHERE cypher queries over nodes (i.e. neurons) in neo4j
# NB fields must be prefixed with n. to indicate that they are node properties.
# note also that exists(n.somaLocation) is cypher to ensure soma==TRUE
neuprint_search("where:exists(n.somaLocation) AND n.post>30000 AND NOT n.cropped")
#>       bodyid   pre   post status    statusLabel cropped      voxels
#> 1  612371421  2208  32516 Traced         Traced   FALSE  6798484776
#> 2 5813105172 17628  77269 Traced Roughly traced   FALSE 15150336407
#> 3  425790257 16060 126513 Traced Roughly traced   FALSE 23074962804
#>                      name   type cellBodyFiber soma
#> 1 MBON01(y5B'2a)(ADM07)_R MBON01         aSMPB TRUE
#> 2                   DPM_R    DPM          <NA> TRUE
#> 3                   APL_R    APL          <NA> TRUE
# }

if (FALSE) {
neuprint_search("MBON.*", field = "type")

# fixed=TRUE can be useful when you don't want to worry about special
# characters like brackets
neuprint_search("PEN_a(PEN1)", field="type", fixed=TRUE)
# by default fixed=TRUE returns partial matches
neuprint_search("MBON16", field = "type", fixed=TRUE)
# here the type must exactly match the query i.e. complete match
neuprint_search("MBON16", field = "type", fixed=TRUE, exact = TRUE)

neuprint_search("AVF1", field = "cellBodyFiber")
neuprint_search("cellBodyFiber:AVF1")
}
# \donttest{
# exact match against whole type
neuprint_ids("!MBON01")
#> [1] "612371421" "673509195"
# partial match
neuprint_ids("MBON01")
#> [1] "612371421" "673509195"
# partial match against name field rather than type
neuprint_ids("name:MBON01")
#> [1] "673509195" "612371421"

# initial / indicates to use regex search (which must be exact)
neuprint_ids("/MBON01")
#> [1] "612371421" "673509195"
# more interesting regex search
neuprint_ids("/MBON0[1-4]")
#> [1] "612371421"  "673509195"  "424789697"  "5813022341" "612738462" 
#> [6] "487925037"  "487925063"  "613079053" 

# partial regex search against the name field (note leading/trailing .*)
neuprint_ids("/name:.*MBON0[1-4].*")
#> [1] "673509195"  "612371421"  "5813022341" "424789697"  "612738462" 
#> [6] "487925037"  "613079053"  "487925063" 
# }