559

Is it possible to read binary MATLAB .mat files in Python?

I've seen that SciPy has alleged support for reading .mat files, but I'm unsuccessful with it. I installed SciPy version 0.7.0, and I can't find the loadmat() method.

16 Answers 16

768

An import is required, import scipy.io...

import scipy.io
mat = scipy.io.loadmat('file.mat')
4
214

Neither scipy.io.savemat, nor scipy.io.loadmat work for MATLAB arrays version 7.3. But the good part is that MATLAB version 7.3 files are hdf5 datasets. So they can be read using a number of tools, including NumPy.

For Python, you will need the h5py extension, which requires HDF5 on your system.

import numpy as np
import h5py
f = h5py.File('somefile.mat','r')
data = f.get('data/variable1')
data = np.array(data) # For converting to a NumPy array
9
  • 8
    This works fine, if you use the '-v7.3' flag in Matlab when saving out your data. Using the default save (at least in Matlab R2014b) results in a file that cannot be read using the technique above. If you do use the '-v7.3' flag, the numeric data can be read just fine. May 6, 2015 at 17:58
  • 5
    Yes, that's what I said in my post. You need to use -v7.3 while saving in Matlab. You should do that anyways as it uses a better/more supported/standardized format.
    – vikrantt
    May 10, 2015 at 22:18
  • 5
    Could you please explain what is the relation between f and data in your example? How can I move f to a numpy array?
    – heracho
    Jun 6, 2017 at 19:02
  • 4
    How would i even know that it contains data under data/variable1 ??
    – devspartan
    Jul 5, 2020 at 3:09
  • 8
    @devSpartan f.keys() will show you what you can access Oct 22, 2020 at 16:17
33

First save the .mat file as:

save('test.mat', '-v7')

After that, in Python, use the usual loadmat function:

import scipy.io as sio
test = sio.loadmat('test.mat')
0
26

There is a nice package called mat4py which can easily be installed using

pip install mat4py

It is straightforward to use (from the website):

Load data from a MAT-file

The function loadmat loads all variables stored in the MAT-file into a simple Python data structure, using only Python’s dict and list objects. Numeric and cell arrays are converted to row-ordered nested lists. Arrays are squeezed to eliminate arrays with only one element. The resulting data structure is composed of simple types that are compatible with the JSON format.

Example: Load a MAT-file into a Python data structure:

from mat4py import loadmat

data = loadmat('datafile.mat')

The variable data is a dict with the variables and values contained in the MAT-file.

Save a Python data structure to a MAT-file

Python data can be saved to a MAT-file, with the function savemat. Data has to be structured in the same way as for loadmat, i.e. it should be composed of simple data types, like dict, list, str, int, and float.

Example: Save a Python data structure to a MAT-file:

from mat4py import savemat

savemat('datafile.mat', data)

The parameter data shall be a dict with the variables.

10
  • Note that mat4py gives you a json-like tree of dicts, lists, lists of lists ... -- no numpy at all. (mat4py/cmd.py my.mat writes my.json, 1 long line.)
    – denis
    Nov 14, 2018 at 14:20
  • 1
    @denis: Yes, that's also stated above. But a good point indeed: I usually like this structure, e.g. in web applications as numpy arrays are not JSON serializable.
    – Cleb
    Nov 14, 2018 at 15:34
  • 1
    Encountered: mat4py.loadmat.ParseError: Can only read from Matlab level 5 MAT-files
    – s2t2
    Jul 19, 2019 at 14:19
  • @s2t2: never ran into this issue before. What matlab version and which scipy version are you using?
    – Cleb
    Jul 19, 2019 at 15:09
  • 1
    good solution for fallback if scipy is not available (for example on Rasperry Pi). its also faster with pure number data but slower if there are strings
    – save_jeff
    Mar 5 at 8:09
17

Having MATLAB 2014b or newer installed, the MATLAB engine for Python could be used:

