io.matlab.miobase

Base classes for MATLAB file stream reading.

MATLAB is a registered trademark of the Mathworks inc.

Module Contents

Classes

MatReadError()
MatWriteError()
MatReadWarning()
MatVarReader(self,file_reader) Abstract class defining required interface for var readers
MatFileReader(self,mat_stream,byte_order=None,mat_dtype=False,squeeze_me=False,chars_as_strings=True,matlab_compatible=False,struct_as_record=True,verify_compressed_data_integrity=True) Base object for reading mat files

Functions

convert_dtypes(dtype_template,order_code) Convert dtypes in mapping to given order
read_dtype(mat_stream,a_dtype) Generic get of byte stream data of known type
get_matfile_version(fileobj) Return major, minor tuple depending on apparent mat file type
matdims(arr,oned_as=”column”) Determine equivalent MATLAB dimensions for given array
arr_dtype_number(arr,num) Return dtype for given number of items per element
arr_to_chars(arr) Convert string array to char array
class MatReadError
class MatWriteError
class MatReadWarning
convert_dtypes(dtype_template, order_code)

Convert dtypes in mapping to given order

dtype_template : mapping
mapping with values returning numpy dtype from np.dtype(val)
order_code : str
an order code suitable for using in dtype.newbyteorder()
dtypes : mapping
mapping where values have been replaced by np.dtype(val).newbyteorder(order_code)
read_dtype(mat_stream, a_dtype)

Generic get of byte stream data of known type

mat_stream : file_like object
MATLAB (tm) mat file stream
a_dtype : dtype
dtype of array to read. a_dtype is assumed to be correct endianness.
arr : ndarray
Array of dtype a_dtype read from stream.
get_matfile_version(fileobj)

Return major, minor tuple depending on apparent mat file type

Where:

  1. 0,x -> version 4 format mat files
  2. 1,x -> version 5 format mat files
  3. 2,x -> version 7.3 format mat files (HDF format)
fileobj : file_like
object implementing seek() and read()
major_version : {0, 1, 2}
major MATLAB File format version
minor_version : int
minor MATLAB file format version
MatReadError
If the file is empty.
ValueError
The matfile version is unknown.

Has the side effect of setting the file read pointer to 0

matdims(arr, oned_as="column")

Determine equivalent MATLAB dimensions for given array

arr : ndarray
Input array
oned_as : {‘column’, ‘row’}, optional
Whether 1-D arrays are returned as MATLAB row or column matrices. Default is ‘column’.
dims : tuple
Shape tuple, in the form MATLAB expects it.

We had to decide what shape a 1 dimensional array would be by default. np.atleast_2d thinks it is a row vector. The default for a vector in MATLAB (e.g. >> 1:12) is a row vector.

Versions of scipy up to and including 0.11 resulted (accidentally) in 1-D arrays being read as column vectors. For the moment, we maintain the same tradition here.

>>> matdims(np.array(1)) # numpy scalar
(1, 1)
>>> matdims(np.array([1])) # 1d array, 1 element
(1, 1)
>>> matdims(np.array([1,2])) # 1d array, 2 elements
(2, 1)
>>> matdims(np.array([[2],[3]])) # 2d array, column vector
(2, 1)
>>> matdims(np.array([[2,3]])) # 2d array, row vector
(1, 2)
>>> matdims(np.array([[[2,3]]])) # 3d array, rowish vector
(1, 1, 2)
>>> matdims(np.array([])) # empty 1d array
(0, 0)
>>> matdims(np.array([[]])) # empty 2d
(0, 0)
>>> matdims(np.array([[[]]])) # empty 3d
(0, 0, 0)

Optional argument flips 1-D shape behavior.

>>> matdims(np.array([1,2]), 'row') # 1d array, 2 elements
(1, 2)

The argument has to make sense though

>>> matdims(np.array([1,2]), 'bizarre')
Traceback (most recent call last):
   ...
ValueError: 1D option "bizarre" is strange
class MatVarReader(file_reader)

Abstract class defining required interface for var readers

__init__(file_reader)
read_header()

Returns header

array_from_header(header)

Reads array given header

class MatFileReader(mat_stream, byte_order=None, mat_dtype=False, squeeze_me=False, chars_as_strings=True, matlab_compatible=False, struct_as_record=True, verify_compressed_data_integrity=True)

Base object for reading mat files

To make this class functional, you will need to override the following methods:

matrix_getter_factory - gives object to fetch next matrix from stream guess_byte_order - guesses file byte order from file

__init__(mat_stream, byte_order=None, mat_dtype=False, squeeze_me=False, chars_as_strings=True, matlab_compatible=False, struct_as_record=True, verify_compressed_data_integrity=True)

Initializer for mat file reader

mat_stream : file-like
object with file API, open for reading

%(load_args)s

set_matlab_compatible()

Sets options to return arrays as MATLAB loads them

guess_byte_order()

As we do not know what file type we have, assume native

end_of_stream()
arr_dtype_number(arr, num)

Return dtype for given number of items per element

arr_to_chars(arr)

Convert string array to char array