Record, XY Graph

Log data to the workspace, to a file, or both

Since R2021a

• 

Libraries:
Simulink / Sinks

Description

You can use the Record block or the XY Graph block to record data to the workspace, to a file, or to both the workspace and a file. When you log data to a file, you can choose to log to a MAT file, an MLDATX file, or an Excel^® file. Signals connected to a Record block always log to the Simulation Data Inspector. If you decide that you need to save data after simulation, you can export data from the Record block to the workspace or to any supported file type.

You can also use the Record block to visualize connected signals. To view data for signals connected to the Record block, double-click the block. You have access to simulation controls, such as the Run button, while viewing data in the Record block.

By default, the Record block displays all connected signals on a sparklines plot. A sparkline is added for each connected signal. After sparklines fill the visible space, a scrollbar allows you to continue plotting signals.

Build Visualizations

The Record block supports most visualizations available in the Simulation Data Inspector. When a different visualization makes sense for your data, you can modify the plot layout and plot types using the Layouts option and the plot types selector, labeled Sparklines by default. Use the Layouts list to select a layout of subplots. To change the plot type of a subplot, select the subplot then select the desired plot type from the plot types selector.

For more information, see Log Data to the Workspace and a File Using the Record Block. For examples that show how to use each visualization type, see:

• Sparklines — View Many Signals Together Using Sparklines

• XY — Visualize Simulation Data on an XY Plot and Analyze Data Using the XY Plot

• Map — View and Replay Map Data

• Time plot and text editor — Create Plots Using the Simulation Data Inspector

The Record block does not support the array visualization available in the Simulation Data Inspector. The Record block supports logging multidimensional signal data, including variable-size signals, but does not support visualizing multidimensional data. To visualize the data for a multidimensional signal using the Record block, convert the signal with multidimensional sample values to a set of signals, called channels, that each have scalar sample values. For more information, see Analyze Multidimensional Signal Data.

XY Graph Block

The XY Graph block in the Simulink^® Sinks library is an alternative configuration of the Record block that visualizes two input signals on an XY plot. The first input port provides the x data for the XY plot, and the second input port provides the y data.

The XY Graph block supports logging and visualizing data for nonscalar inputs. However, the XY visualization does not support multidimensional data. When you connect nonscalar signals to the XY Graph block, you must manually configure which channels or elements of the nonscalar signal provide the x and y data for the XY plot.

Examples

Log Data to the Workspace and a File Using the Record Block

Use the Record block to log data to the workspace, to a file, or to both the workspace and a file.

Open Model

Plot a Circle Using the XY Graph Block

Plot x and y data for a circle using the XY Graph block.

Open Model

Load Data Using Playback Block

Load data from the workspace, a file, and the Simulation Data Inspector using the Playback block.

Open Live Script

Ports

Input

Port_1 — Signal to record

scalar | vector | matrix | array | bus

Signal to record. You can add ports to the Record block by dragging lines to the edge of the block or by using the Ports parameter.

The Record block supports logging variable-size signals but does not support visualizing variable-size signals.

The XY Graph block is an alternative configuration of the Record block that visualizes data connected to two input ports on an XY plot. The first input port provides the x data for the XY plot, and the second input port provides the y data.

Tips

• To log frame-based data, specify the Input Processing parameter for each port that receives a frame-based signal.

• When you connect a nonscalar signal to an input port of the XY Graph block, you must manually configure which channels or elements of the nonscalar signal provide the x and y data for the XY plot.

Data Types: single | double | half | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | Boolean | fixed point | enumerated | bus | image
Complex Number Support: Yes

Parameters

To modify Record block parameters, use the Property Inspector.

Main

Number of input ports — Number of input ports

1 (default) | integer in the range [1,100]

Number of input ports, specified as an integer between 1 and 100, inclusive.

The XY Graph block is an alternative configuration of the Record block that visualizes data connected to two input ports on an XY plot. The first input port provides the x data for the XY plot, and the second input port provides the y data.

Programmatic Use

Block Parameter: 'NumPorts'

