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")
)A neuronlist
Function to be applied to each element of X
Additional arguments for FUN (see details)
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.
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.
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.
a list of other arguments to FUN.
logical or character string; attempt to reduce the
result to a vector, matrix or higher dimensional array; see
the simplify argument of sapply.
logical; use the names of the first ... argument, or if that is an unnamed character vector, use that vector as the names.
A neuronlist
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).
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.
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.
Other neuronlist:
*.neuronlist(),
is.neuronlist(),
neuronlist-dataframe-methods,
neuronlistfh(),
neuronlistz(),
neuronlist(),
read.neurons(),
write.neurons()
## 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)
}