signalbuilder

(Not recommended) Create and access Signal Builder blocks

The signalbuilder function is not recommended. Use Signal Editor instead. For more information on why you should migrate your models, see Migrate from Signal Builder Block to Signal Editor Block.

Syntax

[time,data] = signalbuilder(block)

[time,data,signames] = signalbuilder(block)

[time,data,signames,groupnames] = signalbuilder(block)

block = signalbuilder(path,'create',time,data)

block = signalbuilder(path,'create',time,data,signames,groupnames)

block = signalbuilder(path,'create',time,data,signames,groupnames,vis)

block = signalbuilder(path,'create',time,data,signames,groupnames,vis,pos)

block = signalbuilder(path,'create',time,data,signames,groupnames,vis,pos,{openui openmodel})

blk = signalbuilder(blk,'appendgroup',time,data,signames,groupnames)

signalbuilder(block,'appendgroup',ds)

signalbuilder(block,'appendgroup',[ds1 ...dsN])

signalbuilder(block,'appendsignal',time,data,signames)

signalbuilder(block,'showsignal',signal,group)

signalbuilder(block,'hidesignal',signal, group)

[time,data] = signalbuilder(block,'get',signal,group)

ds = signalbuilder(block,'get',group)

[ds, …dsN] = signalbuilder(block,'get',group)

signalbuilder(block,'set',signal,group,time,data)

signalbuilder(block,'set',group,ds)

signalbuilder(block,'set',group,[ds1 ...dsN])

index = signalbuilder(block,'activegroup')

[index, activeGroupLabel] = signalbuilder(block,'activegroup')

signalbuilder(block,'activegroup',index)

signalbuilder(block,'annotategroup')

signalbuilder(block,'print',config,printArgs)

figh = signalbuilder(block,'print',config,'figure')

Description

[time,data] = signalbuilder(block) returns the time and data of the Signal Builder block, block.

[time,data,signames] = signalbuilder(block) returns signal names, signames, and time and data.

[time,data,signames,groupnames] = signalbuilder(block) returns the signal names, signames, and group names, groupnames, and time and data.

block = signalbuilder(path,'create',time,data) creates a new Signal Builder block at path with specified time and data. Signal and group names are default.

block = signalbuilder(path,'create',time,data,signames,groupnames) creates a new Signal Builder block at path with specified time and data, signal names, and group names.

block = signalbuilder(path,'create',time,data,signames,groupnames,vis) creates a new Signal Builder block and sets the visible signals in each group based on the values of the matrix vis.

block = signalbuilder(path,'create',time,data,signames,groupnames,vis,pos) creates a new Signal Builder block and sets the block position to pos.

If you create signals that are smaller than the display range or do not start from 0, the Signal Builder block extrapolates the undefined signal data. It does so by holding the final value.

block = signalbuilder(path,'create',time,data,signames,groupnames,vis,pos,{openui openmodel}) creates a new Signal Builder block and opens or invisibly loads the model and Signal Builder block window.

blk = signalbuilder(blk,'appendgroup',time,data,signames,groupnames) appends new groups (groupnames) containing signames to the Signal Builder block, block. The time and data arguments must have the same number of signals as the existing block.

signalbuilder(block,'appendgroup',ds) appends one dataset.

signalbuilder(block,'appendgroup',[ds1 ...dsN]) appends N datasets.

signalbuilder(block,'appendsignal',time,data,signames) appends new signals to all signal groups in the Signal Builder block, block. You can append either the same signals to all groups, or append different signals to different groups. Regardless of which signals you append, append the same number of signals to all the groups. Append signals to all the groups in the block; you cannot append signals to a subset of the groups. Correspondingly, provide time and data arguments for either one group (append the same information to all groups) or different time and data arguments for different groups.

signalbuilder(block,'showsignal',signal,group) makes signals that are hidden from the Signal Builder block visible. By default, signals in the current active group are visible when created.

signalbuilder(block,'hidesignal',signal, group) makes signals, signal, hidden from the Signal Builder block. By default, all signals are visible when created.

[time,data] = signalbuilder(block,'get',signal,group) gets the time and data values for the specified signal(s) and group(s).

ds = signalbuilder(block,'get',group) gets one or more datasets for one requested Signal Builder group. r gets N datasets for N requested Signal Builder groups.

[ds, …dsN] = signalbuilder(block,'get',group) gets N datasets for N requested Signal Builder groups.

signalbuilder(block,'set',signal,group,time,data) sets the time and data values for the specified signal and group. Use empty values of time and data to remove groups and signals. To remove a signal group, you must also remove all the signals in that group in the same command.

signalbuilder(block,'set',group,ds) sets one dataset for the requested Signal Builder group. Specifying an empty dataset deletes the groups specified in group.

signalbuilder(block,'set',group,[ds1 ...dsN]) sets N datasets for N requested groups.

