R: Read and write external matrix formats

externalFormats {Matrix} | R Documentation

## Read and write external matrix formats

### Description

Read matrices stored in the Harwell-Boeing or MatrixMarket formats or write `sparseMatrix` objects to one of these formats.

### Usage

    readHB(file)
    readMM(file)
    writeMM(obj, file, ...)

### Arguments

`obj` | a real sparse matrix
`file` | for `writeMM` - the name of the file to be written. For `readHB` and `readMM` the name of the file to read, as a character scalar. The names of files storing matrices in the Harwell-Boeing format usually end in `".rua"` or `".rsa"`. Those storing matrices in the MatrixMarket format usually end in `".mtx"`. Alternatively, `readHB` and `readMM` accept connection objects.
`...` | optional additional arguments. Currently none are used in any methods.

### Value

The `readHB` and `readMM` functions return an object that inherits from the `"Matrix"` class. Methods for the `writeMM` generic functions usually return `NULL` and, as a side effect, the matrix `obj` is written to `file` in the MatrixMarket format (writeMM).

### Note

The Harwell-Boeing format is older and less flexible than the MatrixMarket format. The function `writeHB` was deprecated and has now been removed. Please use `writeMM` instead.

Note that these formats do not know anything about `dimnames`, hence these are dropped by `writeMM()`.

A very simple way to export small sparse matrices `S`, is to use `summary(S)` which returns a `data.frame` with columns `i`, `j`, and possibly `x`, see `summary` in `sparseMatrix-class`, and an example below.

### References

https://math.nist.gov/MatrixMarket/

https://sparse.tamu.edu/

### Examples

    str(pores <- readMM(system.file("external/pores_1.mtx",
                                    package = "Matrix")))
    str(utm <- readHB(system.file("external/utm300.rua",
                                   package = "Matrix")))
    str(lundA <- readMM(system.file("external/lund_a.mtx",
                                    package = "Matrix")))
    str(lundA <- readHB(system.file("external/lund_a.rsa",
                                    package = "Matrix")))
    str(jgl009 <- ## https://math.nist.gov/MatrixMarket/data/Harwell-Boeing/counterx/counterx.html
            readMM(system.file("external/jgl009.mtx", package = "Matrix")))
    ## Not run:
    ## NOTE: The following examples take quite some time
    ## ----  even on a fast internet connection:
    if(FALSE) # the URL has been corrected, but we need an un-tar step!
    str(sm <-
     readHB(gzcon(url("https://www.cise.ufl.edu/research/sparse/RB/Boeing/msc00726.tar.gz"))))

    ## End(Not run)
    data(KNex)
    ## Store as MatrixMarket (".mtx") file, here inside temporary dir./folder:
    (MMfile <- file.path(tempdir(), "mmMM.mtx"))
    writeMM(KNex$mm, file=MMfile)
    file.info(MMfile)[,c("size", "ctime")] # (some confirmation of the file's)

    ## very simple export - in triplet format - to text file:
    data(CAex)
    s.CA <- summary(CAex)
    s.CA # shows  (i, j, x)  [columns of a data frame]
    message("writing to ", outf <- tempfile())
    write.table(s.CA, file = outf, row.names=FALSE)
    ## and read it back -- showing off  sparseMatrix():
    str(dd <- read.table(outf, header=TRUE))
    ## has columns (i, j, x) -> we can use via do.call() as arguments to sparseMatrix():
    mm <- do.call(sparseMatrix, dd)
    stopifnot(all.equal(mm, CAex, tolerance=1e-15))

[Package Matrix version 1.4-1 Index]