read.neurons: Read one or more neurons from file to a neuronlist in memory

Description

Read one or more neurons from file to a neuronlist in memory

Usage

read.neurons(
  paths,
  pattern = NULL,
  neuronnames = basename,
  format = NULL,
  nl = NULL,
  df = NULL,
  OmitFailures = TRUE,
  SortOnUpdate = FALSE,
  ...
)

Value

neuronlist object containing the neurons

Arguments

paths: Paths to neuron input files or a directory containing neurons or a neuronlistfh object, or a zip archive containing multiple neurons.
pattern: If paths is a directory, regex that file names must match.
neuronnames: Character vector or function that specifies neuron names. See details.
format: File format for neuron (see read.neuron)
nl: An existing neuronlist to be updated (see details)
df: Optional data frame containing information about each neuron
OmitFailures: Omit failures (when TRUE) or leave an NA value in the list
SortOnUpdate: When nl!=NULL the resultant neuronlist will be sorted so that neurons are ordered according to the value of the paths argument.
...: Additional arguements to passed to read.neuron methods

Details

This function will cope with the same set of file formats offered by read.neuron.

If the paths argument specifies a (single) directory then all files in that directory will be read unless an optional regex pattern is also specified. Similarly, if paths specifies a zip archive, all neurons within the archive will be loaded.

neuronnames must specify a unique set of names that will be used as the names of the neurons in the resultant neuronlist. If neuronnames is a a function then this will be applied to the path to each neuron. The default value is the function basename which results in each neuron being named for the input file from which it was read.

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 is TRUE then updating an existing neuronlist should result in a new neuronlist with ordering identical to reading all neurons from scratch.

Examples

Run this code

if (FALSE) {
## Read C. elegans neurons from OpenWorm github repository
vds=paste0("VD", 1:13)
vdurls=paste0("https://raw.githubusercontent.com/openworm/CElegansNeuroML/",
  "103d500e066125688aa7ac5eac7e9b2bb4490561/CElegans/generatedNeuroML/",vds,
  ".morph.xml")
vdnl=read.neurons(vdurls, neuronnames=vds)
plot3d(vdnl)

## The same, but this time add some metadata to neuronlist
# fetch table of worm neurons from wormbase
library(rvest)
nlurl="http://wormatlas.org/neurons/Individual%20Neurons/Neuronframeset.html"
wormneurons = html_table(html(nlurl), fill=TRUE)[[4]]
vddf=subset(wormneurons, Neuron%in%vds)
rownames(vddf)=vddf$Neuron
# attach metadata to neuronlist
vdnl=read.neurons(vdurls, neuronnames=vds, df=vddf)
# use metadata to plot a subset of neurons
clear3d()
plot3d(vdnl, grepl("P[1-6].app", Lineage))
}