mat-io 0.1.0__tar.gz

mat_io-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, foreverallama
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

mat_io-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: mat-io
+Version: 0.1.0
+Summary: A package for reading MATLAB .mat files
+Author-email: foreverallama <klockatoo@gmail.com>
+Project-URL: Homepage, https://github.com/foreverallama/matio
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scipy>=1.15.0
+Requires-Dist: numpy>=2.2.2
+Requires-Dist: pytz
+Requires-Dist: pandas>=2.2.0
+Dynamic: license-file

mat_io-0.1.0/mat_io.egg-info/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: mat-io
+Version: 0.1.0
+Summary: A package for reading MATLAB .mat files
+Author-email: foreverallama <klockatoo@gmail.com>
+Project-URL: Homepage, https://github.com/foreverallama/matio
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scipy>=1.15.0
+Requires-Dist: numpy>=2.2.2
+Requires-Dist: pytz
+Requires-Dist: pandas>=2.2.0
+Dynamic: license-file

mat_io-0.1.0/mat_io.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+pyproject.toml
+mat_io.egg-info/PKG-INFO
+mat_io.egg-info/SOURCES.txt
+mat_io.egg-info/dependency_links.txt
+mat_io.egg-info/requires.txt
+mat_io.egg-info/top_level.txt
+matio/__init__.py
+matio/class_parser.py
+matio/readmat.py
+matio/subsystem.py
+tests/test_mcos/test_datetime/test_datetime.py
+tests/test_mcos/test_duration/test_duration.py
+tests/test_mcos/test_enum/test_enum.py
+tests/test_mcos/test_simple/test_simple.py
+tests/test_mcos/test_string/test_string.py
+tests/test_mcos/test_user_defined/test_user_defined.py

mat_io-0.1.0/mat_io.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mat_io-0.1.0/mat_io.egg-info/requires.txt

@@ -0,0 +1,4 @@
+scipy>=1.15.0
+numpy>=2.2.2
+pytz
+pandas>=2.2.0

mat_io-0.1.0/mat_io.egg-info/top_level.txt

@@ -0,0 +1,6 @@
+dist
+docs
+examples
+matio
+patches
+tests

mat_io-0.1.0/matio/__init__.py

@@ -0,0 +1,3 @@
+from .readmat import load_from_mat
+
+__all__ = ["load_from_mat"]

mat_io-0.1.0/matio/class_parser.py

