nat provides tools to read, analyse, plot, transform and convert neuroanatomical data, especially representations of neurons.
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.
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 using the nlapply function, which
also provides options for progress bars and simple parallelisation.
neuron or dotprops
objects can be transformed from e.g. sample to template brain space using
affine or non-rigid registrations. nat has built in support for
registrations calculated with the open source CMTK package available at
www.nitrc.org/projects/cmtk. See ?cmtk for installation
details. The function xform has methods to deal with a
variety of types of interest.
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:
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.
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.
Since nat v1.9.2 there is support for
plotly as an alternative 3D visualisation
engine. You can set option(nat.plotengine='plotly') to make this the
default. See the 3D graphics vignette for further details.
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.
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.plotengine A character string naming a plotengine to use
either 'rgl' or 'plotly'. rgl is the default if unset, see 3D
Graphics vignette for details.
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".
nat.use_natcpp Whether or not to use the
natcpp package (if available) to
accelerate some basic neuron processing functions. Set to FALSE if
you don't want this to happen.
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.
neuron, dotprops,
neuronlist, nlapply, plot3d,
xform, im3d, read.hxsurf,
rgl which is used for visualisation,
fileformats, read.neurons, cmtk.