BiocParallelParam-class {BiocParallel} | R Documentation |
BiocParallelParam objects
Description
The BiocParallelParam
virtual class stores configuration parameters
for parallel execution. Concrete subclasses include SnowParam
,
MulticoreParam
, BatchtoolsParam
, and DoparParam
and SerialParam
.
Details
BiocParallelParam
is the virtual base class on which other
parameter objects build. There are 5 concrete subclasses:
SnowParam
: distributed memory computingMulticoreParam
: shared memory computingBatchtoolsParam
: scheduled cluster computingDoparParam
: foreach computingSerialParam
: non-parallel execution
The parameter objects hold configuration parameters related to the method of parallel execution such as shared memory, independent memory or computing with a cluster scheduler.
Construction
The BiocParallelParam
class is virtual and has no constructor.
Instances of the subclasses can be created with the following:
-
SnowParam()
-
MulticoreParam()
-
BatchtoolsParam()
-
DoparParam()
-
SerialParam()
Accessors
Back-end control
In the code below BPPARAM
is a BiocParallelParam
object.
-
bpworkers(x)
,bpworkers(x, ...)
:integer(1)
orcharacter()
. Gets the number or names of the back-end workers. The setter is supported for SnowParam and MulticoreParam only. -
bpnworkers(x)
:integer(1)
. Gets the number of the back-end workers. -
bptasks(x)
,bptasks(x) <- value
:integer(1)
. Get or set the number of tasks for a job.value
can be a scalar integer > 0L, or integer 0L for matching the worker number, orNA
for representing an infinite task number.DoparParam
andBatchtoolsParam
have their own approach to dividing a job among workers.We define a job as a single call to a function such as
bplapply
,bpmapply
etc. A task is the division of theX
argument into chunks. Whentasks == 0
(default),X
is divided by the number of workers. This approach distributesX
in (approximately) equal chunks.A
tasks
value of > 0 dictates the total number of tasks. Values can range from 1 (all ofX
to a single worker) to the length ofX
(each element ofX
to a different worker); values greater thanlength(X)
(e.g.,.Machine$integer.max
) are rounded tolength(X)
.When the length of
X
is less than the number of workers each element ofX
is sent to a worker andtasks
is ignored. Another case where thetasks
value is ignored is when using thebpiterate
function; the number of tasks are defined by the number of data chunks returned by theITER
function. -
bpstart(x)
:logical(1)
. Starts the back-end, if necessary. -
bpstop(x)
:logical(1)
. Stops the back-end, if necessary and possible. -
bpisup(x)
:logical(1)
. Tests whether the back-end is available for processing, returning a scalar logical value.bp*
functions such asbplapply
automatically start the back-end if necessary. -
bpbackend(x)
,bpbackend(x) <- value
: Gets or sets the parallelbpbackend
. Not all back-ends can be retrieved; seemethods("bpbackend")
. -
bplog(x)
,bplog(x) <- value
: Get or enable logging, if available.value
must be alogical(1)
. -
bpthreshold(x)
,bpthreshold(x) <- value
: Get or set the logging threshold.value
must be acharacter(1)
string of one of the levels defined in thefutile.logger
package: “TRACE”, “DEBUG”, “INFO”, “WARN”, “ERROR”, or “FATAL”. -
bplogdir(x)
,bplogdir(x) <- value
: Get or set an optional directory for saving log files. The directory must already exist with read / write ability. -
bpresultdir(x)
,bpresultdir(x) <- value
: Get or set an optional directory for saving results as 'rda' files. The directory must already exist with read / write ability. -
bptimeout(x)
,bptimeout(x) <- value
:numeric(1)
Time (in seconds) allowed for worker to complete a task. This value is passed to base::setTimeLimit() as both thecpu
andelapsed
arguments. If the computation exceedstimeout
an error is thrown with message 'reached elapsed time limit'. -
bpexportglobals(x)
,bpexportglobals(x) <- value
:logical(1)
Exportbase::options()
from manager to workers? DefaultTRUE
. -
bpexportvariables(x)
,bpexportvariables(x) <- value
:logical(1)
Automatically export the variables which are defined in the global environment and used by the function from manager to workers. DefaultTRUE
. -
bpprogressbar(x)
,bpprogressbar(x) <- value
: Get or set the value to enable text progress bar.value
must be alogical(1)
. -
bpRNGseed(x)
,bpRNGseed(x) <- value
: Get or set the seed for random number generaton.value
must be anumeric(1)
orNULL
. -
bpjobname(x)
,bpjobname(x) <- value
: Get or set the job name. -
bpforceGC(x)
,bpforceGC(x) <- value
: Get or set whether 'garbage collection' should be invoked at the end of each call toFUN
. -
bpfallback(x)
,bpfallback(x) <- value
: Get or set whether the fallbackSerialParam
should be used (e.g., for efficiency when starting a cluster) when the currentBPPARAM
has not been started and the worker number is less than or equal to 1.
Error Handling
In the code below BPPARAM
is a BiocParallelParam
object.
-
bpstopOnError(x)
,bpstopOnError(x) <- value
:logical()
. Controls if the job stops when an error is hit.stop.on.error
controls whether the job stops after an error is thrown. WhenTRUE
, the output contains all successfully completed results up to and including the error. Whenstop.on.error == TRUE
all computations stop once the error is hit. WhenFALSE
, the job runs to completion and successful results are returned along with any error messages.
Methods
Evaluation
In the code below BPPARAM
is a BiocParallelParam
object.
Full documentation for these functions are on separate man pages: see
?bpmapply
, ?bplapply
, ?bpvec
, ?bpiterate
and
?bpaggregate
.
-
bpmapply(FUN, ..., MoreArgs=NULL, SIMPLIFY=TRUE, USE.NAMES=TRUE, BPPARAM=bpparam())
-
bplapply(X, FUN, ..., BPPARAM=bpparam())
-
bpvec(X, FUN, ..., AGGREGATE=c, BPPARAM=bpparam())
-
bpiterate(ITER, FUN, ..., BPPARAM=bpparam())
-
bpaggregate(x, data, FUN, ..., BPPARAM=bpparam())
Other
In the code below BPPARAM
is a BiocParallelParam
object.
-
show(x)
Author(s)
Martin Morgan and Valerie Obenchain.
See Also
-
SnowParam
for computing in distributed memory -
MulticoreParam
for computing in shared memory -
BatchtoolsParam
for computing with cluster schedulers -
DoparParam
for computing with foreach -
SerialParam
for non-parallel execution
Examples
getClass("BiocParallelParam")
## For examples see ?SnowParam, ?MulticoreParam, ?BatchtoolsParam
## and ?SerialParam.