Package 'nat'

Description

nat provides tools to read, analyse, plot, transform and convert neuroanatomical data, especially representations of neurons.

Neuron Objects

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 neurons or selected vertex indices can be used to subset a neuron with subset.neuron.

Collections of Neurons

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 using the nlapply function, which also provides options for progress bars and simple parallelisation.

Transformations

neuron or dotprops objects can be transformed from e.g. sample to template brain space using affine or non-rigid registrations. nat has built in support for registrations 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.

3D Image Data

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.

Surface Data

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.

rgl Package

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.

plotly Package

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.

File Formats

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.

Package Options

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

nat.use_natcpp

Whether or not to use the natcpp package (if available) to accelerate some basic neuron processing functions. Set to FALSE if you don't want this to happen.

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.

Author(s)

Maintainer: Gregory Jefferis [email protected] (ORCID)

Authors:

• James Manton (ORCID)

• Sridhar Jagannathan (ORCID)

Other contributors:

• Dominik Krzeminski (ORCID) [contributor]

See Also

neuron, dotprops, neuronlist, nlapply, plot3d, xform, im3d, read.hxsurf, rgl which is used for visualisation, fileformats, read.neurons, cmtk.

Description

[.neuronlistfh extracts either a sublist from a neuronlistfh (converting it to a regular in memory list in the process) or its attached data.frame.

Usage

## S3 method for class 'neuronlistfh'
x[i, j, drop]

Arguments

Details

Note that if i is a numeric or logical indexing vector, it will be converted internally to a vector of names by using the (sorted) names of the objects in x (i.e. names(x)[i])

Value

A new in-memory neuronlist or when using two subscripts, a data.frame - see examples.

See Also

neuronlistfh, [.neuronlist, [.data.frame, [<-.data.frame,

Other neuronlistfh: neuronlistfh(), read.neuronlistfh(), remotesync(), write.neuronlistfh()

Examples

# make a test neuronlistfh backed by a temporary folder on disk
tf=tempfile('kcs20fh')
kcs20fh<-as.neuronlistfh(kcs20, dbdir=tf)

# get first neurons as an in memory neuronlist
class(kcs20fh[1:3])

# extract attached data.frame
str(kcs20fh[,])
# or part of the data.frame
str(kcs20fh[1:2,1:3])

# data.frame assignment (this one changes nothing)
kcs20fh[1:2,'gene_name'] <- kcs20fh[1:2,'gene_name']

# clean up
unlink(tf, recursive=TRUE)

Description

If x is one number or 3-vector, multiply coordinates by that If x is a 4-vector, multiply xyz and diameter TODO Figure out how to document arithmetic functions in one go

Usage

## S3 method for class 'neuronlist'
x * y

## S3 method for class 'neuronlist'
x + y

## S3 method for class 'neuronlist'
x - y

## S3 method for class 'neuronlist'
x / y

Arguments

Value

modified neuronlist

See Also

Other neuronlist: is.neuronlist(), neuronlist(), neuronlist-dataframe-methods, neuronlistfh(), neuronlistz(), nlapply(), read.neurons(), write.neurons()

Examples

mn2<-Cell07PNs[1:10]*2

Description

Decompose homogeneous affine matrix to CMTK registration parameters

Usage

affmat2cmtkparams(matrix, centre = c(0, 0, 0))

Arguments

Details

The version attribute of the resultant matrix marks this as compliant with CMTK>v2.4 (~ Dec 2013) when a bug in affine matrix (de)composition was fixed.

Value

5x3 matrix of CMTK registration parameters with a version attribute

See Also

Other cmtk-geometry: cmtk.dof2mat(), cmtk.mat2dof(), cmtkparams2affmat()

Description

all.equal method tailored to dotprops objects

Usage

## S3 method for class 'equal.dotprops'
all(target, current, check.attributes = FALSE, absoluteVectors = TRUE, ...)

Arguments

Details

This method is required because the direction vectors are computed using an eigenvector decomposition where the sign of the eigenvector is essentially random and subject to small numerical instabilities. Therefore it does not usually make sense to check the value of vect exactly.

Examples

# equal using default 
kc1=kcs20[[1]]
kc1.recalc=dotprops(kc1)
# not equal due to differences in attributes and vectors
all.equal.default(kc1.recalc, kc1)
# still not equal because of tangent vector flipping
all.equal.default(kc1.recalc, kc1, check.attributes=FALSE)
# equal using appropriate method
stopifnot(isTRUE(all.equal(kc1.recalc, kc1)))
# NB identical when recalculated on same setup from same data
stopifnot(isTRUE(all.equal.default(kc1.recalc, dotprops(kc1))))

Description

Check equality on data and key attributes of im3d objects

Usage

## S3 method for class 'equal.im3d'
all(
  target,
  current,
  tolerance = 1e-06,
  attrsToCheck = c("BoundingBox"),
  attrsToCheckIfPresent = c("dim", "names", "dimnames", "x", "y", "z"),
  CheckSharedAttrsOnly = FALSE,
  ...
)

Arguments

See Also

all.equal

Description

Check equality on key fields of neuron object

Usage

## S3 method for class 'equal.neuron'
all(
  target,
  current,
  tolerance = 1e-06,
  check.attributes = FALSE,
  fieldsToCheck = c("NumPoints", "StartPoint", "BranchPoints", "EndPoints", "NumSegs",
    "SegList", "d"),
  fieldsToCheckIfPresent = c("NeuronName", "nTrees", "SubTrees"),
  fieldsToExclude = character(),
  CheckSharedFieldsOnly = FALSE,
  ...
)

Arguments

See Also

all.equal

Examples

x=Cell07PNs[[1]]
y=x
y$NeuronName='rhubarb'
# NOT TRUE
all.equal(x, y)
# TRUE
all.equal(x, y, fieldsToExclude='NeuronName')

Description

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

Usage

amiratype(x, bytes = NULL)

Arguments

Details

Note that when checking a file we first test if it is an AmiraMesh file (fast, especially when bytes!=NULL) before reading the header and determining content type (slow).

Value

character vector (NA_character_ when file invalid)

See Also

Other amira: is.amiramesh(), read.amiramesh(), read.hxsurf(), write.hxsurf()

Description

For as.data.frame, when there is no attached data.frame the result will be a data.frame with 0 columns but an appropriate number of rows, named by the objects in the neuronlist.

data.frame<- methods set the data frame attached to an object. At present this is only used for neuronlist objects.

Usage

## S3 method for class 'neuronlist'
as.data.frame(x, row.names = names(x), optional = FALSE, ...)

data.frame(x) <- value

## S3 replacement method for class 'neuronlist'
data.frame(x) <- value

Arguments

Value

for as.data.frame.neuronlist, a data.frame with length(x) rows, named according to names(x) and containing the columns from the attached data.frame, when present.

for data.frame<-.neuronlist, a neuronlist with the attached data.frame.

See Also

data.frame, neuronlist

Examples

head(as.data.frame(kcs20))

# add additional variables
str(as.data.frame(kcs20, i=seq(kcs20), abc=LETTERS[seq(kcs20)]))
# stop character columns being turned into factors
newdf <- as.data.frame(kcs20, i=seq(kcs20), abc=LETTERS[seq(kcs20)], 
  stringsAsFactors=FALSE)
str(newdf)
data.frame(kcs20)=newdf

Description

Convert an object to a nat hxsurf object

Usage

as.hxsurf(x, ...)

## S3 method for class 'mesh3d'
as.hxsurf(x, region = "Interior", col = NULL, ...)

Arguments

Details

hxsurf objects are based on the format of Amira's surface objects (see read.hxsurf). They have the ability to include multiple distinct regions. However, at the moment the only method that we provide converts mesh3d objects, which can only include one region.

Value

A new surface object of class hxsurf (see read.hxsurf) for details.

See Also

as.mesh3d

Other hxsurf: as.mesh3d(), materials(), plot3d.hxsurf(), read.hxsurf(), subset.hxsurf(), write.hxsurf()

Examples

tet=tetrahedron3d(col='red')
teth=as.hxsurf(tet)

plot3d(teth)

Description

Convert a suitable object to an im3d object.

Usage

as.im3d(x, ...)

## S3 method for class 'im3d'
as.im3d(x, ...)

## S3 method for class 'matrix'
as.im3d(x, voxdims, origin = NULL, BoundingBox = NULL, ...)

Arguments

Details

At present the only interesting method in nat is as.im3d.matrix which can be used to convert a matrix of 3D points into a 3D volume representation. ind2coord can be used to do the reverse: convert a set of 3D coords to an im3d volume.

Other than that, this is a largely a placeholder function with the expectation that other packages may wish to provide suitable methods.

as.im3d.matrix can accept any object that can be converted to an im3d object in the voxdims argument This will completely specify the dims, voxdims, origin etc. Any value passed to those parameters will be ignored. This can be useful for producing a new im3d to match a target image on disk or a nat.templatebrains::templatebrain object. See examples.

See Also

im3d, ind2coord

im3d, as.im3d

Other im3d: boundingbox(), im3d(), im3d-coords, im3d-io, imexpand.grid(), imslice(), is.im3d(), mask(), origin(), projection(), threshold(), unmask(), voxdims()

Examples

## convert a list of neurons into an image volume
im=as.im3d(xyzmatrix(kcs20), voxdims=c(1, 1, 1),
  BoundingBox=c(250, 410, 0, 130, 0, 120))
## Not run: 
write.im3d(im, 'kc20volume.nrrd')

## use image dimensions of an image on disk
# nb note use of ReadData = FALSE so that we just fetch the dimensions of
# the target image
diskim=read.im3d("/path/to/my/image.nrrd", ReadData = FALSE)
im=as.im3d(xyzmatrix(kcs20), diskim)

## use image dimensions of JFRC2 template brain to define the image space
library(nat.flybrains)
im=as.im3d(xyzmatrix(kcs20), JFRC2)

## End(Not run)

Description

as.mesh3d.ashape3d converts an alphashape3d::ashape3d object into a nat/rgl compatible mesh3d surface

Note that this provides a link to the Rvcg package

as.mesh3d.boundingbox converts a nat boundingbox object into an rgl compatible mesh3d object.

Usage

## S3 method for class 'ashape3d'
as.mesh3d(x, tri_to_keep = 2L, ...)

## S3 method for class 'hxsurf'
as.mesh3d(x, Regions = NULL, material = NULL, drop = TRUE, ...)

## S3 method for class 'boundingbox'
as.mesh3d(x, ...)

Arguments

Details

An alpha shape is a generalisation of a convex hull enclosing a set of points. Unlike a convex hull, the resultant surface can be partly concave allowing the surface to more closely follow the set of points.

In this implementation, the parameter alpha is a scale factor with units of length that defines a spatial domain. When alpha is larger the alpha shape approaches the convex hull; when alpha is smaller the alpha shape has a greater number of faces / vertices i.e. it follows the points more closely.

Value

a mesh3d object which can be plotted and manipulated using rgl and nat packages.

See Also

ashape3d, mesh3d

as.mesh3d, tmesh3d, as.hxsurf, read.hxsurf

Other hxsurf: as.hxsurf(), materials(), plot3d.hxsurf(), read.hxsurf(), subset.hxsurf(), write.hxsurf()

Examples

library(alphashape3d)
kcs20.a=ashape3d(xyzmatrix(kcs20), alpha = 10)
plot(kcs20.a)

# convert to mesh3d
kcs20.mesh=as.mesh3d(kcs20.a)

# check that all points are inside mesh
all(pointsinside(kcs20, kcs20.mesh))
# and show that we can also use the alphashape directly
all(pointsinside(kcs20, kcs20.a))

nclear3d()
wire3d(kcs20.mesh)
plot3d(kcs20, col=type, lwd=2)

bb=boundingbox(kcs20)
mbb=as.mesh3d(bb)

plot3d(kcs20)
# simple plot
plot3d(bb)
shade3d(mbb, col='red', alpha=0.3)

Description

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

Usage

as.neuronlist(l, ...)

## Default S3 method:
as.neuronlist(l, df = NULL, AddClassToNeurons = TRUE, ...)

Arguments

Details

Note that as.neuronlist can cope with both neurons and dotprops objects but AddClassToNeurons will only apply to things that look like neurons but don't have a class of neuron.

See neuronlist details for more information.

Value

neuronlist with attr('df')

See Also

is.neuronlist,is.neuron,is.dotprops

Description

convert neuronlistfh to a regular (in memory) neuronlist

Usage

## S3 method for class 'neuronlistfh'
as.neuronlist(l, ...)

Arguments

Description

Set the bounding box of an im3d object

Usage

boundingbox(x, ...)

## S3 method for class 'im3d'
boundingbox(x, dims = dim(x), ...)

## S3 method for class 'character'
boundingbox(x, ...)

## Default S3 method:
boundingbox(x, na.rm = FALSE, ...)

boundingbox(x) <- value

Arguments

Details

The bounding box is defined as the position of the voxels at the two opposite corners of the cuboid encompassing an image, when each voxel is assumed to have a single position (sometimes thought of as its centre) and no physical extent. When written as a vector it should look like: c(x0,x1,y0,y1,z0,z1). When written as a matrix it should look like: rbind(c(x0,y0,z0),c(x1,y1,z1)) where x0,y0,z0 is the position of the origin.

Note that there are two competing definitions for the physical extent of an image that are discussed e.g. https://teem.sourceforge.net/nrrd/format.html. The definition that makes most sense depends largely on whether you think of a pixel as a little square with some defined area (and therefore a voxel as a cube with some defined volume) or you take the view that you can only define with certainty the grid points at which image data was acquired. The first view implies a physical extent which we call the bounds=dim(x) * c(dx,dy,dz); the second is defined as BoundingBox=dim(x)-1 * c(dx,dy,dz) and assumes that the extent of the image is defined by a cuboid including the sample points at the extreme corner of the grid. Amira takes this second view and this is the one we favour given our background in microscopy. If you wish to convert a bounds type definition into an im3d BoundingBox, you should pass the argument input='bounds'.

boundingbox.default is designed to be used on objects that contain 3D point information. This includes any object for which an xyzmatrix method is defined including matrix or data.frame objects describing 3D points as well as specialised classes such as neuron, neuronlist, rgl mesh3d objects.

Value

a matrix with 2 rows and 3 columns with class='boundingbox' or NULL when missing.

See Also

makeboundingbox, plot3d.boundingbox

Other im3d: as.im3d(), im3d(), im3d-coords, im3d-io, imexpand.grid(), imslice(), is.im3d(), mask(), origin(), projection(), threshold(), unmask(), voxdims()

Examples

# bounding box for a neuron
boundingbox(Cell07PNs[[1]])

Description

Concatenate HyperSurface objects

Usage

## S3 method for class 'hxsurf'
c(...)

Arguments

Value

new hxsurf

Examples

h1 = as.hxsurf(icosahedron3d(), 'a')
h2 = as.hxsurf(tetrahedron3d()+1, 'b')
h3 = as.hxsurf(icosahedron3d()+3, 'c')
hc = c(h1, h2, h3)

Description

Combine multiple neuronlists into a single list

Usage

## S3 method for class 'neuronlist'
c(..., recursive = FALSE)

Arguments

Details

Uses rbind.fill to join any attached dataframes, so missing values are replaced with NAs.

See Also

c

Examples

stopifnot(all.equal(kcs20[1:2],c(kcs20[1],kcs20[2])))

Description

These R lists (which have additional class neuronlist) contain 40 traced olfactory projection neurons from Jefferis, Potter et al 2007 that have been transformed onto the IS2 template brain (Cachero, Ostrovsky et al 2010).

References

Jefferis G.S.X.E., Potter C.J., Chan A.M., Marin E.C., Rohlfing T., Maurer C.R.J., and Luo L. (2007). Comprehensive maps of Drosophila higher olfactory centers: spatially segregated fruit and pheromone representation. Cell 128 (6), 1187–1203. doi:10.1016/j.cell.2007.01.040

Cachero S., Ostrovsky A.D., Yu J.Y., Dickson B.J., and Jefferis G.S.X.E. (2010). Sexual dimorphism in the fly brain. Curr Biol 20 (18), 1589–601. doi:10.1016/j.cub.2010.07.045

See Also

head.neuronlist, with.neuronlist, dl1neuron

Other nat-data: MBL.surf, kcs20

Examples

head(Cell07PNs)
table(with(Cell07PNs,Glomerulus))

Description

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

Usage

clampmax(xmin, xmax, replace.infinite = NA_real_)

Arguments

Details

Note that by default infinite values in the input vector are converted to NAs before the being compared with the clampmax range.

Value

A function with signature f(x, ..., na.rm)

Examples

## Not run: 
LHMask=read.im3d(system.file('tests/testthat/testdata/nrrd/LHMask.nrrd',package='nat'))
d=unmask(rnorm(sum(LHMask),mean=5,sd=5),LHMask)
op=par(mfrow=c(1,2))
rval=image(projection(d,projfun=max))
image(projection(d,projfun=clampmax(0,10)),zlim=rval$zlim)
par(op)

## End(Not run)

Description

The Computational Morphometry Toolkit (CMTK) is the default image registration toolkit supported by nat. An external CMTK installation is required in order to apply CMTK registrations. This function attempts to locate the full path to the CMTK executable files and can query and set an option.

Usage

cmtk.bindir(
  firstdir = getOption("nat.cmtk.bindir"),
  extradirs = c("~/bin", "/usr/local/lib/cmtk/bin", "/usr/local/bin", "/opt/local/bin",
    "/opt/local/lib/cmtk/bin/", "/Applications/IGSRegistrationTools/bin",
    "C:\\cygwin64\\usr\\local\\lib\\cmtk\\bin",
    "C:\\Program Files\\CMTK-3.3\\CMTK\\lib\\cmtk\\bin"),
  set = FALSE,
  check = FALSE,
  cmtktool = "gregxform"
)

Arguments

Details

Queries options('nat.cmtk.bindir') if firstdir is not specified. If that does not contain the appropriate binaries, it will look in the system PATH for the cmtk wrapper script installed by most recent cmtk installations.

Failing that, it will look for the cmtk tool specified by cmtktool, first in the path and then a succession of plausible places until it finds something. Setting options(nat.cmtk.bindir=NA) or passing firstdir=NA will stop the function from trying to locate CMTK, always returning NULL unless check=TRUE, in which case it will error out.

Value

Character vector giving path to CMTK binary directory or NULL when this cannot be found.

Installation

It is recommended to install released CMTK versions available from the NITRC website. A bug in composition of affine transformations from CMTK parameters in the CMTK versions <2.4 series means that CMTK>=3.0 is strongly recommended. CMTK v3 registrations are not backwards compatible with CMTK v2, but CMTK v3 can correctly interpret and convert registrations from earlier versions.

On Windows, when set=TRUE, cmtk.bindir will also check that the cygwin bin directory is in the PATH. If it is not, then it is added for the current R session. This should solve issues with missing cygwin DLLs.

See Also

options

Examples

message(ifelse(is.null(d<-cmtk.bindir()), "CMTK not found!",
               paste("CMTK is at:",d)))
## Not run: 
# set options('nat.cmtk.bindir') according to where cmtk was found
op=options(nat.cmtk.bindir=NULL)
cmtk.bindir(set=TRUE)
options(op)
## End(Not run)

Description

cmtk.call processes arguments into a form compatible with CMTK command line tools.

cmtk.system2 actually calls a cmtk tool using a call list produced by cmtk.call

Usage

cmtk.call(
  tool,
  PROCESSED.ARGS = NULL,
  ...,
  FINAL.ARGS = NULL,
  RETURN.TYPE = c("string", "list")
)

cmtk.system2(cmtkcall, moreargs = NULL, ...)

Arguments

Details

cmtk.call processes arguments in ... as follows:

argument names

will be converted from arg.name to --arg-name

logical vectors

(which must be of length 1) will be passed on as --arg-name

character vectors

(which must be of length 1) will be passed on as --arg-name arg i.e. quoting is left up to callee.

numeric vectors

will be collapsed with commas if of length greater than 1 and then passed on unquoted e.g. target.offset=c(1,2,3) will result in --target-offset 1,2,3

Value

Either a string of the form "<tool> <PROCESSED.ARGS> <...> <FINAL.ARGS>" or a list containing elements

• command A character vector of length 1 indicating the full path to the CMTK tool, shell quoted for protection.

• args A character vector of arguments of length 0 or greater.

See the help of system2 for details.

See Also

cmtk.bindir

Examples

## Not run: 
cmtk.call("reformatx",'--outfile=out.nrrd', floating='floating.nrrd',
  mask=TRUE, target.offset=c(1,2,3), FINAL.ARGS=c('target.nrrd','reg.list'))
# get help for a cmtk tool
system(cmtk.call('reformatx', help=TRUE))

## End(Not run)
## Not run: 
cmtk.system2(cmtk.call('mat2dof', help=TRUE, RETURN.TYPE="list"))
# capture response into an R variable
helptext=cmtk.system2(cmtk.call('mat2dof', help=TRUE, RETURN.TYPE="list"),
  stdout=TRUE)

## End(Not run)

Description

Convert CMTK registration to homogeneous affine matrix with dof2mat

Usage

cmtk.dof2mat(reg, Transpose = TRUE, version = FALSE)

Arguments

Details

Transpose is true by default since this results in the orientation of cmtk output files matching the orientation in R. Do not change this unless you're sure you know what you're doing!

Value

4x4 transformation matrix

See Also

Other cmtk-commandline: cmtk.mat2dof()

Other cmtk-geometry: affmat2cmtkparams(), cmtk.mat2dof(), cmtkparams2affmat()

Description

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

Usage

cmtk.extract_affine(r, outdir)

Arguments

Value

When outdir is missing a list containing the registration parameters Otherwise NULL invisibly.

See Also

cmtkreglist

Other cmtk-io: read.cmtk(), read.cmtkreg(), write.cmtk(), write.cmtkreg()

Description

Use CMTK mat2dof to convert homogeneous affine matrix into CMTK registration

Usage

cmtk.mat2dof(m, f = NULL, centre = NULL, Transpose = TRUE, version = FALSE)

Arguments

Details

If no output file is supplied, 5x3 params matrix will be returned directly. Otherwise a logical will be returned indicating success or failure at writing to disk.

Transpose is true by default since this results in an R matrix with the transpose in the fourth column being correctly interpreted by cmtk.

Value

5x3 matrix of CMTK registration parameters or logical

See Also

Other cmtk-commandline: cmtk.dof2mat()

Other cmtk-geometry: affmat2cmtkparams(), cmtk.dof2mat(), cmtkparams2affmat()

Description

Reformat an image with a CMTK registration using the reformatx tool

Usage

cmtk.reformatx(
  floating,
  registrations,
  output,
  target,
  mask = FALSE,
  direction = NULL,
  interpolation = c("linear", "nn", "cubic", "pv", "sinc-cosine", "sinc-hamming"),
  dryrun = FALSE,
  Verbose = TRUE,
  MakeLock = TRUE,
  OverWrite = c("no", "update", "yes"),
  filesToIgnoreModTimes = NULL,
  ...
)

Arguments

Details

Note that if you are reformatting a mask then you will need to change the interpolation to "nn", since interpolating between e.g. mask levels 72 and 74 with 73 may have unintended consequences. Presently we have no way of knowing whether an image should be treated as a mask, so the interpolation must be handled manually.

Value

the path to the output image (whether or not it was re-created afresh) or NA_character_ if no output was possible.

See Also

cmtk.bindir, cmtk.call, makelock, RunCmdForNewerInput

Examples

## Not run: 
cmtk.reformatx('myimage.nrrd', target='template.nrrd',
  registrations='template_myimage.list')

# get full listing of command line options  
system(cmtk.call('reformatx', help=TRUE))

## End(Not run)

Description

Calculate image statistics for a nrrd or other CMTK compatible file

Usage

cmtk.statistics(
  f,
  mask,
  imagetype = c("greyscale", "label"),
  masktype = c("label", "binary"),
  ...,
  Verbose = FALSE
)

Arguments

Details

When given a label mask, returns a dataframe with a row for each level of the label field.

Note that the Entropy column (sometimes H, sometimes Entropy) will always be named Entropy in the returned dataframe.

Value

data.frame describing results with the following columns when image f is of imagetype='greyscale' (optionally with a mask):

• MaskLevel (only present when using a mask) the integer value of the label field for this region

• min The minimum voxel value within the current region

• max The maximum voxel value within the current region

• mean The mean voxel value within the current region

• sdev The standard deviation of voxel values within the current region

• n The count of all voxel within the region (irrespective of their value)

• Entropy Information theoretic entropy of voxel value distribution within region

• sum Sum of voxel values within the region

When image f is of imagetype='label', the following results are returned:

• level The integer value of the label field for this region

• count The number of voxels in this region

• surface The surface area of this region

• volume The volume of this region

• X,Y,Z 3D coordinates of the centroid of this region

Examples

## Not run: 
cmtk.statistics('someneuron.nrrd', mask='neuropilregionmask.nrrd')
cmtk.statistics('somelabelfield.nrrd', imagetype='label')

## End(Not run)

Description

cmtk.targetvolume.list is designed to cope with any user-defined class for which an as.im3d method exists. Presently the only example in the nat.* ecosystem is nat.templatebrains::as.im3d.templatebrain.

Usage

cmtk.targetvolume(target, ...)

## S3 method for class 'im3d'
cmtk.targetvolume(target, ...)

## S3 method for class 'list'
cmtk.targetvolume(target, ...)

## S3 method for class 'character'
cmtk.targetvolume(target, ...)

## Default S3 method:
cmtk.targetvolume(target, ...)

Arguments

Details

if the character vector specifies an AmiraMesh file, it will be converted to a bare im3d object and then to an appropriate '–target-grid' specification.

Value

a character vector specifying the full cmtk reformatx '–target' or '–target-grid' argument

Examples

## Not run: 
# see https://github.com/natverse/nat.flybrains
library(nat.flybrains)
cmtk.targetvolume(FCWB)

## End(Not run)

Description

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

Usage

cmtk.version(minimum = NULL)

Arguments

Details

NB this function has the side effect of setting an option nat.cmtk.version the first time that it is run in the current R session.

Value

returns numeric_version representation of CMTK version or if minimum is not NULL, returns a logical indicating whether the installed version exceeds the current version. If CMTK is not installed returns NA.

See Also

cmtk.bindir, cmtk.dof2mat

Examples

## Not run: 
cmtk.version()
cmtk.version('3.2.2')

## End(Not run)

Description

Compose homogeneous affine matrix from CMTK registration parameters

Usage

cmtkparams2affmat(
  params = NULL,
  tx = 0,
  ty = 0,
  tz = 0,
  rx = 0,
  ry = 0,
  rz = 0,
  sx = 1,
  sy = 1,
  sz = 1,
  shx = 0,
  shy = 0,
  shz = 0,
  cx = 0,
  cy = 0,
  cz = 0,
  legacy = NA
)

Arguments

Details

If the legacy parameter is not set explicitly, then it will be set to TRUE if params has a version attribute <2.4 or FALSE otherwise.

translation and centre components are assumed to be in physical coordinates.

Value

4x4 homogeneous affine transformation matrix

See Also

Other cmtk-geometry: affmat2cmtkparams(), cmtk.dof2mat(), cmtk.mat2dof()

Description

cmtkreg creates an object of class cmtkreg that describes one (or more) CMTK registrations. This is simply a character vector that also has class cmtkreg.

as.cmtkreg converts objects to class cmtkreg, minimally just by adding an appropriate class attribute.

is.cmtkreg checks if an object is a cmtk registration either by checking class (default), or inspecting file. Supports CMTK parameter files as well as NRRD deformation fields.

Usage

cmtkreg(x, returnDir = NA)

as.cmtkreg(x, ...)

## S3 method for class 'matrix'
as.cmtkreg(x, ...)

## S3 method for class 'reglist'
as.cmtkreg(x, ...)

## Default S3 method:
as.cmtkreg(x, ...)

is.cmtkreg(x, filecheck = c("none", "exists", "magic"))

Arguments

Description

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

Usage

cmtkreglist(x, centre = c(0, 0, 0), reference = "dummy", floating = "dummy")

Arguments

Details

Note that this uses the modern CMTK notation of floating_study rather than model_study as used by IGSParamsToIGSRegistration (which results in an implicit inversion by CMTK tools).

Note that the reference and floating fields have no impact on the transformation encoded in the resultant .list folder and can be overridden on the command line of CMTK tools.

Value

list of class cmtkreg containing registration parameters suitable for write.cmtkreg

See Also

write.cmtkreg, affmat2cmtkparams, cmtkreg

Description

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

Usage

coord2ind(coords, ...)

## Default S3 method:
coord2ind(
  coords,
  imdims,
  voxdims = NULL,
  origin = NULL,
  linear.indices = TRUE,
  aperm = NULL,
  Clamp = FALSE,
  CheckRanges = !Clamp,
  ...
)

Arguments

Details

coord2ind is designed to cope with any user-defined class for which an as.im3d method exists. Presently the only example in the nat.* ecosystem is nat.templatebrains::as.im3d.templatebrain. The existence of an as.im3d method implies that voxdims,origin, and dim functions can be called. This is the necessary information required to convert i,j,k logical indices into x,y,z spatial indices.

See Also

ind2coord, sub2ind, ijkpos

Examples

coord2ind(cbind(1,2,3), imdims = c(1024,512,218), 
  voxdims = c(0.622088, 0.622088, 0.622088), origin = c(0,0,0))
## Not run: 
## repeat but using a templatebrain object to specify the coordinate system
library(nat.flybrains)
coord2ind(cbind(1,2,3), JFRC2)

## End(Not run)

Description

Cycle through and manually re-root neurons using an rgl window. This will typically be used for manual identification of the soma of a neuron.

Usage

correct_root(someneuronlist, brain = NULL)

Arguments

Value

a matrix of 3D points

Examples

## Not run: 
## NB these neurons actually have their somata chopped off
correctedsomas = correct_root(Cell07PNs[1:3])
plot3d(correctedsomas, soma=TRUE)

## End(Not run)

Description

This function returns a list (containing the order of nodes) travelled using a depth first search starting from the given node.

Usage

distal_to(
  x,
  node.idx = NULL,
  node.pointno = NULL,
  root.idx = NULL,
  root.pointno = NULL
)

Arguments

Value

Integer 1-based indices into the point array of points that are distal to the specified node(s) when traversing the neuron from the root to that node. Will be a vector if only one node is specified, otherwise a list is returned

See Also

subset.neuron, prune

Examples

## Use EM  finished DL1 projection neuron

## subset to part of neuron distal to a tag "SCHLEGEL_LH"
# nb distal_to can accept either the PointNo vertex id or raw index as a
# pivot point
dl1.lh=subset(dl1neuron, distal_to(dl1neuron,
  node.pointno = dl1neuron$tags$SCHLEGEL_LH))
plot(dl1neuron,col='blue', WithNodes = FALSE)
plot(dl1.lh, col='red', WithNodes = FALSE, add=TRUE)

Description

A DL1 olfactory projection neuron object traced in CATMAID from the FAFB whole brain EM volume. This has a complex morphology that makes a good test for pruning and simplification strategies.

Usage

dl1neuron

Format

A neuron object with additional class catmaidneuron

See Also

Cell07PNs

Description

dotprops makes dotprops representation from raw 3D points (extracting vertices from S3 objects that have them)

dotprops.character makes dotprops objects from one or more files on disk (typically binary segmentations saved as NRRDs). x can a vector of paths or be a directory (in which case pattern can be used to restrict the files to read). The ... argument is passed first to nlapply (if there is more than one file) and then to dotprops.default.

dotprops.dotprops will default to the original vale of k and copy over all attributes that are not set by dotprops.default.

dotprops.neuronlist will run for every object in the neuronlist using nlapply. ... arguments will be passed to nlapply in addition to the named argument OmitFailures.

Usage

is.dotprops(x)

as.dotprops(x, ...)

dotprops(x, ...)

## S3 method for class 'character'
dotprops(x, pattern = NULL, OmitFailures = NA, ...)

## S3 method for class 'dotprops'
dotprops(x, k = attr(x, "k"), ...)

## S3 method for class 'im3d'
dotprops(x, ...)

## S3 method for class 'neuronlist'
dotprops(x, ..., OmitFailures = NA)

## S3 method for class 'neuron'
dotprops(x, Labels = NULL, resample = NA, topo = FALSE, ...)

## Default S3 method:
dotprops(x, k = NULL, Labels = NULL, na.rm = FALSE, topo_features = NULL, ...)

Arguments

Details

k will default to 20 nearest neighbours when unset (i.e. when it has default value of NA) unless x is a dotprops object (when the original value of k is reused).

References

The dotprops format is essentially identical to that developed in:

Masse N.Y., Cachero S., Ostrovsky A., and Jefferis G.S.X.E. (2012). A mutual information approach to automate identification of neuronal clusters in Drosophila brain images. Frontiers in Neuroinformatics 6 (00021). doi:10.3389/fninf.2012.00021

See Also

nlapply

Examples

## Not run: 
# process a single file on disk
dp=dotprops.character('~/skeleton-nrrds/file01.nrrd', k=5)
# process a whole directory of files
dps=dotprops.character('~/skeleton-nrrds/', OmitFailures=T, k=5)

## End(Not run)

Description

fileformats returns format names, a format definition list or a table of information about the formats that match the given filter conditions.

registerformat registers a format in the io registry

getformatreader gets the function to read a file

getformatwriter gets the function to write a file

Usage

fileformats(
  format = NULL,
  ext = NULL,
  read = NULL,
  write = NULL,
  class = NULL,
  rval = c("names", "info", "all")
)

registerformat(
  format = NULL,
  ext = format,
  read = NULL,
  write = NULL,
  magic = NULL,
  magiclen = NA_integer_,
  class = NULL
)

getformatreader(file, class = NULL)

getformatwriter(format = NULL, file = NULL, ext = NULL, class = NULL)

Arguments

Details

if a format argument is passed to fileformats it will be matched with partial string matching and iif a unique match exists that will be returned.

getformatreader starts by reading a set number of bytes from the start off the current file and then checks using file extension and magic functions to see if it can identify the file. Presently formats are in a queue in alphabetical order, dispatching on the first match.

Value

• fileformats returns a character vector, matrix or list according to the value of rval.

• getformatreader returns a list. The reader can be accessed with $read and the format can be accessed by $format.

• getformatwriter returns a list. The writer can be accessed with $write.

getformatwriter output file

If getformatwriter is passed a file argument, it will be processed based on the registered fileformats information and the ext argument to give a final output path in the $file element of the returned list.

If ext='.someext' getformatwriter will use the specified extension to overwrite the default value returned by fileformats.

If ext=NULL, the default, and file='somefilename.someext' then file will be untouched and ext will be set to 'someext' (overriding the value returned by fileformats).

If file='somefile_without_extension' then the supplied or calculated extension will be appended to file.

If ext=NA then the input file name will not be touched (even if it has no extension at all).

Note that if ext=NULL or ext=NA, then only the specified format or, failing that, the file extension will be used to query the fileformats database for a match.

See write.neuron for code to make this discussion more concrete.

See Also

write.neuron

Examples

# information about the currently registered file formats
fileformats(rval='info')
## Not run: 
registerformat("swc",read=read.swc,write=read.swc,magic=is.swc,magiclen=10,
  class='neuron')

## End(Not run)
swc=tempfile(fileext = '.swc')
write.neuron(Cell07PNs[[1]], swc)
stopifnot(isTRUE(getformatreader(swc)$format=='swc'))
unlink(swc)

Description

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

Usage

find.neuron(
  sel3dfun = select3d(),
  indices = names(db),
  db = getOption("nat.default.neuronlist"),
  threshold = 0,
  invert = FALSE,
  rval = c("names", "data.frame", "neuronlist")
)

Arguments

Details

Uses subset.neuronlist, so can work on dotprops or neuron lists.

Value

Character vector of names of selected neurons, neuronlist, or data.frame of attached metadata according to the value of rval.

See Also

select3d, find.soma, subset.neuronlist

Examples

## Not run: 
plot3d(kcs20)
# draw a 3D selection e.g. around tip of vertical lobe when ready
find.neuron(db=kcs20)
# would return 9 neurons
# make a standalone selection function
vertical_lobe=select3d()
find.neuron(vertical_lobe, db=kcs20)
# use base::Negate function to invert the selection function 
# i.e. choose neurons that do not overlap the selection region
find.neuron(Negate(vertical_lobe), db=kcs20)

## End(Not run)

Description

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

Usage

find.soma(
  sel3dfun = select3d(),
  indices = names(db),
  db = getOption("nat.default.neuronlist"),
  invert = FALSE,
  rval = c("names", "neuronlist", "data.frame")
)

Arguments

Details

Can work on neuronlists containing neuron objects or neuronlists whose attached data.frame contains soma positions specified in columns called X,Y,Z .

Value

Character vector of names of selected neurons

See Also

select3d, subset.neuronlist, find.neuron

Description

Flip an array, matrix or vector about an axis

Usage

flip(x, ...)

## S3 method for class 'array'
flip(x, flipdim = "X", ...)

Arguments

Details

Note that dimensions 1 and 2 for R matrices will be rows and columns, respectively, which does not map easily onto the intuition of a 2D image matrix where the X axis would typically be thought of as running from left to right on the page and the Y axis would run from top to bottom.

Description

Assigns to each node a distance from cell body.

Usage

get_topo_features(n)

get_distance_to_soma(n)

Arguments

Value

list with distance and Reversed Strahler order features per node.

vector with distances from soma

See Also

dotprops, ngraph

Examples

get_topo_features(Cell07PNs[[1]])
get_distance_to_soma(Cell07PNs[[1]])

Description

Return root, end, or branchpoints of an igraph object

Usage

graph.nodes(
  x,
  type = c("root", "end", "branch"),
  original.ids = "name",
  exclude.isolated = TRUE
)

Arguments

Details

This function underlies rootpoints.igraph methods and friends. It is conceived of as slightly lower level and end users would normally use the rootpoints methods.

graph.nodes should work for any igraph object (including ngraph objects, which inherit from igraph). However the graph must be directed in order to return a root point

See Also

rootpoints, ngraph

Examples

ng=as.ngraph(Cell07PNs[[1]])
# set some arbitrary vertex identifiers
igraph::vertex_attr(ng, 'name') <-sample(500, nvertices(ng))
# return those identifiers
graph.nodes(ng, type = 'end')
# ... or raw vertex indices
graph.nodes(ng,type = 'end', original.ids = FALSE)

Description

im3d objects consist of a data array with attributes defining the spatial positions at which the voxels are located. There should always be a BoundingBox attribute which defines the physical extent of the volume in the same manner as the Amira 3D visualisation and analysis software. This corresponds to the node centers option in the NRRD format.

Usage

im3d(
  x = numeric(0),
  dims = NULL,
  voxdims = NULL,
  origin = NULL,
  BoundingBox = NULL,
  bounds = NULL,
  ...
)

Arguments

Details

We follow Amira's convention of setting the bounding box equal to voxel dimension (rather than 0) for any dimension with only 1 voxel.

Value

An array with additional class im3d

See Also

Other im3d: as.im3d(), boundingbox(), im3d-coords, im3d-io, imexpand.grid(), imslice(), is.im3d(), mask(), origin(), projection(), threshold(), unmask(), voxdims()

Description

xyzpos converts pixel coordinates to physical coordinates

ijkpos converts physical coordinates to pixel coordinates

Usage

xyzpos(d, ijk)

ijkpos(d, xyz, roundToNearestPixel = TRUE)

Arguments

Value

Nx3 matrix of physical or pixel coordinates

See Also

ind2coord

Other im3d: as.im3d(), boundingbox(), im3d(), im3d-io, imexpand.grid(), imslice(), is.im3d(), mask(), origin(), projection(), threshold(), unmask(), voxdims()

Examples

# make an emty im3d
d=im3d(,dim=c(20,30,40),origin=c(10,20,30),voxdims=c(1,2,3))
# check round trip for origin
stopifnot(all.equal(ijkpos(d,xyzpos(d,c(1,1,1))), c(1,1,1)))

Description

Read/Write calibrated 3D blocks of image data

Usage

read.im3d(
  file,
  ReadData = TRUE,
  SimplifyAttributes = FALSE,
  ReadByteAsRaw = FALSE,
  ...
)

write.im3d(x, file, format = NULL, ...)

Arguments

Details

Currently only nrrd and amira formats are implemented. Furthermore implementing a registry to allow extension to arbitrary formats remains a TODO item.

The core attributes of an im3d object are BoundingBox, origin, x, y , z where x, y, z are the locations of samples in the x, y and z image axes (which are assumed to be orthogonal).

Value

For read.im3d an objecting inheriting from base array and im3d classes.

See Also

read.nrrd, read.amiramesh

write.nrrd, getformatwriter

Other im3d: as.im3d(), boundingbox(), im3d(), im3d-coords, imexpand.grid(), imslice(), is.im3d(), mask(), origin(), projection(), threshold(), unmask(), voxdims()

Examples

## Not run: 
# read attributes of vaa3d raw file
read.im3d("L1DS1_crop_straight.raw", ReadData = F, chan=2)

## End(Not run)

Description

Method to plot spatially calibrated image arrays

Usage

## S3 method for class 'im3d'
image(
  x,
  xlim = NULL,
  ylim = NULL,
  zlim = NULL,
  plotdims = NULL,
  flipdims = "y",
  filled.contour = FALSE,
  asp = 1,
  axes = FALSE,
  xlab = NULL,
  ylab = NULL,
  nlevels = 20,
  levels = pretty(zlim, nlevels + 1),
  color.palette = colorRampPalette(c("navy", "cyan", "yellow", "red")),
  col = color.palette(length(levels) - 1),
  useRaster = NULL,
  ...
)

Arguments

Value

A list with elements:

zlim

The z (intensity limits)

nlevels.actual

The actual number of plotted levels

nlevels.orig

The requested number of plotted levels

levels

The chosen levels

colors

A character vector of colours

Examples

## Not run: 
LHMask=read.im3d(system.file('tests/testthat/testdata/nrrd/LHMask.nrrd',package='nat'))
image(imslice(LHMask,10), asp=TRUE)
# useRaster is appreciably quicker in most cases
image(imslice(LHMask,10), asp=TRUE, useRaster=TRUE)

## End(Not run)

Description

Convert locations of im3d voxel grid into XYZ coordinates

Usage

imexpand.grid(d)

Arguments

Value

Nx3 matrix of image coordinates

See Also

expand.grid

Other im3d: as.im3d(), boundingbox(), im3d(), im3d-coords, im3d-io, imslice(), is.im3d(), mask(), origin(), projection(), threshold(), unmask(), voxdims()

Examples

d=im3d(,dim=c(2,3,2),origin=c(10,20,30),voxdims=c(1,2,3))
imexpand.grid(d)

Description

Make a scalebar to accompany an image.im3d plot

Usage

imscalebar(
  levels,
  col,
  nlevels = NULL,
  zlim = NULL,
  horizontal = TRUE,
  lab = "Density",
  mar = c(4, 2, 2, 2) + 0.1,
  border = NULL,
  ...
)

Arguments

Examples

## Not run: 
LHMask=read.im3d(system.file('tests/testthat/testdata/nrrd/LHMask.nrrd',package='nat'))
op=par(no.readonly = TRUE)
layout(matrix(c(1, 2), ncol = 2L), widths = c(1, 0.2))
rval=image(imslice(LHMask,10), asp=TRUE)
imscalebar(rval)
par(op)

## End(Not run)

Description

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

Usage

imslice(x, slice, slicedim = "z", drop = TRUE)

Arguments

Details

Note the sample locations stored in the x,y,z attributes will be updated appropriately. FIXME: Should we also update bounding box?

See Also

Other im3d: as.im3d(), boundingbox(), im3d(), im3d-coords, im3d-io, imexpand.grid(), is.im3d(), mask(), origin(), projection(), threshold(), unmask(), voxdims()

Description

If you have an image-like object and you want to turn it into a matrix of 3D coords then you need ind2coord. For the reverse operation we offer as.im3d.matrix which allows you to turn a matrix of 3D coordinates into an im3d image object.

Usage

ind2coord(inds, ...)

## Default S3 method:
ind2coord(inds, dims, voxdims, origin, ...)

## S3 method for class 'array'
ind2coord(inds, voxdims = NULL, origin = NULL, ...)

## S3 method for class 'im3d'
ind2coord(inds, voxdims = NULL, origin = NULL, ...)

Arguments

See Also

coord2ind, sub2ind, xyzpos, as.im3d.matrix

Description

Find the intersection of two collections of objects

Usage

intersect(x, y, ...)

## Default S3 method:
intersect(x, y, ...)

## S3 method for class 'neuronlist'
intersect(x, y, ...)

Arguments

Details

Note that intersect.default calls base::intersect to ensure consistent behaviour for regular vectors.

Value

A collection of the same mode as x that contains all elements of x that are also present in y.

See Also

intersect

Description

intersect_plane.neuron finds the place where a neuron intersection

Usage

intersect_plane(x, plane, ...)

## Default S3 method:
intersect_plane(x, plane, ...)

## S3 method for class 'neuron'
intersect_plane(x, plane, closestpoint = NULL, ...)

Arguments

Value

A Nx3 matrix of the X,Y,Z positions of the intersections (NA when there is no intersection)

See Also

Other geometry: plane_coefficients()

Examples

## Find plane coefficients
# point on plane
cent=c(250.4987, 95.73561, 140.2052)
# vector normal to plane
vec=c(0.7709581, 0.03417276, -0.411977)
plc=plane_coefficients(cent, vec)

## intersect with plane
ip=intersect_plane(Cell07PNs[[1]], plc)
plot(Cell07PNs[[1]], WithNodes=FALSE)
points(ip[1], ip[2], pch=19, cex=2, col='red')

## Not run: 
plot3d(Cell07PNs[[1]], col='grey', WithNodes=FALSE)
spheres3d(matrix(ip, ncol=3), col='red', rad=2)
planes3d(plc[,1:3], d=plc[,'d'])

## End(Not run)

Description

Check if file is AmiraMesh format

Usage

is.amiramesh(f = NULL, bytes = NULL)

Arguments

Details

Tries to be as fast as possible by reading only first 11 bytes and checking if they equal to "# AmiraMesh" or (deprecated) "# HyperMesh".

Value

logical

See Also

Other amira: amiratype(), read.amiramesh(), read.hxsurf(), write.hxsurf()

Description

This will check a file on disk to see if it is in Fiji's simple neurite tracer XML format.

Usage

is.fijitraces(f, bytes = NULL)

Arguments

Details

Some prechecks (optionally taking place on a supplied raw vector of bytes) should weed out nearly all true negatives and identify many true positives without having to read/parse the file header.

Description

Test if an object is of class im3d

Usage

is.im3d(x)

Arguments

Value

logical

See Also

Other im3d: as.im3d(), boundingbox(), im3d(), im3d-coords, im3d-io, imexpand.grid(), imslice(), mask(), origin(), projection(), threshold(), unmask(), voxdims()

Description

This will check a file on disk to see if it is in NeuroML format. Some prechecks (optionally taking place on a supplied raw vector of bytes) should weed out nearly all true negatives and identify many true positives without having to read/parse the file header.

Usage

is.neuroml(f, bytes = NULL)

Arguments

Description

Tests if object is a neuronlist.

Usage

is.neuronlist(x)

Arguments

Details

is.neuronlist uses a relaxed definition to cope with older lists of neurons that do not have a class attribute of neuronlist.

Value

A logical indicating whether the object is a neuronlist.

See Also

Other neuronlist: *.neuronlist(), neuronlist(), neuronlist-dataframe-methods, neuronlistfh(), neuronlistz(), nlapply(), read.neurons(), write.neurons()

Description

Check if a file is a NRRD file

Usage

is.nrrd(f = NULL, bytes = NULL, ReturnVersion = FALSE, TrustSuffix = FALSE)

Arguments

Details

Note that multiple files can be checked when a character vector of length > 1 is provided, but only one file can be checked when a raw byte array is provided.

See Also

Other nrrd: nrrd.voxdims(), read.nrrd(), write.nrrd()

Description

Test if a file is an SWC format neuron

Usage

is.swc(f, TrustSuffix = TRUE)

Arguments

Details

Note that this test is somewhat expensive compared with the other file tests since SWC files do not have a consistent magic value. It therefore often has to read and parse the first few lines of the file in order to determine whether they are consistent with the SWC format.

Value

logical value

See Also

read.neuron

Description

See http://www.vaa3d.org/ and https://github.com/fiji/Vaa3d_Reader/blob/master/src/main/java/org/janelia/vaa3d/reader/V3dRawImageStream.java

Usage

is.vaa3draw(f, bytes = NULL)

Arguments

Details

Note that multiple files can be checked when a character vector of length > 1 is provided, but only one file can be checked when a raw byte array is provided.

Description

This R list (which has additional class neuronlist) contains 20 skeletonised Drosophila Kenyon cells as dotprops objects. Original data is due to Chiang et al. 2011, who have generously shared their raw data at http://flycircuit.tw. Image registration and further processing was carried out by Greg Jefferis.

References

[1] Chiang A.S., Lin C.Y., Chuang C.C., Chang H.M., Hsieh C.H., Yeh C.W., Shih C.T., Wu J.J., Wang G.T., Chen Y.C., Wu C.C., Chen G.Y., Ching Y.T., Lee P.C., Lin C.Y., Lin H.H., Wu C.C., Hsu H.W., Huang Y.A., Chen J.Y., et al. (2011). Three-dimensional reconstruction of brain-wide wiring networks in Drosophila at single-cell resolution. Curr Biol 21 (1), 1–11.

See Also

head.neuronlist, with.neuronlist, plot3d.neuronlist, plot3d.dotprops, dotprops

Other nat-data: Cell07PNs, MBL.surf

Examples

head(kcs20)
table(with(kcs20, type))
nopen3d()
# see plot3d.neuronlist documentation for more details

plot3d(kcs20, col=type)

Description

Generate a mesh3d model based on points contained in a neuronlist or neuron object, or another object that consists of 3D points.

Usage

make_model(
  x,
  substrate = c("cable", "connectors", "both"),
  alpha = 30,
  auto.selection = TRUE
)

Arguments

Details

Interactive function that allows a users to select points in 3D space from neuronlist/neuron objects, or another object that is coercible in 3D points using xyzmatrix. Points can first be automatically chosen, by selecting an integer number of nearest neighbours to find for each point using nabor::knn, and then a maximum distance at which nodes can be part of a cluster. Next, select_points is used to manually pick desired 3D points. Lastly, alphashape3d::ashape3d is used to create an alphashape around these points. The user can trial different values for alpha until they get their desired result.

Value

A mesh3d object

See Also

prune_online

Examples

## Not run: 
# Make a model based off of fly olfactory projection neuron arbours
PN_blob = make_model(Cell07PNs)

## End(Not run)

Description

makeboundingbox explicitly constructs a 3D bounding box from a set of 6 numbers defining the opposite corners of a cube. Most of the time as an end user you will want to compute/get the bounding box of objects/vertices using boundingbox.

Usage

makeboundingbox(x, dims, input = c("boundingbox", "bounds"))

Arguments

See Also

link{boundingbox}

Description

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

Usage

mask(x, ...)

## S3 method for class 'im3d'
mask(x, mask, levels = NULL, rval = c("im3d", "values"), invert = FALSE, ...)

Arguments

Details

Note that mask.im3d passes ... arguments on to im3d

Value

an object with attributes matching x and elements with value as.vector(TRUE, mode=mode) i.e. TRUE, 1, 0x01 and as.vector(FALSE, mode=mode) i.e. FALSE, 0, 0x00 as appropriate.

A copy of x with

See Also

Other im3d: as.im3d(), boundingbox(), im3d(), im3d-coords, im3d-io, imexpand.grid(), imslice(), is.im3d(), origin(), projection(), threshold(), unmask(), voxdims()

Examples

x=im3d(array(rnorm(1000),dim=c(10,10,10)), BoundingBox=c(20,200,100,200,200,300))
m=array(1:5,dim=c(10,10,10))
image(x[,,1])
image(mask(x, mask=m, levels=1)[,,1])
image(mask(x, mask=m, levels=1:2)[,,1])

Description

materials.character will read the materials from an im3d compatible image file on disk.

materials.hxsurf will extract the materials from an hxsurf object

Usage

materials(x, ...)

## Default S3 method:
materials(x, ...)

## S3 method for class 'character'
materials(x, ...)

## S3 method for class 'hxsurf'
materials(x, ...)

Arguments

Details

Note that the id column will be the 1-indexed order that the material appears in the surf$Region list for hxsurf objects and the 0-indexed mask values for an image.

Presently only AmiraMesh images are supported since they have a standardised way of encoding labels, whereas NRRDs would have to use key-value pairs according to some ad hoc convention.

Value

A data.frame with columns name, id, col

See Also

Other hxsurf: as.hxsurf(), as.mesh3d(), plot3d.hxsurf(), read.hxsurf(), subset.hxsurf(), write.hxsurf()

Description

This surface object is in the same space as the 20 Kenyon cells in kcs20.

See Also

hxsurf

Other nat-data: Cell07PNs, kcs20

Examples

plot3d(kcs20)
plot3d(MBL.surf, alpha=0.3)


## Not run: 
## originally generated as follows
library(nat.flybrains)
MBL.surf=subset(FCWBNP.surf, "MB.*_L", drop = TRUE)

## End(Not run)

Description

mirroring with a warping registration can be used to account e.g. for the asymmetry between brain hemispheres.

mirror.character handles images on disk

Usage

mirror(x, ...)

## S3 method for class 'character'
mirror(x, output, mirrorAxisSize = NULL, target = x, ...)

## Default S3 method:
mirror(
  x,
  mirrorAxisSize,
  mirrorAxis = c("X", "Y", "Z"),
  warpfile = NULL,
  transform = c("warp", "affine", "flip"),
  ...
)

## S3 method for class 'neuronlist'
mirror(x, subset = NULL, OmitFailures = NA, ...)

Arguments

Details

The mirrorAxisSize argument can be specified in 3 ways for the x axis with extreme values, x0+x1:

• a single number equal to x0+x1

• a 2-vector c(x0, x1) (recommended)

• the boundingbox for the 3D data to be mirrored: the relevant axis specified by mirrorAxis will be extracted.

This function is agnostic re node vs cell data, but for node data BoundingBox should be supplied while for cell, it should be bounds. See boundingbox for details of BoundingBox vs bounds.

See nlapply for details of the subset and OmitFailures arguments.

Value

Object with transformed points

See Also

xform, boundingbox

nlapply

Examples

nopen3d()
x=Cell07PNs[[1]]
mx=mirror(x,168)

plot3d(x,col='red')
plot3d(mx,col='green')


# also works with dotprops objects
nclear3d()
y=kcs20[[1]]
my=mirror(y,mirrorAxisSize=564.2532,transform='flip')

plot3d(y, col='red')
plot3d(my, col='green')


## Not run: 
## Example with an image
# note that we must specify an output image (obviously) but that as a
# convenience mirror calculates the mirrorAxisSize for us
mirror('myimage.nrrd', output='myimage-mirrored.nrrd', 
  warpfile='myimage_mirror.list')

# Simple flip along a different axis
mirror('myimage.nrrd', output='myimage-flipped.nrrd', mirrorAxis="Y", 
  transform='flip')

## End(Not run)

Description

Clear the rgl or plotly 3D scene

Usage

nclear3d(..., plotengine = getOption("nat.plotengine"))

Arguments

Details

rgl and plotly have quite different models for how to handle the active plot. nclear3d and nopen3d allow you to treat them more similarly. Use them wherever you use the rgl clear3d and open3d commands and your could she be able to run with both plotly or rgl as the plotengine.

See Also

rgl::clear3d, plot3d, plot3d.neuronlist, nopen3d

Examples

nclear3d()
plot3d(Cell07PNs[[1]])

Description

The normalised digest should exclude any fields or attributes irrelevant to the core contents of the object (e.g. timestamps, absolute location of the input files on disk etc). In theory then, this value should be constant for the same data regardless of the particular machine on which the digest is being computed.

Usage

ndigest(x, ...)

## S3 method for class 'neuronlistfh'
ndigest(x, ...)

## S3 method for class 'dotprops'
ndigest(x, absoluteVectors = TRUE, ...)

## S3 method for class 'neuron'
ndigest(
  x,
  fieldsToExclude = c("InputFileName", "CreatedAt", "NodeName", "InputFileStat",
    "InputFileMD5"),
  ...
)

Arguments

Details

ndigest.neuronlistfh only considers the keyfilemap and df (metadata data.frame) when computing the hash value. See neuronlistfh for the significance of these two fields.

ndigest.dotprops ignores any mtime or file attributes. It also converts tangent vectors to absolute values (when absoluteVectors=TRUE) because the direction vectors are computed using an eigenvector decomposition where the sign of the eigenvector is essentially random and subject to small numerical instabilities. Therefore it does not usually make sense to rely on the value of vect exactly.

ndigest.neuron ignores the following fields:

• InputFileName

• CreatedAt

• NodeName

• InputFileStat

• InputFileMD5

Value

A character string containing the digest of the supplied object computed by digest.

See Also

digest

all.equal.dotprops

all.equal.neuron

Examples

stopifnot(all.equal(ndigest(kcs20[[1]]), "4c045b0343938259cd9986494fc1c2b0"))

Description

neuron makes a neuron object from appropriate variables.

is.neuron will check if an object looks like a neuron.

as.neuron will convert a suitable object to a neuron

as.neuron.data.frame expects a block of SWC format data

as.neuron.ngraph converts a graph (typically an ngraph object) to a neuron

as.neuron.igraph will convert an ngraph compatible igraph object into a neuron.

as.neuron.default will add class "neuron" to a neuron-like object.

Usage

neuron(
  d,
  NumPoints = nrow(d),
  StartPoint,
  BranchPoints = integer(),
  EndPoints,
  SegList,
  SubTrees = NULL,
  InputFileName = NULL,
  NeuronName = NULL,
  ...,
  MD5 = TRUE
)

is.neuron(x, Strict = FALSE)

as.neuron(x, ...)

## S3 method for class 'data.frame'
as.neuron(x, ...)

## S3 method for class 'ngraph'
as.neuron(x, vertexData = NULL, origin = NULL, Verbose = FALSE, ...)

## S3 method for class 'igraph'
as.neuron(x, ...)

## Default S3 method:
as.neuron(x, ...)

Arguments

Details

neuron objects consist of a list containing multiple fields describing the 3D location and connectivity of points in a traced neuron. The critical fields of a neuron, n, are n$d which contains a dataframe in SWC format and n$SegList which contains a representation of the neuron's topology used for most internal calculations. For historical reasons, n$SegList is limited to a single fully-connected tree. If the tree contains multiple unconnected subtrees, then these are stored in n$SubTrees and nTrees will be >1; the "master" subtree (typically the one with the most points) will then be stored in n$SegList and n$NumPoints will refer to the number of points in that subtree, not the whole neuron.

StartPoint, BranchPoints, EndPoints are indices matching the rows of the vertices in d not arbitrary point numbers typically encoded in d$PointNo.

Columns will be ordered c('PointNo','Label','X','Y','Z','W','Parent')

Uses a depth first search on the tree to reorder using the given origin.

When the graph contains multiple subgraphs, only one will be chosen as the master tree and used to construct the SegList of the resultant neuron. However all subgraphs will be listed in the SubTrees element of the neuron and nTrees will be set appropriately.

When the graph vertices have a label attribute derived from PointNo, the origin is assumed to be specified with respect to the vertex labels rather than the raw vertex ids.

Value

A list with elements: (NumPoints,StartPoint,BranchPoints,EndPoints,nTrees,NumSegs,SegList, [SubTrees]) NB SubTrees will only be present when nTrees>1.

See Also

neuronlist

dfs, as.seglist

Other neuron: ngraph(), plot.dotprops(), potential_synapses(), prune(), resample(), rootpoints(), spine(), subset.neuron()

Examples

## See help for functions listed in See Also for more detailed examples
## Basic properties
# a sample neuron 
n = Cell07PNs[[1]]

# summarise it
n

# inspect its internal structure
str(n)
# summary of 3D points
summary(xyzmatrix(n))
# identify 3d location of endpoints
xyzmatrix(n)[endpoints(n),]

## Other methods
# plot
plot(n)
# all methods for neuron objects
methods(class = 'neuron')

## Neurons as graphs 
# convert to graph and find longest paths by number of nodes
ng=as.ngraph(n)
hist(igraph::distances(ng))
# ... or in distances  microns
ngw=as.ngraph(n, weights=TRUE)
hist(igraph::distances(ngw))

# converting back and forth between neurons and graphs
g=as.ngraph(Cell07PNs[[1]])
gstem=igraph::induced_subgraph(g, 1:10)
# this is fine
plot(gstem)
plot(as.neuron(gstem))

# but if you had an undirected graph 
ug=igraph::as.undirected(gstem)
# you get a warning because there is no explicit origin for the graph
as.neuron(ug)

# If you need finer control of the conversion process 
gstem2=as.ngraph(ug, root = 10)
plot(gstem2)
plot(as.neuron(gstem2))

Description

neuronlist objects consist of a list of neuron objects (usually of class neuron or dotprops) along with an optional attached dataframe containing information about the neurons. neuronlist objects can be indexed using their name or the number of the neuron like a regular list. Both the list itself and the attached data.frame must have the same unique (row)names. If the [ operator is used to index the list, the attached dataframe will also be subsetted.

It is perfectly acceptable not to pass any parameters, generating an empty neuronlist

Usage

neuronlist(..., DATAFRAME = NULL)

Arguments

Value

A new neuronlist object.

See Also

as.data.frame.neuronlist, neuronlist-dataframe-methods, neuron, dotprops

Other neuronlist: *.neuronlist(), is.neuronlist(), neuronlist-dataframe-methods, neuronlistfh(), neuronlistz(), nlapply(), read.neurons(), write.neurons()

Examples

# generate an empty neuronlist
nl=neuronlist()
# slice an existing neuronlist with regular indexing
kcs5=kcs20[1:5]

# simple summary of neuronlist contents
Cell07PNs
# subset to make a smaller neuronlist
Cell07PNs[1:3]
# extract a single neuron from a neuronlist
n1=Cell07PNs[[1]]
n1


# list all methods for neuronlist objects
methods(class='neuronlist')

Description

[.neuronlist and [<-.neuronlist behave like the corresponding base methods ([.data.frame, [<-.data.frame) allowing extraction or replacement of parts of the data.frame attached to the neuronlist.

droplevels Remove redundant factor levels in dataframe attached to neuronlist

with Evaluate expression in the context of dataframe attached to a neuronlist

head Return the first part of data.frame attached to neuronlist

tail Return the last part of data.frame attached to neuronlist

Usage

## S3 method for class 'neuronlist'
x[i, j, drop]

## S3 replacement method for class 'neuronlist'
x[i, j] <- value

## S3 method for class 'neuronlist'
droplevels(x, except = NULL, ...)

## S3 method for class 'neuronlist'
with(data, expr, ...)

## S3 method for class 'neuronlist'
head(x, ...)

## S3 method for class 'neuronlist'
tail(x, ...)

Arguments

Value

the attached dataframe with levels dropped (NB not the neuronlist)

See Also

[.data.frame, @seealso [<-.data.frame

droplevels

with

head

tail

Other neuronlist: *.neuronlist(), is.neuronlist(), neuronlist(), neuronlistfh(), neuronlistz(), nlapply(), read.neurons(), write.neurons()

Examples

## treat kcs20 as data.frame
kcs20[1, ]
kcs20[1:3, ]
kcs20[, 1:4]
kcs20[, 'soma_side']
# alternative to as.data.frame(kcs20)
kcs20[, ]

## can also set columns
kcs13=kcs20[1:3]
kcs13[,'side']=as.character(kcs13[,'soma_side'])
head(kcs13)
# or parts of columns
kcs13[1,'soma_side']='R'
kcs13['FruMARCM-M001205_seg002','soma_side']='L'
# remove a column
kcs13[,'side']=NULL
all.equal(kcs13, kcs20[1:3])

# can even replace the whole data.frame like this
kcs13[,]=kcs13[,]
all.equal(kcs13, kcs20[1:3])

## get row/column names of attached data.frame 
# (unfortunately implementing ncol/nrow is challenging)
rownames(kcs20)
colnames(kcs20)

Description

neuronlistfh objects consist of a list of neuron objects along with an optional attached dataframe containing information about the neurons. In contrast to neuronlist objects the neurons are not present in memory but are instead dynamically loaded from disk as required. neuronlistfh objects also inherit from neuronlist and therefore any appropriate methods e.g. plot3d.neuronlist can also be used on neuronlistfh objects.

neuronlistfh constructs a neuronlistfh object from a filehash, data.frame and keyfilemap. End users will not typically use this function to make a neuronlistfh. They will usually read them using read.neuronlistfh and sometimes create them by using as.neuronlistfh on a neuronlist object.

is.neuronlistfh test if an object is a neuronlistfh

as.neuronlistfh generic function to convert an object to neuronlistfh

as.neuronlistfh.neuronlist converts a regular neuronlist to one backed by a filehash object with an on disk representation

c.neuronlistfh adds additional neurons from one or more neuronlist objects to a neuronlistfh object.

Usage

neuronlistfh(db, df, keyfilemap, hashmap = 1000L)

is.neuronlistfh(nl)

as.neuronlistfh(x, df, ...)

## S3 method for class 'neuronlist'
as.neuronlistfh(
  x,
  df = attr(x, "df"),
  dbdir = NULL,
  dbClass = c("RDS", "RDS2", "DB1"),
  remote = NULL,
  WriteObjects = c("yes", "no", "missing"),
  ...
)

## S3 method for class 'neuronlistfh'
c(..., recursive = FALSE)