Type:	Package
Title:	NeuroAnatomy Toolbox for Analysis of 3D Image Data
Version:	1.8.24
URL:	https://github.com/natverse/nat, https://natverse.org/
BugReports:	https://github.com/natverse/nat/issues
Description:	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 package).
Depends:	R (≥ 2.15.1), rgl (≥ 0.98.1)
Imports:	nabor, igraph (≥ 1.3.0), methods, filehash (≥ 2.3), digest, nat.utils (≥ 0.4.2), plyr, yaml
Suggests:	Rvcg (≥ 0.17), testthat, httr, XML, knitr, rmarkdown, markdown, MASS, alphashape3d, webshot2
License:	GPL-3
LazyData:	yes
Collate:	'alphashape3d.R' 'amiralandmarks-io.R' 'amiramesh-io.R' 'cmtk-reformat.R' 'cmtk.R' 'cmtk_geometry.R' 'cmtk_io.R' 'cmtkreg.R' 'coordinates.R' 'dist3D_Segment_to_Segment.R' 'neuron.R' 'dotprops.R' 'graph-nodes.R' 'hxsurf.R' 'im3d.R' 'nat-data.R' 'nat-package.R' 'ndigest.R' 'neuron-io-amira.R' 'neuron-io-fiji.R' 'neuron-io-neuroml.R' 'neuron-io.R' 'neuron-plot.R' 'neuronlist.R' 'neuronlist_interactive_3d.R' 'neuronlist_sets.R' 'neuronlistfh.R' 'ngraph.R' 'nrrd-io.R' 'pop3d.R' 'potential_synapses.R' 'reglist.R' 'seglist.R' 'summary.R' 'utils.R' 'vaa3draw-io.R' 'vtk-io.R' 'xform.R' 'xformimage.R' 'xformpoints.R' 'zzz.R'
RoxygenNote:	7.2.3
Encoding:	UTF-8
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2024-02-05 17:47:03 UTC; jefferis
Author:	Gregory Jefferis [aut, cre], James Manton [aut], Dominik Krzeminski [ctb]
Maintainer:	Gregory Jefferis <jefferis@gmail.com>
Repository:	CRAN
Date/Publication:	2024-02-05 18:30:02 UTC

Analyse 3D biological image data especially neurons

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 can be applied 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, typically calculated with the open source CMTK package available at https://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.

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

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.

See Also

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

Arithmetic for dotprops objects

Description

Arithmetic for dotprops objects

Usage

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

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

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

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

Arguments

Value

A new dotprops object

Arithmetic for neuron coordinates

Description

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

Usage

## S3 method for class 'neuron'
n * x

## S3 method for class 'neuron'
n + x

## S3 method for class 'neuron'
n - x

## S3 method for class 'neuron'
n / x

Arguments

Value

modified neuron

See Also

neuron

Examples

n1<-Cell07PNs[[1]]*2
n2<-Cell07PNs[[1]]*c(2,2,2,1)
stopifnot(all.equal(n1,n2))
n3<-Cell07PNs[[1]]*c(2,2,4)

Arithmetic for neuron coordinates applied to neuronlists

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 arithemtic 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-dataframe-methods, neuronlistfh(), neuronlist(), nlapply(), read.neurons(), write.neurons()

Examples

mn2<-Cell07PNs[1:10]*2

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

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

Other nat-data: MBL.surf, kcs20

Examples

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

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

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 = T)

## End(Not run)

Extract from neuronlistfh object or its attached data.frame

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)

Decompose homogeneous affine matrix to CMTK registration parameters

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()

all.equal method tailored to dotprops objects

Description

all.equal method tailored to dotprops objects

Usage

## S3 method for class 'dotprops'
all.equal(
  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))))

Check equality on data and key attributes of im3d objects

Description

Check equality on data and key attributes of im3d objects

Usage

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

Arguments

See Also

all.equal

Check equality on key fields of neuron object

Description

Check equality on key fields of neuron object

Usage

## S3 method for class 'neuron'
all.equal(
  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')

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

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()

Get or set the attached data.frame of a neuronlist

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

Convert an object to a nat hxsurf object

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)

Convert a suitable object to an im3d object.

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-coords, im3d-io, im3d(), 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)

Convert an object to an rgl mesh3d

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

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, ...)

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))

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

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

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

convert neuronlistfh to a regular (in memory) neuronlist

Description

convert neuronlistfh to a regular (in memory) neuronlist

Usage

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

Arguments

Get the bounding box of an im3d volume or other compatible object

Description

boundingbox.list is designed to be used on objects that contain 3D point information and for which xyzmatrix is defined.

boundingbox.shape3d is designed to be used on objects that contain 3D point information and inherit from rgl's shape3d class and for which xyzmatrix is defined. Presently this applies to mesh3d objects.

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, ...)

## S3 method for class 'list'
boundingbox(x, na.rm = FALSE, ...)

## S3 method for class 'neuron'
boundingbox(x, na.rm = FALSE, ...)

## S3 method for class 'shape3d'
boundingbox(x, na.rm = FALSE, ...)

## Default S3 method:
boundingbox(x, dims, input = c("boundingbox", "bounds"), ...)

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

Value

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

See Also

plot3d.boundingbox

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

Examples

boundingbox(c(x0=0,x1=10,y0=0,y1=20,z0=0,z1=30))
# bounding box for a neuron
boundingbox(Cell07PNs[[1]])

Combine multiple neuronlists into a single list

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])))

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

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)

Return path to directory containing CMTK binaries

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 CMTKv3 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)

Utility function to create and run calls to CMTK commandline tools

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)

Convert CMTK registration to homogeneous affine matrix with dof2mat

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()

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

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 paramers. Otherwise NULL invisibly.

See Also

cmtkreglist

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

Use CMTK mat2dof to convert homogeneous affine matrix into CMTK registration

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()

Reformat an image with a CMTK registration using the reformatx tool

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 unintened 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 ouput 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)

Calculate image statistics for a nrrd or other CMTK compatible file

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)

Defines a target volume for a CMTK reformatx operation

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, ...)

## 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/jefferislab/nat.flybrains
library(nat.flybrains)
cmtk.targetvolume(FCWB)

## End(Not run)

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

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)

Compose homogeneous affine matrix from CMTK registration parameters

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()

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

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 approriate class attribute.

is.cmtkreg checks if an object is a cmtk registration either by checking class (default), or inspecting file.

Usage

cmtkreg(x, returnDir = TRUE)

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

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

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

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

Description

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

Usage

coord2ind(coords, ...)

## Default S3 method:
coord2ind(
  coords,
  imdims,
  voxdims = NULL,
  origin = NULL,
  aperm,
  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)

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

Description

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

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, ...)

## 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, ...)

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

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

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

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 if 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 suppplied 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)

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

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)

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

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

Flip an array, matrix or vector about an axis

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.

Return root, end, or branchpoints of an igraph object

Description

Return root, end, or branchpoints of an igraph object

Usage

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

Arguments

Details

Note that the graph must be directed in order to return a root point

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

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()

Interconvert pixel and physical coordinates

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 physica l or pixel coordinates

See Also

ind2coord

Other im3d: as.im3d(), boundingbox(), im3d-io, im3d(), 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)))

Read/Write calibrated 3D blocks of image data

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 orthogonsl).

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-coords, im3d(), 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)

Method to plot spatially calibrated image arrays

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)

Convert locations of im3d voxel grid into XYZ coordinates

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-coords, im3d-io, im3d(), 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)

Make a scalebar to accompany an image.im3d plot

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)

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

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-coords, im3d-io, im3d(), imexpand.grid(), is.im3d(), mask(), origin(), projection(), threshold(), unmask(), voxdims()

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

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

Find the intersection of two collections of objects

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

Check if file is amiramesh format

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()

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

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.

Test if an object is of class im3d

Description

Test if an object is of class im3d

Usage

is.im3d(x)

Arguments

Value

logical

See Also

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

Check whether a file is in NeuroML format

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

Test objects of neuronlist class to store multiple neurons

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-dataframe-methods, neuronlistfh(), neuronlist(), nlapply(), read.neurons(), write.neurons()

Check if a file is a NRRD file

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.

Test if a file is an SWC format neuron

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

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

Description

See http://www.vaa3d.org/ https://github.com/Vaa3D/v3d_external/blob/master/imagej_io/v3draw_io_imagej/raw_reader.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.

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

Description

This R list (which has additional class neuronlist) contains 20 skeletonized Drosophila Kenyon cells as dotprops objects. Original data is due to Chiang et al. 2011, who have generously shared their raw data doi:10.1016/j.cub.2010.11.056. Image registration and further processing was carried out by Greg Jefferis (see doi:10.1016/j.neuron.2016.06.012).

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)

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

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 oject 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-coords, im3d-io, im3d(), 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])

Extract or set the materials for an object

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()

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

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
clear3d()
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)

Calculated normalised digest value for an object

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

neuron: class to represent traced neurons

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.neuron(), 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]]
# 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))

Create a neuronlist from zero or more neurons

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(), nlapply(), read.neurons(), write.neurons()

Examples

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

# extract a single neuron from a neuronlist
n1=Cell07PNs[[1]]

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

Methods for working with the dataframe attached to a 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(), neuronlistfh(), neuronlist(), 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)

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

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

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"),
  remote = NULL,
  WriteObjects = c("yes", "no", "missing"),
  ...
)

Arguments

Value

a neuronlistfh object which is a character vector with classes neuronlistfh, neuronlist and attributes db, df. See Implementation details.

