BiocSingularParam: BiocSingularParam classes

In LTLA/BiocSingular: Singular Value Decomposition for Bioconductor Packages

BiocSingularParam classes

Description

Classes for specifying the type of singular value decomposition (SVD) algorithm and associated parameters.

Usage

ExactParam(deferred=FALSE, fold=Inf)

IrlbaParam(deferred=FALSE, fold=Inf, extra.work=7, ...)

RandomParam(deferred=FALSE, fold=Inf, ...)

FastAutoParam(deferred=FALSE, fold=Inf)

bsparam()

Arguments

deferred	Logical scalar indicating whether centering/scaling should be deferred, see ?"BiocSingular-options".
fold	Numeric scalar specifying the minimum fold-difference for cross-product calculation, see ?"BiocSingular-options".
extra.work	Integer scalar, additional dimensionality of the workspace in runIrlbaSVD.
...	Additional arguments to pass to runIrlbaSVD or runRandomSVD. This should not include any named arguments in those functions.

Details

The BiocSingularParam class controls dispatch of the runSVD generic to specific algorithms for SVD. The BiocSingularParam class itself is virtual, with several concrete subclasses available in this package:

ExactParam:

exact SVD with runExactSVD.

IrlbaParam:

approximate SVD with irlba via runIrlbaSVD.

RandomParam:

approximate SVD with rsvd via runRandomSVD.

FastAutoParam:

fast approximate SVD, chosen based on the matrix representation.

These objects also hold parameters specifying how each algorithm should be run on an arbitrary data set. See the associated documentation pages for each specific SVD method for more details.

Value

Each constructor returns a BiocSingularParam subclass of the same type, containing the specified parameters.

Methods

In the following code snippets, x is a BiocSingularParam object.

show(object):

Display the class of object and a summary of the set parameters.

bsfold(object):

Return a numeric scalar specifying the fold-difference for cross-product calculation, see “Computing the cross-product” in ?"BiocSingular-options".

bsdeferred(object):

Return a logical scalar indicating whether centering and scaling should be deferred. see “Deferred centering and scaling” in ?"BiocSingular-options".

Automatically choosing a fast SVD algorithm

Running runSVD with a FastAutoParam object will dispatch to runIrlbaSVD for most matrices. This is the default choice as IRLBA is fast and the approximation is highly similar to the exact SVD result. The exception is that of instances of the DelayedMatrix class, or any subclass that lacks its own specialized %*% method. In such cases, runSVD with a FastAutoParam will dispatch to runRandomSVD, which minimizes the number of matrix multiplication steps and the associated costly block processing. However, if a DelayedMatrix subclass has its own %*% method, it is assumed to be efficient enough to afford repeated multiplications in runIrlbaSVD.

Setting a session-wide default

bsparam() will return a session-wide value for the BiocSingularParam object, analogous to bpparam(). This defaults to a FastAutoParam object but can be modified by setting the "BiocSingularParam.default" global option to any BiocSingularParam object. Any code that uses bsparam() will automatically use this new default without needing to explicitly pass the BiocSingularParam object to those functions.

Author(s)

Aaron Lun

See Also

runSVD for generic dispatch.

runExactSVD, runIrlbaSVD and runRandomSVD for specific methods.

Examples

ExactParam()

IrlbaParam(tol=1e-8)

RandomParam(q=20)

# Modifying the default.
bsparam()
options(BiocSingularParam.default=IrlbaParam())
bsparam()

LTLA/BiocSingular documentation built on Sept. 26, 2024, 4:14 a.m.