import matlab.engine
eng = matlab.engine.start_matlab()
content = eng.load("example.mat", nargout=1)
3
  • I got this error: ModuleNotFoundError: No module named 'pylab'. Jun 13, 2018 at 1:51
  • 3
    You got the error when trying this answers? That is odd, it does not use pylab.
    – Daniel
    Jun 13, 2018 at 5:40
  • 1
    For the record, this answer requires a valid Matlab installation and license - it runs Matlab in the background to accomplish the read. And there may be limitations on what format you get the items in that need further work to make them readable. For example, Simulink.Bus objects come in as a "matlab object" and must be processed further, with issues if you want to extract the Bus Element objects.
    – LightCC
    Jun 23, 2022 at 20:13
15

Reading the file

import scipy.io
mat = scipy.io.loadmat(file_name)

Inspecting the type of MAT variable

print(type(mat))
#OUTPUT - <class 'dict'>

The keys inside the dictionary are MATLAB variables, and the values are the objects assigned to those variables.

1
  • I am getting the error "ValueError: Unknown mat file type, version 9, 99". Any idea how to solve this?
    – sam wolfe
    Jul 23 at 15:01
14

There is a great library for this task called: pymatreader.

Just do as follows:

  1. Install the package: pip install pymatreader

  2. Import the relevant function of this package: from pymatreader import read_mat

  3. Use the function to read the matlab struct: data = read_mat('matlab_struct.mat')

  4. use data.keys() to locate where the data is actually stored.

  • The keys will usually look like: dict_keys(['__header__', '__version__', '__globals__', 'data_opp']). Where data_opp will be the actual key which stores the data. The name of this key can ofcourse be changed between different files.
  1. Last step - Create your dataframe: my_df = pd.DataFrame(data['data_opp'])

That's it :)

2
  • 1
    The 2 things that it did better are: it preserve the mat object dimension and the loaded object was in NumPy array. Thanks
    – nKandel
    Feb 19, 2022 at 21:40
  • 1
    I'm glad it helped :) Mar 6, 2022 at 15:25
10

There is also the MATLAB Engine for Python by MathWorks itself. If you have MATLAB, this might be worth considering (I haven't tried it myself but it has a lot more functionality than just reading MATLAB files). However, I don't know if it is allowed to distribute it to other users (it is probably not a problem if those persons have MATLAB. Otherwise, maybe NumPy is the right way to go?).

Also, if you want to do all the basics yourself, MathWorks provides (if the link changes, try to google for matfile_format.pdf or its title MAT-FILE Format) a detailed documentation on the structure of the file format. It's not as complicated as I personally thought, but obviously, this is not the easiest way to go. It also depends on how many features of the .mat-files you want to support.

I've written a "small" (about 700 lines) Python script which can read some basic .mat-files. I'm neither a Python expert nor a beginner and it took me about two days to write it (using the MathWorks documentation linked above). I've learned a lot of new stuff and it was quite fun (most of the time). As I've written the Python script at work, I'm afraid I cannot publish it... But I can give some advice here:

  • First read the documentation.
  • Use a hex editor (such as HxD) and look into a reference .mat-file you want to parse.
  • Try to figure out the meaning of each byte by saving the bytes to a .txt file and annotate each line.
  • Use classes to save each data element (such as miCOMPRESSED, miMATRIX, mxDOUBLE, or miINT32)
  • The .mat-files' structure is optimal for saving the data elements in a tree data structure; each node has one class and subnodes
4
  • 12
    That's a somehow crazy documentation provided by mathworks. 40 pages explaining the format, without mentioning that it is a subset of HDF5.
    – Daniel
    Aug 11, 2015 at 0:12
  • It is not there any more
    – Mour_Ka
    Aug 26, 2022 at 7:47
  • 1
    @Mour_Ka the linked PDF still opens for me.
    – mozzbozz
    Sep 2, 2022 at 15:43
  • sorry I meant the Matlab Engine for Python. Here is the new link if I am not mistaken de.mathworks.com/help/matlab/matlab-engine-for-python.html.
    – Mour_Ka
    Sep 4, 2022 at 10:05
10

To read mat file to pandas dataFrame with mixed data types

import scipy.io as sio
mat=sio.loadmat('file.mat')# load mat-file
mdata = mat['myVar']  # variable in mat file 
ndata = {n: mdata[n][0,0] for n in mdata.dtype.names}
Columns = [n for n, v in ndata.items() if v.size == 1]
d=dict((c, ndata[c][0]) for c in Columns)
df=pd.DataFrame.from_dict(d)
display(df)
5

Apart from scipy.io.loadmat for v4 (Level 1.0), v6, v7 to 7.2 matfiles and h5py.File for 7.3 format matfiles, there is anther type of matfiles in text data format instead of binary, usually created by Octave, which can't even be read in MATLAB.

Both of scipy.io.loadmat and h5py.File can't load them (tested on scipy 1.5.3 and h5py 3.1.0), and the only solution I found is numpy.loadtxt.

import numpy as np
mat = np.loadtxt('xxx.mat')
3
  • 1
    At least for .mat files generated with MATLAB, this will result in a UnicodeDecodeError.
    – emilaz
    Jul 6, 2021 at 10:02
  • 1
    @emilaz This is expected. np.loadtxt is only meant for .mat files generated by Octave.
    – MrCrHaM
    Jul 6, 2021 at 10:57
  • 1
    Yes, I just put it there as clarification for future people looking at this :)
    – emilaz
    Jul 6, 2021 at 11:45