Implementation details

neuronlistfh objects are a hybrid between regular neuronlist objects that organise data and metadata for collections of neurons and a backing filehash object. Instead of keeping objects in memory, they are always loaded from disk. Although this sounds like it might be slow, for nearly all practical purposes (e.g. plotting neurons) the time to read the neuron from disk is small compared with the time to plot the neuron; the OS will cache repeated reads of the same file. The benefits in memory and startup time (<1s vs 100s for our 16,000 neuron database) are vital for collections of 1000s of neurons e.g. for dynamic report generation using knitr or for users with <8Gb RAM or running 32 bit R.

neuronlistfh objects include:

attr("keyfilemap")

A named character vector that determines the ordering of objects in the neuronlist and translates keys in R to filenames on disk. For objects created by as.neuronlistfh the filenames will be the md5 hash of the object as calculated using digest. This design means that the same key can be used to refer to multiple distinct objects on disk. Objects are effecitvely versioned by their contents. So if an updated neuronlistfh object is posted to a website and then fetched by a user it will result in the automated download of any updated objects to which it refers.

attr("db")

The backing database - typically of class filehashRDS. This manages the loading of objects from disk.

attr(x,"df")

The data.frame of metadata which can be used to select and plot neurons. See neuronlist for examples.

attr(x,"hashmap")

(Optional) a hashed environment which can be used for rapid lookup using key names (rather than numeric/logical indices). There is a space potential to pay for this redundant lookup method, but it is normally worth while given that the dataframe object is typically considerably larger. To give some numbers, the additional environment might occupy ~ 1 time from 0.5 ms to 1us. Having located the object, on my machine it can take as little as 0.1ms to load from disk, so these savings are relevant.

Presently only backing objects which extend the filehash class are supported (although in theory other backing objects could be added). These include:

• filehash RDS

• filehash RDS2 (experimental)

We have also implemented a simple remote access protocol (currently only for the RDS format). This allows a neuronlistfh object to be read from a url and downloaded to a local path. Subsequent attempts to access neurons stored in this list will result in automated download of the requested neuron to the local cache.

