io.matlab.mio4

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

Module Contents

Classes

VarHeader4(self,name,dtype,mclass,dims,is_complex)
VarReader4(self,file_reader) Class to read matlab 4 variables
MatFile4Reader(self,mat_stream,*args,**kwargs) Reader for Mat4 files
VarWriter4(self,file_writer)
MatFile4Writer(self,file_stream,oned_as=None) Class for writing matlab 4 format files

Functions

arr_to_2d(arr,oned_as=”row”) Make arr exactly two dimensional
class VarHeader4(name, dtype, mclass, dims, is_complex)
__init__(name, dtype, mclass, dims, is_complex)
class VarReader4(file_reader)

Class to read matlab 4 variables

__init__(file_reader)
read_header()

Read and return header for variable

array_from_header(hdr, process=True)
read_sub_array(hdr, copy=True)

Mat4 read using header hdr dtype and dims

hdr : object
object with attributes dtype, dims. dtype is assumed to be the correct endianness
copy : bool, optional
copies array before return if True (default True) (buffer is usually read only)
arr : ndarray
of dtype givem by hdr dtype and shape givem by hdr dims
read_full_array(hdr)

Full (rather than sparse) matrix getter

Read matrix (array) can be real or complex

hdr : VarHeader4 instance

arr : ndarray
complex array if hdr.is_complex is True, otherwise a real numeric array
read_char_array(hdr)

latin-1 text matrix (char matrix) reader

hdr : VarHeader4 instance

arr : ndarray
with dtype ‘U1’, shape given by hdr dims
read_sparse_array(hdr)

Read and return sparse matrix type

hdr : VarHeader4 instance

arr : scipy.sparse.coo_matrix
with dtype float and shape read from the sparse matrix data

MATLAB 4 real sparse arrays are saved in a N+1 by 3 array format, where N is the number of non-zero values. Column 1 values [0:N] are the (1-based) row indices of the each non-zero value, column 2 [0:N] are the column indices, column 3 [0:N] are the (real) values. The last values [-1,0:2] of the rows, column indices are shape[0] and shape[1] respectively of the output matrix. The last value for the values column is a padding 0. mrows and ncols values from the header give the shape of the stored matrix, here [N+1, 3]. Complex data is saved as a 4 column matrix, where the fourth column contains the imaginary component; the last value is again 0. Complex sparse data do not have the header imagf field set to True; the fact that the data are complex is only detectable because there are 4 storage columns

shape_from_header(hdr)

Read the shape of the array described by the header. The file position after this call is unspecified.

class MatFile4Reader(mat_stream, *args, **kwargs)

Reader for Mat4 files

__init__(mat_stream, *args, **kwargs)

Initialize matlab 4 file reader

%(matstream_arg)s %(load_args)s

guess_byte_order()
initialize_read()

Run when beginning read of variables

Sets up readers from parameters in self

read_var_header()

Read and return header, next position

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}, 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 : None or str or sequence of str, optional
variable name, or sequence of variable names to get from Mat file / file stream. If None, then get all variables in file
list_variables()

list variables from stream

arr_to_2d(arr, oned_as="row")

Make arr exactly two dimensional

If arr has more than 2 dimensions, raise a ValueError

arr : array oned_as : {‘row’, ‘column’}, optional

Whether to reshape 1D vectors as row vectors or column vectors. See documentation for matdims for more detail
arr2d : array
2D version of the array
class VarWriter4(file_writer)
__init__(file_writer)
write_bytes(arr)
write_string(s)
write_header(name, shape, P=miDOUBLE, T=mxFULL_CLASS, imagf=0)

Write header for given data options

name : str
name of variable
shape : sequence
Shape of array as it will be read in matlab
P : int, optional
code for mat4 data type, one of miDOUBLE, miSINGLE, miINT32, miINT16, miUINT16, miUINT8
T : int, optional
code for mat4 matrix class, one of mxFULL_CLASS, mxCHAR_CLASS, mxSPARSE_CLASS
imagf : int, optional
flag indicating complex
write(arr, name)

Write matrix arr, with name name

arr : array_like
array to write
name : str
name in matlab workspace
write_numeric(arr, name)
write_char(arr, name)
write_sparse(arr, name)

Sparse matrices are 2D

See docstring for VarReader4.read_sparse_array

class MatFile4Writer(file_stream, oned_as=None)

Class for writing matlab 4 format files

__init__(file_stream, oned_as=None)
put_variables(mdict, write_header=None)

Write variables in mdict to stream

mdict : mapping
mapping with method items return name, contents pairs where name which will appeak 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}
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