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

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

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

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 arguments to passed to read.neuron methods

Value

neuronlist object containing the neurons

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 function then this will be applied to the path of each input file. The default value of basename=NULL results in each neuron being named for the input file from which it was read after trimming the file extension. This should match the NeuronName field of each individual neuron.

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.

See also

read.neuron, write.neurons, fileformats

Other neuronlist: *.neuronlist(), is.neuronlist(), neuronlist-dataframe-methods, neuronlistfh(), neuronlistz(), neuronlist(), nlapply(), write.neurons()

Examples

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(read_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
nclear3d()
plot3d(vdnl, grepl("P[1-6].app", Lineage))
}