index = signalbuilder(block,'activegroup') gets the index of the active group.

[index, activeGroupLabel] = signalbuilder(block,'activegroup') gets the label value of the active group.

signalbuilder(block,'activegroup',index) sets the active group to indexed active group.

signalbuilder(block,'annotategroup') controls the display of the current group name on the mask of the Signal Builder block. 'annotategroup' takes one of these values:

• 'on' — Shows the current group name

• 'off' — Hides the current group name

signalbuilder(block,'print',config,printArgs) prints the currently active signal group or the signal group that config specifies. Use the config to customize the printed appearance of a signal group.

figh = signalbuilder(block,'print',config,'figure') prints the currently active signal group or the signal group that config specifies to a new hidden figure handle, figh.

Examples

Create Signal Builder Block

Create a Signal Builder block in a new model editor window.

block = signalbuilder([], 'create', [0 5], {[2 2];[0 2]});

Get Signal Builder data from this block.

[time, data, signames, groupnames] = signalbuilder(block)

time =

  2×1 cell array

    {1×2 double}
    {1×2 double}

data =

  2×1 cell array

    {1×2 double}
    {1×2 double}

signames =

  1×2 cell array

    {'Signal 1'}    {'Signal 2'}

groupnames =

  1×1 cell array

    {'Group 1'}

The Signal Builder block contains two signals in one group. Alter the second signal in the group.

signalbuilder(block, 'set', 2, 1, [0 5], [2 0]);

To make this same change using the signal name and group name:

signalbuilder(block, 'set', 'Signal 2', 'Group 1', [0 5], [2 0])

Create Signal Builder Block and Delete Group

Create a Signal Builder block with two signal groups and delete one of the groups.

block = signalbuilder([], 'create', [0 2], {[0 1],[1 0]});

The Signal Builder block has two groups, each of which contains a signal.

To delete the second group, also delete its signal.

signalbuilder(block, 'set', 1, 2, [], [])

Create Signal Builder Block with Two Groups

Create a Signal Builder block with two groups, each of which contains three signals.

block = signalbuilder([], 'create', [0 1], ...
         {[0 0],[1 1];[1 0],[0 1];[1 1],[0 0]});

Create Signal Builder Block and Append Signal Groups

Create a Signal Builder block in a new model editor window.

block = signalbuilder([],'create',{[0 10],[0 20]},{[6 -6],...
[2 5]});

The Signal Builder block has two groups. Each group contains one signal.

Append a new signal group to the existing block.

block = signalbuilder(block,'appendgroup',[0 30],[10 -10]);

Append a new signal, sig3, to all groups.

signalbuilder(block,'appendsignal',[0 30],[0 10],'sig3');

Create Signal Builder Block and Delete Signal Group

Create a Signal Builder block in a new model editor window.

time = [0 1];
data = {[0 0],[1 1];[1 0],[0 1];[1 1],[0 0]};
block = signalbuilder([], 'create', time, data);

The Signal Builder block has two groups. Each group contains three signals.

Delete the second group. To delete a signal group, also delete all the signals in the group.

signalbuilder(block, 'set',[1,2,3],'Group 2',[]);

Create Signal Builder Block and Hide Signal

Create a Signal Builder block in a new model editor window and hide signal.

block = signalbuilder([], 'create', [0 5], {[2 2];[0 2]});

The Signal Builder block has one group that contains two signals.

Hide the signal, Signal 1.

signalbuilder(block,'hidesignal','Signal 1', 'Group 1')

Signal 1 is no longer visible in the Signal Builder block.

Make Signal 1 visible again.

signalbuilder(block,'showsignal','Signal 1', 'Group 1')

Create Two Signal Builder Blocks

Create two Signal Builder blocks in new model editor windows.

block = signalbuilder([], 'create', [0 5], {[2 2];[0 2]});
block1 = signalbuilder('untitled/Signal Builder1', 'create', [1 2], {[1 2];[0 10]});

Get a dataset for group 1 of block.

ds=signalbuilder(block,'get',1);

Get a dataset for group 1 of block1.

ds1=signalbuilder(block1,'get',1);

Set the dataset for group 1 of block to ds1.

signalbuilder(block,'set',1,ds1);

Append the original dataset for group 1 of block (ds) to block.

signalbuilder(block,'appendgroup',ds);

To create a third group in block, append ds1 to the end of the groups in block.

signalbuilder(block,'appendgroup',ds1);

Input Arguments

blk — Signal Builder block path or handle

[] (default) | block handle | block name

Signal Builder block handle or name. If you specify [] for this argument, the block has the path 'untitled/Signal Builder'.

Example: 'untitled/Signal Builder'

Example: block_handle = gcbh

Data Types: char | string

time — Time

row vector | column cell vector | row cell vector | cell matrix

