Skip to contents

Getting Started

Rohit Goswami

2024-10-28

Source: vignettes/fastMatMR.Rmd
fastMatMR.Rmd

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:

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"))'