nat-package: Analyse 3D biological image data especially neurons

Description

nat provides tools to read, analyse, plot, transform and convert neuroanatomical data, especially representations of neurons.

Arguments

Neuron Objects

At present there are 2 main representations of neuronal data:

neuron: objects contain one or more connected trees that make up a neuron
dotprops: objects can contain one (or more) neurons represented as points and tangent vectors in which the connectivity information has been discarded

The subset function has both subset.neuron and subset.dotprops methods, which can be used to keep (or reject) specified vertices within a neuron e.g. by spatial constraints. subset.neuron will look after the tree structure of neurons in these circumstances.

neuron objects containing connected trees can be converted to ngraph objects, a lightweight wrapper around the igraph library's graph class that preserves 3D coordinate information. This allows neurons to be manipulated based on their graph structure, e.g. by finding all nodes upstream (closer to the root) or downstream of a given node. The as.neuron function can convert ngraph objects back to neurons or selected vertex indices can be used to subset a neuron with subset.neuron.

Collections of Neurons

Neurons can be collected as neuronlist objects, which contain multiple neuron or dotprops objects along with an attached dataframe of metadata. The metadata can be accessed and manipulated using the myneuronlist[i,j] notation (see neuronlist-dataframe-methods).

Neurons can be read in to a neuronlist using read.neurons or written out using write.neurons with support for many of the most common formats including swc.

Metadata can be used to colour or subset the neurons during plotting (see plot3d.neuronlist and subset.neuronlist). Interactive 3D selection of neurons in a neuronlist is also possible using find.neuron (which makes use of rgl's select3d function.

neuronlist objects also provide additional functionality to streamline arithmetic (e.g. scaling all the points in all neurons see *.neuronlist) and transformations (see Transformations section below and xform). Arbitrary functions can be applied to each individual neuron can be applied using the nlapply function, which also provides options for progress bars and simple parallelisation.

Transformations

neuron or dotprops objects can be transformed from e.g. sample to template brain space using affine or non-rigid registrations, typically calculated with the open source CMTK package available at https://www.nitrc.org/projects/cmtk/, see ?cmtk for installation details. The function xform has methods to deal with a variety of types of interest.

3D Image Data

In addition to data types defined by unstructured collections of 3D vertices such as neuron, dotprops and hxsurf objects nat provides the im3d class to handle image/density data on a regular grid. I/O is handled by read.im3d and write.im3d, which are currently implemented for the amiramesh and nrrd file formats; there is also read only access to the vaa3d raw format.

Spatial information can be queried with voxdims, boundingbox and ijkpos, xyzpos methods. You can convert between voxel data and coordinate (vertex) -based representations using the following functions:

as.im3d The as.im3d.matrix method converts XYZ coordinates to an im3d image volume
ind2coord Find XYZ coordinates of specified voxels of an im3d image volume
dotprops The dotprops.im3d method converts an im3d object to a dotprops format neuron, i.e. a cloud of unconnected segments.

Surface Data

nat can read, write, transform and subset surface (mesh) objects defined by Amira's HxSurface class. See read.hxsurf and links therein. In addition hxsurf objects can be converted to the mesh3d format, which provides a link to the rgl package and also to packages for morphometrics and sophisticated mesh manipulation such as Morpho and Rvcg.

rgl Package

nat uses the rgl package extensively for 3D visualisation. rgl's core function is to provide interactive visualisation (usually in an X11 window depending on OpenGL - and therefore on a graphics card or OpenGL software emulator) but recently significant functionality for static snapshots and embedding results in reports such as web pages has been added. With this in mind, Duncan Murdoch has added the rgl.useNULL option. As of nat 1.8.0, options(rgl.useNULL=TRUE) will be set before nat is loaded in non-interactive R sessions. If you want to use nat in interactive environments where X11 is not available, you may want to set options(rgl.useNULL=TRUE) manually before loading nat.

File Formats

nat supports multiple input and output data formats for the object classes. There is a registry-based mechanism which allows support for reading or writing specific file formats (see fileformats) to be plugged in to reasonably generic functions such as read.neurons. It is perfectly possible for other R packages or end users to extend the supported list of file types by registering new read/write or identification functions.

Package Options

The following options can be set to specify default behaviour.

nat.cmtk.bindir: Location of CMTK binaries. See cmtk.bindir
nat.default.neuronlist: A character string naming a neuronlist to use with the plot3d.character method
nat.progress: The default progress reporter to use with nlapply. See create_progress_bar for possible values. When unset is equivalent to special value 'auto'. To suppress altogether, use nat.progress="none".

In addition there is one read-only option:

nat.cmtk.version which is used to store the current cmtk version when there are repeated calls to cmtk.version.