3
  1. Install scipy

    pip install scipy

  2. Import the scipy.io.loadmat module

     from scipy.io import loadmat
      annots = loadmat('annotation_0001.mat')
      print(annots)
  1. Parse the .mat file structure
   con_list = [[element for element in upperElement] for upperElement in annots['obj_contour']]
  1. Use Pandas dataframes to work with the data
import pandas as pd
   newData = list(zip(con_list[0], con_list[1]))
   columns = ['obj_contour_x', 'obj_contour_y']
   df = pd.DataFrame(newData, columns=columns)

refrence: https://www.askpython.com/python/examples/mat-files-in-python

1
  • This is already well covered in the accepted answer, and others. Please don't repeat answers.
    – Chris
    May 13 at 21:44
2

Can also use the hdf5storage library. official documentation here for details on matlab version support.

import hdf5storage

label_file = "./LabelTrain.mat"
out = hdf5storage.loadmat(label_file) 

print(type(out)) # <class 'dict'>
1
  • 1
    hdf5storage uses scipy in the background
    – save_jeff
    Mar 5 at 8:51
1
from os.path import dirname, join as pjoin
import scipy.io as sio
data_dir = pjoin(dirname(sio.__file__), 'matlab', 'tests', 'data')
mat_fname = pjoin(data_dir, 'testdouble_7.4_GLNX86.mat')
mat_contents = sio.loadmat(mat_fname)

You can use above code to read the default saved .mat file in Python.

1

After struggling with this problem myself and trying other libraries (I have to say mat4py is a good one as well but with a few limitations) I have built this library ("matdata2py") that can handle most variable types and most importantly for me the "string" type. The .mat file needs to be saved in the -V7.3 version. I hope this can be useful for the community.

Installation:

pip install matdata2py

How to use this lib:

import matdata2py as mtp

To load the Matlab data file:

Variables_output = mtp.loadmatfile(file_Name, StructsExportLikeMatlab = True, ExportVar2PyEnv = False)
print(Variables_output.keys()) # with ExportVar2PyEnv = False the variables are as elements of the Variables_output dictionary. 

with ExportVar2PyEnv = True you can see each variable separately as python variables with the same name as saved in the Mat file.

Flag descriptions

StructsExportLikeMatlab = True/False structures are exported in dictionary format (False) or dot-based format similar to Matlab (True)

ExportVar2PyEnv = True/False export all variables in a single dictionary (True) or as separate individual variables into the python environment (False)

0

scipy will work perfectly to load the .mat files. And we can use the get() function to convert it to a numpy array.

mat = scipy.io.loadmat('point05m_matrix.mat')

x = mat.get("matrix")
print(type(x))
print(len(x))

plt.imshow(x, extent=[0,60,0,55], aspect='auto')
plt.show()
0

To Upload and Read mat files in python

  1. Install mat4py in python.On successful installation we get:
  2. Successfully installed mat4py-0.5.0.
  3. Importing loadmat from mat4py.
  4. Save file actual location inside a variable.
  5. Load mat file format to a data value using python
    pip install mat4py
    from mat4py import loadmat
    boston = r"E:\Downloads\boston.mat" data = loadmat(boston, meta=False)

Not the answer you're looking for? Browse other questions tagged or ask your own question.