@@ -0,0 +1,259 @@
+import warnings
+from datetime import datetime
+from zoneinfo import ZoneInfo
+
+import numpy as np
+import pandas as pd
+
+# TODO: Add support for following classes:
+# 1. dynamicprops
+# 2. function_handle
+# 3. event.proplistener
+
+
+def get_tz_offset(tz):
+    """Get timezone offset in milliseconds
+    Inputs:
+        1. tz (str): Timezone string
+    Returns:
+        1. offset (int): Timezone offset in milliseconds
+    """
+    try:
+        tzinfo = ZoneInfo(tz)
+        utc_offset = tzinfo.utcoffset(datetime.now())
+        if utc_offset is not None:
+            offset = int(utc_offset.total_seconds() * 1000)
+        else:
+            offset = 0
+    except Exception as e:
+        warnings.warn(
+            f"Could not get timezone offset for {tz}: {e}. Defaulting to UTC."
+        )
+        offset = 0
+    return offset
+
+
+def MatDatetime(props):
+    """Convert MATLAB datetime to Python datetime
+    Datetime returned as numpy.datetime64[ms]
+    """
+
+    data = props[0, 0].get("data", np.array([]))
+    if data.size == 0:
+        props[0, 0]["data"] = np.array([], dtype="datetime64[ms]")
+        return props
+    tz = props[0, 0].get("tz", None)
+    if tz.size > 0:
+        offset = get_tz_offset(tz.item())
+    else:
+        offset = 0
+
+    millis = data.real + data.imag * 1e3 + offset
+
+    props[0, 0]["data"] = millis.astype("datetime64[ms]")
+    return props
+
+
+def MatDuration(props):
+    """Convert MATLAB duration to Python timedelta
+    Duration returned as numpy.timedelta64
+    """
+
+    millis = props[0, 0]["millis"]
+    if millis.size == 0:
+        props[0, 0]["millis"] = np.array([], dtype="timedelta64[ms]")
+        return props
+
+    fmt = props[0, 0].get("fmt", None)
+    if fmt == "s":
+        count = millis / 1000  # Seconds
+        dur = count.astype("timedelta64[s]")
+    elif fmt == "m":
+        count = millis / 60000  # Minutes
+        dur = count.astype("timedelta64[m]")
+    elif fmt == "h":
+        count = millis / 3600000  # Hours
+        dur = count.astype("timedelta64[h]")
+    elif fmt == "d":
+        count = millis / 86400000  # Days
+        dur = count.astype("timedelta64[D]")
+    else:
+        count = millis
+        dur = count.astype("timedelta64[ms]")
+        # Default case
+
+    props[0, 0]["millis"] = dur
+    return props
+
+
+def MatString(props, byte_order):
+    """Parse string data from MATLAB file
+    Strings are stored within a uint64 array with the following format:
+        1. version
+        2. ndims
+        3. shape
+        4. char_counts
+        5. List of null-terminated strings as uint16 integers
+    """
+
+    data = props[0, 0].get("any", np.array([]))
+    if data.size == 0:
+        data = np.array([[]], dtype="U")
+        props[0, 0]["any"] = data
+        return props
+
+    version = data[0, 0]
+    if version != 1:
+        warnings.warn(
+            "String saved from a different MAT-file version. This may work unexpectedly",
+            UserWarning,
+        )
+
+    ndims = data[0, 1]
+    shape = data[0, 2 : 2 + ndims]
+    num_strings = np.prod(shape)
+    char_counts = data[0, 2 + ndims : 2 + ndims + num_strings]
+    offset = 2 + ndims + num_strings  # start of string data
+    byte_data = data[0, offset:].tobytes()
+
+    strings = []
+    pos = 0
+    encoding = "utf-16-le" if byte_order[0] == "<" else "utf-16-be"
+    for char_count in char_counts:
+        byte_length = char_count * 2  # UTF-16 encoding
+        extracted_string = byte_data[pos : pos + byte_length].decode(encoding)
+        strings.append(extracted_string)
+        pos += byte_length
+
+    arr_str = np.reshape(strings, shape, order="F")
+    props[0, 0]["any"] = arr_str
+    return props
+
+
+class MatTable:
+    # TODO: Collect cases and fix
+    def __init__(self, props, defaults):
+        self.data = defaults["data"]
+
+        for field in [
+            "data",
+            "ndims",
+            "nrows",
+            "nvars",
+            "rownames",
+            "varnames",
+            "props",
+        ]:
+            if field in props.dtype.names:
+                setattr(self, field, props[field])
+
+        self.df = self._build_dataframe()
+
+    def __repr__(self):
+        return repr(self.df)
+
+    def __str__(self):
+        return str(self.df)
+
+    def _extract_cell_value(self, cell):
+        if isinstance(cell, np.ndarray) and cell.dtype == object:
+            return cell[0, 0]["__fields__"]
+        if isinstance(cell, dict):
+            return cell["__properties__"]
+        return cell
+
+    def _build_dataframe(self):
+        columns = {}
+        for i in range(int(self.nvars.item())):
+            varname = self._extract_cell_value(self.varnames[0, i]).item()
+            coldata = [
+                data.item() for data in self._extract_cell_value(self.data[0, i])
+            ]
+            columns[varname] = coldata
+
+        df = pd.DataFrame(columns)
+        if self.rownames.size > 0:
+            rownames = [self._extract_cell_value(rn) for rn in self.rownames[0]]
+            if len(rownames) == self.nrows:
+                df.index = rownames
+
+        return df
+
+
+class MatTimetable:
+    # TODO: Collect cases and fix
+    def __init__(self, obj_dict):
+        self.any = obj_dict.get("any")[0, 0]
+        self.data = self.any["data"]
+        self.numDims = self.any["numDims"]
+        self.dimNames = self.any["dimNames"]
+        self.varNames = self.any["varNames"]
+        self.numRows = self.any["numRows"]
+        self.numVars = self.any["numVars"]
+        self.rowTimes = self.any["rowTimes"]
+        self.df = self._build_dataframe()
+
+    def __str__(self):
+        return str(self.df)
+
+    def __repr__(self):
+        return repr(self.df)
+
+    def _extract_cell_value(self, cell):
+        if isinstance(cell, np.ndarray) and cell.dtype == object:
+            return cell[0, 0]["__fields__"]
+        return cell
+
+    def _build_dataframe(self):
+        columns = {}
+        for i in range(int(self.numVars.item())):
+            varname = self._extract_cell_value(self.varNames[0, i]).item()
+            coldata = [
+                data.item() for data in self._extract_cell_value(self.data[0, i])
+            ]
+            columns[varname] = coldata
+
+        df = pd.DataFrame(columns)
+        time_arr = self.rowTimes[0, 0]["__fields__"]
+        times = [time_arr[i].item() for i in range(int(self.numRows.item()))]
+        df.index = pd.to_datetime(times)
+        df.index.name = self._extract_cell_value(self.dimNames[0, 0]).item()
+
+        return df
+
+
+def convert_to_object(props, class_name, byte_order):
+    """Converts the object to a Python compatible object"""
+
+    if class_name == "datetime":
+        obj = MatDatetime(props)
+
+    elif class_name == "duration":
+        obj = MatDuration(props)
+
+    elif class_name == "string":
+        obj = MatString(props, byte_order)
+
+    # elif class_name == "table":
+    #     obj = MatTable(props[0, 0], defaults)
+
+    # elif class_name == "timetable":
+    #     if "any" in props.dtype.names:
+    #         obj = MatTimetable(props[0, 0], defaults)
+
+    else:
+        # For all other classes, return raw data
+        obj = props
+
+    return obj
+
+
+def wrap_enumeration_instance(enum_array, shapes):
+    """Wraps enumeration instance data into a dictionary"""
+    wrapped_dict = {"_Values": np.empty(shapes, dtype=object)}
+    if len(enum_array) == 0:
+        wrapped_dict["_Values"] = np.array([], dtype=object)
+    else:
+        enum_props = [item.get("_Props", np.array([]))[0, 0] for item in enum_array]
+        wrapped_dict["_Values"] = np.array(enum_props).reshape(shapes, order="F")
+    return wrapped_dict

