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 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` must be a scalar integer >= 0L. This argument applies to `SnowParam` and `MulticoreParam` only; `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`.

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

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

[Package BiocParallel version 1.28.3 Index]