Package Help

Provides an overview of key functions and classes

nat-package

Analyse 3D biological image data especially neurons

Neurons (traced)

Functions for working with traced neurons (fully connected tree structures)

neuron() is.neuron() as.neuron()

neuron: class to represent traced neurons

read.neuron()

Read a single neuron from a file

write.neuron()

Write out a neuron skeleton or mesh in any of the file formats we know about

plot(<dotprops>) plot(<neuron>)

Plot a 2D projection of a neuron

subset(<neuron>)

Subset neuron by keeping only vertices that match given conditions

prune()

prune an object by removing points near (or far) from a target object

prune_vertices() prune_edges()

Prune selected vertices or edges from a neuron

prune_in_volume()

Prune neuron(s) within a volume defined by a 3D mesh

Ops(<neuron>)

Arithmetic for neuron coordinates

scale(<neuron>) scale(<dotprops>)

Scale and centre neuron 3D coordinates

resample()

Resample an object with a new spacing

seglist() as.seglist()

Make/convert neuron connectivity information into a seglist object

seglist2swc()

Recalculate Neurons's SWCData using SegList and point information

seglengths()

Calculate length of all segments in neuron

smooth_neuron() smooth_segment_gauss()

Smooth the 3D coordinates of a neuron skeleton

normalise_swc()

Normalise an SWC format block of neuron morphology data

Neurons (as graphs)

Functions for working with the graph structure of neurons

ngraph() as.ngraph()

ngraph: a graph to encode a neuron's connectivity

graph.nodes()

Return root, end, or branchpoints of an igraph object

rootpoints() branchpoints() endpoints()

Return the root, branch, or end points of a neuron or graph

segmentgraph()

Return a simplified segment graph for a neuron

distal_to()

Return indices of points in a neuron distal to a given node

spine()

Compute the longest path (aka spine or backbone) of a neuron

strahler_order()

Find the Strahler order of each point in a neuron

prune_strahler()

Prune a neuron by removing segments with a given Strahler order

get_topo_features() get_distance_to_soma()

Get topological features per each node

prune_twigs()

Remove all twigs less than a certain path length from a neuron

simplify_neuron()

Simplify a neuron to the longest tree with n branch points

stitch_neuron()

Stitch two neurons together at their closest endpoint

stitch_neurons()

Stitch multiple fragments into single neuron using nearest endpoints

stitch_neurons_mst()

Stitch multiple fragments into single neuron using minimum spanning tree

reroot()

Reroot neurons

Skeletonised Neurons (dotprops aka vector cloud)

Functions for working with skeletonised neurons consisting of unconnected vectors rather than a fully connected tree.

is.dotprops() as.dotprops() dotprops()

dotprops: Neurons as point clouds with tangent vectors (but no connectivity)

subset(<dotprops>)

Subset points in dotprops object that match given conditions

Ops(<dotprops>) Ops(<mesh3d>) Ops(<hxsurf>)

Arithmetic for nat dotprops and surface objects

Collections of Neurons (neuronlists)

Functions for working with collections of neurons, which are packaged as neuronlist objects with an attached data.frame containing metadata.

neuronlist()

Create a neuronlist from zero or more neurons

read.neurons()

Read one or more neurons from file to a neuronlist in memory

write.neurons()

Write neurons from a neuronlist object to individual files, or a zip archive

neuronlistz() as.neuronlist(<neuronlistz>)

A neuronlist object that will read neurons from a zip file on demand

nlapply() progress_natprogress() nmapply()

lapply and mapply for neuronlists (with optional parallelisation)

plot(<neuronlist>)

2D plots of the elements in a neuronlist, optionally using a subset expression

plot3d(<neuronlist>) plot3d(<character>)

3D plots of the elements in a neuronlist, optionally using a subset expression

subset(<neuronlist>)

Subset neuronlist returning either new neuronlist or names of chosen neurons

summary(<neuronlist>) summary(<neuron>) summary(<mesh3d>) summary(<dotprops>)

Summary statistics for neurons (e.g. cable length, number of nodes)

as.neuronlist()

Make a list of neurons that can be used for coordinate plotting/analysis

c(<neuronlist>)

Combine multiple neuronlists into a single list

as.data.frame(<neuronlist>) `data.frame<-`()

Get or set the attached data.frame of a neuronlist

is.neuronlist()

Test objects of neuronlist class to store multiple neurons

`*`(<neuronlist>) `+`(<neuronlist>) `-`(<neuronlist>) `/`(<neuronlist>)

Arithmetic for neuron coordinates applied to neuronlists

`[`(<neuronlist>) `[<-`(<neuronlist>) droplevels(<neuronlist>) with(<neuronlist>) head(<neuronlist>) tail(<neuronlist>)

Methods for working with the dataframe attached to a neuronlist

Collections of Neurons with Remote Data (neuronlistfh)

Functions for working with collections of neurons where the data will be dynamically loaded into memory from disk and/or downloaded from a remote site.

