fm.create {filematrix}

Functions to Create a New, or Open an Existing Filematrix

Description

Create a new or open existing filematrix object.

fm.create creates a new filematrix. If a filematrix with this name exists, it is overwritten (destroyed).

fm.create.from.matrix creates a new filematrix copy of an existing R matrix.

fm.open opens an existing filematrix for read/write access.

fm.load loads entire existing filematrix into memory as an ordinary R matrix.

fm.create.from.text.file reads a matrix from a text file into a new filematrix. The rows in the text file become columns in the filematrix. The transposition happens because the text files stores data by rows and filematrices store data by columns.

Usage

fm.create( 
    filenamebase,
    nrow = 0,
    ncol = 1,
    type = "double",
    size = NULL,
    lockfile = NULL)
    
fm.create.from.matrix( 
    filenamebase,
    mat,
    size = NULL,
    lockfile = NULL)

fm.open(
    filenamebase,
    readonly = FALSE,
    lockfile = NULL)

fm.load(filenamebase, lockfile = NULL)

fm.create.from.text.file(
    textfilename,
    filenamebase,
    skipRows = 1,
    skipColumns = 1,
    sliceSize = 1000,
    omitCharacters = "NA",
    delimiter = "\t",
    rowNamesColumn = 1,
    type = "double",
    size = NULL)

## S4 method for signature 'filematrix'
close(con)

closeAndDeleteFiles(con)

Arguments

filenamebase

Name without extension for the files storing the filematrix.
The file <filenamebase>.bmat keeps the matrix values and <filenamebase>.desc.txt stores the matrix dimensions, data type, and data type size. Names of rows and columns, if defined, are stored in <filenamebase>.nmsrow.txt and <filenamebase>.nmscol.txt.

nrow

Number of rows in the matrix. Values over 2^32 are supported.

ncol

Number of columns in the matrix. Values over 2^32 are supported.

type

The type of values stored in the matrix. Can be either "double", "integer", "logical", or "raw".

size

Size of each item of the matrix in bytes.
Default values are 8 for "double", 4 for "integer", and 1 for "logical" and "raw".
Do not change if not sure.

mat

Regular R matrix, to be copied into a new filematrix.

readonly

If TRUE, the values in the opened filematrix cannot be changed.

textfilename

Name of the text file with matrix data, to be copied into a new filematrix.

skipRows

Number of rows with column names. The matrix values are expected after first skipRows rows of the file. Can be zero.

skipColumns

Number of columns before matrix values begin. Can be zero.

sliceSize

The text file with matrix is read in chuncks of sliceSize rows. This is a performance tuning parameter, it does not affect the outcome.

omitCharacters

The text string representing missing values. Default value is NA.

delimiter

The delimiter separating values in the text matrix file.

rowNamesColumn

The row names are taken from the rowNamesColumn-th column of the text file. By default, row names are extracted from the first column.

con

A filematrix object.

lockfile

Optional. Name of a lock file (file is overwritten). Used to avoid simultaneous operations by multiple R instances accessing the same filematrix or different filematrices on the same hard drive. Do not use if not sure.

Details

Once created or opened, a filematrix object can be accessed as an ordinary matrix using both matrix fm[,] and vector fm[] indexing. The indices can be integer (no zeros) or logical vectors.

Value

Returns a filematrix object. The object can be closed with close command or closed and deleted from disk with closeAndDeleteFiles command.

Author(s)

Andrey A Shabalin [e-mail]

See Also

For more on the use of filematrices see filematrix.

Run browseVignettes("filematrix") for the list of vignettes.

Examples

# Create a 10x10 matrix
fm = fm.create(filenamebase=tempfile(), nrow=10, ncol=10)

# Change values in the top 3x3 corner
fm[1:3,1:3] = 1:9

# View the values in the top 4x4 corner
fm[1:4,1:4]

# Close and delete the filematrix
closeAndDeleteFiles(fm)