R: The 'disk.matrix' class

disk.matrix {NetRep} | R Documentation

## The 'disk.matrix' class

### Description

A `'disk.matrix'` contains a file path to a matrix stored on disk, along with meta data for how to read that file. This allows NetRep to load datasets into RAM only when required, i.e. one at a time. This significantly reduces the memory usage of R when analysing large datasets. `'disk.matrix'` objects may be supplied instead of `'matrix'` objects in the input list arguments `'network'`, `'data'`, and `'correlation'`, which are common to most of NetRep's functions.

### Usage

    attach.disk.matrix(file, serialized = TRUE, ...)

    serialize.table(file, ...)

    is.disk.matrix(x)

    as.disk.matrix(x, file, serialize = TRUE)

    ## S4 method for signature 'disk.matrix'
    as.disk.matrix(x, file, serialize = TRUE)

    ## S4 method for signature 'matrix'
    as.disk.matrix(x, file, serialize = TRUE)

    ## S4 method for signature 'ANY'
    as.disk.matrix(x, file, serialize = TRUE)

    ## S4 method for signature 'disk.matrix'
    as.matrix(x)

    ## S4 method for signature 'disk.matrix'
    show(object)

### Arguments

`file` | for `attach.disk.matrix` the file name of a matrix on disk. For `as.disk.matrix` the file name to save the matrix to. For `serialize.table` the file name of a matrix in table format on disk.
`serialized` | determines how the matrix will be loaded from disk into R by `as.matrix`. If `TRUE`, the `readRDS` function will be used. If `FALSE`, the `read.table` function will be used.
`...` | arguments to be used by `read.table` when reading in matrix data from a file in table format.
`x` | for `as.matrix` a `disk.matrix` object to load into R. For `as.disk.matrix` an object to convert to a `disk.matrix`. For `is.disk.matrix` an object to check if its a `disk.matrix`.
`serialize` | determines how the matrix is saved to disk by `as.disk.matrix`. If `TRUE` it will be stored as a serialized R object using `saveRDS`. If `FALSE` it will be stored as a tab-separated file using `write.table`.
`object` | a `'disk.matrix'` object.

### Details

Matrices may either be stored as regular table files that can be read by `read.table`, or as serialized R objects that can be read by `readRDS`. Serialized objects are much faster to load, but cannot be read by other programs.

The `attach.disk.matrix` function creates a `disk.matrix` object from a file path. The `as.matrix` function will load the data from disk into the R session as a regular `matrix` object.

The `as.disk.matrix` function converts a matrix into a `disk.matrix` by saving its contents to the specified `file`. The `serialize` argument determines whether the data is stored as a serialized R object or as a tab-separated file (i.e. `sep="\t"`). We recommend storing the matrix as a serialized R object unless disk space is a concern. More control over the storage format can be obtained by using `saveRDS` or `write.table` directly.

The `serialize.matrix` function converts a file in table format to a serialized R object with the same file name, but with the ".rds" extension.

### Value

A `disk.matrix` object (`attach.disk.matrix`, `as.disk.matrix`), a `matrix` (`as.matrix`), the file path to a serialized matrix (`serialize.table`), or a `TRUE` or `FALSE` indicating whether an object is a `disk.matrix` (`is.disk.matrix`).

### Slots

`file`

  the name of the file where the matrix is saved.

`read.func`

  either `"read.table"` or `"readRDS"`.

`func.args`

  a list of arguments to be supplied to the `'read.func'`.

### Warning

`attach.disk.matrix` does not check whether the specified file can be read into R. `as.matrix` will fail and throw an error if this is the case.

[Package NetRep version 1.2.4 Index]