Type: integer | character vector

Values: integer in the range [1,100]

Default: 1

Port — Port for which to specify input processing mode

1 (default) | integer

Use the Port and Input Processing parameters together to specify the input processing mode for a port. The input processing mode determines how the Record block interprets matrix data:

• Sample-based — Each element in the matrix is a separate channel.

• Frame-based — Each column in the matrix is a separate channel.

To use frame-based input processing, the signal must have a discrete sample rate, and the sample values must be nonscalar with fixed dimensions.

By default, each port processes the input signal as sample-based.

To change the input processing mode for a port:

1. Select the port number using the Port parameter.

2. Select the input processing mode using the Input Processing parameter.

Programmatic Use

Programmatically specify the input processing mode for each port by specifying the FrameSettings parameter as a row vector with as many elements as block ports. The element index corresponds to the port number on the block. Specify 1 to use frame-based input processing for the port and 0 to use sample-based processing.

Block Parameter: 'FrameSettings'

Type: logical array

Values: 1-by-n row vector, where n is equal to the number of ports

Default: 0

Input Processing — Input processing mode for selected port

Elements as channels (sample-based) (default) | Columns as channels (frame-based)

Use the Port and Input Processing parameters together to specify the input processing mode for a port. The input processing mode determines how the Record block interprets matrix data:

• Sample-based — Each element in the matrix is a separate channel.

• Frame-based — Each column in the matrix is a separate channel.

To use frame-based input processing, the signal must have a discrete sample rate, and the sample values must be nonscalar with fixed dimensions.

By default, each port processes the input signal as sample-based.

To change the input processing mode for a port:

1. Select the port number using the Port parameter.

2. Select the input processing mode using the Input Processing parameter.

Programmatic Use

Programmatically specify the input processing mode for each port by specifying the FrameSettings parameter as a row vector with as many elements as block ports. The element index corresponds to the port number on the block. Specify 1 to use frame-based input processing for the port and 0 to use sample-based processing.

Block Parameter: 'FrameSettings'

Type: logical array

Values: 1-by-n row vector, where n is equal to the number of ports

Default: 0

Record

Record to Workspace — Workspace logging option

off (default) | on

Workspace logging option. By default, the Record block logs data to the Simulation Data Inspector only. Select Record to Workspace to log data for signals connected to the Record block to the MATLAB^® workspace in a Simulink.SimulationData.Dataset object.

Use the Workspace Variable Name parameter to specify the name of the Dataset object that contains the logged Record block data.

Tips

• When you log data to the workspace, the way you access the data depends on your model configuration. By default, models provide all logged data in a single output variable as a Simulink.SimulationOutput object. You can access the Record block data using the get function or a dot with the Record block workspace variable name. When the Single simulation output option is disabled, logging data appears in separate variables in the workspace, and you access the Record block data directly.

• Logging intervals specified using the Logging intervals configuration parameter apply to data logged to the workspace using the Record block.

• You can use a single Record block to log data to the Simulation Data Inspector, to the workspace, and to a file.

Programmatic Use

Block Parameter: 'RecordToWorkspace'

Type: character vector | boolean | numeric

Values: 'on' | 'off' | true or 1 | false or 0

Default: 'off'

Workspace Variable Name — Name for workspace variable that contains logged block data

recordout (default) | character vector | string

Name for the workspace variable that contains the logged block data.

Dependencies

To enable this parameter, select the Record to Workspace parameter.

Programmatic Use

Block Parameter: 'VariableName'

Type: character vector | string

Default: 'recordout'

Record to File — Log to file option

off (default) | on

Log to file option. By default, the Record block logs data to the Simulation Data Inspector only. Select Record to File to log data for signals connected to the Record block to a file.

Tips

• Use the File Name parameter to specify a name for the file.

• Use the File Type parameter to specify whether to log data to an MLDATX file, a MAT file, or an Excel file.

• Use the File Location parameter to specify the path to the file.

• Logging intervals specified using the Logging intervals configuration parameter do not apply to data logged to a file using the Record block.

