---
title: "Getting Started"
author: "Rohit Goswami"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
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](https://github.com/alugowski/fast_matrix_market), ensuring optimal
performance.

Performance vignettes for
[write](https://docs.ropensci.org/fastMatMR/articles/fmm_write_bench.html) and
[read](https://docs.ropensci.org/fastMatMR/articles/fmm_read_bench.html)
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](https://docs.ropensci.org/fastMatMR/articles/fmm_write_bench.html) and
[read](https://docs.ropensci.org/fastMatMR/articles/fmm_read_bench.html)
operations.

# Installation

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

```{r, eval=FALSE}
install.packages("devtools")
devtools::install_github("ropensci/fastMatMR")
```

# Basic Usage

Load the `fastMatMR` package:

```{r}
library(fastMatMR)
```

## Writing Matrix Market files

### With Dense Vectors

```{r}
vec <- c(1, 2, 3)
temp_file_vec <- tempfile(fileext = ".mtx")
write_fmm(vec, temp_file_vec)
```

### With Dense Matrices

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

### With Sparse Matrices

```{r}
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

```{r}
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:

```{r, eval=FALSE}
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"))'
```