nat: NeuroAnatomy Toolbox

Build Status

An R package for the (3D) visualisation and analysis of biological image data, especially tracings of single neurons. See nat.examples and frulhns for sample code.

nat is a cleaned up version of code that has been used in a number of papers from our group including:

Cell 2007 Cover CB 2010 Cover Nature 2011 Cell 2013 Abstract

Quick Start

For the impatient ...

# install
install.packages("nat")
# use
library(nat)

# plot some test data (?kcs20 for details)
# Drosophila Kenyon cells processed from raw data at http://flycircuit.tw
head(kcs20)
open3d()
plot3d(kcs20, col=type)
# get help
?nat

A larger data set, 300 olfactory projection neurons from Grosjean et al 2011

load(url("http://flybrain.mrc-lmb.cam.ac.uk/si/grosjean11/MyNeuronsFCIR.rda"))
plot3d(MyNeurons[[1]])
clear3d()
head(MyNeurons)

# 3d plot of neurons from olfactory glomeruli beginning DM
# coloured by glomerulus
rval=plot3d(MyNeurons, subset=grepl("^DM",Glomerulus), col=factor(Glomerulus),
  lwd=2, WithNodes=FALSE)
# make a legend so that you know which colours match which glomerulus
with(attr(rval,'df'), legend('center', legend = unique(Glomerulus), fill=unique(col)))

# more help
?plot3d.neuronlist
?subset.neuronlist

Details

Installation

As of v1.0 there is a released version on CRAN.

install.packages("nat")

It you wish to run the package tests, it is necessary to install with dependencies=TRUE.

Released versions

Interim source code packages for released versions are available from our lab repository:

# when binary packages are preferred (e.g. mac/windows)
install.packages("nat",repos=c("http://jefferislab.org/R",getOption("repos")),
                 type="both")
# when source packages are the default (e.g. linux)
install.packages("nat",repos=c("http://jefferislab.org/R",getOption("repos")))

Note the specification of both the jefferislab.org repository and the default CRAN repository in order to ensure that package dependencies are installed from CRAN and the main package is installed from our repository. Note also that it is necessary to specify type="both" on platforms where binary packages are the norm (Windows/MacOS X) since nat is only provided as a source package on our repository.

Bleeding Edge

You can, however, download the tar ball, and run R CMD INSTALL on it, or use the devtools package to install the development version:

# install.packages("devtools")
devtools::install_github("nat", "jefferis")

Note: Windows users need Rtools and devtools to install this way.

External Dependencies

nat is self sufficient for core functionality, but the transformation of 3d data using Computational Morphometry Toolkit (CMTK) registrations depends on an external installation of that toolkit. CMTK binaries can be downloaded for Windows, Linux and Mac at http://www.nitrc.org/projects/cmtk/. Source code is available from the same site or an unofficial mirror repository at https://github.com/jefferis/cmtk. We have extensive experience of using CMTK under linux (where we compile from source) and mac (where we compile or use the MacOSX-10.6-x86_64.dmg binary installers). We have also used neurodebian to install as part of the travis continuous integration setup (see the project's .travis.yml file).