| Name | mat-io JSON |
| Version |
0.4.0
JSON |
| download |
| home_page | None |
| Summary | A package for reading MATLAB .mat files, with support for MATLAB datatypes like table and string |
| upload_time | 2025-08-18 22:06:35 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
matlab
mat
io
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
scipy
numpy
pytz
pandas
h5py
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Mat-IO Module
The `mat-io` module provides tools for load & save with `.mat` files, particularly perfomring read-write operations on user-defined objects or MATLAB datatypes such as `datetime`, `table` and `string`. It uses a wrapper built around `scipy.io` to read-write subsystem data in MAT-files, which is where MATLAB stores serialized object data. MAT-file versions `v7` to `v7.3` are supported.
`mat-io` can load and save almost all types of objects from MAT-files, including user-defined objects and handle class objects. Additionally, it includes utilities to convert the following MATLAB datatypes into their respective _Pythonic_ objects, and vice versa:
- `string`
- `datetime`, `duration` and `calendarDuration`
- `table` and `timetable`
- `containers.Map` and `dictionary`
- `categorical`
- Enumeration Instance Arrays
**Note**: `load_from_mat()` uses a modified version of `scipy`. The modifications include a few minor changes to `scipy.io` to process `mxOPAQUE_CLASS` variables. You can view the changes under `patches/` and apply it manually. Note that you might need to rebuild as parts of the Cython code was modified. Follow the instructions on the [official SciPy documentation](https://scipy.github.io/devdocs/building/index.html#building-from-source).
## Usage
Install using pip
```bash
pip install mat-io
```
### Available Commands
To read MATLAB objects from a `.mat` file:
```python
from matio import load_from_mat
file_path = "path/to/your/file.mat"
data = load_from_mat(
file_path,
raw_data=False,
add_table_attrs=False,
mdict=None,
variable_names=None,
**kwargs
)
print(data)
```
MATLAB Opaque objects are returned as an instance of class `MatioOpaque` with the following attributes:
- `classname`: The class name, including namespace qualifiers (if any).
- `type_system`: An interal MATLAB type identifier. Usually `MCOS`, but could also be `java` or `handle`.
- `properties`: A dictionary containing the property names and property values.
These objects are contained within `numpy.ndarray` in case of object arrays. If the `raw_data` parameter is set to `False`, then `load_from_mat` converts these objects into a corresponding Pythonic datatype.
---
To write Python objects to a `.mat` file:
```python
from matio import save_to_mat
file_path = "path/to/your/file.mat"
mdict = {"var1": data1, "var2": data2}
save_to_mat(
file_path,
mdict=mdict,
version="v7",
do_compression=True,
global_vars=None,
oned_as="row",
)
```
When writing objects, `matio` tries to guess the class name of the object based on its datatype. For example, `pandas.DataFrames` could be read in as `table` or `timetable`. You can also explicitly mention the object by wrapping your data around an instance of `MatioOpaque` as follows:
```python
from matio import MatioOpaque, save_to_mat
df = some_dataframe
mat_df = MatioOpaque(properties=df, classname="table")
mdict = {"table1": mat_df}
data = save_to_mat(file_path="temp.mat", mdict=mdict)
```
For user-defined classes, a dictionary of property name-value pairs must be wrapped around a `MatioOpaque` instance. In case of arrays, these objects should be contained within a `numpy.ndarray` with `dtype=object` and each `MatioOpaque` instance should be flagged with the `is_array` attribute. All user-defined classes default to the `MCOS` type system.
### Notes
- Extra keyword arguments (`**kwargs`) are passed directly to [`scipy.io.loadmat`](https://docs.scipy.org/doc/scipy/reference/generated/scipy.io.loadmat.html) or [`scipy.io.savemat`](https://docs.scipy.org/doc/scipy/reference/generated/scipy.io.savemat.html).
- For conversion rules between MATLAB and Python datatypes, see the [documentation](./docs/field_contents.md).
- To differentiate between MATLAB character and string arrays, it would be ideal to wrap a numpy string array around a `MatioOpaque` instance. However, this is not feasible all the time, especially as MATLAB seems to be using strings in most of their new datatypes. Hence, this module uses Scipy's convention of converting Python `str`, `list(str)` or `numpy.array(dtype=<U1/S1)` to a character array. Numpy string arrays with multiple strings is converted to a MATLAB string
## Contribution
Feel free to create a PR if you'd like to add something, or open up an issue if you'd like to discuss! I've also opened an [issue](https://github.com/scipy/scipy/issues/22736) with `scipy.io` detailing some of the workflow, as well as a [PR](https://github.com/scipy/scipy/pull/22847) to develop this iteratively. Please feel free to contribute there as well!
## Acknowledgement
Big thanks to [mahalex](https://github.com/mahalex/MatFileHandler) for their detailed breakdown of MAT-files. A lot of this wouldn't be possible without it.
Raw data
{
"_id": null,
"home_page": null,
"name": "mat-io",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "MATLAB, mat, io",
"author": null,
"author_email": "foreverallama <klockatoo@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/7e/fb/836d22a3e51dd7a80891625320a5684d347a758f8d39ea4c69f41a6d05a3/mat_io-0.4.0.tar.gz",
"platform": null,
"description": "# Mat-IO Module\n\nThe `mat-io` module provides tools for load & save with `.mat` files, particularly perfomring read-write operations on user-defined objects or MATLAB datatypes such as `datetime`, `table` and `string`. It uses a wrapper built around `scipy.io` to read-write subsystem data in MAT-files, which is where MATLAB stores serialized object data. MAT-file versions `v7` to `v7.3` are supported.\n\n`mat-io` can load and save almost all types of objects from MAT-files, including user-defined objects and handle class objects. Additionally, it includes utilities to convert the following MATLAB datatypes into their respective _Pythonic_ objects, and vice versa:\n\n- `string`\n- `datetime`, `duration` and `calendarDuration`\n- `table` and `timetable`\n- `containers.Map` and `dictionary`\n- `categorical`\n- Enumeration Instance Arrays\n\n**Note**: `load_from_mat()` uses a modified version of `scipy`. The modifications include a few minor changes to `scipy.io` to process `mxOPAQUE_CLASS` variables. You can view the changes under `patches/` and apply it manually. Note that you might need to rebuild as parts of the Cython code was modified. Follow the instructions on the [official SciPy documentation](https://scipy.github.io/devdocs/building/index.html#building-from-source).\n\n## Usage\n\nInstall using pip\n\n```bash\npip install mat-io\n```\n\n### Available Commands\n\nTo read MATLAB objects from a `.mat` file:\n\n```python\nfrom matio import load_from_mat\n\nfile_path = \"path/to/your/file.mat\"\ndata = load_from_mat(\n file_path,\n raw_data=False,\n add_table_attrs=False,\n mdict=None,\n variable_names=None,\n **kwargs\n)\nprint(data)\n```\n\nMATLAB Opaque objects are returned as an instance of class `MatioOpaque` with the following attributes:\n\n- `classname`: The class name, including namespace qualifiers (if any).\n- `type_system`: An interal MATLAB type identifier. Usually `MCOS`, but could also be `java` or `handle`.\n- `properties`: A dictionary containing the property names and property values.\n\nThese objects are contained within `numpy.ndarray` in case of object arrays. If the `raw_data` parameter is set to `False`, then `load_from_mat` converts these objects into a corresponding Pythonic datatype.\n\n---\n\nTo write Python objects to a `.mat` file:\n\n```python\nfrom matio import save_to_mat\n\nfile_path = \"path/to/your/file.mat\"\nmdict = {\"var1\": data1, \"var2\": data2}\nsave_to_mat(\n file_path,\n mdict=mdict,\n version=\"v7\",\n do_compression=True,\n global_vars=None,\n oned_as=\"row\",\n)\n```\n\nWhen writing objects, `matio` tries to guess the class name of the object based on its datatype. For example, `pandas.DataFrames` could be read in as `table` or `timetable`. You can also explicitly mention the object by wrapping your data around an instance of `MatioOpaque` as follows:\n\n```python\nfrom matio import MatioOpaque, save_to_mat\n\ndf = some_dataframe\nmat_df = MatioOpaque(properties=df, classname=\"table\")\nmdict = {\"table1\": mat_df}\ndata = save_to_mat(file_path=\"temp.mat\", mdict=mdict)\n```\n\nFor user-defined classes, a dictionary of property name-value pairs must be wrapped around a `MatioOpaque` instance. In case of arrays, these objects should be contained within a `numpy.ndarray` with `dtype=object` and each `MatioOpaque` instance should be flagged with the `is_array` attribute. All user-defined classes default to the `MCOS` type system.\n\n### Notes\n\n- Extra keyword arguments (`**kwargs`) are passed directly to [`scipy.io.loadmat`](https://docs.scipy.org/doc/scipy/reference/generated/scipy.io.loadmat.html) or [`scipy.io.savemat`](https://docs.scipy.org/doc/scipy/reference/generated/scipy.io.savemat.html).\n\n- For conversion rules between MATLAB and Python datatypes, see the [documentation](./docs/field_contents.md).\n\n- To differentiate between MATLAB character and string arrays, it would be ideal to wrap a numpy string array around a `MatioOpaque` instance. However, this is not feasible all the time, especially as MATLAB seems to be using strings in most of their new datatypes. Hence, this module uses Scipy's convention of converting Python `str`, `list(str)` or `numpy.array(dtype=<U1/S1)` to a character array. Numpy string arrays with multiple strings is converted to a MATLAB string\n\n## Contribution\n\nFeel free to create a PR if you'd like to add something, or open up an issue if you'd like to discuss! I've also opened an [issue](https://github.com/scipy/scipy/issues/22736) with `scipy.io` detailing some of the workflow, as well as a [PR](https://github.com/scipy/scipy/pull/22847) to develop this iteratively. Please feel free to contribute there as well!\n\n## Acknowledgement\n\nBig thanks to [mahalex](https://github.com/mahalex/MatFileHandler) for their detailed breakdown of MAT-files. A lot of this wouldn't be possible without it.\n",
"bugtrack_url": null,
"license": null,
"summary": "A package for reading MATLAB .mat files, with support for MATLAB datatypes like table and string",
"version": "0.4.0",
"project_urls": {
"Homepage": "https://github.com/foreverallama/matio",
"Issues": "https://github.com/foreverallama/matio",
"Repository": "https://github.com/foreverallama/matio"
},
"split_keywords": [
"matlab",
" mat",
" io"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2f9e27a79ba5035a98e7af6f359d02d6f4c176245f1f712bc92312105989e470",
"md5": "ed76cd775e63730ed3cfadac044750e0",
"sha256": "879e9251c70329b940b66a2a450539941dce14dc784b5dd41b1ea3428265a165"
},
"downloads": -1,
"filename": "mat_io-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ed76cd775e63730ed3cfadac044750e0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 170205,
"upload_time": "2025-08-18T22:06:33",
"upload_time_iso_8601": "2025-08-18T22:06:33.456669Z",
"url": "https://files.pythonhosted.org/packages/2f/9e/27a79ba5035a98e7af6f359d02d6f4c176245f1f712bc92312105989e470/mat_io-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7efb836d22a3e51dd7a80891625320a5684d347a758f8d39ea4c69f41a6d05a3",
"md5": "89b59460192be14a842ef02553df7726",
"sha256": "ba38c635e7e2ca9733e767b87e40f39df893ca1c3aa3e21043373eabc13acb1a"
},
"downloads": -1,
"filename": "mat_io-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "89b59460192be14a842ef02553df7726",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 158216,
"upload_time": "2025-08-18T22:06:35",
"upload_time_iso_8601": "2025-08-18T22:06:35.719837Z",
"url": "https://files.pythonhosted.org/packages/7e/fb/836d22a3e51dd7a80891625320a5684d347a758f8d39ea4c69f41a6d05a3/mat_io-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 22:06:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "foreverallama",
"github_project": "matio",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "scipy",
"specs": [
[
">=",
"1.16.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"2.2.2"
]
]
},
{
"name": "pytz",
"specs": []
},
{
"name": "pandas",
"specs": [
[
">=",
"2.2.0"
]
]
},
{
"name": "h5py",
"specs": [
[
">=",
"3.13.0"
]
]
}
],
"lcname": "mat-io"
}
