nat-package | R Documentation |
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 neuron
s 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 can be applied 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, 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.
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.
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.
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.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
.
neuron
, dotprops
,
neuronlist
, nlapply
, plot3d
,
xform
, im3d
, read.hxsurf
,
rgl
which is used for visualisation,
fileformats
, read.neurons
, cmtk
.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.