blockApply {DelayedArray} | R Documentation |
blockApply() and family
Description
A family of convenience functions to walk on the blocks of an array-like object and process them.
Usage
## Main looping functions:
blockApply(x, FUN, ..., grid=NULL, as.sparse=FALSE,
BPPARAM=getAutoBPPARAM(), verbose=NA)
blockReduce(FUN, x, init, ..., BREAKIF=NULL, grid=NULL, as.sparse=FALSE,
verbose=NA)
## Lower-level looping functions:
gridApply(grid, FUN, ..., BPPARAM=getAutoBPPARAM(), verbose=NA)
gridReduce(FUN, grid, init, ..., BREAKIF=NULL, verbose=NA)
## Retrieve grid context for the current block/viewport:
effectiveGrid(envir=parent.frame(2))
currentBlockId(envir=parent.frame(2))
currentViewport(envir=parent.frame(2))
## Get/set automatic parallel back-end:
getAutoBPPARAM()
setAutoBPPARAM(BPPARAM=NULL)
## For testing/debugging callback functions:
set_grid_context(effective_grid, current_block_id, envir=parent.frame(1))
Arguments
x |
An array-like object, typically a DelayedArray object or derivative. |
FUN |
For IMPORTANT: If For Beware that
In both cases, the exact names of the two arguments doesn't really matter.
Also |
... |
Additional arguments passed to |
grid |
The grid used for the walk, that is, an ArrayGrid object that defines the blocks (or viewports) to walk on. For |
as.sparse |
Passed to the internal calls to |
BPPARAM |
A |
verbose |
Whether block processing progress should be displayed or not.
If set to |
init |
The value to pass to the first call to |
BREAKIF |
An optional callback function that detects a break condition.
Must return |
envir |
Do not use (unless you know what you are doing). |
effective_grid , current_block_id |
See Details below. |
Details
effectiveGrid()
, currentBlockId()
, and currentViewport()
return the "grid context" for the block/viewport being currently processed.
By "grid context" we mean:
The effective grid, that is, the user-supplied grid or
defaultAutoGrid(x)
if the user didn't supply any grid.The current block id (a.k.a. block rank).
The current viewport, that is, the ArrayViewport object describing the position of the current block w.r.t. the effective grid.
Note that effectiveGrid()
, currentBlockId()
, and
currentViewport()
can only be called (with no arguments) from
**within** the callback functions FUN
and/or BREAKIF
passed to blockApply()
and family.
If you need to be able to test/debug your callback function as a standalone function, set an arbitrary effective grid and current block id by calling
set_grid_context(effective_grid, current_block_id)
**right before** calling the callback function.
Value
For blockApply()
and gridApply()
, a list with one
list element per block/viewport visited.
For blockReduce()
and gridReduce()
, the result of
the last call to FUN
.
For effectiveGrid()
, the grid (ArrayGrid object) being
effectively used.
For currentBlockId()
, the id (a.k.a. rank) of the current block.
For currentViewport()
, the viewport (ArrayViewport object)
of the current block.
See Also
-
defaultAutoGrid
and family to create automatic grids to use for block processing of array-like objects. -
ArrayGrid for the formal representation of grids and viewports.
-
read_block
andwrite_block
. -
MulticoreParam
,SnowParam
, andbpparam
, from the BiocParallel package. -
DelayedArray objects.
Examples
m <- matrix(1:60, nrow=10)
m_grid <- defaultAutoGrid(m, block.length=16, block.shape="hypercube")
## ---------------------------------------------------------------------
## blockApply()
## ---------------------------------------------------------------------
blockApply(m, identity, grid=m_grid)
blockApply(m, sum, grid=m_grid)
blockApply(m, function(block) {block + currentBlockId()*1e3}, grid=m_grid)
blockApply(m, function(block) currentViewport(), grid=m_grid)
blockApply(m, dim, grid=m_grid)
## The grid does not need to be regularly spaced:
a <- array(runif(8000), dim=c(25, 40, 8))
a_tickmarks <- list(c(7L, 15L, 25L), c(14L, 22L, 40L), c(2L, 8L))
a_grid <- ArbitraryArrayGrid(a_tickmarks)
a_grid
blockApply(a, function(block) sum(log(block + 0.5)), grid=a_grid)
## See block processing in action:
blockApply(m, function(block) sum(log(block + 0.5)), grid=m_grid,
verbose=TRUE)
## Use parallel evaluation:
library(BiocParallel)
if (.Platform$OS.type != "windows") {
BPPARAM <- MulticoreParam(workers=4)
} else {
## MulticoreParam() is not supported on Windows so we use
## SnowParam() on this platform.
BPPARAM <- SnowParam(4)
}
blockApply(m, function(block) sum(log(block + 0.5)), grid=m_grid,
BPPARAM=BPPARAM, verbose=TRUE)
## Note that blocks can be visited in any order!
## ---------------------------------------------------------------------
## blockReduce()
## ---------------------------------------------------------------------
FUN <- function(block, init) anyNA(block) || init
blockReduce(FUN, m, init=FALSE, grid=m_grid, verbose=TRUE)
m[10, 1] <- NA
blockReduce(FUN, m, init=FALSE, grid=m_grid, verbose=TRUE)
## With early bailout:
blockReduce(FUN, m, init=FALSE, BREAKIF=identity, grid=m_grid,
verbose=TRUE)
## Note that this is how the anyNA() method for DelayedArray objects is
## implemented.