An alternative backend, the experimental RDS2 format is supported (available at https://github.com/jefferis/filehash). This is likely to be the most effective for large (5,000-500,000) collections of neurons, especially when using network filesystems (nfs, afp) which are typically very slow at listing large directories.

Note that objects are stored in a filehash, which by definition does not have any ordering of its elements. However neuronlist objects (like lists) do have an ordering. Therefore the names of a neuronlistfh object are not necessarily the same as the result of calling names() on the underlying filehash object.

See Also

filehash-class

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

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

Examples

## Not run: 
kcnl=read.neuronlistfh('http://jefferislab.org/si/nblast/flycircuit/kcs20.rds',
'path/to/my/project/folder')
# this will automatically download the neurons from the web the first time
# it is run
plot3d(kcnl)

## End(Not run)
## Not run: 
# create neuronlistfh object backed by filehash with one file per neuron
# by convention we create a subfolder called data in which the objects live
kcs20fh=as.neuronlistfh(kcs20, dbdir='/path/to/my/kcdb/data')
plot3d(subset(kcs20fh,type=='gamma'))
# ... and, again by convention, save the neuronlisfh object next to filehash 
# backing database
write.neuronlistfh(kcs20fh, file='/path/to/my/kcdb/kcdb.rds')

# in a new session
read.neuronlistfh("/path/to/my/kcdb/kcdb.rds")
plot3d(subset(kcs20fh, type=='gamma'))

## End(Not run)

ngraph: a graph to encode a neuron's connectivity

Description

the ngraph class contains a (completely general) graph representation of a neuron's connectivity in an igraph object. It may additionally contain vertex label or position data. See details.

ngraph() creates an ngraph from edge and vertex information.

as.ngraph converts an object to an ngraph

as.ngraph.dataframe construct ngraph from a data.frame containing SWC format data

as.ngraph.neuron construct ngraph from a neuron

Usage

ngraph(
  el,
  vertexlabels,
  xyz = NULL,
  diam = NULL,
  directed = TRUE,
  weights = FALSE,
  vertex.attributes = NULL,
  graph.attributes = NULL
)

as.ngraph(x, ...)

## S3 method for class 'data.frame'
as.ngraph(x, directed = TRUE, ...)

## S3 method for class 'neuron'
as.ngraph(x, directed = TRUE, method = c("swc", "seglist"), ...)

Arguments

Details

Note that the as.ngraph.neuron method always keeps the original vertex labels (a.k.a. PointNo) as read in from the original file.

Value

an igraph object with additional class ngraph, having a vertex for each entry in vertexlabels, each vertex having a label attribute. All vertices are included whether connected or not.

Connectivity

We make the following assumptions about neurons coming in

• They have an integer vertex label that need not start from 1 and that may have gaps

• The edge list which defines connectivity specifies edges using pairs of vertex labels, _not_ raw vertex ids.

We make no attempt to determine the root points at this stage.

The raw vertex ids in the graph will be in the order of vertexlabels and can therefore be used to index a block of vertex coordinates. The vertexlabels will be stored using the vertex attribute label

When the graph is directed (default) the edges will be from the root to the other tips of the neuron.

Morphology

The morphology of the neuron is encoded by the combination of connectivity information (i.e. the graph) and spatial data encoded as the 3D position and diameter of each vertex. Position information is stored as vertex attributes X, Y, and Z.

See Also

igraph, set_vertex_attr, subset.neuron for example of graph-based manipulation of a neuron.

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

Examples

g=as.ngraph(Cell07PNs[[1]])
library(igraph)
# check that vertex attributes of graph match X position
all.equal(V(g)$X, Cell07PNs[[1]]$d$X)

lapply and mapply for neuronlists (with optional parallelisation)

Description

versions of lapply and mapply that look after the class and attached dataframe of neuronlist objects. nlapply can apply a function to only a subset of elements in the input neuronlist. Internally nlapply uses plyr::llply thereby enabling progress bars and simple parallelisation (see plyr section and examples).

Usage

nlapply(
  X,
  FUN,
  ...,
  subset = NULL,
  OmitFailures = NA,
  .progress = getOption("nat.progress", default = "auto")
)

nmapply(
  FUN,
  X,
  ...,
  MoreArgs = NULL,
  SIMPLIFY = FALSE,
  USE.NAMES = TRUE,
  subset = NULL,
  OmitFailures = NA
)

Arguments

Details

When OmitFailures is not NA, FUN will be wrapped in a call to try to ensure that failure for any single neuron does not abort the nlapply/nmapply call. When OmitFailures=TRUE the resultant neuronlist will be subsetted down to return values for which FUN evaluated successfully. When OmitFailures=FALSE, "try-error" objects will be left in place. In either of the last 2 cases error messages will not be printed because the call is wrapped as try(expr, silent=TRUE).

Value

A neuronlist

plyr

The arguments of most interest from plyr are:

• .inform set to TRUE to give more informative error messages that should indicate which neurons are failing for a given applied function.

• .progress set to "text" for a basic progress bar

• .parallel set to TRUE for parallelisation after registering a parallel backend (see below).

• .paropts Additional arguments for parallel computation. See llply for details.

Before using parallel code within an R session you must register a suitable parallel backend. The simplest example is the multicore option provided by the doMC package that is suitable for a spreading computational load across multiple cores on a single machine. An example is provided below.

Note that the progess bar and parallel options cannot be used at the same time. You may want to start a potentially long-running job with the progress bar option and then abort and re-run with .parallel=TRUE if it looks likely to take a very long time.

See Also

lapply

mapply

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

Examples

## nlapply example
kcs.reduced=nlapply(kcs20,function(x) subset(x,sample(nrow(x$points),50)))
open3d()
plot3d(kcs.reduced,col='red', lwd=2)
plot3d(kcs20,col='grey')
close3d()

## Not run: 
# example of using plyr's .inform argument for debugging error conditions
xx=nlapply(Cell07PNs, prune_strahler)
# oh dear there was an error, let's get some details about the neuron
# that caused the problem
xx=nlapply(Cell07PNs, prune_strahler, .inform=TRUE)

## End(Not run)

## Not run: 
## nlapply example with plyr
## dotprops.neuronlist uses nlapply under the hood
## the .progress and .parallel arguments are passed straight to 
system.time(d1<-dotprops(kcs20,resample=1,k=5,.progress='text'))
## plyr+parallel
library(doMC)
# can also specify cores e.g. registerDoMC(cores=4)
registerDoMC()
system.time(d2<-dotprops(kcs20,resample=1,k=5,.parallel=TRUE))
stopifnot(all.equal(d1,d2))

## End(Not run)

## nmapply example
# flip first neuron in X, second in Y and 3rd in Z
xyzflip=nmapply(mirror, kcs20[1:3], mirrorAxis = c("X","Y","Z"),
 mirrorAxisSize=c(400,20,30))

open3d()
plot3d(kcs20[1:3])
plot3d(xyzflip)
close3d()


## Not run: 
## Override default progress bar behaviour via options
sl=nlapply(Cell07PNs, FUN = seglengths)
options(nat.progress='none')
sl=nlapply(Cell07PNs, FUN = seglengths)
options(nat.progress=NULL)
sl=nlapply(Cell07PNs, FUN = seglengths)

## End(Not run)

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

Description

Can also choose to select specific neurons along the way and navigate forwards and backwards.

Usage

nlscan(
  neurons,
  db = NULL,
  col = "red",
  Verbose = T,
  Wait = T,
  sleep = 0.1,
  extrafun = NULL,
  selected_file = NULL,
  selected_col = "green",
  yaml = TRUE,
  ...
)

Arguments

Value

A character vector of names of any selected neurons, of length 0 if none selected.

See Also

plot3d.character, plot3d.neuronlist

Examples

## Not run: 
# scan a neuronlist
nlscan(kcs20)

# using neuron names
nlscan(names(kcs20), db=kcs20)
# equivalently using a default neuron list
options(nat.default.neuronlist='kcs20')
nlscan(names(kcs20))

## End(Not run)
# scan without waiting
nlscan(kcs20[1:4], Wait=FALSE, sleep=0)
## Not run: 
# could select e.g. the gamma neurons with unbranched axons
gammas=nlscan(kcs20)
clear3d()
plot3d(kcs20[gammas])

# plot surface model of brain first
# nb depends on package only available on github
devtools::install_github(username = "jefferislab/nat.flybrains")
library(nat.flybrains)
plot3d(FCWB)
# could select e.g. the gamma neurons with unbranched axons
gammas=nlscan(kcs20)
clear3d()
plot3d(kcs20[gammas])

## End(Not run)

Open customised rgl window

Description

Pan with right button (Ctrl+click), zoom with middle (Alt/Meta+click) button. Defaults to a white background and orthogonal projection (FOV=0)

Usage

nopen3d(bgcol = "white", FOV = 0, ...)

Arguments

Details

Note that sometimes (parts of) objects seem to disappear after panning and zooming. See help for pan3d.

Value

current rgl device

See Also

open3d,pan3d

Normalise an SWC format block of neuron morphology data

Description

Normalise an SWC format block of neuron morphology data

Usage

normalise_swc(
  x,
  requiredColumns = c("PointNo", "Label", "X", "Y", "Z", "W", "Parent"),
  ifMissing = c("usedefaults", "warning", "stop"),
  includeExtraCols = TRUE,
  defaultValue = list(PointNo = seq.int(nrow(x)), Label = 2L, X = NA_real_, Y = NA_real_,
    Z = NA_real_, W = NA_real_, Parent = NA_integer_)
)

Arguments

Details

Note that row.names of the resultant data.frame will be set to NULL so that they have completely standard values.

Value

A data.frame containing the normalised block of SWC data with standard columns in standard order.

See Also

as.neuron.data.frame, seglist2swc

Remove plotted neurons or other 3D objects

Description

The normal usage will not specify x in which case the last neurons plotted by plot3d.neuronlist or any of its friends will be removed.

Usage

npop3d(x, slow = FALSE, type = "shapes")

Arguments

See Also

pop3d, plot3d.neuronlist

Return voxel dimensions (by default absolute voxel dimensions)

Description

Return voxel dimensions (by default absolute voxel dimensions)

Usage

nrrd.voxdims(file, ReturnAbsoluteDims = TRUE)

Arguments

Details

NB Can handle off diagonal terms in space directions matrix, BUT assumes that space direction vectors are orthogonal.

Will produce a warning if no valid dimensions can be found.

Value

numeric vector of voxel dimensions (NA_real_ when missing) of length equal to the image dimension.

Author(s)

jefferis

See Also

read.nrrd.header

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

Description

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

Usage

nvertices(x, ...)

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

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

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

Arguments

Value

an integer number of vertices (or a vector of length equal to a neuronlist)

Examples

nvertices(Cell07PNs[[1]])
nvertices(kcs20)

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

Description

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

Usage

nview3d(
  viewpoint = c("frontal", "anterior", "dorsal", "ventral", "posterior", "left", "right",
    "oblique_right", "oblique_left"),
  FOV = 0,
  extramat = NULL,
  ...
)

Arguments

See Also

nopen3d, view3d

Examples

plot3d(kcs20, soma=TRUE)
nview3d('frontal')
nview3d('ant')
nview3d()
nview3d('posterior')
nview3d('oblique_right')
# a slightly oblique frontal view
nview3d('frontal', extramat=rotationMatrix(pi/10, 1, 1, 0))

Return the space origin of a 3D image object

Description

Defined as the first coordinates (x,y,z) of the bounding box, which in turn matches the nrrd definition of the location of the "centre" of the first voxel.

Usage

origin(x, ...)

Arguments

See Also

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

Some useful extensions / changes to rgl defaults

Description

Set up pan call back for current rgl device

Usage

pan3d(button)

Arguments

Details

Copied verbatim from ?rgl.setMouseCallbacks for rgl version 0.92.892 Mouse button 2 is right and button 3 is middle (accessed by meta/alt key)

Note that sometimes (parts of) objects seem to disappear after panning and zooming. The example in rgl.setMouseCallbacks from which this is copied includes a note that "this doesn't play well with rescaling"

Author(s)

Duncan Murdoch

See Also

rgl.setMouseCallbacks

Examples

## Not run: 
 open3d()
 pan3d(2)

## End(Not run)

Plot a 2D projection of a neuron

Description

Plot a 2D projection of a neuron

Usage

## S3 method for class 'neuron'
plot(
  x,
  WithLine = TRUE,
  WithNodes = TRUE,
  WithAllPoints = FALSE,
  WithText = FALSE,
  PlotSubTrees = TRUE,
  soma = FALSE,
  PlotAxes = c("XY", "YZ", "XZ", "ZY"),
  axes = TRUE,
  asp = 1,
  main = x$NeuronName,
  sub = NULL,
  xlim = NULL,
  ylim = NULL,
  AxisDirections = c(1, -1, 1),
  add = FALSE,
  col = NULL,
  PointAlpha = 1,
  tck = NA,
  lwd = par("lwd"),
  boundingbox = NULL,
  ...
)

Arguments

Details

This functions sets the axis ranges based on the chosen PlotAxes and the range of the data in x. It is still possible to use PlotAxes in combination with a boundingbox, for example to set the range of a plot of a number of objects.

nat assumes the default axis convention used in biological imaging, where the origin of the y axis is the top rather than the bottom of the plot. This is achieved by reversing the y axis of the 2D plot when the second data axis is the Y axis of the 3D data. Other settings can be achieved by modfiying the AxisDirections argument.

Value

list of plotted points (invisibly)

See Also

plot3d.neuron

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

Examples

# Draw first example neuron
plot(Cell07PNs[[1]])
# Overlay second example neuron
plot(Cell07PNs[[2]], add=TRUE)
# Clear the current plot and draw the third neuron from a different view
plot(Cell07PNs[[3]], PlotAxes="YZ")
# Just plot the end points for the fourth example neuron
plot(Cell07PNs[[4]], WithNodes=FALSE)
# Plot with soma (of default radius)
plot(Cell07PNs[[4]], WithNodes=FALSE, soma=TRUE)
# Plot with soma of defined radius
plot(Cell07PNs[[4]], WithNodes=FALSE, soma=1.25)

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

Description

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

Usage

## S3 method for class 'neuronlist'
plot(
  x,
  subset = NULL,
  col = NULL,
  colpal = rainbow,
  add = NULL,
  boundingbox = NULL,
  ...,
  SUBSTITUTE = TRUE
)

Arguments

Details

The col and subset parameters are evaluated in the context of the dataframe attribute of the neuronlist. If col evaluates to a factor and colpal is a named vector then colours will be assigned by matching factor levels against the named elements of colpal. If there is one unnamed level, this will be used as catch-all default value (see examples).

If col evaluates to a factor and colpal is a function then it will be used to generate colours with the same number of levels as are used in col.

Value

list of values of plot with subsetted dataframe as attribute 'df'

See Also

nat-package, plot3d.neuronlist

Examples

# plot 4 cells
plot(Cell07PNs[1:4])
# modify some default plot arguments
plot(Cell07PNs[1:4], ylim=c(140,75), main='First 4 neurons')
# plot one class of neurons in red and all the others in grey
plot(Cell07PNs, col=Glomerulus, colpal=c(DA1='red', 'grey'), WithNodes=FALSE)
# subset operation
plot(Cell07PNs, subset=Glomerulus%in%c("DA1", "DP1m"), col=Glomerulus,
  ylim=c(140,75), WithNodes=FALSE)

plot3d methods for different nat objects

Description

These methods enable nat objects including neuronlists and dotprops objects to be plotted in 3D. See the help for each individual method for details along with the help for the generic in the rgl package.

See Also

plot3d, plot3d.boundingbox, plot3d.character, plot3d.cmtkreg, plot3d.dotprops, plot3d.hxsurf, plot3d.neuron, plot3d.neuronlist

Examples

# all known plot3d methods
methods("plot3d")

# up to date list of all plot3d nethods in this package
intersect(methods("plot3d"), ls(asNamespace("nat")))

Plot a bounding box in 3D

Description

Plot a bounding box in 3D

Usage

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

Arguments

Value

A list of RGL object IDs.

See Also

boundingbox

Examples

# find the bounding box of all the neurons in a list
boundingbox(kcs20)
boundingbox(kcs20[1:3])

# plot those neurons
plot3d(kcs20)
# ... with their bounding box
plot3d(boundingbox(kcs20))

plot3d(kcs20)
# plot bounding box (in matching colours) for each neuron
# NB makes use of nlapply/neuronlist in slightly unsusual context - 
# plot3d.neuronlist can cope with lists containing anything with
# a valid plot3d method.
plot3d(nlapply(kcs20,boundingbox))

Plot the domain of a CMTK registration

Description

Plot the domain of a CMTK registration

Usage

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

Arguments

See Also

cmtkreg, read.cmtkreg, plot3d

Examples

## Not run: 
testdatadir=system.file("tests/testthat/testdata/cmtk", package="nat")
regpath=file.path(testdatadir,'FCWB_JFRC2_01_warp_level-01.list/')
plot3d(cmtkreg(regpath))

# or read registration into memory if you want to work with it
reg=read.cmtkreg(regpath)
# nb calling plot3d.cmtkreg directly (rather than using the generic plot3d) 
# is considered bad style but read.cmtkreg returns a plain list 
# so method dispatch will fail
nat:::plot3d.cmtkreg(reg)

## End(Not run)

3D plots of dotprops objects using rgl package

Description

3D plots of dotprops objects using rgl package

Usage

## S3 method for class 'dotprops'
plot3d(
  x,
  scalevecs = 1,
  alpharange = NULL,
  color = "black",
  PlotPoints = FALSE,
  PlotVectors = TRUE,
  UseAlpha = FALSE,
  ...
)

Arguments

Details

Tangent vectors are plotted by segments3d and centered on the relevant point. Points are plotted by points3d.

color will be recycled by points3d and segments3d. However in the special case that color has length equal to the number of points in x, then it will be duplicated before being passed to segments3d so that the result is that each vector is coloured uniformly according to color (since segments3d expects 2 colours for each line segment, blending them if they are different).

Value

invisible list of results of rgl plotting commands

See Also

dotprops, plot3d, points3d, segments3d

Examples

open3d()
plot3d(kcs20[[1]])
clear3d()
plot3d(kcs20[[1]],col='red')
clear3d()
plot3d(kcs20[[1]],col='red',lwd=2)
plot3d(kcs20[[2]],col='green',lwd=2)

Plot amira surface objects in 3D using rgl

Description

Plot amira surface objects in 3D using rgl

Usage

## S3 method for class 'hxsurf'
plot3d(x, materials = NULL, col = NULL, ...)

Arguments

See Also

read.hxsurf

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

Examples

plot3d(kcs20)
plot3d(MBL.surf)


# plot only vertical lobe
clear3d()
plot3d(MBL.surf, materials="VL", alpha=0.3)

# everything except vertical lobe
clear3d()
plot3d(MBL.surf, alpha=0.3, 
  materials=grep("VL", MBL.surf$RegionList, value = TRUE, invert = TRUE))

Plot neurons in 3D using rgl library

Description

Plot neurons in 3D using rgl library

Usage

## S3 method for class 'neuron'
plot3d(
  x,
  WithLine = TRUE,
  NeuronNames = FALSE,
  WithNodes = TRUE,
  WithAllPoints = FALSE,
  WithText = FALSE,
  PlotSubTrees = TRUE,
  add = TRUE,
  col = NULL,
  soma = FALSE,
  ...
)

Arguments

Details

Note that when WithText=TRUE, the numeric identifiers plotted are raw indices into the x$d array of the neuron, not the values of the PointNo column.

Value

list of rgl plotting ids (invisibly) separated into lines, points, texts according to plot element. See rgl::plot3d for details.

See Also

plot3d.neuronlist, plot3d.dotprops, nat::plot3d, rgl::plot3d

Examples

# A new plot would have been opened if required
open3d()
plot3d(Cell07PNs[[1]],col='red')
plot3d(Cell07PNs[[2]],col='green')

# clear the current plot
clear3d()
plot3d(Cell07PNs[[2]],col='blue',add=FALSE)
# plot the number of all nodes
clear3d()
plot3d(Cell07PNs[[2]],col='red',WithText=TRUE,add=FALSE)
# include cell bodies
plot3d(Cell07PNs[3:4], col='red', soma=TRUE)
plot3d(Cell07PNs[5], col='red', soma=3)
close3d()

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

Description

plot3d.character is a convenience method intended for exploratory work on the command line.

Usage

## S3 method for class 'neuronlist'
plot3d(
  x,
  subset = NULL,
  col = NULL,
  colpal = rainbow,
  skipRedraw = ifelse(interactive(), 200L, TRUE),
  WithNodes = FALSE,
  soma = FALSE,
  ...,
  SUBSTITUTE = TRUE
)

## S3 method for class 'character'
plot3d(x, db = NULL, ...)

Arguments

Details

The col and subset parameters are evaluated in the context of the dataframe attribute of the neuronlist. If col evaluates to a factor and colpal is a named vector then colours will be assigned by matching factor levels against the named elements of colpal. If there is one unnamed level, this will be used as catch-all default value (see examples).

If col evaluates to a factor and colpal is a function then it will be used to generate colours with the same number of levels as are used in col.

WithNodes is FALSE by default when using plot3d.neuronlist but remains TRUE by default when plotting single neurons with plot3d.neuron. This is because the nodes quickly make plots with multiple neurons rather busy.

When soma is TRUE or a vector of numeric values (recycled as appropriate), the values are used to plot cell bodies. For neurons the values are passed to plot3d.neuron for neurons. In contrast dotprops objects still need special handling. There must be columns called X,Y,Z in the data.frame attached to x, that are then used directly by code in plot3d.neuronlist.

Whenever plot3d.neuronlist is called, it will add an entry to an environment .plotted3d in nat that stores the ids of all the plotted shapes (neurons, cell bodies) so that they can then be removed by a call to npop3d.

plot3d.character will check if options('nat.default.neuronlist') has been set and then use x as an identifier to find a neuron in that neuronlist.

Value

list of values of plot3d with subsetted dataframe as attribute 'df'

See Also

nat-package

Examples

open3d()
plot3d(kcs20,type=='gamma',col='green')

clear3d()
plot3d(kcs20,col=type)
plot3d(Cell07PNs,Glomerulus=="DA1",col='red')
plot3d(Cell07PNs,Glomerulus=="VA1d",col='green')
# Note use of default colour for non DA1 neurons
plot3d(Cell07PNs,col=Glomerulus, colpal=c(DA1='red', 'grey'))
# a subset expression
plot3d(Cell07PNs,Glomerulus%in%c("DA1",'VA1d'),
  col=c("red","green")[factor(Glomerulus)])
# the same but not specifying colours explicitly
plot3d(Cell07PNs,Glomerulus%in%c("DA1",'VA1d'),col=Glomerulus)

## Not run: 
## more complex colouring strategies for a larger neuron set
# see https://github.com/jefferis/frulhns for details
library(frulhns)
# notice the sexually dimorphic projection patterns for these neurons
plot3d(jkn,cluster=='aSP-f' &shortGenotype=='JK1029', 
  col=sex,colpal=c(male='green',female='magenta'))

## colour neurons of a class by input resistance
jkn.aspg=subset(jkn, cluster=='aSP-g')
# NB this comes in as a factor
Ri=with(jkn.aspg,as.numeric(as.character(Ri..GOhm.)))
# the matlab jet palette
jet.colors<-colorRampPalette(c('navy','cyan','yellow','red'))
plot3d(jkn.aspg,col=cut(Ri,20),colpal=jet.colors)

## End(Not run)

Find which points of an object are inside a surface

Description

Find which points of an object are inside a surface

Usage

pointsinside(x, surf, ...)

## Default S3 method:
pointsinside(x, surf, ..., rval = c("logical", "distance", "mesh3d"))

Arguments

Details

Note that hxsurf surface objects will be converted to mesh3d before being passed to Rvcg::vcgClostKD, so if you are testing repeatedly against the same surface, it may make sense to pre-convert.

pointsinside depends on the face normals for each face pointing out of the object (see example). The face normals are defined by the order of the three vertices making up a triangular face. You can flip the face normal for a face by permuting the vertices (i.e. 1,2,3 -> 1,3,2). If you find for a given surface that points are outside when you expect them to be inside then the face normals are probably all the wrong way round. You can invert them yourself or use the Morpho::invertFaces function to fix this.

If you find that some points but not all points are not behaving as you would expect, then it may be that some faces are not coherently oriented. The Rvcg::vcgClean function can sometimes be used to correct the orientation of the faces. Fixing more problematic cases may be possible by generating a new surface using alphashape3d::ashape3d (see examples).

Value

A vector of logical values or distances (positive inside, negative outside) equal to the number of points in x or the mesh3d object returned by Rvcg::vcgClostKD.

Examples

# check if the vertices in these neurons are inside the mushroom body calyx
# surface object
inout=pointsinside(kcs20, surf=subset(MBL.surf, "MB_CA_L"))
table(inout)

# be a bit more lenient and include points less than 5 microns from surface
MBCAL=subset(MBL.surf, "MB_CA_L")
inout5=pointsinside(kcs20, surf=MBCAL, rval='distance') > -5
table(inout5)

# show which points are in or out
# Hmm seems like there are a few red points in the vertical lobe
# that are well outside the calyx
points3d(xyzmatrix(kcs20), col=ifelse(inout5, 'red', 'black'))
plot3d(MBL.surf, alpha=.3)

# Let's try to make an alphashape for the mesh to clean it up
library(alphashape3d)
MBCAL.as=ashape3d(xyzmatrix(MBCAL), alpha = 10)
# Plotting the points, we can see that is much better behaved
points3d(xyzmatrix(kcs20), 
  col=ifelse(pointsinside(kcs20, MBCAL.as), 'red', 'black'))


## Not run: 
# Show the face normals for a surface
if(require('Morpho')) {
  # convert to a mesh3d object used by rgl and Morpho packge
  MBCAL.mesh=as.mesh3d(subset(MBL.surf, "MB_CA_L"))
  fn=facenormals(MBCAL.mesh)
  wire3d(MBCAL.mesh)
  # show that the normals point out of the object
  plotNormals(fn, long=5, col='red')
  
  # invert the faces of the mesh and show that normals point in
  MBCAL.inv=invertFaces(MBCAL.mesh)
  plotNormals(facenormals(MBCAL.inv), long=5, col='cyan')
}

## End(Not run)

Calculate number of potential synapses between two neurons

Description

This implements the method of Stepanyants and Chklovskii

Usage

potential_synapses(a, b, s, ...)

## S3 method for class 'neuronlist'
potential_synapses(a, b, s, ...)

## S3 method for class 'neuron'
potential_synapses(
  a,
  b,
  s,
  sigma = s,
  bounds,
  method = c("direct", "approx"),
  ...
)

## S3 method for class 'dotprops'
potential_synapses(
  a,
  b,
  s,
  sigma = s,
  seglength = 1,
  bounds = NULL,
  method = c("direct", "approx"),
  ...
)

Arguments

Details

Note that potential_synapses.neuronlist uses nlapply to process its first argument (a). This enables progress bars, robustness to errors and simple parallel execution. See the nlapply examples for further details of these arguments in action.

For this reason if you have two neuronlists of unequal sizes, it is recommended to put the larger one in argument a.

References

Neurogeometry and potential synaptic connectivity. Stepanyants A, Chklovskii DB. Trends Neurosci. 2005 Jul;28(7):387-94. doi:10.1016/j.tins.2005.05.006

See Also

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

Examples

potential_synapses(Cell07PNs[1], Cell07PNs[1:3], s=2)
## Not run: 
# if you have many neurons to calculate you should get a progress bar
potential_synapses(Cell07PNs[1:10], Cell07PNs[11:20], s=2)

# you can also use parallel execution, here over 7 cores
# doMC::registerDoMC(7)
potential_synapses(Cell07PNs[1:10], Cell07PNs[11:20], s=2, .parallel=TRUE)

## End(Not run)

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

Description

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

Usage

projection(
  a,
  projdim = "z",
  projfun = c("integrate", "mean", "sum"),
  na.rm = T,
  mask = NULL,
  ...
)

Arguments

Details

Note that projfun must have an argument na.rm like the S3 Summary groupGeneric functions such as sum, min etc.

Note also that the BoundingBox of a 2d projection is not well-defined for the axis along which the projection was made. Presently both the evaluation location and the BoundingBox extremes are set to 0 after a projection is made but FIXME this is not completely satisfactory. Perhaps defining this to be NA or the midpoint of the orginal axis would be better justified.

See Also

groupGeneric, clampmax

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

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)
## Not run: 
LHMask=read.im3d(system.file('tests/testthat/testdata/nrrd/LHMask.nrrd',package='nat'))
image(projection(LHMask),asp=TRUE)