Programmatic Use

Block Parameter: 'RecordToFile'

Type: character vector | boolean | numeric

Values: 'on' | 'off' | true or 1 | false or 0

Default: 'off'

File Name — Name of file with logged data

recording.mldatx (default) | character vector | string

Name of the file that contains the logged data. The name does not need to include the file extension. If you do include the file extension in the name, ensure the name uses a valid extension for the specified File Type.

Tips

• If you do not change the name or location of the file you log to from one run to the next, the Record block overwrites prior data in the file.

• When you want to save the file in a location other than your working directory, use the File Location parameter to specify the path to the directory where you want to save the file.

Dependencies

To enable this parameter, select the Record to File parameter.

Programmatic Use

Use the FileName parameter to specify the File Name, File Type, and File Location parameters. Include the extension for the desired file type in the name you pass to set_param. When you want to save the file somewhere other than the current working directory, specify the path with the file name and extension.

Block Parameter: 'FileName'

Type: character vector | string

Default: 'recording.mldatx'

File Type — Type of file for logged data

*.mldatx (default) | *.mat | *.xslx

Use the File Type parameter to specify whether you want to log data to an MLDATX file, a MAT file, or an Excel file.

Tips

• When you log data to an Excel file, the data is formatted as described in Microsoft Excel Import, Export, and Logging Format.

• When you log data to an Excel file, you can specify whether to share time columns using the Time parameter and which signal attributes to log using the Attributes parameter.

Dependencies

To enable this parameter, select Record to File.

Programmatic Use

Use the FileName parameter to specify the File Name, File Type, and File Location parameters. Include the extension for the desired file type in the name you pass to set_param. When you want to save the file somewhere other than the current working directory, specify the path with the file name and extension.

Block Parameter: 'FileName'

Type: character vector | string

Default: 'recording.mldatx'

File Location — Path to file with logged data

working directory (default) | character vector | string

Use the File Location parameter to specify the location where you want to save the file with the logged data when you want to save the file somewhere other than the working directory. Ensure you have write permissions in the directory you specify.

Dependencies

To enable this parameter, select Record to File.

Programmatic Use

Use the FileName parameter to specify the File Name, File Type, and File Location parameters. Include the extension for the desired file type in the name you pass to set_param. When you want to save the file somewhere other than the current working directory, specify the path with the file name and extension.

Block Parameter: 'FileName'

Type: character vector | string

Default: 'recording.mldatx'

Time — Options for exporting time data to Excel file

Shared Time Columns (default) | Individual Time Columns

Use the Time parameter to specify how to log signal time data when you log the Record block data to an Excel file.

• Shared Time Columns — When time data is identical for multiple signals, the signals share a single time column in the logging file. The logging file may still include multiple time columns if the Record block logs data for signals with unique time data.

• Individual Time Columns — Each logged signal always has its own time column in the logging file.

Dependencies

To enable this parameter, select Record to File and specify File Type as *.xlsx.

Attributes — Signal attributes to export to Excel file

Data Type | Units | Port Index | Block Path | Interpolation

Select one or more signal attribute options to include in the logging file when you log data to an Excel file. Selected signal attributes appear in the signal column above the first data point according to the format described in Microsoft Excel Import, Export, and Logging Format.

Dependencies

To enable this parameter, select Record to File and specify File Type as *.xlsx.

Block Characteristics

Data Types	Boolean | bus | double | enumerated | fixed point | half | integer | single | string
Direct Feedthrough	no
Multidimensional Signals	yes
Variable-Size Signals	yes
Zero-Crossing Detection	no

Tips

• To open the Record block in a new window, right-click the block, then select Open In New Window.

• To open the Record block in a new tab, right-click the block, then select Open In New Tab.

Extended Capabilities

HDL Code Generation

Generate Verilog and VHDL code for FPGA and ASIC designs using HDL Coder™.

You can use this block to record data from a simulation when you use the block with subsystems that generate HDL code. The block cannot be included in the hardware implementation.

Version History

Introduced in R2021a