Read neuron(s) from CATMAID server into NeuroAnatomy Toolbox (nat) format

Source: R/catmaid_nat.R

read.neuron.catmaid reads a single neuron, while read.neurons.catmaid generates a neuronlist object including some metadata information.

read.neuron.catmaid(skid, pid = 1L, conn = NULL, ...)

read.neurons.catmaid(
  skids,
  pid = 1L,
  conn = NULL,
  OmitFailures = NA,
  df = NULL,
  fetch.annotations = FALSE,
  ...
)

Arguments

skid

A numeric skeleton id

pid

Project id (default 1)

conn

A catmaid_connection objection returned by catmaid_login. If NULL (the default) a new connection object will be generated using the values of the catmaid.* package options as described in the help for catmaid_login.

...

Additional arguments passed to the catmaid_fetch function

skids

One or more numeric skeleton ids or a character vector defining a query (see catmaid_skids or examples for the syntax).

OmitFailures

Whether to omit neurons for which FUN gives an error. The default value (NA) will result in nlapply stopping with an error message the moment there is an error. For other values, see details.

df

Optional data frame containing information about each neuron

fetch.annotations

Whether or not to fetch the annotations for each skeleton (default FALSE)

Value

a neuron or neuronlist object containing one or more neurons. These neurons will have an additional class catmaidneuron which provides for some extra functionality in certain methods.

Details

These functions provide a bridge between CATMAID and the neuronanatomy toolbox R package (https://github.com/natverse/nat), which provides extensive functionality for analysing and plotting neurons within the context of template brains.

Note that the soma is set by inspecting CATMAID tags that (case-insensitively) match the regex "(cell body|soma)". Where >1 tag exists, the one that tags an endpoint is preferred. When a soma is identified via a CATMAID tag in this way, the Label column for the single node identified as the soma is set to 1, the standard SWC code. Other nodes will have Label=0 i.e. undefined.

When OmitFailures is not NA, FUN will be wrapped in a call to try to ensure that failure for any single neuron does not abort the nlapply call. When OmitFailures=TRUE the resultant neuronlist will be subsetted down to return values for which FUN evaluated successfully. When OmitFailures=FALSE, "try-error" objects will be left in place. In either of the last 2 cases error messages will not be printed because the call is wrapped as try(expr, silent=TRUE).

The optional dataframe (df) detailing each neuron should have rownames that match the names of each neuron. It would also make sense if the same key was present in a column of the data frame. If the dataframe contains more rows than neurons, the superfluous rows are dropped with a warning. If the dataframe is missing rows for some neurons an error is generated. If SortOnUpdate=TRUE then updating an existing neuronlist should result in a new neuronlist with ordering identical to reading all neurons from scratch.

When fetch.annotations=TRUE then a second data.frame containing the annotations for each neurons as returned by catmaid_get_annotations_for_skeletons will be attached as the attribute anndf (see examples).

See also

plot3d.catmaidneuron, read.neuron, connectors to extract connector information from a catmaid.neuron

catmaid_skids, catmaid_get_annotations_for_skeletons

Examples

if (FALSE) {
library(nat)
nl=read.neurons.catmaid(c(10418394,4453485))
plot3d(nl)

nl=read.neurons.catmaid(c(10418394,4453485), fetch.annotations=TRUE)
# look at those annotations
head(attr(nl, 'anndf'))

## Full worked example looking at Olfactory Receptor Neurons
# read in ORNs (using exact match to ORN annotation)
# note that use a progress bar drop any failures
orns=read.neurons.catmaid("ORN", OmitFailures = T, .progress='text')

# Add two extra columns to the attached data.frame
# for the Odorant receptor genes and the side of brain
orns[,'side']=factor(ifelse(grepl("left", orns[,'name']), "L", "R"))
orns[,'Or']= factor(sub(" ORN.*", "", orns[,'name']))

# check what we have
# see ?head.neuronlist and ?with.neuronlist for details of how this works
head(orns)
with(orns, ftable(side~Or))

# now some plots
open3d()
# colour by side of brain
plot3d(orns, col=side)
clear3d()
# colour by Odorant Receptor
# note similar position of axon terminals for same ORN class on left and right
plot3d(orns, col=Or)

## Additional example using Olfactory Projection Neurons
pns=read.neurons.catmaid("annotation:ORN PNs$", .progress='text')
pns[,'side']=factor(ifelse(grepl("left", pns[,'name']), "L", "R"))
pns[,'Or']= factor(sub(" PN.*", "", pns[,'name']))

# check that we have the same levels for the Odorant Receptor (Or) factor
# for ORNs and PNs
stopifnot(levels(pns[,'Or'])==levels(orns[,'Or']))

# Ok, let's plot the PNs - they will be in matching colours
plot3d(pns, col=Or)

}