Leer archivos mat de Matlab en Python

MATLAB guarda las variables del espacio de trabajo en archivos .mat, y Python no tiene una forma integrada de abrirlos: la biblioteca de lectura se elige según la versión del archivo MAT. Esta guía muestra cómo identificar el formato de un archivo y cargar sus variables con scipy.io, h5py, mat4py o la API matlab.engine, y explica dónde deja de funcionar cada enfoque.

Elija un lector según la versión del archivo MAT

MATLAB ha utilizado dos estructuras de archivo. Las versiones 5 a 7.2 de los archivos MAT usan el formato binario propio de MATLAB y comienzan con una cabecera de texto de 128 bytes que empieza por MATLAB; los archivos MATLAB 4, aún más antiguos, usan la misma estructura clásica, pero no tienen una cabecera descriptiva: comienzan directamente con elementos de datos. scipy.io.loadmat lee toda la familia clásica, con o sin cabecera. Los archivos guardados con -v7.3 son archivos HDF5: conservan un pequeño bloque de usuario de MATLAB, pero almacenan los datos como conjuntos de datos HDF5, que es lo que abre h5py. NumPy por sí solo no puede abrir ninguna de las dos estructuras: solo convierte en un arreglo un conjunto de datos ya cargado.

Puede identificar un archivo sin instalar nada observando sus primeros bytes. El código y las etiquetas que imprime el ejemplo permanecen en inglés. Ejecute este ejemplo, que escribe un archivo de cada tipo común en una carpeta temporal y los clasifica según la cabecera:

import os
import tempfile

folder = tempfile.mkdtemp()
classic = os.path.join(folder, "classic.mat")
modern = os.path.join(folder, "v73.mat")

with open(classic, "wb") as f:
    f.write(b"MATLAB 5.0 MAT-file, Platform: GLNXA64, Created on: Thu Oct 29 2026".ljust(128, b" "))

with open(modern, "wb") as f:
    f.write(b"MATLAB 7.3 MAT-file, Platform: GLNXA64, HDF5 schema 1.00".ljust(512, b" "))
    f.write(b"\x89HDF\r\n\x1a\n")

def mat_kind(path):
    with open(path, "rb") as f:
        head = f.read(128)
        f.seek(512)
        signature = f.read(8)
    if b"HDF5" in head or signature.startswith(b"\x89HDF"):
        return "MATLAB 7.3 (HDF5): read with h5py"
    if head.startswith(b"MATLAB"):
        return "MAT-file 7.2 or older: read with scipy.io.loadmat"
    return "no v5+ header or HDF5 signature — possibly a MATLAB 4 file: try scipy.io.loadmat"

print(mat_kind(classic))
print(mat_kind(modern))

MAT-file 7.2 or older: read with scipy.io.loadmat
MATLAB 7.3 (HDF5): read with h5py

Un archivo 7.3 real menciona HDF5 en el texto de su cabecera y lleva la firma HDF5 después del bloque de usuario, mientras que la cabecera de un archivo de la versión 5–7.2 simplemente empieza por MATLAB. La comprobación clasifica solo mediante esos dos marcadores: un archivo MATLAB 4 no muestra ninguno, por lo que cae en el mensaje alternativo; sin embargo, scipy.io.loadmat aún puede abrirlo, así que interprete ese resultado como una señal para probar loadmat directamente, no como prueba de que el archivo sea ilegible. Como regla general, use primero scipy.io.loadmat cuando el archivo sea de la versión 7.2 o anterior, use h5py para los archivos 7.3, elija mat4py cuando quiera listas normales de Python en lugar de arreglos de NumPy a partir de un archivo clásico y use matlab.engine solo cuando el propio MATLAB esté instalado y necesite máxima fidelidad para tipos complejos. Una vez que las variables están en Python, pandas puede exportarlas a CSV o Excel, y scipy.io.savemat o un conjunto de datos HDF5 puede volver a escribir un archivo .mat si más adelante lo necesita.

Las secciones siguientes usan sample.mat (un archivo clásico) y sample_v73.mat (un archivo 7.3), que se supone que contienen una variable llamada measurements. Esos fragmentos dependen de cada paquete: suponen que el paquete indicado está instalado, por lo que debe ejecutarlos en su propio entorno y no en un intérprete básico.

