R.matlab (version 3.3.0)

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

Description

Reads a MAT file structure from a connection or a file. Both the MAT version 4 and MAT version 5 file formats are supported. The implementation is based on [1-5]. Note: Do not mix up version numbers for the MATLAB software and the MATLAB file formats.

Usage

## S3 method for class 'default':
readMat(con, maxLength=NULL, fixNames=TRUE, drop=c("singletonLists"),
  sparseMatrixClass=c("Matrix", "SparseM", "matrix"), verbose=FALSE, ...)

Arguments

con

Binary connection from which the MAT file structure should be read. If a character string, it is interpreted as filename, wh

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, underscores within names of MATLAB variables and fields are converted to periods.

drop

A character vector specifying cases when one or more dimensions of elements should be dropped in order to decrease the amount of "nestedness"

sparseMatrixClass

If "matrix", a sparse matrix is expanded to a regular matrix. If either "Matrix" (default) or "SparseM", the sparse matrix representation by the package of

verbose

Either a logical, a numeric, or a Verbose object specifying how much verbose/debug inform

...

Not used.

Value

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

Speed performance

This function uses a MAT file parser implemented completely using pure R. For MAT files containing large vectorized objects, for instance long vectors and large matrices, the R implementation is indeed fast enough because it can read and parse each such objects in one go.

On the other hand, for MAT files containing a large number of small objects, e.g. a large number of cell structures, there will be a significant slowdown, because each of the small objects has to be parsed individually. In such cases, if possible, try to (re)save the data in MATLAB using larger ("more vectorized") objects.

MAT cell structures

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

Unicode strings

Recent versions of MATLAB store some strings using Unicode encodings. If the R installation supports iconv, these strings will be read correctly. Otherwise non-ASCII codes are converted to NA. Saving to an earlier file format version may avoid this problem as well.

Reading compressed MAT files

From MATLAB v7, compressed MAT version 5 files are used by default [3,4]. This function supports reading such files, if running R v2.10.0 or newer. For older versions of R, the Rcompression package is used. To install that package, please see instructions at http://www.omegahat.org/cranRepository.html.

As a last resort, use save -V6 in MATLAB to write MAT files that are compatible with MATLAB v6, that is, to write non-compressed MAT version 5 files.

About MAT files saved in MATLAB using '-v7.3'

MAT v7.3 files, saved using for instance save('foo.mat', '-v7.3'), stores the data in the Hierarchical Data Format (HDF5) [5,6], which is a format not supported by this function/package. However, there exist other R packages that can parse HDF5, e.g. CRAN package h5 and Bioconductor package rhdf5.

Reading MAT file structures input streams

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.

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 Versions, July 2013. http://www.mathworks.com/help/matlab/import_export/mat-file-versions.html [6] Undocumented Matlab, Improving save performance, May 2013. http://undocumentedmatlab.com/blog/improving-save-performance/ [7] J. Gilbert et al., {Sparse Matrices in MATLAB: Design and Implementation}, SIAM J. Matrix Anal. Appl., 1992. https://www.mathworks.com/help/pdf_doc/otherdocs/simax.pdf [8] J. Burkardt, HB Files: Harwell Boeing Sparse Matrix File Format, Apr 2010. http://people.sc.fsu.edu/~jburkardt/data/hb/hb.html

See Also

writeMat().

Examples

path <- system.file("mat-files", package="R.matlab")
pathname <- file.path(path, "ABC.mat")
data <- readMat(pathname)
print(data)