Specify time format depending on the block configuration.

If data is a cell array and time is a vector, the time values are duplicated for each element of data. Each vector within time and data must be the same length and have at least two elements. If time is a cell array, all elements in a column must have the same initial and final value.

Configuration	Time Format
1 signal, 1 group	Row vector of break points.
>1 signal, 1 group	Column cell vector where each element corresponds to a separate signal and contains a row vector of points.
1 signal, >1 group	Row cell vector where each element corresponds to a separate group and contains a row vector of points.
>1 signal, >1 group	Cell matrix where each element (i, j) corresponds to signal i and group j.

Dependencies

If signalbuilder is called for an existing block, the time argument must have the same number of signals as the existing block.

Data Types: double

data — Data

row vector | column cell vector | row cell vector | cell matrix

Specify data format depending on the block configuration.

If data is a cell array and time is a vector, the time values are duplicated for each element of data. Each vector within time and data must be the same length and have at least two elements. If time is a cell array, all elements in a column must have the same initial and final value.

Configuration	Time/Data Format
1 signal, 1 group	Row vector of break points.
>1 signal, 1 group	Column cell vector where each element corresponds to a separate signal and contains a row vector of points.
1 signal, >1 group	Row cell vector where each element corresponds to a separate group and contains a row vector of points.
>1 signal, >1 group	Cell matrix where each element (i, j) corresponds to signal i and group j.

Data Types: double

config — Configuration structure name

structure name

Configuration structure containing instructions to display signal group information on the block mask. Set up the structure with one or more of these fields before you print.

