neuprint_search: Search for body IDs based on a given name

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

Search for body IDs based on a given name

Description

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.

Usage

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.

See Also

neuprint_get_meta, neuprint_get_neuron_names

Examples

neuprint_search(".*DA2.*")
neuprint_search(".*DA2.*", meta=FALSE)

# Search the type field
neuprint_search("MBON.*", field = "type", meta=FALSE)
neuprint_search("MBON[0-9]+", field = "type", meta=FALSE)

# compact specification of field
neuprint_search("type:MBON[0-9]+", meta=FALSE)

# starts with MBON
neuprint_search("type:MBON.*", meta=FALSE)

# 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")


## Not run: 
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")

## End(Not run)

# exact match against whole type
neuprint_ids("!MBON01")
# partial match
neuprint_ids("MBON01")
# partial match against name field rather than type
neuprint_ids("name:MBON01")

# initial / indicates to use regex search (which must be exact)
neuprint_ids("/MBON01")
# more interesting regex search
neuprint_ids("/MBON0[1-4]")

# partial regex search against the name field (note leading/trailing .*)
neuprint_ids("/name:.*MBON0[1-4].*")

natverse/neuprintr documentation built on July 28, 2024, 11:50 a.m.