nlapply: lapply and mapply for neuronlists (with optional...
In natverse/nat: NeuroAnatomy Toolbox for Analysis of 3D Image Data

nlapply

R Documentation

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

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

Usage

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.

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

Value

A neuronlist

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')
close3d()

## Not run: 
# 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)

## End(Not run)

## Not run: 
## 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))

## End(Not run)

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

open3d()
plot3d(kcs20[1:3])
plot3d(xyzflip)
close3d()


## Not run: 
## 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)

## End(Not run)

natverse/nat documentation built on Feb. 19, 2024, 7:19 a.m.