plot3d.neuronlist: 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 neuronlist
plot3d(
  x,
  subset = NULL,
  col = NULL,
  colpal = rainbow,
  skipRedraw = ifelse(interactive(), 200L, TRUE),
  WithNodes = FALSE,
  soma = FALSE,
  ...,
  SUBSTITUTE = TRUE
)
# S3 method for character
plot3d(x, db = NULL, ...)

Value

list of values of plot3d with subsetted dataframe as attribute

'df'

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: When plotting more than this many (default 200) neurons skip redraw for individual neurons (this is much faster for large number of neurons). Can also accept logical values TRUE (always skip) FALSE (never skip).
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.
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')

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.

Examples

Run this code

open3d()
plot3d(kcs20,type=='gamma',col='green')
# \donttest{
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)
# }
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)
}