R.matlab (version 3.7.0)

writeMat: Writes a MAT file structure

Description

This function takes the given variables (...) and places them in a MAT file structure, which is then written to a binary connection.

Usage

# S3 method for default
writeMat(con, ..., fixNames=TRUE, matVersion="5", onWrite=NULL, verbose=FALSE)

Value

Returns (invisibly) the number of bytes written. Any bytes written by any onWrite function are not included in this count.

Arguments

con

Binary connection to which the MAT file structure should be written to. A string is interpreted as filename, which then will be opened (and closed afterwards).

...

Named variables to be written where the names must be unique.

fixNames

If TRUE, periods within names of R variables and fields are converted to underscores.

matVersion

A character string specifying what MAT file format version to be written to the connection. If "5", a MAT v5 file structure is written. No other formats are currently supported.

onWrite

Function to be called just before starting to write to connection. Since the MAT file structure does not contain information about the total size of the structure this argument makes it possible to first write the structure size (in bytes) to the connection.

verbose

Either a logical, a numeric, or a Verbose object specifying how much verbose/debug information is written to standard output. If a Verbose object, how detailed the information is is specified by the threshold level of the object. If a numeric, the value is used to set the threshold of a new Verbose object. If TRUE, the threshold is set to -1 (minimal). If FALSE, no output is written (and neither is the R.utils package required).

Note that ... must not contain variables with names equal to the arguments matVersion and onWrite, which were chosen because we believe they are quite unique to this write method.

Limitations

Currently only the uncompressed MAT version 5 file format [6] is supported, that is, compressed MAT files cannot be written (only read).

Moreover, the maximum variable size supported by the MAT version 5 file format is 2^31 bytes [6]. In R, this limitation translates to 2^31-1 bytes, which corresponds to for instance an integer object with 536870912 elements or double object with 268435456 elements.

Details on onWrite()

If specified, the onWrite() function is called before the data is written to the connection. This function must take a list argument as the first argument. This will hold the element con which is the opened connection to be written to. It will also hold the element length, which specified the number of bytes to be written. See example for an illustration.

Note, in order to provide the number of bytes before actually writing the data, a two-pass procedure has to be taken, where the first pass is imitating a complete writing without writing anything to the connection but only counting the total number of bytes. Then in the second pass, after calling onWrite(), the data is written.

Author

Henrik Bengtsson

References

[1] The MathWorks Inc., MATLAB - MAT-File Format, version 5, June 1999.
[2] The MathWorks Inc., MATLAB - Application Program Interface Guide, version 5, 1998.
[3] The MathWorks Inc., MATLAB - MAT-File Format, version 7, September 2009.
[4] The MathWorks Inc., MATLAB - MAT-File Format, version R2012a, September 2012.
[5] The MathWorks Inc., MATLAB - MAT-File Format, version R2015b, September 2015.
[6] The MathWorks Inc., MATLAB - MAT-File Versions, December 2015. https://www.mathworks.com/help/matlab/import_export/mat-file-versions.html

See Also

readMat().

Examples

A <- matrix(1:27, ncol = 3)
B <- as.matrix(1:10)
C <- array(1:18, dim = c(2, 3, 3))

filename <- paste(tempfile(), ".mat", sep = "")

writeMat(filename, A = A, B = B, C = C)
data <- readMat(filename)
str(data)

X <- list(A = A, B = B, C = C)
stopifnot(all.equal(X, data[names(X)]))

unlink(filename)


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# All objects written must be named uniquely
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
tryCatch({
  # Named
  writeMat(filename, A = A)
  # Not named
  writeMat(filename, A)
}, error = function(ex) {
  cat("ERROR:", ex$message, "\n")
})


tryCatch({
  # Uniquely named
  writeMat(filename, A = A, B = B, C = C)
  # Not uniquely named
  writeMat(filename, A = A, B = B, A = C)
}, error = function(ex) {
  cat("ERROR:", ex$message, "\n")
})


if (FALSE) {
# When writing to a stream connection the receiver needs to know on
# beforehand how many bytes are available. This can be done by using
# the 'onWrite' argument.
onWrite <- function(x)
  writeBin(x$length, con = x$con, size = 4, endian = "little")
  writeMat(con, A = A, B = B, onWrite = onWrite)
}