Field	Description	Example Value
groupIndex	Scalar specifying index of signal group to print	2
timeRange	Two-element vector specifying the time range to print (must not exceed the block's time range)	[3 6]
visibleSignals	Vector specifying index of signals to print	[1 2]
yLimits	Cell array specifying limits for each signal's y-axis	{[-1 1],  [0 1]}
extent	Two-element vector of the form: [width, height] specifying the dimensions (in pixels) of the area in which to print the signals	[500 300]
showTitle	Logical value specifying whether to print a title: true (1) prints the title	false

For example, to print just group 2 using a configuration structure, configstruct, set up the structure as follows. You do not need to specify any other fields.

configstruct.groupIndex=1

Example: configstruct

Data Types: char | string

'create' — Create directive

'create'

Create new Signal Builder block.

Data Types: char | string

signames — Signal names

Signal 1 (default) | ' ' | {} | character vector | cell array of character vectors

Signal names, specified as ' ', {}, a character vector, or cell array of character vectors.

If you specify a value of ' ' or {}, the function uses existing signal names for the new groups.

Data Types: char | string

groupnames — Signal group names

Group 1 (default) | character vector | cell array of character vectors

Group names, specified as a character vector or cell array of character vectors.

Data Types: char | string

path — Block path

[] (default) | full block path

Block path, specified as full block path. To create a Signal Builder block in a new model, untitled, with the name Signal Builder, specify [].

Data Types: char | string

vis — Signal visibility

matrix

Signal visibility, specified as a matrix. The Signal Builder block displays signals in each group based on the values of the matrix vis. This matrix must be the same size as the cell array, data. You cannot create Signal Builder blocks in which all signals are invisible. For example, if you set the vis parameter for all signals to 0, the first signal is still visible.

Data Types: double

pos — Block position in model

[0 0] (default) | [x y right bottom]

Block position in model, specified as [x y right bottom].

Data Types: double

openui — Open Signal Builder block dialog box

0 (default) | 1

Open Signal Builder block dialog upon creation by signalbuilder function, specified as 0 or 1.

Data Types: double

openmodel — Open model

1 (default) | 0

Open model upon creation by signalbuilder function, specified as one of:

• 0 — Load the model but do not open it.

• 1 — Open the model.

Data Types: double

'appendsignal' — Append signals

'appendsignal' (default)

Append new signals to all signal groups in the Signal Builder block. You can append either the same signals to all groups, or append different signals to different groups. Regardless of which signals you append, append the same number of signals to all the groups. Append signals to all the groups in the block. You cannot append signals to a subset of the groups.

Data Types: char | string

'appendgroup' — Append new signal group

'appendgroup'

Append new signal groups whose number of time and signal elements are the same as existing signal groups in the Signal Builder block.

For the showsignal and hidesignal methods, if you do not specify a value for the group argument, signalbuilder applies the operation to all the signals and groups.

Data Types: char

'set' — Set values

'set'

Set values based on input arguments.

• time and data — Return time and data values.

• ds — Return Simulink.SimulationData.Dataset object(s).

Data Types: char

'get' — Get values

'get'

Get values based on output arguments.

• [time, data] — Return time and data values.

• [ds, ...dsN] — Return Simulink.SimulationData.Dataset object(s).

Data Types: char | string

'showsignal' — Make signal visible

'showsignal'

Make one or more signals visible in a signal group. If no group is specified, all the signals and groups are visible.

Data Types: char | string

'hidesignal' — Hide signal

'hidesignal'

Hide one or more signals in a signal group. If no group is specified, all the signals and groups are hidden.

Data Types: char

ds — Dataset

timeseries data elements | 1-D scalar data value at each time | nonempty data and/or time | empty values

Dataset of timeseries elements, specified as a Simulink.SimulationData.Dataset object.

Data Types: double

ds1 ...dsN — Multiple datasets

vectors of timeseries data elements | vectors of 1-D scalar data value at each time | nonempty data and/or time

One or more datasets of timeseries elements, specified as Simulink.SimulationData.Dataset objects.

Example: [ds1 ds2 ds3]

Data Types: double

signal — Signal

signal name | scalar index | array of signal indices

Signal, specified as a signal name, scalar index, or array of signal indices.

Data Types: char | double | string

group — Signal group

group name | scalar index | array of group indices

Signal group, specified as a group name, scalar index, or array of group indices.

Data Types: char | double | string

index — Group index

active group index

Active signal group index.

Data Types: double

'activegroup' — Get active group

'activegroup'

Get currently active signal group.

Data Types: char | string

'annotategroup' — Display active signal group name

'on' (default) | 'off'

Display active signal group name on Signal Builder block mask:

• 'on' — Display active signal group names on block mask.

• 'off' — Do not display active signal group names on block mask.

Data Types: char | string

'print' — Print signal group

'print'

Print signal group.

Data Types: char | string

printArgs — Configure print options

[] | print function arguments

Configure print options (see print).

To print the entire contents of the Signal Builder block, specify [].

Data Types: char | string

'figure' — Figure

'figure'

Create a figure containing contents of Signal Builder block.

Data Types: char | double | string

Output Arguments

time — Time

row vector | column cell vector | row cell vector | cell matrix

Time for the Signal Builder block, returned as row vector, column cell vector, row cell vector, or cell matrix. For the Signal Builder block, time is the x-coordinate.

time returns in different formats depending on the block configuration.

Configuration	Time Format
1 signal, 1 group	Row vector of break points.
>1 signal, 1 group	Column cell vector where each element corresponds to a separate signal and contains a row vector of points.
1 signal, >1 group	Row cell vector where each element corresponds to a separate group and contains a row vector of points.
>1 signal, >1 group	Cell matrix where each element (i, j) corresponds to signal i and group j.

data — Data

row vector | column cell vector | row cell vector | cell matrix

Data of the Signal Builder block, returned as a one-dimensional array. For the Signal Builder block, time is the y-coordinate.

data takes different formats depending on the block configuration.

Configuration	Data Format
1 signal, 1 group	Row vector of break points.
>1 signal, 1 group	Column cell vector where each element corresponds to a separate signal and contains a row vector of points.
1 signal, >1 group	Row cell vector where each element corresponds to a separate group and contains a row vector of points.
>1 signal, >1 group	Cell matrix where each element (i, j) corresponds to signal i and group j.

Datasets must have the same number of elements as the signals in a signal group. Dataset format limitations for the set, append, and appendgroup functions include:

• Elements must be MATLAB^® timeseries data.

  Timeseries data and/or time cannot be empty.

• Timeseries data must be of type double.

• Timeseries data must be 1-D (scalar value at each time).

signames — Signal names

character vector | cell array of character vectors

Signal names, returned as a character vector or cell array of character vectors.

block — Signal Builder block path or handle

block handle

Signal Builder block path or handle, returned by block creation or append commands.

ds — Dataset

timeseries data elements | 1-D scalar data value at each time | nonempty data and/or time

Dataset of timeseries elements, returned as a Simulink.SimulationData.Dataset object.

ds, …dsN — Multiple datasets

vectors of timeseries data elements | vectors of 1-D scalar data value at each time | nonempty data and/or time

One or more datasets of timeseries elements, returned as Simulink.SimulationData.Dataset objects.

index — Group index

active group index

Active signal group index.

activeGroupLabel — Active group label

index

Active group label, returned as an index.

figh — Figure handle

handle

Figure handle, returned when contents of Signal Builder block are printed to the hidden figure.

More About

Interpolating Missing Data Values

When specifying a periodic signal such as a Sine Wave, the signalbuilder function uses linear Lagrangian interpolation to compute data values for time steps that occur between time steps for which the signalbuilder function supplies data. When specifying periodic signals, specify them as a time vector that is defined as multiples of sample time, for example:

t = 0.2*[0:49]';

Version History

Introduced in R2007a

R2019a: signalbuilder Function is not Recommended

The signalbuilder function is not recommended. Use the signalEditor function instead.