BiocParallelParam-class: BiocParallelParam objects

In Bioconductor/BiocParallel: Bioconductor facilities for parallel evaluation

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 computing

MulticoreParam:

shared memory computing

BatchtoolsParam:

scheduled cluster computing

DoparParam:

foreach computing

SerialParam:

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) or character(). 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, or NA for representing an infinite task number. DoparParam and BatchtoolsParam 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 the X argument into chunks. When tasks == 0 (default), X is divided by the number of workers. This approach distributes X in (approximately) equal chunks.

A tasks value of > 0 dictates the total number of tasks. Values can range from 1 (all of X to a single worker) to the length of X (each element of X to a different worker); values greater than length(X) (e.g., .Machine$integer.max) are rounded to length(X).

When the length of X is less than the number of workers each element of X is sent to a worker and tasks is ignored. Another case where the tasks value is ignored is when using the bpiterate function; the number of tasks are defined by the number of data chunks returned by the ITER 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 as bplapply automatically start the back-end if necessary.

bpbackend(x), bpbackend(x) <- value:

Gets or sets the parallel bpbackend. Not all back-ends can be retrieved; see methods("bpbackend").

bplog(x), bplog(x) <- value:

Get or enable logging, if available. value must be a logical(1).

bpthreshold(x), bpthreshold(x) <- value:

Get or set the logging threshold. value must be a character(1) string of one of the levels defined in the futile.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 the cpu and elapsed arguments. If the computation exceeds timeout an error is thrown with message 'reached elapsed time limit'.

bpexportglobals(x), bpexportglobals(x) <- value:

logical(1) Export base::options() from manager to workers? Default TRUE.

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. Default TRUE.

bpprogressbar(x), bpprogressbar(x) <- value:

Get or set the value to enable text progress bar. value must be a logical(1).

bpRNGseed(x), bpRNGseed(x) <- value:

Get or set the seed for random number generaton. value must be a numeric(1) or NULL.

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 to FUN.

bpfallback(x), bpfallback(x) <- value:

Get or set whether the fallback SerialParam should be used (e.g., for efficiency when starting a cluster) when the current BPPARAM 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. When TRUE, the output contains all successfully completed results up to and including the error. When stop.on.error == TRUE all computations stop once the error is hit. When FALSE, 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.

Bioconductor/BiocParallel documentation built on Oct. 31, 2024, 6:58 a.m.