Use MATLAB Tables and Timetables in Python

When working in Python^® with the pandas package installed, you can convert between MATLAB^® tables and timetables and Python pandas DataFrames. MATLAB Engine API for Python handles these conversions. If the pandas package is not available when you return a MATLAB table or timetable to Python, the MATLAB engine converts the table or timetable to a matlab.object.

Convert MATLAB Table or Timetable to Pandas DataFrame

You can return a MATLAB table or timetable to Python as a pandas DataFrame. For example, create a table in MATLAB and return it to Python.

First, start the MATLAB engine in Python.

import matlab.engine
import pandas
eng = matlab.engine.start_matlab('-desktop')

Create a MATLAB table in MATLAB.

style = ["coupe"; "hatchback"; "convertible"; "crossover"];
mpg = [47; 50; 33; 42];
hybrid = [true; true; false; true];
mt = table(style,mpg,hybrid);

In Python, convert the MATLAB table to a pandas DataFrame by returning the table directly to Python using workspace. Then display the pandas DataFrame.

mt2pd = eng.workspace['mt']
mt2pd

         style   mpg  hybrid
0        coupe  47.0    True
1    hatchback  50.0    True
2  convertible  33.0   False
3    crossover  42.0    True

You can also convert a MATLAB timetable to a Python pandas DataFrame. For example, create a MATLAB timetable in MATLAB.

released = datetime(["2015-11-02"; "2024-09-12"; "2016-09-13"; "2022-06-01"]);
mtt = timetable(released,style,mpg,hybrid);

Convert the MATLAB timetable to a pandas DataFrame by returning it to Python. Then display the pandas DataFrame. The MATLAB engine converts the datetime row times of the timetable to the row index of the pandas DataFrame.

mtt2pd = eng.workspace['mtt']
mtt2pd

                  style   mpg  hybrid
released
2015-11-02        coupe  47.0    True
2024-09-12    hatchback  50.0    True
2016-09-13  convertible  33.0   False
2022-06-01    crossover  42.0    True

You can convert a MATLAB table or timetable with up to one level of nesting to a pandas DataFrame. For example, create a nested MATLAB table in MATLAB.

c2 = {1; 2; 3; 4};
mnt = table(c2,mt)

mnt =

  4×2 table

     c2                    mt              
    _____    ______________________________

                 style        mpg    hybrid
             _____________    ___    ______
                                           
    {[1]}    "coupe"          47     true  
    {[2]}    "hatchback"      50     true  
    {[3]}    "convertible"    33     false 
    {[4]}    "crossover"      42     true

In Python, return the MATLAB table and display the resulting pandas DataFrame. This operation results in an error if your MATLAB table or timetable has more than one level of nesting.

pynt = eng.workspace['mnt']
pynt

    c2     mt_style  mt_mpg  mt_hybrid
0  1.0        coupe    47.0       True
1  2.0    hatchback    50.0       True
2  3.0  convertible    33.0      False
3  4.0    crossover    42.0       True

Convert Pandas DataFrame to MATLAB Table or Timetable

You can pass a Python pandas DataFrame to MATLAB directly as a MATLAB table. For example, create a pandas DataFrame from a nested Python list in Python.

s1 = [37.3,29.4,0.1]
s2 = [39.1,29.6,0.9]
s3 = [42.3,30.0,0.0]
pl = [s1,s2,s3]
df = pandas.DataFrame(pl,columns=["temperature","pressure","precipitation"])

In Python, convert the pandas DataFrame to a MATLAB table by passing it to MATLAB.

eng.workspace['df2mt'] = df

In MATLAB, display the MATLAB table.

df2mt

df2mt =

  3×3 table

    temperature    pressure    precipitation
    ___________    ________    _____________

       37.3          29.4           0.1     
       39.1          29.6           0.9     
       42.3            30             0

You can convert a pandas DataFrame with a NumPy datetime64, pandas Timestamp, or datetime datetime column to a MATLAB timetable using the same method. For example, import the numpy package and datetime module and add a column of dates to the pandas DataFrame in Python. Then set the date column as the DataFrame index.

import numpy
import datetime
df.insert(0,"date",[numpy.datetime64('2015-12-18'),pandas.Timestamp('2017-01-01T12'),datetime.datetime(2020,5,17)])
df.set_index("date")

                     temperature  pressure  precipitation
