readMat               package:R.matlab               R Documentation

_R_e_a_d_s _a _M_A_T _f_i_l_e _s_t_r_u_c_t_u_r_e _f_r_o_m _a _c_o_n_n_e_c_t_i_o_n _o_r _a _f_i_l_e

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

     ## Default S3 method:
     readMat(con, maxLength=NULL, fixNames=TRUE, verbose=FALSE, ...)

_A_r_g_u_m_e_n_t_s:

     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.

_D_e_t_a_i_l_s:

     For the MAT v5 format, _cell_ structures are read into R as a
     'list' structure.

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

_V_a_l_u_e:

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

_A_u_t_h_o_r(_s):

     Henrik Bengtsson, Mathematical Statistics, Lund University. The
     internal MAT v4 reader was written by Andy Jacobson at Program in
     Atmospheric and Oceanic Sciences, Princeton University.

_R_e_f_e_r_e_n_c_e_s:

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

_S_e_e _A_l_s_o:

     'writeMat'().

_E_x_a_m_p_l_e_s:

     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, "...\n", 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), "\n", 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=", "), "\n", sep="");

     print(s)

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

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