## End(Not run)

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

Description

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

Usage

prune(x, target, ...)

## S3 method for class 'neuron'
prune(x, target, ...)

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

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

## Default S3 method:
prune(x, target, maxdist, keep = c("near", "far"), return.indices = FALSE, ...)

Arguments

Details

prune.neuron depends on a more basic function prune_vertices and is also related to subset.neuron.

See Also

prune_strahler, spine, prune_vertices

subset.neuron

subset.dotprops

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

Examples

## prune single neurons

plot3d(kcs20[[1]],col='blue')
plot3d(kcs20[[2]],col='red')

# prune neuron 2 down to points that are close to neuron 1
neuron2_close=prune(kcs20[[2]], target=kcs20[[1]], maxdist=10)

plot3d(neuron2_close, col='cyan', lwd=3)

neuron2_far=prune(kcs20[[2]], target=kcs20[[1]], maxdist=10, keep='far')

plot3d(neuron2_far, col='magenta', lwd=3)


## Prune a neuron with a neuronlist
pruned=prune(kcs20[[11]], kcs20[setdiff(1:20, 11)], maxdist=8)

plot3d(pruned, col='red', lwd=3)
plot3d(kcs20[[11]], col='green', lwd=3)
plot3d(kcs20,col='grey')

Prune a neuron by removing segments with a given Strahler order

