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
subset function has both
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
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
function can convert
ngraph objects back to
selected vertex indices can be used to subset a neuron with
Neurons can be collected as
neuronlist objects, which contain multiple
dotprops objects along with an attached
dataframe of metadata. The metadata can be accessed and manipulated using
myneuronlist[i,j] notation (see
Neurons can be read in to a neuronlist using
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
Interactive 3D selection of neurons in a neuronlist is also possible using
find.neuron (which makes use of
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.
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
hxsurf objects nat provides the
im3d class to handle image/density data on a regular grid.
I/O is handled by
which are currently implemented for the AmiraMesh and NRRD file formats;
there is also read only access to the vaa3d raw
Spatial information can be queried with
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
rgl package and also to packages for
morphometrics and sophisticated mesh manipulation such as
nat uses the
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
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
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
nat.default.neuronlist A character string naming a
neuronlist to use with the
nat.plotengine A character string naming a plotengine to use
either 'rgl' or 'plotly'. rgl is the default if unset, see
Graphics vignette for details.
nat.progress The default progress reporter to use with
possible values. When unset is equivalent to special value
To suppress altogether, use
nat.use_natcpp Whether or not to use the
natcpp package (if available) to
accelerate some basic neuron processing functions. Set to
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
rgl which is used for visualisation,