NeuroAnatomy Toolbox for Analysis of 3D Image Data
NeuroAnatomy Toolbox (nat) enables analysis and visualisation of 3D
biological image data, especially traced neurons. Reads and writes 3D images
in NRRD and 'Amira' AmiraMesh formats and reads surfaces in 'Amira' hxsurf
format. Traced neurons can be imported from and written to SWC and 'Amira'
LineSet and SkeletonGraph formats. These data can then be visualised in 3D
via 'rgl', manipulated including applying calculated registrations, e.g.
using the 'CMTK' registration suite, and analysed. There is also a simple
representation for neurons that have been subjected to 3D skeletonisation
but not formally traced; this allows morphological comparison between
neurons including searches and clustering (via the 'nat.nblast' extension
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:
For the impatient ...
# plot some test data (?kcs20 for details)
# Drosophila Kenyon cells processed from raw data at http://flycircuit.tw
# get help
A confirmed stable version of nat can be installed from CRAN.
However, nat remains under quite active development, so we generally
recommend installing the latest development version directly from github using
the devtools package.
# install devtools if required
if (!requireNamespace("devtools")) install.packages("devtools")
# then install nat
If you want some help using nat, then please use the following resources
If you think that you have found a bug
- Install the development version of nat using devtools (see above)
- Check the github issues and
- file a bug report if this seems to be a new problem
- comment on an existing bug report
- Write to the nat-user list
Thanks for your interest in nat!
This release includes some bug fixes and significantly improved online package
documentation visible at http://jefferis.github.io/nat/ including two vignettes.
- Teach xform and friends to transform soma positions (#206)
- Copy attributes (including templatebrains) of neuronlists when subsetting (#310)
- Fix error in read.amiramesh for RLE encoded files. (#317)
(reported by K. Hornik)
- replace nat::trim with base::trimws (#313)
- Add xform.data.frame method (#309)
- Add invert_reglist function (#308)
- Fix bug in imslice storing position of new singleton dim (#306)
- Fix namespace issues for smooth_neuron
The main feature of this release is improved support for nat+CMTK on Windows.
- teach voxdims.character to get voxel dimensions straight from image file on
disk enhancement (#303)
- teach coord2ind to accept nat.templatebrains objects for imdims (#302)
- add simple smooth_neuron function (#300)
- fix bug reading amira surfaces when Color precedes Id (#305)
- cmtk.reformatx needs to use system2 (#301)
- Don't use shell features on Windows (#295)
- fix build failures with testthat >=0.12 (#293)
- ensure that nat still works with igraph <1.0 (#298)
- fix read.hxsurf failure when a region is not listed in the Parameters section (#291)
- Protect find.neuron from trying to filter with a neuronlist (#299)
- Fix simplification of reglist containing one cmtkreg (#297)
- Don't lose swap attribute when >1 cmtk registrations in reglist (#296)
- Documentation improvements for neurons and file formats
- nat now handles compound registrations via reglist objects (#286).
These can contain homogeneous affine, CMTK registrations (in disk or in memory)
and R functions (which can be used to wrap arbitrary registration types not
directly supported by nat). NB xformimage.reglist will currently only work for
CMTK compatible registrations.
- add mask(.im3d) function to zero out parts of an image (#285)
Looks after im3d attributes and material name to integer pixel level mapping.
- add read.ngraph.swc which can be used to read even malformed SWC files (such
as those containing cycles) (#282).
This is exposed by giving read.neuron an argument class, which can be set to
'ngraph' instead of 'neuron'.
Inspired by https://github.com/BigNeuron/BigNeuron-Wiki/wiki/BigNeuron-Imperial-College-London-Hackathon-Discussion-Notes
- add prune_edges to delete by specifying neuron edges rather than vertices (#280)
- Give give spine an invert option (#279) using prune_edges
- Teach spine to return point ids (#278)
- fix bug in pointsinside for distant points (#290)
- fix subsetting neuronlists with a single column data.frame drops column name
- Fix invert option of subset/prune_vertices returns an error with igraph::dfs
- Fix fileformats(, rval='info') to return a well-formatted data.frame
- The idiom neuronlist[,] will never drop columns (since it is a useful shortcut
for as.data.frame(neuronlist)) (#277)
- roll back rgl NULL mode changes from 1.8.0 in favour of less invasive approach
of marking the majority of rgl based plotting examples as donttest (#274)
- fix non-canonical URLs to CRAN packages (thanks to Uwe Ligges)
This is tagged as a major release because of a change in behaviour that (by
default) suppresses interactive rgl windows when running in batch
(non-interactive) mode. See ?nat "rgl Package" section for details.
- nat will only activate an rgl display in interactive mode, otherwise
defaulting to rgl's NULL mode display. This should help run nat in batch mode
situations including knitr runs, the CRAN build server etc. (#272)
- Add summary.neuron(list) functions to calculate tree statistics such as number
of nodes and cable length for neurons/neuronlists (#269)
- Automate progress bar in nlapply - this will always show in interactive mode
when there are more than 10 neurons being processed. (#271)
- Fix bug in c.neuronlist when combining more than 2 neuronlists (#270)
- Fix bug in read.neuronlistfh on Windows (#268)
- Fix bug when constructing an ngraph with a single node (#267)
- Fix bug in
[<-.neuronlist when assigning a whole data.frame using (#256)
- Fix bug in bounding box with input = "bounds" (#273)
- Documentation improvements (especiall package overview - see ?nat)
- new function subset.neuron can keep/remove individual vertices from a neuron
based on internal variables such as position, width, vertex number etc while
still producing a valid neuron with an appropriate graph structure (#261)
- this depends on a new low level function prune_vertices that can remove
- this has also enabled the prune.neuron method to be defined for the first time
enabling pruning by spatial proximity ()
- teach mirror to work with image data (#265) and enable better handling of the
mirrorAxisSize by allowing this to be supplied as a bounding box (#254)
- teach as.im3d.matrix to use an im3d object to specify the desired space (#263)
This enables for example a set or tracings to be turned into volume data that
exactly matches a specific template brain.
- fix bug: seglengths fails for neurons with multiple trees bug (#257)
- fix bug: xformpoint.cmtkreg fails for in memory registration lists (#259)
- new functions strahler_order and prune_strahler to calculate the Strahler
order of points in a neuron and to remove lower order (terminal) branches.
- fix is.cmtkreg for non-existent files (and better handling of status messages)
- export segmentgraph function for end users
- enable segmentgraph to return segment ids
- implement extraction/replacement of the data.frame attached to a neuronlist
using the [ operator (#217)
- fix xform of image data (#143, #199)
- implement handling of inverted (swapped i.e. reference to sample)
registrations in xform(image) (#199)
- normalise handling of registration sequences and inversion in
xform/image/points (all 3 expect reg to be in sample to ref order and for any
individual registration to be marked with swap=T if it is ref->sample)
- read.nrrd no longer returns an im3d (use read.im3d) (#238)
- teach write.nrrd to handle more diverse inputs (including #242)
- add reading of detached nrrds (#236, #237)
- add ability to write detached nrrds
- add ability to make a detached nrrd from a compatible amira file on disk (#243)
- new function is.im3d
- fix cmtk.targetvolume for templatebrain objects (#241)
- fix cmtk.targetvolume for --target-grid specification (#240)
- fix names for [.neuronlistfh with null df (#250)
- plot.neuron can cope with some NA coordinates
- teach plot.neuron(list) to cope with NA points (#247)
- boundingbox has an na.rm argument (#246)
- teach droplevels.neuronlist to use extra arg (#249)
- teach plot.neuron to plot soma (#245)
- fix cmtk.call for numeric args (#235)
- set read.hxsurf RegionChoice="both" by default
- document return values of cmtk.statistics in more detail (#252)
- support for igraph 1.0 (#248)
- Fixes description capitalisation/quoting for CRAN
- Adds ability to write dotprops neuron objects to SWC format (#233)
- fixes bug in xyzmatrix.neuron for single point neurons (#234)
- likewise for xyzmatrix.default for 1-row >3-col matrices
- add xyzmatrix get/set methods for class mesh3d along with xform.shape3d. This
should enable rgl::mesh3d objects (used in a number of other packages) to be
transformed using CMTK registrations.
- add tail.neuronlist
- add as.data.frame.neuronlist for convenient generation of a data.frame from a
- add help topics for generics subset and plot3d so that e.g. ?subset will give
the option to see our documentation as well as base docs.
- subset.hxsurf drops unused vertices by default
- add sample surface object of mushroom body
- teach cmtk.statistics to handle imagetype == 'label' (#221)
- plot.neuronlist sets axes based on boundingbox of all plotted neurons, not just
the first neuron (#223)
- plot.neuron(,AxisDirections) argument is re-implemented (#224)
- don't warn when read.neuronlistfh changes the directory location on disk (#157)
- remove superimposed plots in mirror example (hope this will fix build on
- teach read.neurons to OmitFailures when reading in a neuronlistfh object.
- fix handling of default colours in plot.neuronlist and plot3d.neuronlist (#230)
- fix plot3d.neuronlist returns one element per neuron
- fix bug in xformpoints.cmtkreg when some points could not be transformed -
now give NAs as expected (#227)
- fix bug when xform(na.action='drop') dropped dimensions when only 1 valid
point resulted (#228)
- teach xyz.matrix<- to work for bare 3 column matrices (i.e. without colnames)
- fix bug in xformimage where input image was not being passed on when
transforming with a matrix.
- read.hxsurf can accept RegionChoices='both' (see ?read.hxsurf)
- fix: unary -.neuronlist behaves
- docs: numerous minor doc/example improvements
- dev: improvements in test coverage (up to 84%) catching numerous small bugs in
- Edits to package description for CRAN
- fix invalid url in README.md noticed by r-devel/BDR
- add as.im3d.matrix which allows conversion of a Nx3 matrix of coordinates into
a volume representation
- add ability to use a neuron's StartPoint in the spine function that finds the
longest path (aka backbone or spine) of a neuron
- fix xformimage's handling of in-memory registrations
- fix bug in read.hxsurf docs
- dev: add coveralls code coverage support
- dev: fix use of require in package code (a new note from r-devel)
- dev: fix a cmtk-dependent test that was not guarded against cmtk's absence
- add ability to transform images (specified as path to a file)
- register image file formats to use with read/write.im3d
- register amira types including linesets, surfaces and landmarks
- add ability to read neurons from remote url
- add support for applying multiple registrations in xform.neuronlist, as well
as vectorisation (where each registration is applied to a different object)
- Add support for reading NeuroML and Fiji Simple Neurite Tracer neurons
- recognise SWC neurons by content (rather than just file extension)
- can write a set of neurons to a zip archive (?write.neurons)
- getformatreader returns name of identified format
- Give find.soma and find.neuron invert arguments
- internal function normalise_swc sets sensible defaults for column values (and
these can be overridden from some user functions).
- fix resample.neuron so that it keeps all subtrees and handles width and labels
- fix seglist2swc when receiving flat seglist
- ngraph attaches vertex data to each point and now includes diameter
- fix is.nrrd for raw input
- fix node colours in plot3d.neuron when WithAllPoints=TRUE
- add nlscan function to review a set of neurons, optionally selecting a subset
- add find.soma function to select neurons whose cell bodies fall within an rgl
seelection box (thanks to Ben Sutcliffe).
- add setdiff, intersect and union generics with implementations for neuronlist
objects (note this is done in more or less identical fashion to generics
defined in the dplyr package).
- give write.neurons a format argument to make it more obvious that this is an
option rather than pointing people to the write.neuron docs (suggestion from
- teach as.neuronlist to handle inputs with empty (rather than NULL names)
- simplify calculation of inertia in dotprops
- minor doc fixes and clarifications
- mat2dof output gets descriptive rownames
- ndigest.neuronlistfh only uses 2 key fields (keyfilemap and df)
- fix bug in locating cmtk when only the cmtk wrapper script is in the path
(spotted on neurodebian with /usr/bin/cmtk)
- fix bug in compound registrations when CMTK <3.2.2
- fix rgl import errors on r-devel
- switch from RANN to nabor package for finding nearest neighbours
- dev: update help to roxygen2 4.0.2
- fix bug in updating neuronlistfh objects from remote url
- nlapply now has options for progress bars and parallelisation by using the
plyr package under the hood.
- c.neuronlist can now join lists with attached data.frames with different
columns (missing values are filled with NAs). This also applies when some
neuronlists have no attached data.frame at all.
- read.neurons can read neuronlist files from disk
- cmtk.statistics now has a Verbose argument
- warn if resmapling a neuron with multiple subtrees that only the main subtree
will be kept.
- add cmtk.statistics function
- fix infinite recursion in cmtk.targetvolume
- fix: write.neurons subdir argument can accept a column of the attached
- fix: write.neuron(s) can add an extension to an output filename that does not
- write.neurons now has an explicit files argument
- cmtk.targetvolume (and therefore cmtk.reformatx) can accept e.g.
templatebrains (as contained in nat.flybrains package) to specify target
image for registration.
fix transformation of points using compound CMTK registrations
(this was broken for CMTK<3.2.2, so a workaround is required).
Add cmtk.version function.
xyzmatrix can cope with lower case x,y,z for column names
doc: fixes in xform
dev: fix test for winbuilder
- Add boundingbox.list method to find boundingbox for neurons, surfaces etc
- nmapply and nlapply get OmitFailures arguments
- nlapply also gets a subset argument
- both arguments are also added to xform/mirror.neuronlist
- dotprops.neuronlist also gets the OmitFailures argument.
- fix subset.neuronlist handling of numeric indices
- minor bug/doc fixes
- teach plot3d.neuronlist and friends to plot soma locations.
- add npop3d function to remove last plotted neurons
(identical to flycircuit::pop3dfc, except that it works with any neurons
plotted by plot3d.neuronlist, rather than only those plotted by plot3dfc)
- give mirror/xform.neuronlist subset arguments
- add plot3d.boundingbox
- give plot(3d).neuronlist a SUBSTITUTE argument that can be used to control
non-stadard evaluation. This is useful for people who wish to incoroporate
these funcitons inside other user-defined functions. See ?subset.neuronlist
- fix: write.neurons into subdirs when df=NULL
- fix bug in reading swc files with many decimal places specific to R 3.1.0
- fix bug in header when writing swc files [ajdm]
- read.im3d now adds file as an attribute to output
- read.im3d can now add amiramesh files without the standard file extension
- doc: minor improvements to read.im3d docs and examples
- remove internal is.gzip function and depend on nat.utils >=0.4.2
- new function pointsinside to determine if points (e.g. neuron) are inside a
- resample.neuron implemented (no support for interpolating widths or multiple
- dotprops.neuron can resample to a consistent segment length
- consistent return values for as.seglist and seglengths when all subtrees are
- seglengths can return lengths for each edge as well as the sum for each
neurite segment (the default)
- suppress remote tests if flybrain unreachable
- zenodo DOI for package
- add seglengths function for neurons
- add segmentgraph function to produced a simplified graph representation of
neurons with one edge per segment
- add potential_synapses.dotprops method
- add as.seglist.neuron method
- teach plot3d.hxsurf and subset.hxsurf to accept regexes
- always drop unused vertices in as.mesh3d.hxsurf
- fix bug in write.neurons when subdir not specified
- fix colouring of vectors by plot3d.dotprops
- dev: switch to roxygygen2 v4
- add potential_synapses (from nat.as)
- surfaces: add subset.hxsurf and as.mesh3d
- Teach read.im3d to read Vaa3d raw format
- add plot.neuronlist (for 2d plotting)
- add c.neuronlist function to combine neuronlists
- add db argument to plot3d.character
- make WithNodes=FALSE the default for plot3d.neuronlist
- make asp=1 the default for image.im3d
- write.cmtkreg warns if versions specified by cmtkreg attribute and argument
differ (to avoid writing old registrations as if they were new or vice versa)
- fix: prune.neuronlist method signature (and therefore dispatch)
- add function to prune objects by removing points close to or far from another
- add nmapply function for neuronlists
- add xyzmatrix method for neuronlists
- add materials function with methods for im3d and hxsurf objects
- enh: read.im3d can read materials from amiramesh files
- enh: download neurnonlistfh objects to session temp directory if no localdir
- fix: find CMTK in its new default location on macosx
- fix: plot3d should skip redrawing if par3d() skipRedraw is set
- fix: failure to export ngraph constructor function
- fix: set NeuronName when no InputFile argument is passed to neuron
- fix: im3d axis labels
- doc: numerous small documentation improvements
- add spine() function to find longest path (aka backbone) of a neuron
- give ngraph (and therefore as.ngraph methods) a weights argument so that
resultant ngraph objects have edge weights defined by segment lengths.
- add as.im3d generic and as.im3d.im3d method
- fix bug in setting graph attributes in ngraph
- bugfix: ensure ind2coords.im3d is exported
- add ability to make a dotprops object directly from an image file on disk or
an im3d object in memory.
- port ind2coord, coord2ind and sub2ind functions from AnalysisSuite
- fix clampmax function so that it removes Infinite values
- fix reading of gzip encoded amiramesh files
- fix mirror so that dotprops are recalculated for a simple flip
- make plot(3d).neuron colour settings more consistent
- simplify axis handling in plot.neuron
- dev: build nat.flybrains (as well as nat) after flycircuit build
- fix bug in handling vertexData argument in as.neuron.ngraph
- fix test error on Solaris (thanks to Brian Ripley)
- dev: fix remaining warnings in tests
- add plot.neuron for 2d plots (ajdm, from code in AnalysisSuite)
- add nopen3d() which opens an rgl viewer that allows panning. See ?nopen3d for
details of how to use this.
- teach read.neurons to report files that have problems as they are read
- fix temp file left behind by xform.cmtkreg
- fix dangerous looking warning when amira binary files have empty sections
- fix ability of read.neurons to set InputFileName and therefore retain
status information for the file along with its MD5 hash
- fix bug exporting xform.default (so that xform(matrix()) works)
- docs: improve coverage of BoundingBox vs bounds
- tests: simple tests for plot(3d).neuron
- tests: clear up temp files and suppress most warnings
- dev: restart travis build of flycircuit package when nat is pushed to github
- fix handling of logical expressions including NAs by subset.neuronlist
- add soma argument to plot3d.neuron
- fix: boundingbox.im3d() returns NULL when bounding box is not defined
- give remotesync.neuronlistfh an indices argument to allow download/update
from the web of a selected population of neurons
- add ndigest.neuron method
- fix: export ndigest.dotprops method
- give image.im3d a useRaster option, which defaults to TRUE when possible.
- new ndigest (normalised digest) function to compute hash values. Methods for
neuronlistfh and dotprops objects. Can be used e.g. to compute a hash value
for a standard dps object to determine if a data.
- new threshold function with a method for im3d objects. Can be used to make
- more flexible im3d constructor can use an existing im3d object to supply
- fix bug in read.neuronlistfh resulting in error if a remote file was
downloaded and then read back in (using cached copy) before any neurons were
- fix bug in write.nrrd - was failing to write essential space dimensions field.
- make gzip the default encoding for nrrd images - this is pretty much always
what one wants.
- add cmtk.reformatx command for reformatting images using CMTK registrations
- new function remotesync to synchronise a neuronlistfh object with its remote
- add write.neuronlistfh and improve consistency/docs of path handling in
- option to write missing (or no) neurons when using as.neuronlistfh.neuronlist
this makes it much faster to re-export these objects or prepare neuronlistfh
for subsets of an existing group of neurons
- fix hashmap functionality of neuronlistfh (speeds up access to single neurons)
- fix bug in find.neuron for neuronlistfh objects
- fix bug in neuronlistfh constructor (wasn't adding hashmap) and
[[.neuronlistfh (was not searching properly for objects when using hashmap).
- add find.neuron for interactive selection of neurons in 3d.
- implementation of new im3d image manipulations functions including image.im3d,
projection, unmask, imslice, imscalebar, imexpand.grid, flip, origin,
boundingbox<-, xyzpos, ijkpos
- see ?im3d, ?boundingbox, ?image3d.im3d, ?imscalebar and ?flip for details
- fix reading of gzipped nrrds on windows
- dev: fix nocran tests
- Basic implementation of reading/writing NRRD format image data.
See read.nrrd and write.nrrd for details.
- Basic implementation of reading/writing Amira format image data.
See read.amiramesh and write.amiramesh for details.
- Basic implementation of a class for 3d images, im3d
- see read.im3d and write.im3d for I/O
- and voxdims and boundingbox methods for physical dimensions
- switch to more flexible neuronlistfh structure in which objects on disk are
named by the md5 hash of their contents.
- workaround for connection leak in filehashRDS objects that stopped downloads
of more than 124 new objects by a neuronlistfh (ajdm).
(see https://github.com/rdpeng/filehash/pull/3 for details)
- dev: approach allowing some tests (e.g. those using the web) to be ignored on
- dev: travis continuous integration support (ajdm)
- Implemented reading and writing of groups of neurons from/to neuronlists.
See read.neurons and write.neurons.
- Implemented writing of single neurons in swc format, Amira's HxLineSet and
SkeletonGraph formats, and R's rds format.
- Can now read Amira HxLineSet format neurons (see read.neuron)
- Give read.neuronlistfh an update argument (default:FALSE) so that it does not
re-download remote data.
- dev: speed and flexibility improvements in fileformats ioregistry.
see ?fileformats for details of new functions.
- fix bug in cmtk.bindir() on Solaris (thanks to Brian Ripley)
- implement reading of amiramesh data
- including amira SkeletonGraph format tracings
- switch to filehashRDS format for repositories of remote neurons
- retire stashR backend for neuronlistfh remote repositories (too slow)
- support for automatic download of neurons from stashR remote repositories on
the web. ?neuronlistfh for details and an example.
- Relies on stashR package
- dev: small doc fixes to make package CRAN compatible.
- important new feature: neuronlistfh objects backed by an on disk filehash
allow single neurons to be loaded from disk on demand
- this allows 1) fast startup suitable for knitr documents and 2) working with
more neurons than fit in main memory
- of course this is slower than working with an in-memory list but for plotting
etc this should not be problem
- furthermore neuronlistfh objects can be subsetted/converted to give in memory
- implement read.neuron and read.neurons
- so far only works for rda, rds and swc files
- reading of additional file types will be implemented by registering functions =
to test, read and write for the format using a package regsistry controlled by
- developer: seglists in neurons now have class 'seglist'
- major new functionality - bidirectional interconversion of graph and regular
- see as.neuron.* methods and as.ngraph.* methods
- plan is to use graph representation as the common intermediate with reading
different neuron file formats
- depends on igraph package
- add subset.neuronlist
- add methods for working with dataframe attached to neuronlist
(see e.g. ?with.neuronlist)
- TODO harmonise plot3d.neuronlist subset expressions with subset.neuronlist
- Switch license to GPL-3
- xform (transformation) of hxsurf objects
- fix xform of neuronlist objects
- switch from CMTK gregxform to streamxform (gregxform is deprecated; streamxform can concatenate registrations)
- teach mirror function to accept numeric axis specification
- Fix bug in checking extra directories in cmtk.bindir
- Add dotprops.neuronlist and include all dotprops methods in documentation
- Fix longstanding bug in parsing cmtk warping registrations (only relevant for
reading these into R lists - no effect on transformations).
- fix bug in class of cmtkreg objects
- Remove call to .Internal(La_rs) by calling eigen directly
- doc: some notes on CMTK installation
- fix broken handling of cmtk affine transformations
- implement mirroring of neurons and other objects
- teach xformpoints (and therefore xform) to handle "~/" in paths
- bugfix in visibility of S3method xformpoints.character
- (developer) Switch to roxygen2 v3.0 for documentation
- read.hxsurf and plot3d.hxsurf for reading/plotting Amira surfaces
- better handling of location of cmtk command line tools see ?cmtk for details
- add neuronlist and associated methods (including plot)
- plot3d for neurons and dotprops
- basic and self-contained implementation of neuron class
- basic and self-contained implementation of dotprops
- new xform generic + methods for clean transformation of objects including
neurons and dotprops objects
- this includes improved interaction between dotprops and xform so that xform
can use the previously value of k when recalculating a dotprops object post
- sample data (40 PNs from Jefferis, Potter et al. '07 and 20 KCs from Chiang
et al. 2011)
- 1 use of .Internal and missing nlapply remain to be fixed.
- fix install error due to missing neuron(*).R files that contain docs only so far
- Fairly complete implementation of CMTK registration I/O and geometry
- All functionality is self-contained (i.e. independent of nat.as/AnalysisSuite)
- passes check()
- can be augmented by nat.as (0.6)