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.

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

Returns a named `list`

structure containing all variables in the
MAT file structure.

- con
Binary

`connection`

from which the MAT file structure should be read. If a`character`

string, it is interpreted as filename, which then will be opened (and closed afterwards). If a`raw`

`vector`

, it will be read via as a raw binary`connection`

.- 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" of the returned data structure. This only applies to the MAT v5 file format.- 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 the same name will be used. These packages are only loaded if the a sparse matrix is read.- 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.- ...
Not used.

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.

For the MAT v5 format, *cell* structures are read into
R as a `list`

structure.

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.

From MATLAB v7, *compressed* MAT version 5 files are used by
default [3-5], which is supported by this function.

If for some reason it fails, use `save -V6`

in MATLAB to write
non-compressed MAT v5 files (sic!).

MAT v7.3 files, saved using for instance `save('foo.mat', '-v7.3')`

,
stores the data in the Hierarchical Data Format (HDF5) [6, 7], 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.

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.

Henrik Bengtsson. The internal MAT v4 reader was written by Andy Jacobson (Princeton University). Support for reading sparse matrices, UTF-encoded strings and compressed files, was contributed by Jason Riedy (UC Berkeley).

[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

`writeMat`

().

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

Run the code above in your browser using DataLab