cape.dkit.matfile: MATLAB data interface

This module provides a class MATFile for reading and writing data from files using version 5.0 of MATLAB’s .mat format. Later versions of .mat files utilize HDF5 and are not supported here. It relies on two third-party libraries readily available from the Python Package Index (PyPI):

  • scipy.io for reading many files

  • scipy.io.matlab.mio5_params for MATLAB files

These can be readily installed on any machine with both Python and access to the internet (even without elevated privileges) using the commands below:

$ pip install --user scipy

Because CAPE may also be used on machines without regular access to the internet, this module does not raise an ImportError in the case that these third-party modules are not available. However, the module will provide no functionality if these modules are not available.

class cape.dkit.matfile.MATFile(fname=None, **kw)

Class for reading .mat files (version 5)

Call:
>>> db = MATFile(fname, sheet=0, **kw)
Inputs:
fname: str

Name of .mat file to read

Outputs:
db: cape.dkit.ftypes.xls.XLSFile

XLS file interface

db.cols: list[str]

List of columns read

db.opts: dict

Options for this interface

db[col]: np.ndarray | list

Numeric array or list of strings for each column

Versions:

  • 2019-12-17 @ddalle: First version

from_mat_field(col, V)

Process an array and save it as a column

Call:
>>> db.from_mat_field(col, V)
Inputs:
db: cape.dkit.ftypes.mat.MATFile

MAT file interface

V: list | np.ndarray | float

Numeric or string data to save

col: str

Name of column

Versions:

  • 2019-12-27 @ddalle: First version

from_mat_struct(V, prefix='')

Read fields of a struct

Call:
>>> db.from_mat_struct(V, prefix="")
Inputs:
db: cape.dkit.ftypes.mat.MATFile

MAT file interface

V: mat_struct

Struct read from .mat file

prefix: {""} | str

Prefix to append to col names from V._fieldnames

Versions:

  • 2019-12-27 @ddalle: First version

genr8_mat(**kw)

Create a dict for output as .mat file

Call:
>>> dbmat = db.genr8_mat(dbmat={})
Inputs:
db: cape.dkit.ftypes.mat.MATFile

MAT file interface

dbmat: {{}} | dict

Dictionary to add contents of db to before writing

attrs: {None} | list[str]

List of additional attributes to save in dbmat

Outputs:
dbmat: dict

Dict in format ready for sio.savemat()

dbmat[“DB”]: scipy.io.matlab.mat_struct

Struct containing primary data cols from db

Versions:

  • 2019-12-17 @ddalle: First version

read_mat(fname, **kw)

Read a MATLAB .mat file

The primary data is assumed to be in a variable called DB.

Call:
>>> db.read_mat(f)
>>> db.read_mat(fname)
Inputs:
db: cape.dkit.ftypes.mat.MATFile

MAT file interface

f: file

File open for reading (at position 0)

fname: str

Name of file to read

Versions:

  • 2019-11-25 @ddalle: First version

  • 2020-02-07 @ddalle: Utilize KwargHandler

read_mat_legacy(fname, **kw)

Read a MATLAB .mat file

The primary data is assumed to be in a variable called DB.

Call:
>>> db.read_mat(f)
>>> db.read_mat(fname)
Inputs:
db: cape.dkit.ftypes.mat.MATFile

MAT file interface

f: file

File open for reading (at position 0)

fname: str

Name of file to read

Versions:

  • 2019-11-25 @ddalle: First version

write_mat(fname, **kw)

Write database to .mat file

Call:
>>> db.write_mat(fname, **kw)
Inputs:
db: cape.dkit.ftypes.mat.MATFile

MAT file interface

fname: str

Name of .mat file to write

attrs: {None} | list[str]

List of additional attributes to save in dbmat

See Also:
Versions:

  • 2019-12-17 @ddalle: First version

class cape.dkit.matfile.MATFileDefn(_optsdict=None, _warnmode=1, **kw)
class cape.dkit.matfile.MATFileOpts(_optsdict=None, _warnmode=1, **kw)
cape.dkit.matfile.dict_to_struct(d)

Convert a Python dict to a MATLAB struct

This function is recursive if necessary.

Call:
>>> s = dict_to_struct(d)
Inputs:
d: dict

Dict with keys from s._fieldnames

Outputs:
s: scipy.io.matlab.mio5_params.mat_struct

Interface to MATLAB struct

Versions:

  • 2019-12-17 @ddalle: First version

cape.dkit.matfile.from_matlab(x)

Convert a generic MATLAB object to Python

This function recurses if necessary

MATLAB

Python

struct

dict
Call:
>>> v = from_matlab(x)
Inputs:
x: any (MATLAB)

Item read from .mat file

Outputs:
v: any (Python)

Python interpretation

Versions:

  • 2019-12-17 @ddalle: First version

cape.dkit.matfile.merge_structs(DB1, DB2)

Merge two MATLAB structs

Call:
>>> merge_structs(DB1, DB2)
Inputs:
DB1: scipy.io.matlab.mio5_params.mat_struct

Primary struct

DB2: scipy.io.matlab.mio5_params.mat_struct

Second struct

Effects:
DB1: scipy.io.matlab.mio5_params.mat_struct

Data from DB2 added to DB1

Versions:

  • 2019-12-17 @ddalle: First version

cape.dkit.matfile.struct_to_dict(s)

Convert aMATLAB struct to a Python dict

This function is recursive if necessary.

Call:
>>> d = struct_to_dict(s)
Inputs:
s: scipy.io.matlab.mio5_params.mat_struct

Interface to MATLAB struct

Outputs:
d: dict

Dict with keys from s._fieldnames

Versions:

  • 2019-12-17 @ddalle: First version

cape.dkit.matfile.to_matlab(v)

Convert a generic MATLAB object to Python

This function recurses if necessary

MATLAB

Python

struct

dict
Call:
>>> x = to_matlab(v)
Inputs:
v: any (Python)

Python interpretation

Outputs:
x: any (MATLAB)

Item ready for .mat file

Versions:

  • 2019-12-17 @ddalle: First version