neuronlistfh() is.neuronlistfh() as.neuronlistfh() c(<neuronlistfh>)

neuronlistfh - List of neurons loaded on demand from disk or remote website

read.neuronlistfh()

Read a local, or remote, neuronlistfh object saved to a file.

write.neuronlistfh()

Write out a neuronlistfh object to an RDS file

remotesync()

Synchronise a remote object

as.neuronlist(<neuronlistfh>)

convert neuronlistfh to a regular (in memory) neuronlist

`[`(<neuronlistfh>)

Extract from neuronlistfh object or its attached data.frame

Surfaces and Landmarks (hxsurf, mesh3d)

Functions for working with surface data, either in a class hxsurf modeled on Amira’s representation of surfaces or the rgl::mesh3d class.

read.hxsurf()

Read Amira surface (aka HxSurface or HyperSurface) files into hxsurf object

write.hxsurf()

Write Amira surface (aka HxSurface or HyperSurface) into .surf file.

read.landmarks() write.landmarks()

Generic functions to read/write landmarks in any supported format

plot3d(<hxsurf>)

Plot amira surface objects in 3D using rgl

subset(<hxsurf>)

Subset hxsurf object to specified regions

as.hxsurf()

Convert an object to a nat hxsurf object

c(<hxsurf>)

Concatenate HyperSurface objects

as.mesh3d(<ashape3d>) as.mesh3d(<hxsurf>) as.mesh3d(<boundingbox>)

Convert an object to an rgl mesh3d

pointsinside()

Find which points of an object are inside a surface

3D Plotting of Objects

Functions to help plot neurons, surfaces and other 3D objects via RGL.

plot3d

plot3d methods for different nat objects

nopen3d()

Open customised rgl window

nclear3d()

Clear the rgl or plotly 3D scene

nview3d()

Set the 3D viewpoint of an RGL window using anatomical terms

npop3d()

Remove plotted neurons or other 3D objects

pan3d()

Some useful extensions / changes to rgl defaults

wire3d()

Wire frame plots

nlscan()

Scan through a set of neurons, individually plotting each one in 3D

plot3d(<boundingbox>)

Plot a bounding box in 3D

plot3d(<dotprops>)

3D plots of dotprops objects using rgl package

plot3d(<hxsurf>)

Plot amira surface objects in 3D using rgl

plot3d(<neuron>)

Plot neurons in 3D using rgl library or plotly module

plot3d(<cmtkreg>)

Plot the domain of a CMTK registration

plot3d(<ngraph>)

Plot 3d representation of neuron (ngraph) with directed edges

3D Interaction with Objects

Functions to review, identify, and modify objects by interactive selection in RGL windows.

find.neuron()

Find neurons within a 3D selection box (usually drawn in rgl window)

find.soma()

Find neurons with soma inside 3D selection box (usually drawn in rgl window)

select_points()

Interactively select 3D points in space

correct_root()

Interactively re-root neurons (usually to their soma)

prune_online()

Prune a neuron interactively in an rgl window

make_model()

Generate a 3D model from connector and/or tree node data

3D Geometry

Functions for analysing 3D geometry of neurons and other objects

nvertices()

Find the number of vertices in an object (or each element of a neuronlist)

xyzmatrix() `xyzmatrix<-`() xyzmatrix2str() xyzmatrix2list()

Get and assign coordinates for classes containing 3D vertex data

potential_synapses()

Calculate number of potential synapses between two neurons

overlap_score()

Generate a connectivity matrix based on euclidean distance between points

sholl_analysis()

Perform a Sholl analysis on neuron skeletons

plane_coefficients()

Find the coefficients of the plane equation

intersect_plane()

Find the points on a plane that are intersected by an object

Object transformation

Generic strategies for transforming 3D objects/images and registration

xform()

Transform the 3D location of objects such as neurons

mirror()

Mirror 3D object about a given axis, optionally using a warping registration

reglist() invert_reglist() c(<reglist>)

A simple wrapper class for multiple transformations

xformimage()

Transform image files using a registration or affine matrix

xformpoints()

Transform 3D points using a registration, affine matrix or function

simplify_reglist()

Simplify a registration list

tpsreg() xformpoints(<tpsreg>)

Thin plate spline registrations via xform and friends

Images (im3d)

Functions for working with 3d image volumes

im3d()

Construct an im3d object representing 3D image data, densities etc

read.im3d() write.im3d()

Read/Write calibrated 3D blocks of image data

as.im3d()

Convert a suitable object to an im3d object.

is.im3d()

Test if an object is of class im3d

imslice()

Slice out a 3D subarray (or 2d matrix) from a 3D image array

image(<im3d>)

Method to plot spatially calibrated image arrays

imscalebar()

Make a scalebar to accompany an image.im3d plot

flip()

Flip an array, matrix or vector about an axis

projection()

Make 2D (orthogonal) projection of 3D image data

threshold()

Threshold an object, typically to produce a mask

mask()

Mask an object, typically to produce a copy with some values zeroed out

