Ler arquivos mat Matlab em Python

O MATLAB salva as variáveis do espaço de trabalho em arquivos .mat, e o Python não tem uma forma nativa de abri-los — você escolhe uma biblioteca de leitura com base na versão do arquivo MAT. Este guia mostra como identificar o formato de um arquivo e carregar suas variáveis com scipy.io, h5py, mat4py ou a API matlab.engine, e explica onde cada abordagem deixa de funcionar.

Escolha um leitor para a versão do arquivo MAT

O MATLAB já usou dois layouts de arquivo. As versões 5 a 7.2 do formato MAT usam o formato binário próprio do MATLAB e começam com um cabeçalho de texto de 128 bytes que inicia com MATLAB; os arquivos ainda mais antigos do MATLAB 4 usam o mesmo layout clássico, mas não têm cabeçalho descritivo — começam diretamente com os elementos de dados. O scipy.io.loadmat lê toda a família clássica, com ou sem cabeçalho. Os arquivos salvos com -v7.3 são arquivos HDF5: eles mantêm um pequeno bloco de usuário do MATLAB, mas armazenam os dados como conjuntos de dados HDF5, que é o que o h5py abre. O NumPy sozinho não consegue abrir nenhum dos dois layouts — ele apenas converte um conjunto de dados já carregado em um array.

Você pode identificar um arquivo sem instalar nada observando seus primeiros bytes. Execute este exemplo, que grava um arquivo de cada tipo comum em uma pasta temporária e os classifica pelo cabeçalho:

O código e os rótulos exibidos nesta seção permanecem em inglês.

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

Um arquivo 7.3 real menciona HDF5 no texto do cabeçalho e carrega a assinatura HDF5 após o bloco de usuário, enquanto o cabeçalho de um arquivo da versão 5–7.2 simplesmente começa com MATLAB. A verificação classifica apenas por esses dois marcadores: um arquivo do MATLAB 4 não mostra nenhum deles, então cai na mensagem de fallback — mas o scipy.io.loadmat ainda o abre, portanto trate esse resultado como uma deixa para tentar o loadmat diretamente, e não como prova de que o arquivo é ilegível. Como regra, use o scipy.io.loadmat primeiro quando o arquivo for da versão 7.2 ou anterior, use o h5py para arquivos 7.3, escolha o mat4py quando quiser listas Python simples em vez de arrays NumPy a partir de um arquivo clássico e use o matlab.engine somente quando o próprio MATLAB estiver instalado e você precisar de fidelidade total para tipos complexos. Depois que as variáveis estiverem no Python, o pandas pode exportá-las para CSV ou Excel, e o scipy.io.savemat ou um conjunto de dados HDF5 pode gravar um arquivo .mat de volta, se você precisar de um mais tarde.

As seções abaixo usam sample.mat (um arquivo clássico) e sample_v73.mat (um arquivo 7.3), que presumimos conter uma variável chamada measurements. Esses trechos são específicos de cada dependência: eles presumem que o pacote indicado está instalado, então execute-os no seu próprio ambiente, e não em um interpretador vazio.

Ler arquivos MATLAB com o SciPy

Instale a biblioteca com pip install scipy e depois chame scipy.io.loadmat("sample.mat"). Ela retorna um dicionário: além das suas variáveis, ele carrega as chaves de metadados __header__, __version__ e __globals__, e cada variável do MATLAB vira um array NumPy sob o nome que tinha no espaço de trabalho, então data["measurements"] recupera essa variável diretamente.

Vale conhecer duas opções quando as dimensões parecerem estranhas. Passar squeeze_me=True para o loadmat colapsa as dimensões unitárias do MATLAB, de modo que um escalar volta como escalar, e combiná-la com struct_as_record=False permite acessar campos de struct como atributos, em vez de elementos de array aninhados. Para gravar resultados de volta, scipy.io.savemat("out.mat", {"measurements": data["measurements"]}) produz um arquivo MAT clássico.

O limite de versão é a restrição importante: o loadmat suporta apenas formatos de arquivo MAT até a versão 7.2. Diante de um arquivo 7.3, ele relata o formato como não suportado, porque o conteúdo é HDF5 — esse arquivo precisa da abordagem da próxima seção. Se você controla o lado do MATLAB, salvar com save data.mat -v7 produz um arquivo que o loadmat aceita.

Ler arquivos MATLAB 7.3 com o h5py

Um arquivo -v7.3 é HDF5 com um bloco de usuário do MATLAB, então pip install h5py é tudo o que você precisa para abri-lo. h5py.File("sample_v73.mat", "r") abre o arquivo para leitura, e list(f.keys()) mostra os grupos de nível superior — um por variável do MATLAB, mais um grupo #refs# que armazena o conteúdo compartilhado de células e structs.

Ler f["measurements"][()] materializa o conjunto de dados como um array NumPy; aqui o NumPy está apenas convertendo os dados, já que foi o h5py que abriu o arquivo. Dois detalhes de layout importam na prática. O MATLAB grava arrays em ordem de coluna (column-major), então um conjunto de dados 2-D normalmente volta transposto, e f["measurements"][()].T restaura a orientação do MATLAB. Cell arrays e structs chegam como referências de objeto HDF5 para o grupo #refs#, então você desreferencia cada entrada com f[ref] em vez de lê-la diretamente.

Ler arquivos MATLAB com o mat4py

pip install mat4py oferece uma API menor, voltada para arquivos MAT clássicos. Depois de from mat4py import loadmat, chamar loadmat("sample.mat") retorna um dicionário comum em que arrays numéricos são listas Python aninhadas e structs viram dicionários aninhados — conveniente quando você quer os dados como tipos puros do Python sem precisar do NumPy.

Trate o mat4py como um leitor para os formatos clássicos: ele não abre arquivos HDF5 7.3, e estruturas do MATLAB muito aninhadas ou incomuns podem não ser mapeadas corretamente, então ele não substitui todos os arquivos MAT. Verifique a conversão de um arquivo complexo comparando-a com o scipy.io antes de construir sobre ela.

Ler arquivos MATLAB com a API MATLAB Engine

Quando o próprio MATLAB está instalado, sua Engine API para Python é a opção de maior fidelidade. Instalar o matlabengine com pip (ou executar o instalador fornecido com o MATLAB) expõe o matlab.engine, que controla uma sessão real do MATLAB nos bastidores. eng = matlab.engine.start_matlab() inicia essa sessão, eng.load("sample.mat") carrega todas as variáveis no espaço de trabalho do engine, independentemente da versão do arquivo, e eng.quit() a encerra quando você termina. Os valores voltam como tipos do MATLAB, como matlab.double, que o NumPy converte com np.asarray.

As desvantagens são práticas, e não relacionadas ao formato: o engine precisa de uma instalação licenciada do MATLAB e de uma versão compatível do engine, a sessão leva alguns segundos para iniciar e não pode rodar em um ambiente Python comum. É também por isso que esta seção mostra as chamadas inline, em vez de um exemplo independente — as outras bibliotecas são o padrão correto sempre que o MATLAB ainda não está na máquina.