io.matlab.mio5

Classes for read / write of matlab (TM) 5 files

The matfile specification last found here:

http://www.mathworks.com/access/helpdesk/help/pdf_doc/matlab/matfile_format.pdf

(as of December 5 2008)

Module Contents

Classes

MatFile5Reader(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,uint16_codec=None) Reader for Mat 5 mat files
EmptyStructMarker() Class to indicate presence of empty matlab struct on output
VarWriter5(self,file_writer) Generic matlab matrix writing class
MatFile5Writer(self,file_stream,do_compression=False,unicode_strings=False,global_vars=None,long_field_names=False,oned_as=”row”) Class for writing mat5 files

Functions

varmats_from_mat(file_obj) Pull variables out of mat 5 file as a sequence of mat file objects
to_writeable(source) Convert input object source to something we can write
class MatFile5Reader(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, uint16_codec=None)

Reader for Mat 5 mat files Adds the following attribute to base class

uint16_codec - char codec to use for uint16 char arrays
(defaults to system default codec)

Uses variable reader that has the following stardard interface (see abstract class in miobase:

__init__(self, file_reader)
read_header(self)
array_from_header(self)

and added interface:

set_stream(self, stream)
read_full_tag(self)
__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, uint16_codec=None)

Initializer for matlab 5 file format reader

%(matstream_arg)s %(load_args)s %(struct_arg)s uint16_codec : {None, string}

Set codec to use for uint16 char arrays (e.g. ‘utf-8’). Use system default codec if None
guess_byte_order()

Guess byte order. Sets stream pointer to 0

read_file_header()

Read in mat 5 file header

initialize_read()

Run when beginning read of variables

Sets up readers from parameters in self

read_var_header()

Read header, return header, next position

Header has to define at least .name and .is_global

None

header : object
object that can be passed to self.read_var_array, and that has attributes .name and .is_global
next_position : int
position in stream of next variable
read_var_array(header, process=True)

Read array, given header

header : header object
object with fields defining variable header
process : {True, False} bool, optional
If True, apply recursive post-processing during loading of array.
arr : array
array with post-processing applied or not according to process.
get_variables(variable_names=None)

get variables from stream as dictionary

variable_names - optional list of variable names to get

If variable_names is None, then get all variables in file

list_variables()

list variables from stream

varmats_from_mat(file_obj)

Pull variables out of mat 5 file as a sequence of mat file objects

This can be useful with a difficult mat file, containing unreadable variables. This routine pulls the variables out in raw form and puts them, unread, back into a file stream for saving or reading. Another use is the pathological case where there is more than one variable of the same name in the file; this routine returns the duplicates, whereas the standard reader will overwrite duplicates in the returned dictionary.

The file pointer in file_obj will be undefined. File pointers for the returned file-like objects are set at 0.

file_obj : file-like
file object containing mat file
named_mats : list
list contains tuples of (name, BytesIO) where BytesIO is a file-like object containing mat file contents as for a single variable. The BytesIO contains a string with the original header and a single var. If var_file_obj is an individual BytesIO instance, then save as a mat file with something like open('test.mat', 'wb').write(var_file_obj.read())
>>> import scipy.io

BytesIO is from the io module in python 3, and is cStringIO for python < 3.

>>> mat_fileobj = BytesIO()
>>> scipy.io.savemat(mat_fileobj, {'b': np.arange(10), 'a': 'a string'})
>>> varmats = varmats_from_mat(mat_fileobj)
>>> sorted([name for name, str_obj in varmats])
['a', 'b']
class EmptyStructMarker

Class to indicate presence of empty matlab struct on output

to_writeable(source)

Convert input object source to something we can write

source : object

arr : None or ndarray or EmptyStructMarker
If source cannot be converted to something we can write to a matfile, return None. If source is equivalent to an empty dictionary, return EmptyStructMarker. Otherwise return source converted to an ndarray with contents for writing to matfile.
class VarWriter5(file_writer)

Generic matlab matrix writing class

__init__(file_writer)
write_bytes(arr)
write_string(s)
write_element(arr, mdtype=None)

write tag and data

write_smalldata_element(arr, mdtype, byte_count)
write_regular_element(arr, mdtype, byte_count)
write_header(shape, mclass, is_complex=False, is_logical=False, nzmax=0)

Write header for given data options shape : sequence

array shape

mclass - mat5 matrix class is_complex - True if matrix is complex is_logical - True if matrix is logical nzmax - max non zero elements for sparse arrays

We get the name and the global flag from the object, and reset them to defaults after we’ve used them

update_matrix_tag(start_pos)
write_top(arr, name, is_global)

Write variable at top level of mat file

arr : array_like
array-like object to create writer for
name : str, optional
name as it will appear in matlab workspace default is empty string
is_global : {False, True}, optional
whether variable will be global on load into matlab
write(arr)

Write arr to stream at top and sub levels

arr : array_like
array-like object to create writer for
write_numeric(arr)
write_char(arr, codec="ascii")

Write string array arr with given codec

write_sparse(arr)

Sparse matrices are 2D

write_cells(arr)
write_empty_struct()
write_struct(arr)
_write_items(arr)
write_object(arr)

Same as writing structs, except different mx class, and extra classname element after header

class MatFile5Writer(file_stream, do_compression=False, unicode_strings=False, global_vars=None, long_field_names=False, oned_as="row")

Class for writing mat5 files

__init__(file_stream, do_compression=False, unicode_strings=False, global_vars=None, long_field_names=False, oned_as="row")

Initialize writer for matlab 5 format files

%(do_compression)s %(unicode_strings)s global_vars : None or sequence of strings, optional

Names of variables to be marked as global for matlab

%(long_fields)s %(oned_as)s

write_file_header()
put_variables(mdict, write_header=None)

Write variables in mdict to stream

mdict : mapping
mapping with method items returns name, contents pairs where name which will appear in the matlab workspace in file load, and contents is something writeable to a matlab file, such as a numpy array.
write_header : {None, True, False}, optional
If True, then write the matlab file header before writing the variables. If None (the default) then write the file header if we are at position 0 in the stream. By setting False here, and setting the stream position to the end of the file, you can append variables to a matlab file