Description

Prune a neuron by removing segments with a given Strahler order

Usage

prune_strahler(x, orderstoprune = 1:2, ...)

Arguments

Value

The pruned neuron

See Also

strahler_order, spine, for finding the longest path in a neuron, prune for subsetting dotprops style neurons by spatial proximity, as.neuron.data.frame, which is used to generate the new neuron.

Examples

x=Cell07PNs[[1]]
pruned12=prune_strahler(x)
pruned1=prune_strahler(x, 1)
plot(x)
plot(pruned1, lwd=3, col='blue', add=TRUE)
plot(pruned12, lwd=3, col='red', add=TRUE)

Prune selected vertices or edges from a neuron

Description

prune_vertices removes vertices from a neuron

prune_edges removes edges (and any unreferenced vertices)

Usage

prune_vertices(x, verticestoprune, invert = FALSE, ...)

prune_edges(x, edges, invert = FALSE, ...)

Arguments

Details

These are relatively low-level functions and you will probably want to use subset.neuron or prune.neuron and friends in many cases.

Note that prune_vertices and prune_edges both use raw vertex ids to specify the vertices/edges to be removed. If you want to use the id in the PointNo field, then you must translate yourself (see examples).

Both prune_vertices and prune_edges first convert their input x to the ngraph representation of the neuron befor removing points. The input x can therefore be in any form compatible with as.ngraph including an existing ngraph. There is an additional requirement that the input must be compatible with xyzmatrix if invert=TRUE.

Note that the edges argument of prune_edges must specify a path traversing a set of vertices in a valid order. However if the input is a matrix or vector the direction of each individual edge in this path is ignored. So if your neuron has edges 2->1 2->3 3->4 then an edge sequence 1:3 would successfully delete 2 edges.

Value

A pruned neuron

See Also

as.neuron.ngraph, subset.neuron, prune.neuron

Examples

n=prune_vertices(Cell07PNs[[1]], 1:25)
# original neuron
plot(Cell07PNs[[1]])
# with pruned neuron superimposed
plot(n, col='green', lwd=3, add=TRUE)

# use the PointNo field (= the original id from an SWC file)
n2=prune_vertices(n, match(26:30, n$d$PointNo))
y=prune_edges(Cell07PNs[[1]], edges=1:25)

# remove the spine of a neuron
spine_ids=spine(Cell07PNs[[1]], rval='ids')
pruned=prune_edges(Cell07PNs[[1]], spine_ids)

# NB this is subtly different from this, which removes vertices along the
# spine *even* if they are part of an edge that is outside the spine.
pruned2=prune_vertices(Cell07PNs[[1]], spine_ids)

Read AmiraMesh data in binary or ascii format

Description

Read AmiraMesh data in binary or ascii format

Read the header of an amiramesh file

Usage

read.amiramesh(
  file,
  sections = NULL,
  header = FALSE,
  simplify = TRUE,
  endian = NULL,
  ReadByteAsRaw = FALSE,
  Verbose = FALSE
)

read.amiramesh.header(file, Parse = TRUE, Verbose = FALSE)

Arguments

Details

reading byte data as raw arrays requires 1/4 memory but complicates arithmetic.

read.amiramesh.header will open a connection if file is a character vector and close it when finished reading.

Value

list of named data chunks

See Also

readBin, .Platform

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

Read CMTK TypedStream file to a list in memory

Description

This function is primarily of developer interest. End users will typically want to use more specialised functions for reading registrations and landmarks.

Usage

read.cmtk(con, CheckLabel = TRUE)

Arguments

Details

This is the default format used by CMTK for registration, studylist, landmarks and image files. Although this is largely a generic function, there is special handling of the coefficients and active members of the spline warp component of a CMTK nonrigid registrartion.

Note that if an open connection is passed to read.cmtk the version number of the CMTK TypedStream will not be checked or recorded.

See Also

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

Read a CMTK format registration

Description

Read a CMTK format registration

Usage

read.cmtkreg(filename, ReturnRegistrationOnly = FALSE, ...)

Arguments

See Also

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

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

Description

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

Usage

read.hxsurf(
  filename,
  RegionNames = NULL,
  RegionChoice = "both",
  FallbackRegionCol = "grey",
  Verbose = FALSE
)

Arguments

Details

Note that when RegionChoice="both" or RegionChoice=c("Inner", "Outer") both polygons in inner and outer regions will be added to named regions. To understand the significance of this, consider two adjacent regions, A and B, with a shared surface. For the polygons in both A and B, Amira will have a patch with (say) InnerRegion A and OuterRegion B. This avoids duplication in the file. However, it might be convenient to add these polygons to both regions when we read them into R, so that regions A and B in our R object are both closed surfaces. To achieve this when RegionChoice="both", read.hxsurf adds these polygons to region B (as well as region A) but swaps the order of the vertices defining the polygon to ensure that the surface directionality is correct.

As a rule of thumb, stick with RegionChoice="both". If you get more regions than you wanted, then try switching to RegionChoice="Inner" or RegionChoice="Outer".

Value

A list with S3 class hxsurf with elements

Vertices

A data.frame with columns X, Y, Z, PointNo

Regions

A list with 3 column data.frames specifying triplets of vertices for each region (with reference to PointNo column in Vertices element)

RegionList

Character vector of region names (should match names of Regions element)

RegionColourList

Character vector specifying default colour to plot each region in R's rgb format

See Also

plot3d.hxsurf, rgb

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

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

Examples

## Not run: 
read.hxsurf("my.surf", RegionChoice="both")

