Microsoft Excel Import, Export, and Logging Format - MATLAB & Simulink (original) (raw)

Using the Simulation Data Inspector or Simulink® Test™, you can import data from a Microsoft® Excel® file or export data to a Microsoft Excel file. You can also load data from an Excel spreadsheet into your model using the Playback block, or log data to an Excel file using the Record block. The Simulation Data Inspector,Simulink Test, the Playback block, and the Record block all use the same file format, so you can use the same Microsoft Excel file with multiple applications.

Tip

When the format of the data in your Excel file does not match the specification in this topic, you can write your own file reader to import the data using the io.reader class.

Basic File Format

In the simplest format, the first row in the Excel file is a header that lists the names of the signals in the file. The first column is time. The name for the time column must be time, and the time values must increase monotonically. The rows below the signal names list the signal values that correspond to each time step.

Excel does not support Inf or NaN values, which affects both import and export operations. When you import data from an Excel file, the Simulation Data Inspector:

• Supports all built-in data types
• Does not support importing data with empty cells or number errors, such as those resulting from Inf or NaN values, in the time column
• Treats empty cells and cells with number errors in a signal value column as missing data

When you export data with Inf or NaN values from the Simulation Data Inspector to Excel:

• The Simulation Data Inspector removes NaN values, leaving those cells empty in the exported spreadsheet.
• Due to the limitation that Excel does not natively support Inf as a numeric value, Excel converts Inf data to either an error code or the numerical value 65535 depending on the version of the Excel software.

Multiple Time Vectors

When your data includes signals with different time vectors, the file can include more than one time vector. Every time column must be named time. Time columns specify the sample times for signals to the right, up to the next time vector. For example, the first time column defines the time for signal1 andsignal2, and the second time column defines the time steps forsignal3.

Signal columns must have the same number of data points as the associated time vector.

Signal Metadata

The file can include metadata for signals such as data type, units, and interpolation method. The metadata is used to determine how to plot the data, how to apply unit and data conversions, and how to compute comparison results. For more information about how metadata is used in comparisons, see How the Simulation Data Inspector Compares Data.

Metadata for each signal is listed in rows between the signal names and the signal data. You can specify any combination of metadata for each signal. Leave a blank cell for signals with less specified metadata.

Label each piece of metadata according to this table. The table also indicates which tools and operations support each piece of metadata. When an imported file does not specify signal metadata, double data type, zoh (zero order hold) interpolation, and union synchronization are used.

User-Defined Data Types

In addition to built-in data types, you can use other labels in place of theDataType: label to specify fixed-point, enumerated, alias, and bus data types.

When you specify the type using the name of a Simulink.Bus object and the object is not in the MATLAB workspace, the data still imports from the file. However, individual signals in the bus use data types described in the file rather than data types defined in the Simulink.Bus object.

Complex, Multidimensional, and Bus Signals

You can import and export complex, multidimensional, and bus signals using an Excel file. The signal name for a column of data indicates whether that data is part of a complex, multidimensional, or bus signal. Excel file import and export do not support arrays of buses.

Note

When you export data from a nonvirtual bus with variable-size signals to an Excel file, the variable-size signal data is expanded to individual channels, and the hierarchical nature of the data is lost. Data imported from this file is returned as a flat list.

Multidimensional signal names include index information in parentheses. For example, the signal name for a column might be signal1(2,3). When you import data from a file that includes multidimensional signal data, elements in the data not included in the file take zero sample values with the same data type and complexity as the other elements.

Complex signal data is always in real-imaginary format. Signal names for columns containing complex signal data include (real) and(imag) to indicate which data each column contains. When you import data from a file that includes imaginary signal data without specifying values for the real component of that signal, the signal values for the real component default to zero.

Multidimensional signals can contain complex data. The signal name includes the indication for the index within the multidimensional signal and the real or imaginary tag. For example, signal1(1,3)(real).

Dots in signal names specify the hierarchy for busses. For example:

• bus.y.a
• bus.y.b
• bus.x

Tip

When the name of your signal includes characters that could make it appear as though it were part of a matrix, complex signal, or bus, use theName metadata option to specify the name you want the imported signal to use in the Playback block, Simulation Data Inspector, and Simulink Test.

Function-Call Signals

Signal data specified in columns before the first time column is imported as one or more function-call signals. The data in the column specifies the times at which the function-call signal was enabled. The imported signals have a value of1 for the times specified in the column. The time values for function-call signals must be double, scalar, and real, and must increase monotonically.

When you export data from the Simulation Data Inspector, function-call signals are formatted the same as other signals, with a time column and a column for signal values.

Simulation Parameters

You can import data for parameter values used in simulation. In thePlayback block and the Simulation Data Inspector, the parameter values are shown as signals. Simulink Test uses imported parameter values to specify values for those parameters in the tests it runs based on imported data.

Parameter data is specified using two or three columns. The first column specifies the parameter names, with the cell in the header row for that column labeledParameter:. The second column specifies the value used for each parameter, with the cell in the header row labeled Value:. Parameter data may also include a third column that contains the block path associated with each parameter, with the cell in the header row labeled BlockPath:. Specify names, values, and block paths for parameters starting in the first row that contains signal data, below the rows used to specify signal metadata. For example, this file specifies values for two parameters, X and Y.

For more information, see Create External Data Files to Use in Test Cases (Simulink Test).

Multiple Runs

You can include data for multiple runs in a single file. Within a sheet, you can divide data into runs by labeling data with a simulation number and a source type, such as Input or Output. Specify the simulation number and source type as additional signal metadata, using the labelSimulation: for the simulation number and the labelSource: for the source type. The Playback block and the Simulation Data Inspector use the simulation number and source type only to determine which signals belong in each run. Simulink Test uses the information to define inputs, parameters, and acceptance criteria for tests to run based on imported data.

You do not need to specify the simulation number and output type for every signal. Signals to the right of a signal with a simulation number and source use the same simulation number and source until the next signal with a different source or simulation number. For example, this file defines data for two simulations and imports into four runs in the Simulation Data Inspector:

• Run 1 contains signal1 andsignal2.
• Run 2 contains signal3,X, and Y.
• Run 3 contains signal4.
• Run 4 contains signal5.

You can also use sheets within the Microsoft Excel file to divide the data into runs and tests. When you do not specify simulation number and source information, the data on each sheet is imported into a separate run in the Simulation Data Inspector or the Playback block. When you export multiple runs from the Simulation Data Inspector, the data for each run is saved on a separate sheet. When you import a Microsoft Excel file that contains data on multiple sheets into Simulink Test, an iteration is created for each sheet.

See Also

Simulink.sdi.createRun | Simulink.sdi.exportRun

Topics

• View Simulation Data in Simulation Data Inspector
• Import Data from a CSV File into the Simulation Data Inspector
• Import Data Using Custom File Reader