Import Data Using Custom File Reader

Write Class Definition for Custom Reader

Write a class definition that specifies how your custom reader extracts relevant data and metadata from files and variables that use custom formats. Save the class definition file in a location on the MATLAB® path.

The custom reader in this example uses the readtable function to load data from a Microsoft® Excel® file and uses the first column in the file as time data.

The class definition starts by inheriting from the io.reader class, followed by method definitions that return required and relevant data and metadata.

classdef ExcelFirstColumnTimeReader < io.reader

Every custom reader must define the getName, getTimeValues, and getDataValues methods. Additional methods are available to access certain metadata that might exist in the custom file. The class definition for this example defines the abstract methods as well as the supportsFile and getChildren methods.

The supportsFile method checks the file contents to make sure the file contains signal data.

function supported = supportsFile(~,filename)
    try
        t = readtable(filename);
        supported = height(t) > 0 && numel(t.Properties.VariableNames) > 1;
    catch
        supported = false;
    end
end

To import multiple signals from a file, treat the data as hierarchical with the file being the top node. The reader uses the getChildren method to create an ExcelFirstColumnTimeReader object for each signal in the file.

function childObj = getChildren(obj)
    childObj = {};
    if isempty(obj.VariableName)
        t = readtable(obj.FileName);
        vars = t.Properties.VariableNames;
        vars(1) = [];
        childObj = cell(size(vars));
        for idx = 1:numel(vars)
            childObj{idx} = ExcelFirstColumnTimeReader;
            childObj{idx}.FileName = obj.FileName;
            childObj{idx}.VariableName = vars{idx};
        end
    end
end

The getTimeValues method reads the data in the file using the readtable function and returns the data in the first column for the Simulation Data Inspector to use as time data.

function timeVals = getTimeValues(obj)
    timeVals = [];
    if ~isempty(obj.VariableName)
        t = readtable(obj.FileName);
        timeName = t.Properties.VariableNames{1};
        timeVals = t.(timeName);
    end
end

The getName method uses the file name as the name for the top-level node of the imported data. Signals are named using the VariableName property for the corresponding ExcelFirstColumnTimeReader object returned by the getChildren method.

function retName = getName(obj)
    if isempty(obj.VariableName)
        fullName = obj.FileName;
        [filepath,name,ext] = fileparts(fullName);
        retName = strcat(name,ext);
    else
        retName = obj.VariableName;
    end
end

The getDataValues method returns the data in each column that has data besides the first as signal data. Data for each signal is accessed using the VariableName property for the corresponding object returned by the getChildren method.

function dataVals = getDataValues(obj)
    dataVals = [];
    if ~isempty(obj.VariableName)
        t = readtable(obj.FileName);
        dataVals = t.(obj.VariableName);
    end
end

Register Custom Reader for Simulation Data Inspector

After you write the class definition file for the custom data reader, you need to register the reader with the Simulation Data Inspector before you can use it to import data. The Simulation Data Inspector does not store registered readers between MATLAB sessions, so you need to register a custom reader at the start of each new MATLAB session. You can register a custom reader to read data from the workspace or to read data from a file. To register the file reader in this example, use the registerFileReader method.

registerFileReader(ExcelFirstColumnTimeReader,[".xlsx" ".xls"]);

To confirm that the file reader is registered, use the io.reader.getRegisteredFileReaders method.

io.reader.getRegisteredFileReaders

ans = 
"ExcelFirstColumnTimeReader"

Import Data from File in Custom Format

Once you register the custom file reader, you can import data from a file in a custom format using the Simulation Data Inspector UI or using the Simulink.sdi.createRun function. This example imports a simple data set from a file that contains four columns of data. The custom file reader in this example always loads the first column, in this case a, as time data.

To import the data using the UI, open the Simulation Data Inspector. You can use the Simulink.sdi.view function to open the Simulation Data Inspector from the MATLAB Command Window. Then, click Import .

In the Import dialog, select the File option and import the data from the file into a new run. Click the folder to browse the file system and select the file you want to import. The file for this example is called CustomFile.xlsx.

After you select a file with an extension that corresponds to one or more registered custom readers, an option to select the reader you want to use appears in the dialog. In this example, you can choose between the built-in Microsoft Excel file reader or the custom reader written for this example. By default, a custom reader is selected when one is available for the extension of the selected file.

You can choose which signals you want to import from the file. Use the check box next to NAME to select all or none of the signals. After making your selection, click Import. The data is imported to a new run called Imported_Data.

To import data programmatically, you can use the Simulink.sdi.createRun function. The Simulation Data Inspector has a built-in reader for Microsoft Excel files. You can specify which reader to use to import the data in the call to the Simulink.sdi.createRun function. When you do not specify the reader you want to use to import the data, the Simulation Data Inspector uses the first custom reader that supports the file extension.

Simulink.sdi.createRun("Custom File Run","file","CustomFile.xlsx","ExcelFirstColumnTimeReader");

After importing your data, you can use the Simulation Data Inspector to inspect and analyze the imported data on its own or alongside related simulation data.

The Simulation Data Inspector stores custom readers for the duration of a MATLAB session. To unregister a custom reader without starting a new session, use the unregisterFileReader method.

unregisterFileReader(ExcelFirstColumnTimeReader, [".xlsx" ".xls"])