mat_io-0.1.0/matio/readmat.py

@@ -0,0 +1,170 @@
+from io import BytesIO
+
+import numpy as np
+from scipy.io import loadmat
+from scipy.io.matlab._mio5 import MatFile5Reader
+from scipy.io.matlab._mio5_params import OPAQUE_DTYPE
+
+from .subsystem import SubsystemReader
+
+
+def get_matfile_version(ssStream):
+    """Reads subsystem MAT-file version and endianness
+    Inputs
+        1. ssStream (BytesIO): Subsystem data stream
+    Returns:
+        1. v_major (int): Major version
+        2. v_minor (int): Minor version
+        3. byte_order (str): Endianness
+    """
+
+    ssStream.seek(0)
+    data = ssStream.read(4)
+    maj_ind = int(data[2] == b"I"[0])
+    v_major = int(data[maj_ind])
+    v_minor = int(data[1 - maj_ind])
+    byte_order = "<" if data[2] == b"I"[0] else ">"
+    if v_major in (1, 2):
+        return v_major, v_minor, byte_order
+
+    # Unsure if Subsystem and MAT-file versions can be different
+    raise ValueError(
+        "Unknown subsystem data type, version {}, {}".format(v_major, v_minor)
+    )
+
+
+def read_subsystem(ssdata, **kwargs):
+    """Reads subsystem data as a MAT-file stream
+    Inputs
+        1. ssdata (numpy.ndarray): Subsystem data from "__function_workspace__"
+        2. kwargs: Additional arguments for scipy.io.loadmat
+    Returns:
+        1. subsystem data (numpy.ndarray): Parsed subsystem data
+        2. byte_order (str)
+    """
+    ssStream = BytesIO(ssdata)
+
+    mjv, mnv, byte_order = get_matfile_version(ssStream)
+    if mjv != 1:
+        raise NotImplementedError(f"Subsystem version {mjv}.{mnv} not supported")
+
+    kwargs.pop("byte_order", None)
+    kwargs.pop("variable_names", None)
+
+    ssStream.seek(8)  # Skip subsystem header
+    MR = MatFile5Reader(ssStream, byte_order=byte_order, **kwargs)
+    MR.initialize_read()
+    hdr, _ = MR.read_var_header()
+    try:
+        res = MR.read_var_array(hdr, process=False)
+    except Exception as err:
+        raise ValueError(f"Error reading subsystem data: {err}")
+
+    return res, byte_order
+
+
+def remove_unsupported_args(kwargs):
+    """Removes unsupported arguments for scipy.io.loadmat"""
+    kwargs.pop("simplify_cells", None)
+    kwargs.pop("squeeze_me", None)
+    kwargs.pop("struct_as_record", None)
+    kwargs.pop("uint16_codec", None)
+    kwargs.pop("chars_as_strings", False)
+
+
+def get_function_workspace(file_path, mdict=None, spmatrix=True, **kwargs):
+    """Reads function workspace from MAT-file
+    Inputs
+        1. file_path (str): Path to MAT-file
+        2. mdict (dict): Dictionary to store loaded variables
+        3. spmatrix (bool): Whether to load sparse matrices
+        4. kwargs: Additional arguments for scipy.io.loadmat
+    Returns:
+        1. matfile_dict (dict): Dictionary of loaded variables
+        2. ssdata: Subsystem data from "__function_workspace__"
+    """
+    matfile_dict = loadmat(file_path, mdict=mdict, spmatrix=spmatrix, **kwargs)
+    ssdata = matfile_dict.pop("__function_workspace__", None)
+    return matfile_dict, ssdata
+
+
+def find_opaque_dtype(arr, subsystem, path=()):
+    """Recursively finds and replaces mxOPAQUE_CLASS objects in a numpy array
+    with the corresponding MCOS object.
+
+    This is a hacky solution to find mxOPAQUE_CLASS arrays inside struct arrays or cell arrays.
+    """
+
+    if not isinstance(arr, np.ndarray):
+        return arr
+
+    if arr.dtype == OPAQUE_DTYPE:
+        type_system = arr[0]["_TypeSystem"]
+        metadata = arr[0]["_Metadata"]
+        return subsystem.read_mcos_object(metadata, type_system)
+
+    elif arr.dtype == object:
+        # Iterate through cell arrays
+        for idx in np.ndindex(arr.shape):
+            cell_item = arr[idx]
+            if cell_item.dtype == OPAQUE_DTYPE:
+                type_system = cell_item[0]["_TypeSystem"]
+                metadata = cell_item[0]["_Metadata"]
+                arr[idx] = subsystem.read_mcos_object(metadata, type_system)
+            else:
+                find_opaque_dtype(cell_item, subsystem, path + (idx,))
+
+    elif arr.dtype.names:
+        # Iterate though struct array
+        for idx in np.ndindex(arr.shape):
+            for name in arr.dtype.names:
+                field_val = arr[idx][name]
+                if field_val.dtype == OPAQUE_DTYPE:
+                    type_system = field_val[0]["_TypeSystem"]
+                    metadata = field_val[0]["_Metadata"]
+                    arr[idx][name] = subsystem.read_mcos_object(metadata, type_system)
+                else:
+                    find_opaque_dtype(field_val, subsystem, path + (idx, name))
+
+    return arr
+
+
+def load_from_mat(file_path, mdict=None, raw_data=False, *, spmatrix=True, **kwargs):
+    """Loads variables from MAT-file
+    Calls scipy.io.loadmat to read the MAT-file and then processes the
+    "__function_workspace__" variable to extract subsystem data.
+    Inputs
+        1. file_path (str): Path to MAT-file
+        2. mdict (dict): Dictionary to store loaded variables
+        3. raw_data (bool): Whether to return raw data for objects
+        4. spmatrix (bool): Additional arguments for scipy.io.loadmat
+        5. kwargs: Additional arguments for scipy.io.loadmat
+    Returns:
+        1. mdict (dict): Dictionary of loaded variables
+    """
+
+    remove_unsupported_args(kwargs)
+
+    matfile_dict, ssdata = get_function_workspace(file_path, mdict, spmatrix, **kwargs)
+    if ssdata is None:
+        # No subsystem data in file
+        if mdict is not None:
+            mdict.update(matfile_dict)
+            return mdict
+        return matfile_dict
+
+    ss_array, byte_order = read_subsystem(ssdata, **kwargs)
+    subsystem = SubsystemReader(ss_array, byte_order, raw_data)
+
+    for var, data in matfile_dict.items():
+        if not isinstance(data, np.ndarray):
+            continue
+        matfile_dict[var] = find_opaque_dtype(data, subsystem)
+
+    # Update mdict if present
+    if mdict is not None:
+        mdict.update(matfile_dict)
+    else:
+        mdict = matfile_dict
+
+    return mdict