unmask()

Make im3d image array containing values at locations defined by a mask

clampmax()

Return function that finds maximum of its inputs within a clamping range

boundingbox() `boundingbox<-`()

Get the bounding box of an image volume or object containing 3D vertices

makeboundingbox()

Construct a 3D bounding box object

origin()

Return the space origin of a 3D image object

voxdims()

Return voxel dimensions of an object

nrrd.voxdims()

Return voxel dimensions (by default absolute voxel dimensions)

xyzpos() ijkpos()

Interconvert pixel and physical coordinates

coord2ind()

Find 1D or 3D voxel indices into a 3D image given spatial coordinates

ind2coord()

Find XYZ coords corresponding to 1D indices into a 3D image

sub2ind()

Find 1D index given n-dimensional indices

imexpand.grid()

Convert locations of im3d voxel grid into XYZ coordinates

materials()

Extract or set the materials for an object

CMTK Registration

Functions to interface to the CMTK image registration suite

cmtk.bindir()

Return path to directory containing CMTK binaries

cmtk.version()

Return cmtk version or test for presence of at least a specific version

cmtkparams2affmat()

Compose homogeneous affine matrix from CMTK registration parameters

affmat2cmtkparams()

Decompose homogeneous affine matrix to CMTK registration parameters

cmtk.dof2mat()

Convert CMTK registration to homogeneous affine matrix with dof2mat

cmtk.mat2dof()

Use CMTK mat2dof to convert homogeneous affine matrix into CMTK registration

cmtk.extract_affine()

Extract affine registration from CMTK registration file or in-memory list

cmtk.reformatx()

Reformat an image with a CMTK registration using the reformatx tool

cmtk.statistics()

Calculate image statistics for a nrrd or other CMTK compatible file

cmtk.targetvolume()

Defines a target volume for a CMTK reformatx operation

cmtkreg() as.cmtkreg() is.cmtkreg()

Create and test cmtkreg objects that specify path to a CMTK registration

cmtkreglist()

Make in-memory CMTK registration list from affine matrix or CMTK parameters

cmtk.call() cmtk.system2()

Utility function to create and run calls to CMTK command line tools

Sample Data

Sample data objects (neurons, surfaces)

Cell07PNs

Cell07PNs: 40 Sample Projection Neurons from Jefferis, Potter et al 2007

kcs20

List of 20 Kenyon Cells from Chiang et al 2011 converted to dotprops objects

dl1neuron

Olfactory Projection Neuron reconstructed from EM data

MBL.surf

Surface object (hxsurf) for the left mushroom body in FCWB template space

Generic Functions

Generic versions of base functions for which we provide specialised methods for nat objects.

intersect()

Find the intersection of two collections of objects

setdiff()

Find the (asymmetric) difference between two collections of objects

subset

Subset methods for different nat objects

union()

Find the union of two collections of objects

Utility Functions

Functions primarily intended for developer use

ndigest()

Calculated normalised digest value for an object

all(<equal.dotprops>)

all.equal method tailored to dotprops objects

all(<equal.im3d>)

Check equality on data and key attributes of im3d objects

all(<equal.neuron>)

Check equality on key fields of neuron object

File formats

Support for different formats. It is generally recommended to use more generic functions such as read.neuron(s) rather than these functions.

fileformats() registerformat() getformatreader() getformatwriter()

Set or return list of registered file formats that we can read

read.cmtk()

Read CMTK TypedStream file to a list in memory

read.cmtkreg()

Read a CMTK format registration

read.morphml()

Return parsed XML or R list versions of a NeuroML file

read.neuron.fiji()

Read a neuron saved by Fiji's Simple Neurite Tracer Plugin

read.neuron.neuroml()

Read one or more neurons from a NeuroML v1 file

read.neuron.swc() read.ngraph.swc()

Read a neuron in swc file format

read.nrrd() read.nrrd.header() nrrd.datafiles()

Read NRRD files/headers into memory

read.vaa3draw()

Read Vaa3d format image data

read.amiramesh() read.amiramesh.header()

Read AmiraMesh data in binary or ascii format

write.amiramesh()

Write a 3D data object to an AmiraMesh format file

write.cmtk()

Write a suitable list to a CMTK TypedStream file on disk

write.cmtkreg()

Write out CMTK registration list to folder

write.nrrd() write.nrrd.header() write.nrrd.header.for.file()

Write data and metadata to NRRD file or create a detached NRRD (nhdr) file.

write.vtk()

Write object to VTK file

amiratype()

Return the type of an AmiraMesh file on disk or a parsed header

is.amiramesh()

Check if file is AmiraMesh format

is.fijitraces()

Check whether a file is in Fiji's simple neurite tracer format

is.neuroml()

Check whether a file is in NeuroML format

is.nrrd()

Check if a file is a NRRD file

is.swc()

Test if a file is an SWC format neuron

is.vaa3draw()

Check if a file is in the raw image format used by Hanchuan Peng's Vaa3D