**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 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.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"`

.

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`

.