Leer archivos MATLAB con SciPy

Instale la biblioteca con pip install scipy y luego llame a scipy.io.loadmat("sample.mat"). Devuelve un diccionario: junto con sus variables incluye las claves de metadatos __header__, __version__ y __globals__, y cada variable de MATLAB se convierte en un arreglo de NumPy bajo su nombre del espacio de trabajo, de modo que data["measurements"] recupera esa variable directamente.

Conviene conocer dos opciones cuando las formas no parecen correctas. Pasar squeeze_me=True a loadmat contrae las dimensiones de tamaño uno de MATLAB para que un escalar se devuelva como escalar, y combinarlo con struct_as_record=False permite acceder a los campos de una estructura como atributos en lugar de elementos de arreglos anidados. Para volver a escribir resultados, scipy.io.savemat("out.mat", {"measurements": data["measurements"]}) produce un archivo MAT clásico.

El límite de versión es la restricción importante: loadmat solo admite formatos de archivo MAT hasta la versión 7.2. Si recibe un archivo 7.3, informa que el formato no es compatible, porque el contenido es HDF5; ese archivo necesita el enfoque de la siguiente sección. Si controla el lado de MATLAB, guardar con save data.mat -v7 produce un archivo que loadmat acepta.

Leer archivos MATLAB 7.3 con h5py

Un archivo -v7.3 es HDF5 con un bloque de usuario de MATLAB, por lo que pip install h5py es todo lo que necesita para abrirlo. h5py.File("sample_v73.mat", "r") abre el archivo para lectura y list(f.keys()) muestra los grupos de nivel superior: uno por cada variable de MATLAB, más un grupo #refs# que almacena contenido compartido de celdas y estructuras.

Leer f["measurements"][()] materializa el conjunto de datos como un arreglo de NumPy; aquí NumPy solo convierte los datos, porque h5py es quien abrió el archivo. Dos detalles de organización importan en la práctica. MATLAB escribe los arreglos por columnas, por lo que un conjunto de datos bidimensional suele volver transpuesto, y f["measurements"][()].T restaura la orientación de MATLAB. Los arreglos de celdas y las estructuras llegan como referencias a objetos HDF5 dentro de #refs#, por lo que debe desreferenciar cada entrada con f[ref] en lugar de leerla directamente.

Leer archivos MATLAB con mat4py

pip install mat4py le ofrece una API más pequeña orientada a los archivos MAT clásicos. Después de from mat4py import loadmat, llamar a loadmat("sample.mat") devuelve un diccionario normal en el que los arreglos numéricos son listas anidadas de Python y las estructuras se convierten en diccionarios anidados, lo que resulta práctico cuando quiere los datos como tipos puros de Python sin incorporar NumPy.

Considere mat4py como un lector para los formatos clásicos: no abre archivos HDF5 7.3, y las estructuras de MATLAB muy anidadas o poco habituales pueden no traducirse correctamente, por lo que no es un sustituto para todos los archivos MAT. Verifique la conversión de un archivo complejo comparándola con scipy.io antes de basarse en ella.

Leer archivos MATLAB con la API de MATLAB Engine

Cuando el propio MATLAB está instalado, su API Engine para Python es la opción de mayor fidelidad. Instalar matlabengine con pip (o ejecutar el instalador incluido con MATLAB) expone matlab.engine, que controla una sesión real de MATLAB en segundo plano. eng = matlab.engine.start_matlab() inicia esa sesión, eng.load("sample.mat") carga todas las variables en el espacio de trabajo del motor sin importar la versión del archivo, y eng.quit() la cierra cuando termina. Los valores vuelven como tipos de MATLAB, como matlab.double, que NumPy convierte con np.asarray.

Las desventajas son prácticas y no están relacionadas con el formato: el motor necesita una instalación de MATLAB con licencia y una versión del motor coincidente, la sesión tarda segundos en iniciarse y no puede ejecutarse en un entorno de Python normal. También por eso esta sección muestra las llamadas en línea en lugar de un ejemplo independiente: las demás bibliotecas son la opción predeterminada adecuada siempre que MATLAB no esté ya instalado en el equipo.