xyzmatrix: Get and assign coordinates for classes containing 3D vertex...

In jefferis/nat: NeuroAnatomy Toolbox for Analysis of 3D Image Data

Get and assign coordinates for classes containing 3D vertex data

Description

xyzmatrix gets coordinates from objects containing 3D vertex data

xyzmatrix.list will parse a list containing triplets of 3 numeric values.

xyzmatrix<- assigns xyz elements of neuron or dotprops object and can also handle matrix like objects with columns named X, Y, Z or x, y, z.

xyzmatrix2str will convert the XYZ locations associated with an object to a character vector (by default comma separated).

xyzmatrix2list will convert the Nx3 matrix of XYZ locations associated with an object to a list of length N with each element a vector of length 3.

Usage

xyzmatrix(x, ...)

## Default S3 method:
xyzmatrix(x, y = NULL, z = NULL, ...)

## S3 method for class 'list'
xyzmatrix(x, empty2na = TRUE, ...)

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

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

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

## S3 method for class 'shapelist3d'
xyzmatrix(x, ...)

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

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

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

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

xyzmatrix(x) <- value

## S3 replacement method for class 'character'
xyzmatrix(x) <- value

xyzmatrix2str(x, format = "%g,%g,%g", sep = NULL)

xyzmatrix2list(x)

## S3 replacement method for class 'neuron'
xyzmatrix(x) <- value

## S3 replacement method for class 'dotprops'
xyzmatrix(x) <- value

## S3 replacement method for class 'hxsurf'
xyzmatrix(x) <- value

## S3 replacement method for class 'igraph'
xyzmatrix(x) <- value

## S3 replacement method for class 'shape3d'
xyzmatrix(x) <- value

## S3 replacement method for class 'mesh3d'
xyzmatrix(x) <- value

## S3 replacement method for class 'neuronlist'
xyzmatrix(x) <- value

## S3 replacement method for class 'shapelist3d'
xyzmatrix(x) <- value

Arguments

x	object containing 3D coordinates
...	additional arguments passed to methods
y, z	separate y and z coordinates
empty2na	Whether or not to convert empty elements (NULL or list()) into NAs. Default TRUE.
value	Nx3 matrix specifying new xyz coords
format	A sprintf compatible format string. The default will give comma separated values.
sep	A character vector specifying a separator string. Overrides format when present. The default value of format is equivalent to sep=",".

Details

Note that xyzmatrix can extract or set 3D coordinates in a matrix or data.frame that either has exactly 3 columns or has 3 columns named X,Y,Z or x,y,z. As of Nov 2020, if these columns are character vectors, they will be correctly converted to numeric (with a warning for any NA values). As of Jan 2021 if x is a numeric vector containing exactly 3 numbers it will be parsed as a 1x3 matrix. Support has also been added for setting a list containing 3-vectors in each element.

Value

For xyzmatrix: Nx3 matrix containing 3D coordinates

For xyzmatrix<-: Original object with modified coords

Getting and setting from character vectors

xyzmatrix can also both get and set 3D coordinates from a character vector (including a single data frame column) in which each string encodes all 3 coordinates e.g. "-1, 4, 10". It should handle a range of separators such as spaces, tabs, commas, semicolons and ignore extraneous characters such as brackets. Note that data are rounded by zapsmall in the replacement version to try to avoid cases where rounding errors result in long strings of digits to the right of the decimal place.

Replacement into character vectors introduces a number of corner cases when there are not exactly 3 numbers to replace in the target vector. We handle them as follows:

• 0 values in target, >0 in replacement: use a default pattern

• 1-2 values in target, same number of "good" values in replacement: insert those replacement value

• 1-2 values in target, different number of values in replacement: use default pattern, give a warning

The default pattern will be the first entry in x with 3 numbers. Should there not be such a value, then the pattern will be "x, y, z".

See Also

xyzmatrix

Examples

# see all available methods for different classes
methods('xyzmatrix')
# ... and for the assignment method
methods('xyzmatrix<-')

# basic usage
xyzmatrix(cbind(-1,2,3))

# character vector - useful e.g. when encoded in 1 column of a table 
str123="(-1,+2,3)"
xyzmatrix(str123)
# replace
xyzmatrix(str123) <- xyzmatrix(str123)/3
str123
xyzmatrix(str123) <- xyzmatrix(str123)*3
str123
n=Cell07PNs[[1]]
xyzmatrix(n)<-xyzmatrix(n)
stopifnot(isTRUE(
  all.equal(xyzmatrix(n),xyzmatrix(Cell07PNs[[1]]))
))
head(xyzmatrix2str(kcs20[[1]]))
head(xyzmatrix2str(kcs20[[1]], format="(%g;%g;%g)"))
# if you want to process the xyz locations (here rounded to nearest nm)
# you must extract them from complex objects yourself
xyzmatrix2str(round(xyzmatrix(kcs20[[1]])*1000), format="%d,%d,%d")[1:3]
xyzmatrix2list(kcs20[[1]])[1:2]

jefferis/nat documentation built on Feb. 22, 2024, 12:45 p.m.