Main Content

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.

Description

example

[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.

example

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.

example

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.

example

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.

example

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.

example

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.

example

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.

example

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

collapse all

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 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 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 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 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 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 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

collapse all

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

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

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

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.

FieldDescriptionExample 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 new Signal Builder block.

Data Types: char | string

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

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

Data Types: char | string

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

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

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

Data Types: double

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

Data Types: double

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

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

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 values based on input arguments.

  • time and data — Return time and data values.

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

Data Types: char

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

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

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

Data Types: char

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

Data Types: double

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

Example: [ds1 ds2 ds3]

Data Types: double

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

Data Types: char | double | string

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

Data Types: char | double | string

Active signal group index.

Data Types: double

Get currently active signal group.

Data Types: char | string

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 signal group.

Data Types: char | string

Configure print options (see print).

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

Data Types: char | string

Create a figure containing contents of Signal Builder block.

Data Types: char | double | string

Output Arguments

collapse all

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 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).

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

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

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

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

Active signal group index.

Active group label, returned as an index.

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

More About

collapse all

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

collapse all

R2019a: signalbuilder Function is not Recommended

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