fm.create: Functions to Create a New, or Open an Existing Filematrix

In filematrix: File-Backed Matrix Class with Convenient Read and Write Access

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)

Example output

     [,1] [,2] [,3] [,4]
[1,]    1    4    7    0
[2,]    2    5    8    0
[3,]    3    6    9    0
[4,]    0    0    0    0

filematrix documentation built on May 2, 2019, 7:23 a.m.