output: github_document

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"

# sparseMatrixStats <a href='https://github.com/const-ae/sparseMatrixStats'><img src='man/figures/logo.png' align="right" height="209" /></a>

<!-- badges: start -->

<!-- badges: end -->

The goal of `sparseMatrixStats` is to make the API of [matrixStats](https://github.com/HenrikBengtsson/matrixStats) available
for sparse matrices.

## Installation

You can install the release version of *[sparseMatrixStats](https://bioconductor.org/packages/sparseMatrixStats)* from BioConductor:

``` r
if (!requireNamespace("BiocManager", quietly = TRUE))


Alternatively, you can get the development version of the package from [GitHub](https://github.com/const-ae/sparseMatrixStats) with:

``` r
# install.packages("devtools")

## Example

```{r include=FALSE}


mat <- matrix(0, nrow=10, ncol=6)
mat[sample(seq_len(60), 4)] <- 1:4
# Convert dense matrix to sparse matrix
sparse_mat <- as(mat, "dgCMatrix")

The package provides an interface to quickly do common operations on the rows or columns. For example calculate
the variance:

apply(mat, 2, var)

On this small example data, all methods are basically equally fast, but if we have a much larger dataset, the 
optimizations for the sparse data start to show.

I generate a dataset with 10,000 rows and 50 columns that is 99% empty

big_mat <- matrix(0, nrow=1e4, ncol=50)
big_mat[sample(seq_len(1e4 * 50), 5000)] <- rnorm(5000)
# Convert dense matrix to sparse matrix
big_sparse_mat <- as(big_mat, "dgCMatrix")

I use the `bench` package to benchmark the performance difference:

  apply=apply(big_mat, 2, var)

As you can see `sparseMatrixStats` is ca. 35 times fast than `matrixStats`, which in turn is 7 times faster than the `apply()` version.


The package now supports all functions from the `matrixStats` API for column sparse matrices (`dgCMatrix`). And thanks to the [`MatrixGenerics`](https://bioconductor.org/packages/MatrixGenerics/) it can be easily integrated along-side [`matrixStats`](https://cran.r-project.org/package=matrixStats) and [`DelayedMatrixStats`](https://bioconductor.org/packages/DelayedMatrixStats/).
Note that the `rowXXX()` functions are called by transposing the input and calling the corresponding `colXXX()` function. Special optimized implementations are available for `rowSums2()`, `rowMeans2()`, and `rowVars()`.

```{r, echo=FALSE, results="asis"}
matrixStats_functions <- sort(
  c("colsum", "rowsum", grep("^(col|row)", 
                             value = TRUE)))
DelayedMatrixStats_functions <- grep("^(col|row)", getNamespaceExports("DelayedMatrixStats"), value=TRUE)
DelayedArray_functions <- grep("^(col|row)", getNamespaceExports("DelayedArray"), value=TRUE)
sparseMatrixStats_functions <- grep("^(col|row)", getNamespaceExports("sparseMatrixStats"), value=TRUE)

notes <- c("colAnyMissings"="Not implemented because it is deprecated in favor of `colAnyNAs()`",
           "rowAnyMissings"="Not implemented because it is deprecated in favor of `rowAnyNAs()`",
           "colsum"="Base R function",
           "rowsum"="Base R function",
           "colWeightedMedians"="Only equivalent if `interpolate=FALSE`",
           "rowWeightedMedians"="Only equivalent if `interpolate=FALSE`",
           "colWeightedMads"="Sparse version behaves slightly differently, because it always uses `interpolate=FALSE`.",
           "rowWeightedMads"="Sparse version behaves slightly differently, because it always uses `interpolate=FALSE`.")

api_df <- data.frame(
  Method = paste0(matrixStats_functions, "()"),
  matrixStats = ifelse(matrixStats_functions %in% matrixStats_functions, "✔", "❌"),
  sparseMatrixStats = ifelse(matrixStats_functions %in%sparseMatrixStats_functions, "✔", "❌"),
  Notes = ifelse(matrixStats_functions %in% names(notes), notes[matrixStats_functions], ""),
  stringsAsFactors = FALSE
knitr::kable(api_df, row.names = FALSE)