R/nat-package.R

In jefferis/nat: NeuroAnatomy Toolbox for Analysis of 3D Image Data

#' Analyse 3D biological image data especially neurons
#'
#' \bold{nat} provides tools to read, analyse, plot, transform and convert
#' neuroanatomical data, especially representations of neurons.
#' @section Neuron Objects: At present there are 2 main representations of
#'   neuronal data:
#'
#'   \describe{
#'
#'   \item{\code{\link{neuron}}}{ objects contain one or more connected trees
#'   that make up a neuron}
#'
#'   \item{\code{\link{dotprops}}}{ objects can contain one (or more) neurons
#'   represented as points and tangent vectors in which the connectivity
#'   information has been discarded}
#'
#'   }
#'
#'   The \code{subset} function has both \code{\link{subset.neuron}} and
#'   \code{\link{subset.dotprops}} methods, which can be used to keep (or
#'   reject) specified vertices within a neuron e.g. by spatial constraints.
#'   \code{\link{subset.neuron}} will look after the tree structure of neurons
#'   in these circumstances.
#'
#'   \code{neuron} objects containing connected trees can be converted to
#'   \code{\link{ngraph}} objects, a lightweight wrapper around the
#'   \code{\link{igraph}} library's \code{\link[igraph]{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 \code{\link{as.neuron}}
#'   function can convert \code{ngraph} objects back to \code{neuron}s or
#'   selected vertex indices can be used to subset a neuron with
#'   \code{\link{subset.neuron}}.
#'
#' @section Collections of Neurons: Neurons can be collected as
#'   \code{\link{neuronlist}} objects, which contain multiple
#'   \code{\link{neuron}} or \code{dotprops} objects along with an attached
#'   dataframe of metadata. The metadata can be accessed and manipulated using
#'   the \code{myneuronlist[i,j]} notation (see
#'   \code{\link{neuronlist-dataframe-methods}}).
#'
#'   Neurons can be read in to a neuronlist using \code{\link{read.neurons}} or
#'   written out using \code{\link{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
#'   \code{\link{plot3d.neuronlist}} and \code{\link{subset.neuronlist}}).
#'   Interactive 3D selection of neurons in a neuronlist is also possible using
#'   \code{\link{find.neuron}} (which makes use of \code{rgl}'s
#'   \code{\link{select3d}} function.
#'
#'   \code{neuronlist} objects also provide additional functionality to
#'   streamline arithmetic (e.g. scaling all the points in all neurons see
#'   \code{\link{*.neuronlist}}) and transformations (see \bold{Transformations}
#'   section below and \code{\link{xform}}). Arbitrary functions can be applied
#'   to each individual neuron using the \code{\link{nlapply}} function, which
#'   also provides options for progress bars and simple parallelisation.
#'
#' @section Transformations: \code{\link{neuron}} or \code{\link{dotprops}}
#'   objects can be transformed from e.g. sample to template brain space using
#'   affine or non-rigid registrations. \bold{nat} has built in support for
#'   registrations calculated with the open source CMTK package available at
#'   \url{www.nitrc.org/projects/cmtk}. See ?\link{cmtk} for installation
#'   details. The function \code{\link{xform}} has methods to deal with a
#'   variety of types of interest.
#'
#' @section 3D Image Data: In addition to data types defined by unstructured
#'   collections of 3D vertices such as \code{\link{neuron}},
#'   \code{\link{dotprops}} and \code{\link{hxsurf}} objects nat provides the
#'   \code{\link{im3d}} class to handle image/density data on a regular grid.
#'   I/O is handled by \code{\link{read.im3d}} and \code{\link{write.im3d}},
#'   which are currently implemented for the AmiraMesh and NRRD file formats;
#'   there is also read only access to the \href{www.vaa3d.org/}{vaa3d} raw
#'   format.
#'
#'   Spatial information can be queried with \code{\link{voxdims}},
#'   \code{\link{boundingbox}} and \code{\link{ijkpos}}, \code{\link{xyzpos}}
#'   methods. You can convert between voxel data and coordinate (vertex) -based
#'   representations using the following functions:
#'
#'   \itemize{
#'
#'   \item \code{\link{as.im3d}} The \code{as.im3d.matrix} method converts XYZ
#'   coordinates to an \code{im3d} image volume
#'
#'   \item \code{\link{ind2coord}} Find XYZ coordinates of specified voxels of
#'   an \code{im3d} image volume
#'
#'   \item \code{\link{dotprops}} The \code{dotprops.im3d} method converts an
#'   \code{im3d} object to a \code{dotprops} format neuron, i.e. a cloud of
#'   unconnected segments.
#'
#'   }
#'
#' @section Surface Data: \bold{nat} can read, write, transform and subset
#'   surface (mesh) objects defined by Amira's HxSurface class. See
#'   \code{\link{read.hxsurf}} and links therein. In addition hxsurf objects can
#'   be converted to the \code{\link[rgl]{mesh3d}} format, which provides a link
#'   to the \code{\link[rgl]{rgl}} package and also to packages for
#'   morphometrics and sophisticated mesh manipulation such as
#'   \href{https://cran.r-project.org/package=Morpho}{Morpho} and
#'   \href{https://cran.r-project.org/package=Rvcg}{Rvcg}.
#'
#' @section rgl Package: \bold{nat} uses the \bold{\code{\link[rgl]{rgl}}}
#'   package extensively for 3D visualisation. \code{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 \code{\link[rgl]{rgl.useNULL}} option. As of
#'   nat 1.8.0, \code{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
#'   \code{options(rgl.useNULL=TRUE)} manually before loading nat.
#'
#' @section plotly Package: Since \bold{nat} v1.9.2 there is support for
#'   \code{\link[plotly:plot_ly]{plotly}} as an alternative 3D visualisation
#'   engine. You can set \code{option(nat.plotengine='plotly')} to make this the
#'   default. See the 3D graphics vignette for further details.
#'
#' @section File Formats: \bold{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
#'   \code{\link{fileformats}}) to be plugged in to reasonably generic functions
#'   such as \code{\link{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.
#'
#' @section Package Options: The following options can be set to specify default
#'   behaviour.
#'
#'   \describe{
#'
#'   \item{\code{nat.cmtk.bindir}}{ Location of CMTK binaries. See
#'   \code{\link{cmtk.bindir}}}
#'
#'   \item{\code{nat.default.neuronlist}}{ A character string naming a
#'   \code{\link{neuronlist}} to use with the \code{\link{plot3d.character}}
#'   method}
#'
#'   \item{\code{nat.plotengine}}{ A character string naming a plotengine to use
#'   either 'rgl' or 'plotly'}. rgl is the default if unset, see \code{3D
#'   Graphics} vignette for details.
#'
#'   \item{\code{nat.progress}}{ The default progress reporter to use with
#'   \code{\link{nlapply}}. See \code{\link[plyr]{create_progress_bar}} for
#'   possible values. When unset is equivalent to special value \code{'auto'}.
#'   To suppress altogether, use \code{nat.progress="none"}.}
#'
#'   \item{\code{nat.use_natcpp}}{ Whether or not to use the
#'   \href{https://natverse.org/natcpp/}{natcpp} package (if available) to
#'   accelerate some basic neuron processing functions. Set to \code{FALSE} if
#'   you don't want this to happen.}
#'
#'   }
#'
#'   In addition there is one read-only option: \itemize{
#'
#'   \item \code{nat.cmtk.version} which is used to store the current cmtk
#'   version when there are repeated calls to \code{\link{cmtk.version}}.
#'
#'   }
#' @name nat-package
#' @aliases nat
#' @seealso \code{\link{neuron}}, \code{\link{dotprops}},
#'   \code{\link{neuronlist}}, \code{\link{nlapply}}, \code{\link[nat]{plot3d}},
#'   \code{\link{xform}}, \code{\link{im3d}}, \code{\link{read.hxsurf}},
#'   \code{\link{rgl}} which is used for visualisation,
#'   \code{\link{fileformats}}, \code{\link{read.neurons}}, \code{\link{cmtk}}.
#' @docType package
#' @keywords package
#' @import rgl graphics grDevices utils
NULL