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

Value

A neuronlist

Arguments

X: A neuronlist
FUN: Function to be applied to each element of X
...: Additional arguments for FUN (see details)
subset: Character, numeric or logical vector specifying on which subset of X the function FUN should be applied. Elements outside the subset are passed through unmodified.
OmitFailures: Whether to omit neurons for which FUN gives an error. The default value (NA) will result in nlapply stopping with an error message the moment there is an eror. For other values, see details.
.progress: Character vector specifying the type of progress bar (see create_progress_bar for options.) The default value of "auto" shows a progress bar in interactive use when there are >=10 elements in X. The default value can be overridden for the current session by setting the value of options(nat.progressbar) (see examples).
MoreArgs: a list of other arguments to FUN.
SIMPLIFY: logical or character string; attempt to reduce the result to a vector, matrix or higher dimensional array; see the simplify argument of sapply.
USE.NAMES: logical; use the names of the first ... argument, or if that is an unnamed character vector, use that vector as the names.

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.

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

Examples

Run this code

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

if (FALSE) {
# 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)
}

if (FALSE) {
## 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))
}

## 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))
# \donttest{
open3d()
plot3d(kcs20[1:3])
plot3d(xyzflip)
close3d()
# }

if (FALSE) {
## 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)
}

Run the code above in your browser using DataCamp Workspace