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

progress_natprogress provides a progress bar compatible with the progress::progress_bar.

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

progress_natprogress(...)

nmapply(
  FUN,
  X,
  ...,
  MoreArgs = NULL,
  SIMPLIFY = FALSE,
  USE.NAMES = TRUE,
  subset = NULL,
  OmitFailures = NA,
  .progress = getOption("nat.progress", default = "auto")
)

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 error. For other values, see details.

.progress

Character vector specifying the type of progress bar (see Progress bar section for details) The default value of "auto" shows a progress bar in interactive use after 2s. The default value can be overridden for the current session by setting the value of options(nat.progressbar) (see examples). Values of T and F are aliases for 'text' and 'none', respectively.

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.

Value

A neuronlist

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

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

Progress bar

There are currently two supported approaches to defining progress bars for nlapply. The default (when progress="auto") now uses a progress bar built using progress_bar from the progress package, which can be highly customised. The alternative is to use the progress bars distributed directly with the plyr package such as progress_text.

In either case the value of the .progress argument must be a character vector which names a function. According to plyr's convention an external function called progress_myprogressbar will be identified by setting the argument to .progress="myprogressbar". By default the supplied progress_natprogress function will be used when .progress="auto"; this function will probably not be used directly by end users; however it must be exported for nlapply with progress to work properly in other functions.

For nmapply only the default nat_progress bar can be shown for architectural reasons. It will be shown in interactive mode when .progress='auto' (the default). The progress bar can be suppressed by setting .progress='none'. Any other value will result in a progress bar being shown in both interactive and batch modes.

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')
rgl.close()

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

# this artificial example will show a progress bar in interactive use
xyzflip=nmapply(function(...) {Sys.sleep(.2);mirror(...)}, kcs20,
  mirrorAxis= sample(LETTERS[24:26], size = 20, replace = TRUE),
  mirrorAxisSize=runif(20, min=40, max=200))
# \donttest{
open3d()
plot3d(kcs20[1:3])
plot3d(xyzflip)
rgl.close()
# }

if (FALSE) {
## Override default progress bar behaviour via options
# sleep 50ms per neuron to ensure progress bar gets triggered
sl=nlapply(Cell07PNs, FUN = function(x) {Sys.sleep(0.05);seglengths(x)})
# the default progess bar for nat < 1.9.1
options(nat.progress='traditional')
sl=nlapply(Cell07PNs, FUN = seglengths)
# no progress bar ever
options(nat.progress='none')
sl=nlapply(Cell07PNs, FUN = function(x) {Sys.sleep(0.05);seglengths(x)})
# back to normal
options(nat.progress=NULL)
sl=nlapply(Cell07PNs, FUN = seglengths)
}