Author: Rohit Goswami
Date: 2023-11-03

# Getting Started

#### Rohit Goswami

#### 2023-11-03

# Introduction

`fastMatMR` is an R package that provides high-performance reading and writing of Matrix Market files. It wraps around the fast_matrix_market C++ library, ensuring optimal performance.

Performance vignettes for write and read operations are also provided.

## Unique Features

Unlike other packages, such as `Matrix`, `fastMatMR` offers extended support for:

- Dense Vectors: Writing standard R vectors to `.mtx` files.
- Dense Matrices: Writing standard R matrices to `.mtx` files.
- Sparse Matrices: A more efficient way of reading and writing sparse matrices.

For performance benchmarks, see performance our vignettes for write and read operations.

# Installation

To install the development version of `fastMatMR` from GitHub:

    install.packages("devtools")
    devtools::install_github("ropensci/fastMatMR")

# Basic Usage

Load the `fastMatMR` package:

    library(fastMatMR)

## Writing Matrix Market files

### With Dense Vectors

    vec <- c(1, 2, 3)
    temp_file_vec <- tempfile(fileext = ".mtx")
    write_fmm(vec, temp_file_vec)
    #> [1] TRUE

### With Dense Matrices

    mat <- matrix(c(1, 2, 3, 4), nrow = 2)
    temp_file_mat <- tempfile(fileext = ".mtx")
    write_fmm(mat, temp_file_mat)
    #> [1] TRUE

### With Sparse Matrices

    sp_mat <- Matrix::sparseMatrix(i = c(1, 3), j = c(2, 4), x = 7:8)
    temp_file_sp_mat <- tempfile(fileext = ".mtx")
    write_fmm(sp_mat, temp_file_sp_mat)
    #> [1] TRUE

## Reading Matrix Market files

- `fastMatMR` will correctly roundtrip `NaN` values.
- `NA` values are not supported by the Matrix Market format, and are coerced to `NaN`

### With Dense Vectors

    vec <- c(1, 2, 3.32, 225.61)
    temp_file_vec_r <- tempfile(fileext = ".mtx")
    vec_to_fmm(vec, temp_file_vec_r)
    #> [1] TRUE
    fmm_to_vec(temp_file_vec_r)
    #> [1]   1.00   2.00   3.32 225.61

Similarly, other `fmm_to_` functions can be used to read from `.mtx` files.

## Addenum

### Alternatives

Sparse matrices can be written and read by the `Matrix` library:

    spmat <- Matrix::Matrix(c(1, 0, 3, NA), nrow = 2, sparse = TRUE)
    temp_file_sp_na <- tempfile(fileext = ".mtx")
    Matrix::writeMM(spmat, temp_file_sp_na)
    Matrix::readMM(temp_file_sp_na)
    ## NULL
    ## 2 x 2 sparse Matrix of class "dgTMatrix"
    ## [1,] 1  3e+00
    ## [2,] . 1e+308

However, as can be seen above, `NA` values are handled incorrectly, and cause overflow. Dense matrices or vectors cannot be read or written in the matrix market format by the `Matrix` library.

### Reading Back In Python

Since the Matrix Market format is language agnostic, the `.mtx` files produced can even be read into Python:

    pip install fast_matrix_market
    python -c 'import fast_matrix_market as fmm; print(fmm.read_array_or_coo("sparse.mtx"))'