Parallel Low-Rank Approximation with Nonnegativity Constraints

'Rcpp' bindings for 'PLANC', a highly parallel and extensible NMF/NTF (Non-negative Matrix/Tensor Factorization) library. Wraps algorithms described in Kannan et. al (2018) and Eswar et. al (2021) . Implements algorithms described in Welch et al. (2019) , Gao et al. (2021) , and Kriebel & Welch (2022) .

RcppPlanc

About

RcppPlanc is, as the name implies, an Rcpp wrapper for planc. Currently, it implements wrappers for the vanilla NMF and NNLS algorithms. It also implements integrative NMF as described in Welch, J. D. et al, 2019, online integrative NMF as described in Gao, C. et al, 2021 and unshared integrative NMF as described in Kriebel and Welch, 2022. This is, at present, the fastest NMF implementation on CRAN, assuming you set nCores on call.

Requirements

• A complete BLAS library. (OpenBLAS works well. Mac OS on ARM64 will always use the built in vecLib framework.) (Runtime)
• A modern R toolchain (Rtools on Windows, the system toolchain on UNIX-alikes)
• A modern R (tested on 4.3+) (Runtime)
• CMake >=3.21
• HDF5 (tested against 1.12.0) (Runtime)
• OpenMP implementation that uses v4.0 semantics (if using OpenMP). For the GNU stack, this means gcc 9.

Installation

Release (CRAN):

install.packages(RcppPlanc)

Release (Conda Forge)

conda install r-rcppplanc -c conda-forge

HEAD (R-universe, binary)

1. Install the runtime requirements above.
2. install.packages('RcppPlanc', repos = c('https://welch-lab.r-universe.dev', 'https://cloud.r-project.org'))

Ubuntu 24.04 (YMMV on other linuxes)

1. Ensure libhdf5, libhwloc, and libopenblas are installed.

install.packages("RcppPlanc", repos = c(
linux = 'https://welch-lab.r-universe.dev/bin/linux/noble/4.5/',
sources = 'https://welch-lab.r-universe.dev',
cran = 'https://cloud.r-project.org'))

SOURCE:

1. Install the requirements above.
2. Ensure your libraries can be found by CMake.
3. devtools::install_github("welch-lab/RcppPlanc")

Caveats

Non-fatal errors during the CMake run are to be expected as the compiler flags are tailored to each system. Currently, the cblas locator logic only finds headers at the root of the given include directories or in the openblas and flexiblas subdirectories. If CMake cannot find a cblas header, its directory must be specified manually in CMakeCache.txt. This software will not use OpenMP on MacOS and performance on Intel Macs will suffer accordingly. Blame Apple. ARM64 Macs more than make up for the threaded performance loss with their inbuilt matrix coprocessor. If you're on an Intel mac and feeling adventurous, you can always try following the instructions at https://mac.r-project.org/openmp/ but your mileage may vary.

Citations and Prior Works

A huge shoutout goes to Ramakrishnan Kannan for the original work on which this program is based. Relevant citations can be found in his repository at https://github.com/ramkikannan/planc/blob/master/papers.md.

When and if a citation for this package becomes available, it will be posted here.

Parts of this code source are licensed under the 3-clause BSD (c) 2016 , UT-Battelle, LLC and (c) 2017 Ramakrishnan Kannan. The compiled binary and sources not marked otherwise are licensed under the GPLv2 or later.

Licenses for the various CMake scripts (FindHWLOC, FindR, and FindRModule, and PatchFile) are included at the top of each file.

Contributing and Support

Please reach out to us at the Welch Lab using the issue tracker in this repository before contacting upstream. Much of the inherited code is heavily modified and half of the algorithms have not yet been upstreamed.

Pull requests are welcome.

Documentation

Vignettes and R documentation files are available in the standard folders.