readMat {R.matlab} | R Documentation |
Description
Reads a MAT file structure from a connection or a file.Both the MAT version 4 and MAT version 5 file formats aresupported. The implementation is based on [1-5].Note: Do not mix up version numbers for the MATLAB software andthe MATLAB file formats.
Usage
## Default S3 method:readMat(con, maxLength=NULL, fixNames=TRUE, drop=c("singletonLists"), sparseMatrixClass=c("Matrix", "SparseM", "matrix"), verbose=FALSE, ...)
Arguments
con | Binary |
maxLength | The maximum number of bytes to be read from the inputstream, which should be equal to the length of the MAT file structure.If |
fixNames | If |
drop | A |
sparseMatrixClass | If |
verbose | Either a |
... | Not used. |
Value
Returns a named list
structure containing all variables in theMAT file structure.
Speed performance
This function uses a MAT file parser implemented completely usingpure R. For MAT files containing large vectorized objects, for instancelong vectors and large matrices, the R implementation is indeed fastenough because it can read and parse each such objects in one go.
On the other hand, for MAT files containing a large number of smallobjects, e.g. a large number of cell structures, there will be asignificant slowdown, because each of the small objects has to beparsed individually.In such cases, if possible, try to (re)save the data in MATLABusing larger ("more vectorized") objects.
MAT cell structures
For the MAT v5 format, cell structures are read intoR as a list
structure.
Unicode strings
Recent versions of MATLAB store some strings using Unicodeencodings. If the R installation supports iconv
,these strings will be read correctly. Otherwise non-ASCII codesare converted to NA. Saving to an earlier file format versionmay avoid this problem as well.
Reading compressed MAT files
From MATLAB v7, compressed MAT version 5 files are used bydefault [3-5], which is supported by this function.
If for some reason it fails, use save -V6
in MATLAB to writenon-compressed MAT v5 files (sic!).
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) [6, 7], whichis 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 Fileis detected or until maxLength
bytes has been read.Using maxLength
it is possible to read MAT file structure oversocket connections and other non-terminating input streams. In such casesthe maxLength
has to be communicated before sending the actualMAT file structure.
Author(s)
Henrik Bengtsson.The internal MAT v4 reader was written byAndy Jacobson (Princeton University).Support for reading sparse matrices, UTF-encoded strings andcompressed files, was contributed by Jason Riedy (UC Berkeley).
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
[7] Undocumented Matlab, Improving save performance, May 2013.https://undocumentedmatlab.com/articles/improving-save-performance/
[8] 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
[9] J. Burkardt, HB Files: Harwell Boeing Sparse Matrix File Format, Apr 2010.https://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)
[Package R.matlab version 3.7.0 Index]