bpvalidate {BiocParallel} | R Documentation

## Tools for developing functions for parallel execution in distributed memory

### Description

`bpvalidate` interrogates the function environment and search path to locate undefined symbols.

### Usage

    bpvalidate(fun, signal = c("warning", "error", "silent"))

### Arguments

`fun` | The function to be checked. `typeof(fun)` must return either `"closure"` or `"builtin"`.
`signal` | `character(1)` matching `"warning", "error", "silent"` or a function with signature `(..., call.)` to be invoked when reporting errors. Using `"silent"` suppresses output; `"warning"` and `"error"` emit warnings or errors when `fun` contains references to unknown variables or variables defined in the global environment (and hence not serialized to workers).

### Details

`bpvalidate` tests if a function can be run in a distributed memory environment (e.g., SOCK clusters, Windows machines). `bpvalidate` looks in the environment of `fun`, in the NAMESPACE exports of libraries loaded in `fun`, and along the search path to identify any symbols outside the scope of `fun`.

`bpvalidate` can be used to check functions passed to the bp* family of functions in `BiocParallel` or other packages that support parallel evaluation on clusters such as `snow`, `BatchJobs`, `Rmpi`, etc.

testing package functions

  The environment of a function defined inside a package is the NAMESPACE of the package. It is important to test these functions as they will be called from within the package, with the appropriate environment. Specifically, do not copy/paste the function into the workspace; once this is done the GlobalEnv becomes the function environment.

  To test a package function, load the package then call the function by name (myfun) or explicitly (mypkg:::myfun) if not exported.

testing workspace functions

  The environment of a function defined in the workspace is the GlobalEnv. Because these functions do not have an associated package NAMESPACE, the functions and variables used in the body must be explicitly passed or defined. See examples.

  Defining functions in the workspace is often done during development or testing. If the function is later moved inside a package, it can be rewritten in a more lightweight form by taking advantage of imported symbols in the package NAMESPACE.

NOTE: `bpvalidate` does not currently work on Generics.

### Value

An object of class `BPValidate` summarizing symbols identified in the global environment or search path, or undefined in the enviornments the function was defined in. Details are only available via 'show()'.

### Author(s)

Martin Morgan mailto:mtmorgan.bioc@gmail.com and Valerie Obenchain.

### Examples

    ## ---------------------------------------------------------------------
    ## Interactive use
    ## ---------------------------------------------------------------------

    fun <- function()
        .__UNKNOWN_SYMBOL__
    bpvalidate(fun, "silent")

    ## ---------------------------------------------------------------------
    ## Testing package functions
    ## ---------------------------------------------------------------------

    ## Not run:
    library(myPkg)

    ## Test exported functions by name or the double colon:
    bpvalidate(myExportedFun)
    bpvalidate(myPkg::myExportedFun)

    ## Non-exported functions are called with the triple colon:
    bpvalidate(myPkg:::myInternalFun)

    ## End(Not run)

    ## ---------------------------------------------------------------------
    ## Testing workspace functions
    ## ---------------------------------------------------------------------

    ## Functions defined in the workspace have the .GlobalEnv as their
    ## environment. Often the symbols used inside the function body
    ## are not defined in .GlobalEnv and must be passed explicitly.

    ## Loading libraries:
    ## In 'fun1' countBam() is flagged as unknown:
    fun1 <- function(fl, ...)
        countBam(fl)
    v <- bpvalidate(fun1)

    ## countBam() is not defined in .GlobalEnv and must be passed as
    ## an argument or made available by loading the library.
    fun2 <- function(fl, ...) {
        Rsamtools::countBam(fl)
    }
    v <- bpvalidate(fun2)

    ## Passing arguments:
    ## 'param' is defined in the workspace but not passed to 'fun3'.
    ## bpvalidate() flags 'param' as being found '.GlobalEnv' which means
    ## it is not defined in the function environment or inside the function.
    library(Rsamtools)
    param <- ScanBamParam(flag=scanBamFlag(isMinusStrand=FALSE))

    fun3 <- function(fl, ...) {
      Rsamtools::countBam(fl, param=param)
    }
    v <- bpvalidate(fun3)

    ## 'param' is explicitly passed by adding it as a formal argument.
    fun4 <- function(fl, ..., param) {
      Rsamtools::countBam(fl, param=param)
    }
    bpvalidate(fun4)

    ## The corresponding call to a bp* function includes 'param':
    ## Not run:
    bplapply(files, fun4, param=param, BPPARAM=SnowParam(2))

    ## End(Not run)

[Package BiocParallel version 1.28.3 Index]