date
2015-12-18 00:00:00         37.3      29.4            0.1
2017-01-01 12:00:00         39.1      29.6            0.9
2020-05-17 00:00:00         42.3      30.0            0.0

Convert the pandas DataFrame with an index of dates to a MATLAB timetable by passing it to MATLAB from Python.

eng.workspace['df2mtt'] = df

In MATLAB, display the MATLAB timetable.

 df2mtt

df2mtt2 =

  3×3 timetable

                date                 temperature    pressure    precipitation
    _____________________________    ___________    ________    _____________

    2015-12-18T00:00:00.000000000       37.3          29.4           0.1     
    2017-01-01T12:00:00.000000000       39.1          29.6           0.9     
    2020-05-17T00:00:00.000000000       42.3            30             0

You can convert a pandas DataFrame with up to one level of nesting to a MATLAB table or timetable. For example, create a nested pandas DataFrame in Python.

df2 = pandas.DataFrame({
    'A':[1,2],
    'B':[2,3],
    'C':[4,5]
})
ndf = pandas.DataFrame({'ID':[1,2],'Data':[df,df2]})
ndf

   ID                                               Data
0   1                   date  temperature  pressure  ...
1   2                      A  B  C
0  1  2  4
1  2  3  5

In Python, pass the pandas DataFrame to MATLAB. This operation results in an error if your pandas DataFrame has more than one level of nesting.

eng.workspace['mndf'] = ndf

In MATLAB, display the resulting MATLAB table.

mndf

mndf =

  2×2 table

    ID         Data      
    __    _______________

    1     {3×3 timetable}
    2     {2×3 table    }

Data Type Conversion from MATLAB Tables or Timetables to Pandas DataFrames

In Python, when you retrieve a table or timetable from MATLAB, MATLAB Engine API for Python automatically converts the table or timetable data into Python types that best represent the data. In this table, np. refers to NumPy data types and pd. refers to pandas data types.

MATLAB Data Type	Resulting Python Data Type
`uint8`	`np.uint8`
`uint16`	`np.uint16`
`uint32`	`np.uint32`
`uint64`	`np.uint64`
`int8`	`np.int8`
`int16`	`np.int16`
`int32`	`np.int32`
`int64`	`np.int64` `np.int64` is the largest NumPy `int` data type that the MATLAB engine supports.
`single`	`np.float32`
`double`	`np.float64`
`logical`	`bool`
`categorical`	`pd.Categorical`
`datetime`	`np.datetime64`
`duration`	`np.timedelta64`
`complex (single)`	`np.complex64`
`complex (double)`	`np.complex128`
`string`	`str`
`cellstr`	`list`
`struct`	`dict`
`cell`	The MATLAB engine separates `cell` values and converts them into Python types according to this table.
`NaN`	`np.nan`
`NaT`	`pd.NaT`

Data Type Conversion from Pandas DataFrames to MATLAB Tables or Timetables

In Python, when you call a MATLAB function with a pandas DataFrame as input or otherwise pass a pandas DataFrame to MATLAB, MATLAB Engine API for Python automatically converts the pandas data into MATLAB types that best represent the data. In this table, np. refers to NumPy data types and pd. refers to pandas data types.

Pandas Data Type	Resulting MATLAB Data Type
`np.uint8` `pd.UInt8`	`uint8`
`np.uint16` `pd.UInt16`	`uint16`
`np.uint32` `pd.UInt32`	`uint32`
`np.uint64` `pd.UInt64`	`uint64`
`np.int8` `pd.Int8`	`int8`
`np.int16` `pd.Int16`	`int16`
`np.int32` `pd.Int32`	`int32`
`np.int64` `pd.Int64`	`int64` `np.int64` is the largest NumPy `int` data type that the MATLAB engine supports.
`np.float32` `pd.Float32`	`single`
`np.float64` `pd.Float64`	`double`
`bool`	`logical`
`pd.Categorical`	`categorical` array This conversion of the pandas `categorical` type is only supported when the `categorical` type is inside of a pandas DataFrame.
`np.datetime64` `pd.Timestamp`	`datetime`
`np.timedelta64` `pd.Timedelta`	`duration`
`np.complex64`	`complex (single)`
`np.complex128`	`complex (double)`
`str` `pd.StringDtype`	`string`
`tuple`	`cell`
`dict`	`struct`
Other type	Python object – `py.type`
`float('nan')` `np.nan`	`NaN`
`pd.NaT`	`NaT`
None `pd.NA`	The MATLAB engine does not support this conversion.