## End(Not run)

Generic functions to read/write landmarks in any supported format

Description

Generic functions to read/write landmarks in any supported format

Usage

read.landmarks(f, ...)

write.landmarks(
  x,
  file,
  format = "amiralandmarks",
  ext = NULL,
  Force = FALSE,
  MakeDir = TRUE,
  ...
)

Arguments

Details

Presently the supported formats are

• Amira

• CMTK

• Fiji (see https://imagej.net/plugins/name-landmarks-and-register)

See examples section for how to produce a listing of all currently available formats with fileformats.

Value

for read.landmarks a matrix or list of additional class landmarks, where the rownames specify the names of each landmark if available.

For write.landmarks the path to the written file, invisibly.

Paired landmarks

Only the amiralandmarks format supports the use of paired landmarks

See Also

fileformats

Examples

## Listing of supported fileformats for landmarks
fileformats(class = 'landmarks', rval = "info")

## round trip tests
m=matrix(rnorm(6), ncol=3)
rownames(m)=c("nose", "ear")
f=write.landmarks(m, file='knee', format='cmtk')
read.landmarks(f)

# write in amira format which does not support named landmarks
f2=write.landmarks(m, file='knee', format='amira')
read.landmarks(f2)

# clean up
unlink(c(f,f2))

Return parsed XML or R list versions of a NeuroML file

Description

read.morphml is designed to expose the full details of the morphology information in a NeuroML file either as a parsed XML structure processed by the XML package or as an extensively processed R list object. To obtain a neuron object use read.neuron.neuroml.

Usage

read.morphml(f, ..., ReturnXML = FALSE)

Arguments

Details

NeuroML files consist of an XML tree containing one more or more cells. Each cell contains a tree of segments defining the basic connectivity/position and an optional tree cables defining attributes on groups of segments (e.g. a name, whether they are axon/dendrite/soma etc).

read.morphml will either provide the parsed XML tree which you can query using XPath statements or a more heavily processed version which provides as much information as possible from the segments and cables trees in two R data.frames. The latter option will inevitably drop some information, but will probably be more convenient for most purposes.

Value

Either an R list of S3 class containing one morphml_cell object for every cell in the NeuroML document or an object of class XMLDocument when ReturnXML=TRUE.

References

https://neuroml.org/

See Also

link[XML]{xmlParse}, read.neuron.neuroml

Read a single neuron from a file

Description

Read a single neuron from a file

Usage

read.neuron(f, format = NULL, class = c("neuron", "ngraph"), ...)

Arguments

Details

This function will handle neuron and dotprops objects saved in R .rds or .rda format by default. Additional file formats can be registered using fileformats.

At the moment the following formats are supported using file readers already included with the nat package:

• swc See read.neuron.swc. SWC files can also return an ngraph object containing the neuron structure in a (permissive) general graph format that also contains the 3D positions for each vertex.

• neuroml See read.neuron.neuroml

• fijitraces See read.neuron.fiji. The file format used by the SNT plugin of Fiji/ImageJ.

• hxlineset,hxskel Two distinct fileformats used by Amira. hxlineset is the generic one, hxskel is used by the hxskeletonize extension of Schmitt and Evers (see refs).

• rda,rds Native R cross-platform binary formats (see load, readRDS). Note that RDS only contains a single unnamed neuron, whereas rda contains one or more named neurons.

References

Schmitt, S. and Evers, J. F. and Duch, C. and Scholz, M. and Obermayer, K. (2004). New methods for the computer-assisted 3-D reconstruction of neurons from confocal image stacks. Neuroimage 4, 1283–98. doi:10.1016/j.neuroimage.2004.06.047

See Also

write.neuron, read.neurons, fileformats

Examples

## Not run: 
# note that we override the default NeuronName field
n=read.neuron(system.file("tests/testthat/testdata","neuron","EBT7R.CNG.swc",package='nat'),
  NeuronName="EBT7R")
# use a function to set the NeuronName field
n3=read.neuron(system.file("tests/testthat/testdata","neuron","EBT7R.CNG.swc",package='nat'),
  NeuronName=function(x) sub("\\..*","",x))
# show the currently registered file formats that we can read
fileformats(class='neuron', read=TRUE)

## End(Not run)

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

Description

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

Usage

read.neuron.fiji(f, ..., simplify = TRUE, Verbose = FALSE)

Arguments

Details

This is an XML based format so parsing it depends on installation of the suggested XML package.

References

https://imagej.net/plugins/snt/ https://imagej.net/plugins/snt/extending

Read one or more neurons from a NeuroML v1 file

Description

Read one or more neurons from a NeuroML v1 file

Usage

read.neuron.neuroml(f, ..., AlwaysReturnNeuronList = FALSE)

Arguments

Value

When the XML file contains only 1 cell and AlwaysReturnNeuronList=FALSE, a neuron object, otherwise a neuronlist containing one or more neurons.

References

https://neuroml.org/

See Also

read.morphml

Read a neuron in swc file format

Description

read.neuron.swc reads an SWC file on disk into a fully parsed neuron representation.

read.ngraph.swc reads an SWC file on disk into the more generic (and forgiving) ngraph representation which provides a bridge to the igraph library.

Usage

read.neuron.swc(f, ...)

read.ngraph.swc(f, weights = FALSE, directed = TRUE, ...)

Arguments

Details

These functions will accept SWC neurons with multiple trees and arbitrary point index order. However only read.ngraph.swc will accept SWC files with cycles.

These functions would normally be called from read.neuron(s) rather than used directly.

SWC Format

According to http://www.neuronland.org/NLMorphologyConverter/MorphologyFormats/SWC/Spec.html SWC file format has a radius not a diameter specification

See Also

is.swc

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

Description

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

Usage

read.neuronlistfh(file, localdir = NULL, update = FALSE, ...)

Arguments

Details

When reading a remote neuronlistfh object, it is downloaded and cached to localdir. If there is already a cached file at the appropriate location and update=TRUE then the md5sums are checked and the downloaded file will be copied on top of the original copy if they are different; if udpate=FALSE, the default, then no action will be taken. After downloading a remote neuronlistfh object, a check is made for the existence of the data directory that will be used to individual objects. If this does not exist it will be created.

Note also that there is a strict convention for the layout of the files on disk. The neuronlistfh object will be saved in R's RDS format and will be placed next to a folder called data which will contain the data objects, also saved in RDS format. For example if myneurons.rds is downloaded to localdir="\path\to\localdir" the resultant file layout will be as follows:

• \path\to\localdir\myneurons.rds

• \path\to\localdir\data\2f88e16c4f21bfcb290b2a8288c05bd0

• \path\to\localdir\data\5b58e040ee35f3bcc6023fb7836c842e

• \path\to\localdir\data\... etc

Given this arrangment, the data directory should always be at a fixed location with respect to the saved neuronlistfh object and this is enforced on download and the default behaviour on read and write. However it does remain possible (if not recommended) to site the neuronlistfh and filehash database directory in different relative locations; if the neuronlistfh object specified by file does not have a filehash database with a valid dir slot and there is no 'data' directory adjacent to the neuronlistfh object, an error will result.

See Also

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

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

Description

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

Usage

read.neurons(
  paths,
  pattern = NULL,
  neuronnames = basename,
  format = NULL,
  nl = NULL,
  df = NULL,
  OmitFailures = TRUE,
  SortOnUpdate = FALSE,
  ...
)

Arguments

Details

This function will cope with the same set of file formats offered by read.neuron.

If the paths argument specifies a (single) directory then all files in that directory will be read unless an optional regex pattern is also specified. Similarly, if paths specifies a zip archive, all neurons within the archive will be loaded.

neuronnames must specify a unique set of names that will be used as the names of the neurons in the resultant neuronlist. If neuronnames is a a function then this will be applied to the path to each neuron. The default value is the function basename which results in each neuron being named for the input file from which it was read.

The optional dataframe (df) detailing each neuron should have rownames that match the names of each neuron. It would also make sense if the same key was present in a column of the data frame. If the dataframe contains more rows than neurons, the superfluous rows are dropped with a warning. If the dataframe is missing rows for some neurons an error is generated. If SortOnUpdate is TRUE then updating an existing neuronlist should result in a new neuronlist with ordering identical to reading all neurons from scratch.

Value

neuronlist object containing the neurons

See Also

read.neuron, write.neurons, fileformats

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

Examples

## Not run: 
## Read C. elegans neurons from OpenWorm github repository
vds=paste0("VD", 1:13)
vdurls=paste0("https://raw.githubusercontent.com/openworm/CElegansNeuroML/",
  "103d500e066125688aa7ac5eac7e9b2bb4490561/CElegans/generatedNeuroML/",vds,
  ".morph.xml")
vdnl=read.neurons(vdurls, neuronnames=vds)
plot3d(vdnl)

## The same, but this time add some metadata to neuronlist
# fetch table of worm neurons from wormbase
library(rvest)
nlurl="http://wormatlas.org/neurons/Individual%20Neurons/Neuronframeset.html"
wormneurons = html_table(html(nlurl), fill=TRUE)[[4]]
vddf=subset(wormneurons, Neuron%in%vds)
rownames(vddf)=vddf$Neuron
# attach metadata to neuronlist
vdnl=read.neurons(vdurls, neuronnames=vds, df=vddf)
# use metadata to plot a subset of neurons
clear3d()
plot3d(vdnl, grepl("P[1-6].app", Lineage))

## End(Not run)

Read nrrd file into an array in memory

Description

Read nrrd file into an array in memory

Read the (text) header of a NRRD format file

Usage

read.nrrd(
  file,
  origin = NULL,
  ReadData = TRUE,
  AttachFullHeader = TRUE,
  Verbose = FALSE,
  ReadByteAsRaw = c("unsigned", "all", "none")
)

read.nrrd.header(file, Verbose = FALSE)

Arguments

Details

read.nrrd reads data into a raw array. If you wish to generate a im3d object that includes spatial calibration (but is limited to representing 3D data) then you should use read.im3d.

ReadByteAsRaw=unsigned (the default) only reads unsigned byte data as a raw array. This saves quite a bit of space and still allows data to be used for logical indexing.

Value

An array object, optionally with attributes from the nrrd header.

A list with elements for the key nrrd header fields

See Also

write.nrrd, read.im3d

Read Vaa3d format image data

Description

Read Vaa3d format image data

Usage

read.vaa3draw(f, ReadData = TRUE, Verbose = FALSE, ReadByteAsRaw = FALSE)

Arguments

A simple wrapper class for multiple transformations

Description

A reglist is read as a set of transformations to be applied sequentially starting with the first element, then applying the second transformation to the result of the first and so on. Each individual transformation is considered to map data from the sample (floating/moving) space to the reference (fixed/template) space.

Each transformation may have an attribute "swap" indicating that the natural direction of the transformation should be swapped (i.e. inverted). This can be done trivially in the case of affine transformations, expensively for others such as CMTK registrations (see cmtkreg) and not at all for others. Note that the term 'swap' is used to avoid a direct equivalence with inversion - many registration tools use the term inverse for directions that one might naively think of as as the natural direction of the transformation (see xformpoints.cmtkreg for discussion).

invert_reglist inverts a reglist object

c.reglist combines multiple reglists into a single reglist.

Usage

reglist(..., swap = NULL)

invert_reglist(x)

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

Arguments

Details

The swap argument is provided as a convenience, but an attribute 'swap' can also be set directly on each registration.

Inversion

invert_reglist takes a minimal approach to inversion. It reverses the order of the individual elements of the registration and tags each of them with a swap attribute (or changes the value of the attribute if it already exists)

See Also

xform

c

Examples

I=diag(4)
S=I
diag(S)=c(1, 2, 3, 1)
rl=reglist(S, I)
rli=invert_reglist(rl)

## We can check the inversion by simplifying
m=simplify_reglist(rl)[[1]]
mi=simplify_reglist(rli)[[1]]
# NB solve will invert a homogeneous affine matrix
all.equal(m, solve(mi))
I=diag(4)
S=I
diag(S)=c(1, 2, 3, 1)
rl=reglist(S, I)
rl2=c(rl, 'path/to/my/reg.list')
rl3=c(reglist('path/to/my/reg.list'), rl)

Synchronise a remote object

Description

Synchronise a remote object

Usage

remotesync(
  x,
  remote = attr(x, "remote"),
  download.missing = TRUE,
  delete.extra = FALSE,
  ...
)

## S3 method for class 'neuronlistfh'
remotesync(
  x,
  remote = attr(x, "remote"),
  download.missing = FALSE,
  delete.extra = FALSE,
  indices = NULL,
  update.object = TRUE,
  ...
)

Arguments

Value

The updated neuronlistfh object (invisibly)

See Also

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

Examples

## Not run: 
kcs20=read.neuronlistfh('http://flybrain.mrc-lmb.cam.ac.uk/si/nblast/flycircuit/kcs20.rds')
# update object from the web
kcs20=remotesync(kcs20)
# download all neurons with significant innervation of the vertical lobe
mbvl_neurons=subset(kcs20, (MB_VL_R+MB_VL_L)>200, rval='names')
kcs20=remotesync(kcs20, indices=mbvl_neurons, download.missing=TRUE)

## End(Not run)

Resample an object with a new spacing

Description

Resample an object with a new spacing

resample a neuron with a new spacing

Usage

resample(x, ...)

## S3 method for class 'neuron'
resample(x, stepsize, ...)

Arguments

Details

resample.neuron Floating point columns including X,Y,Z,W will be interpolated using linear interpolation, while integer or factor columns will be interpolated using constant interpolation. See approx for details.

See Also

approx, seglengths

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

Return the root or branch points of a neuron or graph

Description

A neuron may have multiple subtrees and therefore multiple roots

Usage

rootpoints(x, ...)

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

## S3 method for class 'neuron'
rootpoints(x, subtrees = 1, ...)

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

branchpoints(x, ...)

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

## S3 method for class 'neuron'
branchpoints(x, subtrees = 1, ...)

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

endpoints(x, ...)

## S3 method for class 'neuron'
endpoints(x, subtrees = 1, ...)

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

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

Arguments

Details

branchpoints.neuron returns a list if more than one subtree is specified

Value

Integer point number of root/branch point

See Also

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

Scale and centre neuron 3D coordinates

Description

note that scale.dotprops recalculates the tangent vectors after scaling the 3D coords. See dotprops for details.

Usage

## S3 method for class 'neuron'
scale(x, center = TRUE, scale = TRUE)

## S3 method for class 'dotprops'
scale(x, center = TRUE, scale = TRUE)

Arguments

Details

If scale=TRUE, the neuron will be rescaled to unit sd in each axis. If center=TRUE, the neuron will be centred around the axis means. See base::scale.default for additional details.

Value

neuron with scaled coordinates

See Also

scale.default, *.neuron

Examples

n1.scaledown=scale(Cell07PNs[[1]],scale=c(2,2,3))
n1.scaleup=scale(Cell07PNs[[1]],scale=1/c(2,2,3))

Calculate length of all segments in neuron

Description

Calculate length of all segments in neuron

Usage

seglengths(x, all = FALSE, flatten = TRUE, sumsegment = TRUE)

Arguments

Details

A segment is an ubranched portion of neurite consisting of at least one vertex joined by edges.Only segments in x$SegList will be calculated unless all=TRUE. Segments containing only one point will have 0 length.

Value

A vector of lengths for each segment or when sumsegment=FALSE a list of vectors

See Also

as.seglist.neuron

Examples

summary(seglengths(Cell07PNs[[1]]))
hist(unlist(seglengths(Cell07PNs[[1]], sumsegment = FALSE)),
  br=20, main='histogram of edge lengths', xlab='edge lengths /microns')

Make/convert neuron connectivity information into a seglist object

Description

seglist makes a seglist object from a list of integer vectors of raw vertex ids. As a convenience if a vector of numeric ids are passed these are assumed to specify a neuron with 1 segment.

as.seglist.neuron will extract the seglist from a neuron, optionally extracting all subtrees (all=TRUE) and (in this case) flattening the list into a single hierarchy when flatten=TRUE. n.b. when all=TRUE but flatten=FALSE the result will always be a list of seglist objects (even if the neuron has only one subtree i.e. is fully connected).

as.seglist.igraph will convert a fully connected acyclic ngraph or igraph object into a seglist consisting of exactly one subtree.

Usage

seglist(...)

as.seglist(x, ...)

## S3 method for class 'neuron'
as.seglist(x, all = FALSE, flatten = FALSE, ...)

## S3 method for class 'igraph'
as.seglist(x, origin = NULL, Verbose = FALSE, ...)

Arguments

Details

see neuron for further information about seglists.

If the graph vertices have vid attributes, typically defining the original vertex ids of a graph that was then decomposed into subgraphs, then the origin is assumed to refer to one of these vids not a raw vertex id of the current graph. The returned seglist will also contain these original vertex ids.

The head of the first segment in the seglist will be the origin.

Value

A list with additional class seglist.

a list with one entry for each unbranched segment.

See Also

neuron

ngraph,igraph

Examples

sl=seglist(c(1:2),c(2:6))

Recalculate Neurons's SWCData using SegList and point information

Description

Uses the SegList field (indices into point array) to recalculate point numbers and parent points for SWC data field (d).

Usage

seglist2swc(x, d, RecalculateParents = TRUE, ...)

Arguments

Details

If any columns are missing then they are set to default values by normalise_swc. In particular

• PointNo integer 1:npoints

• Label = 0 (unknown)

• W NA_real

Note that each numeric entry in the incoming SegList is a raw index into the block of vertex data defined by d.

Value

A neuron if x was a neuron otherwise dataframe of swc data

See Also

as.neuron.data.frame, normalise_swc, neuron

Return a simplified segment graph for a neuron

Description

Return a simplified segment graph for a neuron

Usage

segmentgraph(
  x,
  weights = TRUE,
  segids = FALSE,
  exclude.isolated = FALSE,
  include.xyz = FALSE,
  reverse.edges = FALSE
)

Arguments

Details

The resultant graph will contain all branch and endpoints of the original neuron. This will be constructed from the SegList field, or where present, the SubTrees field (containing multiple SegLists for each isolated graph in the neuron). Each edge in the output graph will match one segment in the original SegList.

Value

igraph object containing only nodes of neuron keeping original labels (x$d$PointNo => V(g)$label) and vertex indices (1:nrow(x$d) => V(g)$vid).

Examples

sg=segmentgraph(Cell07PNs[[1]])
str(sg)
library(igraph)
plot(sg, edge.arrow.size=.4, vertex.size=10)

Find the (asymmetric) difference between two collections of objects

Description

Find the (asymmetric) difference between two collections of objects

Usage

setdiff(x, y, ...)

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

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

Arguments

Details

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

As a convenience setdiff.neuronlist allows y, the second collection, to be a character vector of names.

Value

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

See Also

setdiff

Simplify a registration list

Description

Simplify a registration list

Usage

simplify_reglist(reg, as.cmtk = NULL)

Arguments

Details

This function

• inverts any affine matrices with attribute "swap"

• collapses multiple affine matrices into a single affine

• optionally converts all registrations to CMTK on disk registrations when possible.

Note that if any of the registrations are in CMTK format, the default behaviour is to try to convert all of the other registrations into CMTK format to enable them to be passed to CMTK in a single command. If as.cmtk=TRUE then there will be an error if this is not possible.

See Also

reglist, xform, cmtkreg

Smooth the 3D coordinates of a neuron skeleton

Description

smooth_neuron smooths a neuron.

Usage

smooth_neuron(n, method = c("gauss", "spline"), ...)

smooth_segment_gauss(xyz, sigma, ...)

Arguments

Value

A new neuron with smoothed 3d coordinates

Examples

ns=smooth_neuron(Cell07PNs[[1]], sigma=2)
# plot in 2D zooming in on axon terminals 
plot(Cell07PNs[[1]], col='grey', xlim=c(260,290), ylim=c(115,90))
plot(ns, col='red', add=TRUE)

# 3D plot
plot3d(Cell07PNs[[1]], col='grey')
plot3d(ns, col='red')

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

Description

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

Usage

spine(
  n,
  UseStartPoint = FALSE,
  SpatialWeights = TRUE,
  invert = FALSE,
  rval = c("neuron", "length", "ids")
)

Arguments

Value

Either

• a neuron object corresponding to the longest path or

• the length of the longest path (when rval="length") or

• an integer vector of raw point indices (when rval="ids").

See Also

diameter, distances, prune_strahler for removing lower order branches from a neuron, prune for removing parts of a neuron by spatial criteria.

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

Examples

pn.spine=spine(Cell07PNs[[1]])

plot3d(Cell07PNs[[1]])
plot3d(pn.spine, lwd=4, col='black')

# just extract length
spine(Cell07PNs[[1]], rval='length')
# same result since StartPoint is included in longest path
spine(Cell07PNs[[1]], rval='length', UseStartPoint=TRUE)

# extract everything but the spine
antispine=spine(Cell07PNs[[1]], invert=TRUE)

plot3d(Cell07PNs[[1]])
plot3d(antispine, lwd=4, col='red')

Find the Strahler order of each point in a neuron

Description

The Strahler order will be 1 for each tip segment and then 1 + the maximum of the Strahler order of each parent segment for internal segments. Branch points will have the Strahler order of the closest segment to the root of which they are part.

Usage

strahler_order(x)

Arguments

Details

It is vital that the root of the neuron is valid since this determines the flow direction for calculation of the Strahler order. At present the function is not defined for neurons with multiple subtrees.

Internally, this function uses segmentgraph to find a reduced segmentgraph for the neuron.

Value

A list containing

• points Vector of integer Strahler orders for each point in the neuron

• segments Vector of integer Strahler orders for each segment in the neuron

References

https://en.wikipedia.org/wiki/Strahler_number

See Also

prune_strahler, a segmentgraph (a form of ngraph) representation is used to calculate the Strahler order.

Find 1D index given n-dimensional indices

Description

Emulates the MATLAB function sub2ind.

Usage

sub2ind(dims, indices)

Arguments

Subset methods for different nat objects

Description

These methods enable subsets of some nat objects including neurons and neuronlists to be obtained. See the help for each individual method for details.

See Also

subset.neuron, subset.dotprops, subset.hxsurf, subset.neuronlist

Subset points in dotprops object that match given conditions

Description

Subset points in dotprops object that match given conditions

Usage

## S3 method for class 'dotprops'
subset(x, subset, invert = FALSE, ...)

Arguments

Details

subset defines either logical or numeric indices, in which case these are simply applied to the matrices that define the points, vect fields of the dotprops object etc OR a function (which is called with the 3D points array and returns T/F. OR an expression vector).

Value

subsetted dotprops object

See Also

prune.dotprops, subset.neuron

Examples

## subset using indices ...
dp=kcs20[[10]]
dp1=subset(dp, 1:50)

# ... or an expression
dp2=subset(dp, alpha>0.7)
front=subset(dp, points[,'Z']<40)
# use a helper function
between=function(x, lower, upper) x>=lower & x<=upper
middle=middle=subset(dp, between(points[,'Z'], 40, 60))

# plot results in 3D

plot3d(front, col='red')
plot3d(middle, col='green')
plot3d(dp, col='blue')


## Not run: 

## subset using an selection function
s3d=select3d()
dp1=subset(dp, s3d(points))
# special case of previous version
dp2=subset(dp, s3d)
# keep the points that were removed from dp2
dp2.not=subset(dp, s3d, invert=TRUE)
# (another way of doing the same thing)
dp2.not=subset(dp, Negate(s3d))
stopifnot(all.equal(dp1, dp2))
dp2=subset(dp, alpha>0.5 & s3d(pointd))
dp3=subset(dp, 1:10)

## subset each dotprops object in a whole neuronlist
plot3d(kcs20)
s3d=select3d()
kcs20.partial = nlapply(kcs20, subset, s3d)
clear3d()
plot3d(kcs20.partial, col='red')
plot3d(kcs20, col='grey')

## End(Not run)

Subset hxsurf object to specified regions

Description

Subset hxsurf object to specified regions

Usage

## S3 method for class 'hxsurf'
subset(x, subset = NULL, drop = TRUE, rval = c("hxsurf", "names"), ...)

Arguments

Value

subsetted hxsurf object

See Also

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

Examples

# plot only vertical lobe
vertical_lobe=subset(MBL.surf, "VL")

plot3d(vertical_lobe, alpha=0.3)
plot3d(kcs20)

# there is also a shortcut for this
clear3d()
plot3d(MBL.surf, "VL", alpha=0.3)

Subset neuron by keeping only vertices that match given conditions

Description

Subset neuron by keeping only vertices that match given conditions

Usage

## S3 method for class 'neuron'
subset(x, subset, invert = FALSE, ...)

Arguments

Details

subset defines which vertices of the neuron to keep and is one of

• logical or numeric indices, in which case these are simply used to index the vertices in the order of the data.frame x$d. Note that any NA values are ignored.

• a function (which is called with the 3D points array and returns T/F vector)

• an expression evaluated in the context of the x$d data.frame containing the SWC specification of the points and connectivity of the neuron. This can therefore refer e.g. to the X,Y,Z location of vertices in the neuron.

Value

subsetted neuron

See Also

prune.neuron, prune_vertices, subset.dotprops

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

Examples

n=Cell07PNs[[1]]
# keep vertices if their X location is > 2000
n1=subset(n, X>200)
# diameter of neurite >1 
n2=subset(n, W>1)
# first 50 nodes
n3=subset(n, 1:50)
# everything but first 50 nodes
n4=subset(n, 1:50, invert=TRUE)

## subset neuron by graph structure
# first plot neuron and show the point that we will use to divide the neuron
n=Cell07PNs[[1]]
plot(n)
# this neuron has a tag defining a point at which the neuron enters a brain
# region (AxonLHEP = Axon Lateral Horn Entry Point)
points(t(xyzmatrix(n)[n$AxonLHEP, 1:2]), pch=19, cex=2.5)

# now find the points downstream (distal) of that with respect to the root
ng=as.ngraph(n)
# use a depth first search
distal_points=igraph::dfs(ng, root=n$AxonLHEP, unreachable=FALSE,
  mode='out')$order
distal_tree=subset(n, distal_points)
plot(distal_tree, add=TRUE, col='red', lwd=2)

# Find proximal tree as well
# nb this does not include the AxonLHEP itself as defined here
proximal_points=setdiff(igraph::V(ng), distal_points)
proximal_tree=subset(n, proximal_points)
plot(proximal_tree, add=TRUE, col='blue', lwd=2)

## Not run: 
## subset using interactively defined spatial regions
plot3d(n)
# nb you can save this select3d object using save or saveRDS functions
# for future non-interactive use
s3d=select3d()
n4=subset(n, s3d(xyzmatrix(n)))
# special case of previous version
n5=subset(n, s3d)
stopifnot(all.equal(n4,n5))
# keep the points that were removed from n1
n4.not=subset(n,Negate(s3d))
# vertices with x position > 100 and inside the selector function
n6=subset(n,X>100 & s3d(X,Y,Z))

## subset each neuron object in a whole neuronlist
n10=Cell07PNs[1:10]
plot3d(n10, lwd=0.5, col='grey')
n10.crop = nlapply(n10, subset, X>250)
plot3d(n10.crop, col='red')

## subset a neuron using a surface
library(nat.flybrains)
# extract left lateral horn surface and convert to mesh3d 
lh=as.mesh3d(subset(IS2NP.surf, "LH_L"))
# subset neuron with this surface
x=subset(Cell07PNs[[1]], function(x) pointsinside(x, lh))
shade3d(lh, alpha=0.3)
plot3d(x, lwd=3, col='blue')
# Now find the parts of the neuron outside the surface
y=subset(Cell07PNs[[1]], function(x) Negate(pointsinside)(x, lh))
plot3d(y, col='red', lwd=2)

## End(Not run)

Subset neuronlist returning either new neuronlist or names of chosen neurons

Description

Subset neuronlist returning either new neuronlist or names of chosen neurons

Usage

## S3 method for class 'neuronlist'
subset(
  x,
  subset,
  filterfun,
  rval = c("neuronlist", "names", "data.frame"),
  ...
)

Arguments