readMat: Reads a MAT file structure from a connection or a file

Description

Reads a MAT file structure from an input stream, either until End of File is detected or until maxLength bytes has been read. Using maxLength it is possible to read MAT file structure over socket connections and other non-terminating input streams. In such cases the maxLength has to be communicated before sending the actual MAT file structure. Both the MAT version 4 and MAT version 5 file formats are supported. The implementation is based on [1]. From Matlab v7, compressed MAT version 5 files are used by default [3]. These are not supported. Use save -V6 in Matlab to write a MAT file compatible with Matlab v6, that is, to write a non-compressed MAT version 5 file. Note: Do not mix up version numbers for the Matlab software and the Matlab file formats.

Usage

## S3 method for class 'default}(con, maxLength=NULL, fixNames=TRUE, verbose=FALSE, ...)':
readMatundefined

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).}
  maxLength{The maximum number of bytes to be read from the input
    stream, which should be equal to the length of the MAT file structure.
    If NULL, data will be read until End Of File has been reached.}
  fixNames{If TRUE, names of Matlab variables and fields are
    renamed such that they are valid variables names in R.}
  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).
  }
  ...{Not used.}

Returns a named list structure containing all variables in the
  MAT file structure.

For the MAT v5 format, cell structures are read into
  Ras a list structure.

  Sparse matrices are converted into plain matrices, which means that
  some matrices will be too large to be allocated.

path <- system.file("mat-files", package="R.matlab")

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Reading all example files
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
for (version in 4:5) {
  cat("Loading all MAT v", version, " example files in ",
                                                path, "...
", sep="")

  pattern <- sprintf("-v%d.mat$", version)
  filenames <- list.files(pattern=pattern, path=path, full.names=TRUE)

  for (filename in filenames) {
    cat("Reading MAT file: ", basename(filename), "
", sep="")
    mat <- readMat(filename)
    if (interactive()) {
      cat("Press ENTER to view data:")
      readline()
    }
    print(mat)
  }
}

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Assert that sparse matrices are read identically in MAT v4 and v5
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
mat4 <- readMat(file.path(path, "SparseMatrix3-v4.mat"))
mat5 <- readMat(file.path(path, "SparseMatrix3-v5.mat"))
diff <- sum(abs(mat4$sparseM - mat5$sparseM))
if (diff > .Machine$double.eps)
  stop("Failed to read identical MAT v4 and MAT v5 sparse matrices.")

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Assert that signed and unsigned integers are read correctly
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
bs <- readMat(file.path(path, "unsignedByte.mat"))
if (!identical(as.vector(bs$A), as.double(126:255)))
  stop("Error reading unsigned bytes saved by Matlab.")

is <- readMat(file.path(path, "unsignedInt.mat"))
if (!identical(as.vector(is$B), as.double(127:256)))
  stop("Error reading unsigned ints saved by Matlab.")

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Example of a Matlab struct
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# File was created by
# s = struct('type',{'big','little'},  'color','red',  'x',{3,4})
#  1x2 struct array with fields:
#      type
#      color
#      x
# save structLooped.mat s -v6
mat <- readMat(file.path(path, "structLooped.mat"))

# Extract the structure
s <- mat$s

# Field names are always in the first dimension
fields <- dimnames(s)[[1]]
cat("Field names: ", paste(fields, collapse=", "), "
", sep="");

print(s)

# Get field 'type'
print(s["type",,])

# Get substructure s(:,2)
print(s[,,2])

[object Object],[object Object],[object Object],[object Object]

writeMat().

[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, October 2004, http://www.mathworks.com/access/helpdesk/help/pdf_doc/matlab/matfile_format.pdf



file
IO

Description

Usage

Arguments