Matlab datafile IO (spynal.matIO)

Functions for loading from and saving to Matlab MAT files

Overview

Seamlessly loads all Matlab .mat files, both older versions (which require scipy.io loaders) and the newer HDF5-based version (which requires h5py loaders). Dispatch to appropriate loader takes place under-the-hood, without any user input.

Matlab variables are loaded into the closest Python approximation that is also useful for data analysis, with some user-specified options. These are summarized below (see loadmat for details):

MATLAB	PYTHON
array	Numpy ndarray of appropriate dtype
cell array	Numpy ndarray of object dtype
struct (table-like)	dict or Pandas DataFrame (user’s option)
struct (general)	dict

All “container” variables (structs, cell arrays) are loaded recursively, so each element (and sub-element, etc.) is processed appropriately.

Module also contains functionality for introspection into the contents of mat files without having to load them (whomat), and for saving variables back out to mat files with proper conversion to types encodable in mat files (savemat).

Function list

• loadmat : Loads variables from any Matlab MAT file. Also aliased as ‘load’.

• savemat : Saves given variables into a MAT file. Also aliased as ‘save’.

• whomat : Lists all variables in any MAT file. Also aliased as ‘who’.

Dependencies

• h5py : Python interface to the HDF5 binary data format (used for v7.3 MAT files)

• hdf5storage : Utilities to write Python types to HDF5 files, including v7.3 MAT files.

Function reference

loadmat(filename, variables=None, typemap=None, asdict=False, extract_items=None, order='Matlab', verbose=True)

Load variables from a given MAT file and return them in appropriate Python types

Handles both older (v4-v7) and newer (v7.3) versions of MAT files, transparently to the user.

Variables returned individually or in a dict, where each variable maps to key/value pair

Returned variable types are logical Python equivalents of Matlab types:

MATLAB	PYTHON
double/single	float
int	int
char,string	str
logical	bool
array	Numpy ndarray of appropriate dtype
cell array	Numpy ndarray of object dtype
struct (table-like)	dict or Pandas DataFrame (depends on typemap)
struct (general)	dict

Single-element Matlab arrays are converted to the contained item type (eg float/int/str) by default (behavior can be changed using extract_items argument)

NOTE: Some proprietary or custom Matlab variables cannot be loaded, including: table/timetable, datetime, categorical, function_handle, map container, any custom object class

Parameters:

• filename (str) – Full-path name of MAT file to load from

• variables (list of str, default: <all variables in file>) – Names of all variables to load

• typemap (dict {str:str}, default: {'array':'array', 'cell':'array', 'struct':'dict'}) – Maps names of Matlab variables or variable types to returned Python variable types. Currently alternative options only supported for table-like structs, which can return either as ‘dict’ or ‘dataframe’ (Pandas DataFrame).

• asdict (bool, default: False) – If True, returns variables in a {‘variable_name’:value} dict. If False, returns variables separately (as tuple).

• extract_items (bool or dict, {str:bool}, default: {'array':True, 'cell':False, 'struct':True}) –

  All Matlab variables – even scalar-valued ones – are loaded as arrays. This argument determines whether scalar-valued variables are returned as length-1 arrays (False) or the single item is extracted from the array and returned as its specific dtype (True).

  Can be given as a single bool value to be used for all loaded variables or as a dict that maps names of Matlab variable types or specific Matlab variable names to bools.

  Default: extract scalar items, except for loaded Matlab cell arrays / Python object arrays, where it can break downstream code to have some array elements extracted, but others remaining contained in (sub)arrays (eg spike timestamp lists with a single spike for some trials/units).

• order (str, default: 'Matlab') – Dimension order of returned arrays. Determines how values are arranged when reshaped. Options: - ‘Matlab’/’F’ : Use Matlab/Fortran dimensional ordering (column-major-compatible) - ‘Python’/’C’ : Use Python/C dimensional ordering (row-major compatible)

• verbose (bool, default: True) – If True, prints names and shapes of all loaded variables to stdout

Returns:

• data_dict (dict {str:<variable>}) – Dictionary holding all loaded variables, mapping variable name to its value

• -or-

• vbl1,vbl2,… – Variables returned individually, as in 2nd example above

Examples

data_dict = loadmat(filename, variable, asdict=True)

variable1, variable2, … = loadmat(filename, variable, asdict=False)

whomat(filename, verbose=True)

Return list of variables in a given MAT file and/or print them to stdout

Parameters:

• filename (str) – Full-path name of MAT-file to examine

• verbose (bool, default: True) – If True, prints names of all file variables to stdout

Returns:

variables – Names of variables in file

Return type:

list of str

savemat(filename, variables, version=None, **kwargs)

Save data variables to a Matlab MAT file

Parameters:

• filename (str) – Full-path name of MAT file to save to

• variables (dict {str:<variable>}) – Names and values of variables to save

• version (float, default: (7.3 if any variable is > 2 GB; 7 otherwise)) – Version of MAT file: 7 (older) | 7.3 (newer/HDF5).

• **kwargs – All other keyword args passed to scipy.io.savemat()