SciPy - whosmat() Function

---

---

The scipy.io.whosmat() function can read MATLAB.mat files and look into them without loading the entire information. This function returns information on variables that are in the.mat file, including names, shapes, and types.

This method is often used in cases where the number of variables in the.mat files is high, and the user needs to see and import only the necessary data. It is essential for processes that use MATLAB files in Python-based data processing or analysis.

The savemat() often works together with methods like this, including loadmat() for loading certain variables into Python. Together, these methods comprise a seamless pipeline to use MATLAB files in Python.

The whosmat() function returns metadata, including the names of variables, their shapes and types, without actually loading anything into memory. This can be very useful in memory control and processing large mat files.

The most common errors include FileNotFoundErrors when the file is either nonexistent or has a wrong title and unsupported file format errors when the file is not a valid.mat file. These would be avoided if the file path and format are proper.

Syntax

The syntax for the SciPy whosmat() method is as follows −

.whosmat(file_name, appendmat=True)

Parameters

This method accepts the following parameters −

• file_name: The name of the .mat file to be inspected.

• appendmat: If True (default), .mat is appended to the file name if it is not already included. Set to False if the file name already includes .mat.

Return Value

The method returns a list of tuples, where each tuple contains −

• Variable Name: Name of the variable in the .mat file.

• Shape: Shape of the variable (e.g., (3, 4) for a 3x4 matrix).

• Data Type: Type of the variable (e.g., 'double', 'int').

Example 1: Inspecting a Simple .mat File

The whosmat() function retrieves metadata about the variables in a.mat file without loading the data-including their names, shapes, and types.

The following code creates a 2x3 matrix named my_matrix and saves it to a file called example.mat using the whosmat() function to display its metadata. In addition to the variable's name, shape, and type, the output includes whether it is a row or column vector.

import scipy
import scipy.io 

data_to_save = {'my_matrix': [[1, 2, 3], [4, 5, 6]]}
scipy.io.savemat('example.mat', data_to_save)
info = scipy.io.whosmat("example.mat")
print("Variables in 'example.mat':", info)

When we run above program, it produces following result

Variables in 'example.mat': [('my_matrix', (2, 3), 'int64')]

Example 2: Using appendmat=False

The appendmat parameter automatically appends .mat to the file name if the files are inspected or saved, which simplifies handling files.

This code generates the following .mat file: vector.mat containing a 3x1 vector named my_vector. Setting appendmat=True ensures that it will append.mat so that the file name would always be consistent, whereas whosmat() gets metadata.

import numpy as np
import scipy.io  # Import scipy.io explicitly

# Save a 1D vector as a column in a .mat file
data_to_save = {'my_vector': np.array([1, 2, 3]).reshape(-1, 1)}  # Reshape to column vector
scipy.io.savemat('vector.mat', data_to_save)

# Check stored variables in the .mat file
info = scipy.io.whosmat("vector.mat")  # No need for appendmat=True
print("Variables in 'vector.mat':", info)

Following is an output of the above code

Variables in 'example.mat' with appendmat=True: [('my_vector', (3, 1), 'int64')]

Example 3: Error Handling with Missing Files

If the specified.mat file does not exist, the whosmat() method returns a FileNotFoundError, allowing for robust error handling.

This code demonstrates how to create a .mat file and simulates an error by trying to inspect a file that does not exist. It handles the error gracefully, printing the correct error message.

from scipy.io import savemat
import numpy as np
data_to_save = {'my_vector': np.array([1, 2, 3])}
savemat('vector.mat', data_to_save, oned_as='column')
try:
    scipy.io.whosmat("nonexistent.mat")
except FileNotFoundError as e:
    print("Error:", e)

Output of the above code is as follows

Error: [Errno 2] No such file or directory: 'nonexistent.mat'

Example 4: Filtering Variables Based on Metadata

The whosmat() allows filtering of variables based on metadata; you can choose variables of a certain type or form for focused data analysis.

This code generates a.mat file that contains three variables: a 3x3 matrix (var1), a 1x10 vector (var2), and a 4x4 matrix (var3). It then uses whosmat() to filter the variables based on type double and first dimension greater than two, thus refining the list of variables.

import scipy.io
import numpy as np

data_example = {
    "var1": np.random.rand(3, 3),
    "var2": np.arange(10),      
    "var3": np.ones((4, 4)),
}   
scipy.io.savemat("example.mat", data_example)

info = scipy.io.whosmat("example.mat")
filtered_vars = [var for var in info if var[2] == 'double' and var[1][0] > 2]

print("Filtered Variables:", filtered_vars)

Output of the above code is as follows

Filtered Variables: [('var1', (3, 3), 'double'), ('var3', (4, 4), 'double')]

Example 5: Combining savemat, whosmat, and loadmat

The code demonstrates how to save data to a .mat file using savemat() method, inspect its contents using whosmat(), and load specific variables from a file using loadmat(); therefore, it provides an end-to-end workflow to work with .mat files.

The function saves two matrices named matrix1 and matrix2 in a.mat file called combined_example.mat. The file is then inspected with the help of whosmat(), which returns the metadata, and finally loaded and displayed with loadmat().

import scipy.io
import numpy as np

data_to_save = {
    "matrix1": np.array([[1, 2, 3], [4, 5, 6]]),  # A 2x3 matrix
    "matrix2": np.ones((3, 3)),                   # A 3x3 matrix of ones
}
scipy.io.savemat("combined_example.mat", data_to_save)
print("Data saved to 'combined_example.mat'.")

info = scipy.io.whosmat("combined_example.mat")
print("\nVariables in 'combined_example.mat':", info)

loaded_data = scipy.io.loadmat("combined_example.mat")
print("\nLoaded 'matrix1':\n", loaded_data["matrix1"])
print("\nLoaded 'matrix2':\n", loaded_data["matrix2"])

Output of the above code is as follows

Filtered Variables: [('var1', (3, 3), 'double'), ('var3', (4, 4), 'double')]