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

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

# S3 method for neuronlist
plot3d(
  x,
  subset = NULL,
  col = NULL,
  colpal = rainbow,
  skipRedraw = TRUE,
  add = TRUE,
  WithNodes = FALSE,
  soma = FALSE,
  ...,
  SUBSTITUTE = TRUE,
  gridlines = FALSE,
  plotengine = getOption("nat.plotengine")
)

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

Arguments

x

a neuron list or, for plot3d.character, a character vector of neuron names. The default neuronlist used by plot3d.character can be set by using options(nat.default.neuronlist='mylist'). See ?nat for details. nat-package.

subset

Expression evaluating to logical mask for neurons. See details.

col

An expression specifying a colour evaluated in the context of the dataframe attached to nl (after any subsetting). See details.

colpal

A vector of colours or a function that generates colours

skipRedraw

By default TRUE which is much faster when plotting large numbers of neurons). Can also accept FALSE (never skip) or integers specifying a threshold number of neurons, above which redrawing is skipped.

add

Whether to add the neuron to existing rgl plot rather than clearing the scene (default TRUE)

WithNodes

Whether to plot points for end/branch points. Default: FALSE.

soma

Whether to plot a sphere at neuron's origin representing the soma. Either a logical value or a numeric indicating the radius (default FALSE). When soma=TRUE the radius is hard coded to 2.

...

options passed on to plot3d (such as colours, line width etc)

SUBSTITUTE

Whether to substitute the expressions passed as arguments subset and col. Default: TRUE. For expert use only, when calling from another function.

gridlines

Whether to display gridlines when using plotly as the backend plotting engine (default: FALSE)

plotengine

the plotting backend engine to use either 'rgl' or 'plotly'.

db

A neuronlist to use as the source of objects to plot. If NULL, the default, will use the neuronlist specified by options('nat.default.neuronlist')

Value

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

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.

See also

nat-package

Examples

open3d()
plot3d(kcs20,type=='gamma',col='green')
# \donttest{
nclear3d()
plot3d(kcs20,col=type)

nclear3d()
plot3d(Cell07PNs,Glomerulus=="DA1",col='red')
plot3d(Cell07PNs,Glomerulus=="VA1d",col='green')

# Note use of default colour for non DA1 neurons
nclear3d()
plot3d(Cell07PNs,col=Glomerulus, colpal=c(DA1='red', 'grey'))

# a subset expression
nclear3d()
plot3d(Cell07PNs,Glomerulus%in%c("DA1",'VA1d'),
  col=c("red","green")[factor(Glomerulus)])
# the same but not specifying colours explicitly
nclear3d()
plot3d(Cell07PNs,Glomerulus%in%c("DA1",'VA1d'),col=Glomerulus)
# }
if (FALSE) {
## 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)
}