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.

example

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

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.

example

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.

example

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.

example

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.

example

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

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.

example

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

collapse all

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

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

collapse all

`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

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.

signalbuilder

Syntax

Description

Examples

Create Signal Builder Block

Create Signal Builder Block and Delete Group

Create Signal Builder Block with Two Groups

Create Signal Builder Block and Append Signal Groups

Create Signal Builder Block and Delete Signal Group

Create Signal Builder Block and Hide Signal

Create Two Signal Builder Blocks

Input Arguments

blk — Signal Builder block path or handle [] (default) | block handle | block name

time — Time row vector | column cell vector | row cell vector | cell matrix

Dependencies

data — Data row vector | column cell vector | row cell vector | cell matrix

config — Configuration structure name structure name

'create' — Create directive 'create'

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

groupnames — Signal group names Group 1 (default) | character vector | cell array of character vectors

path — Block path [] (default) | full block path

vis — Signal visibility matrix

pos — Block position in model [0 0] (default) | [x y right bottom]

openui — Open Signal Builder block dialog box 0 (default) | 1

openmodel — Open model 1 (default) | 0

'appendsignal' — Append signals 'appendsignal' (default)

'appendgroup' — Append new signal group 'appendgroup'

'set' — Set values 'set'

'get' — Get values 'get'

'showsignal' — Make signal visible 'showsignal'

'hidesignal' — Hide signal 'hidesignal'

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

ds1 ...dsN — Multiple datasets vectors of timeseries data elements | vectors of 1-D scalar data value at each time | nonempty data and/or time

signal — Signal signal name | scalar index | array of signal indices

group — Signal group group name | scalar index | array of group indices

index — Group index active group index

'activegroup' — Get active group 'activegroup'

'annotategroup' — Display active signal group name 'on' (default) | 'off'

'print' — Print signal group 'print'

printArgs — Configure print options [] | print function arguments

'figure' — Figure 'figure'

Output Arguments

time — Time row vector | column cell vector | row cell vector | cell matrix

data — Data row vector | column cell vector | row cell vector | cell matrix

signames — Signal names character vector | cell array of character vectors

block — Signal Builder block path or handle block handle

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

ds, …dsN — Multiple datasets vectors of timeseries data elements | vectors of 1-D scalar data value at each time | nonempty data and/or time

index — Group index active group index

activeGroupLabel — Active group label index

figh — Figure handle handle

More About

Interpolating Missing Data Values

Version History

R2019a: signalbuilder Function is not Recommended

See Also

Tools

Blocks

Classes

Functions

Topics

`blk` — Signal Builder block path or handle
[] (default) | block handle | block name

`time` — Time
row vector | column cell vector | row cell vector | cell matrix

`data` — Data
row vector | column cell vector | row cell vector | cell matrix

`config` — Configuration structure name
structure name

`'create'` — Create directive
'create'

`signames` — Signal names
`Signal 1` (default) | `' '` | `{}` | character vector | cell array of character vectors

`groupnames` — Signal group names
`Group 1` (default) | character vector | cell array of character vectors

`path` — Block path
`[]` (default) | full block path

`vis` — Signal visibility
matrix

`pos` — Block position in model
`[0 0]` (default) | [x y right bottom]

`openui` — Open Signal Builder block dialog box
`0` (default) | `1`

`openmodel` — Open model
`1` (default) | `0`

`'appendsignal'` — Append signals
`'appendsignal'` (default)

`'appendgroup'` — Append new signal group
`'appendgroup'`

`'set'` — Set values
`'set'`

`'get'` — Get values
`'get'`

`'showsignal'` — Make signal visible
`'showsignal'`

`'hidesignal'` — Hide signal
`'hidesignal'`

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

`ds1 ...dsN` — Multiple datasets
vectors of `timeseries` data elements | vectors of 1-D scalar data value at each time | nonempty data and/or time

`signal` — Signal
signal name | scalar index | array of signal indices

`group` — Signal group
group name | scalar index | array of group indices

`index` — Group index
active group index

`'activegroup'` — Get active group
`'activegroup'`

`'annotategroup'` — Display active signal group name
`'on'` (default) | `'off'`

`'print'` — Print signal group
`'print'`

`printArgs` — Configure print options
`[]` | `print` function arguments

`'figure'` — Figure
`'figure'`

`time` — Time
row vector | column cell vector | row cell vector | cell matrix

`data` — Data
row vector | column cell vector | row cell vector | cell matrix

`signames` — Signal names
character vector | cell array of character vectors

`block` — Signal Builder block path or handle
block handle

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

`ds, …dsN` — Multiple datasets
vectors of timeseries data elements | vectors of 1-D scalar data value at each time | nonempty data and/or time

`index` — Group index
active group index

`activeGroupLabel` — Active group label
index

`figh` — Figure handle
handle

R2019a: `signalbuilder` Function is not Recommended