Getting Started

In fastMatMR: High-Performance Matrix Market File Operations

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

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)

With Dense Matrices

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

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)

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)
fmm_to_vec(temp_file_vec_r)

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:

{bash, eval=FALSE} pip install fast_matrix_market python -c 'import fast_matrix_market as fmm; print(fmm.read_array_or_coo("sparse.mtx"))'

fastMatMR documentation built on Nov. 4, 2023, 1:08 a.m.