nlapply | R Documentation |
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")
)
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 |
OmitFailures |
Whether to omit neurons for which |
.progress |
Character vector specifying the type of progress bar (see
Progress bar section for details) The default value of |
MoreArgs |
a list of other arguments to |
SIMPLIFY |
logical or character string; attempt to reduce the
result to a vector, matrix or higher dimensional array; see
the |
USE.NAMES |
logical; use the names of the first ... argument, or if that is an unnamed character vector, use that vector as the names. |
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)
.
A neuronlist
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.
lapply
mapply
Other neuronlist:
*.neuronlist()
,
is.neuronlist()
,
neuronlist()
,
neuronlist-dataframe-methods
,
neuronlistfh()
,
neuronlistz()
,
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')
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)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.