simbio.diagram.setBlock

Set SimBiology diagram block properties

Since R2021a

Syntax

simbio.diagram.setBlock(sObj,propertyNames,propertyValues)

simbio.diagram.setBlock(sObj,S)

simbio.diagram.setBlock(sObj,Name,Value)

simbio.diagram.setBlock(sObj)

outStruct = simbio.diagram.setBlock(sObj)

CV = simbio.diagram.setBlock(sObj,propertyName)

simbio.diagram.setBlock(speciesObj,exprObj,___)

simbio.diagram.setBlock(speciesObj,exprObj)

Description

simbio.diagram.setBlock sets properties of diagram blocks shown in SimBiology Model Builder. The changes are instantly reflected in the app.

Before you run the function at the command line:

1. Open the corresponding SimBiology^® model in the SimBiology Model Builder app.

2. Export the model from the app to MATLAB^® workspace by selecting Export > Export Model to MATLAB Workspace on the Home tab of the app.

You can query and configure only the properties of the objects shown in the Diagram tab of the app. The objects shown in the diagram are compartments, species, reactions, rate rules, repeated assignment rules, and parameters that are on the left-hand side of a rate rule, a repeated assignment rule, or an event function.

simbio.diagram.setBlock(sObj,propertyNames,propertyValues) sets the values of specified block properties of a SimBiology object or array of objects sObj.

simbio.diagram.setBlock(sObj,S) sets the property values of sObj using a structure S. The field names of S are the property names and the field values are the property values.

simbio.diagram.setBlock(sObj,Name,Value) sets the property values specified by one or more name-value arguments.

Name is the property name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

You can specify a mixture of name-value arguments, structures, and cell array pairs of property names and values in the same function call.

simbio.diagram.setBlock(sObj) displays the names and possible values of configurable block properties of a SimBiology object sObj. sObj must be scalar.

outStruct = simbio.diagram.setBlock(sObj) returns a structure outStruct containing the names and possible values of configurable block properties of a SimBiology object sObj. sObj must be scalar.

CV = simbio.diagram.setBlock(sObj,propertyName) returns a cell array of possible values CV for the block property propertyName. sObj must be scalar.

simbio.diagram.setBlock(speciesObj,exprObj,___) sets the values of the specified block properties of a species object speciesObj that is connected to an expression object exprObj. You can specify any combination of Name,Value pairs, structures, and cell array pairs of property names and values as shown in previous syntaxes.

Use this syntax to configure the Position, Pin, and Visible properties of a specific cloned block when you have multiple clones of the same species. Clones have the same values for all the other properties.

simbio.diagram.setBlock(speciesObj,exprObj) displays the names of configurable block properties of a species object speciesObj that is connected to an expression (reaction, rate rule, or repeated assignment rule) object exprObj.

Use this syntax to check the properties of a specific cloned block when you have multiple clones of the same species.

Examples

Configure SimBiology Diagram Block Properties

You can programmatically adjust the appearances and locations of diagram blocks of a SimBiology model.

Enter the following command to open the lotka model in SimBiology Model Builder.

simBiologyModelBuilder('lotka.sbproj');

The app opens and shows the model in the Diagram tab.

On the Home tab of the app, select Export > Export Model to MATLAB Workspace. In the SimBiology Model Export dialog, click OK to export the model with the variable name m1.

Go to the MATLAB command line and confirm that the model m1 is in the workspace. Get a list of species of the model.

m1.Species

ans = 

   SimBiology Species Array

   Index:    Compartment:    Name:    Value:    Units:
   1         unnamed         x        1               
   2         unnamed         y1       900             
   3         unnamed         y2       900             
   4         unnamed         z        0   

Get the current block shape of species x.

x = m1.Species(1);
v = simbio.diagram.getBlock(x,'Shape')

v =

    'rounded rectangle'

Get a list of all possible shapes for the species block.

simbio.diagram.setBlock(x,'Shape')

ans =

  8×1 cell array

    {'rounded rectangle'}
    {'rectangle'        }
    {'oval'             }
    {'triangle'         }
    {'hexagon'          }
    {'chevron'          }
    {'parallelogram'    }
    {'diamond'          }

Set the shape of the species block to an oval.

simbio.diagram.setBlock(x,'Shape','oval')

Get the current position of the block. The first two numbers represent the x and y coordinates with respect to the top left corner (x = 0, y = 0) of the diagram. The last two numbers represent the width and height of the block.

simbio.diagram.getBlock(x,'Position')

ans =

   223   137    30    15

Set the position to a new location.

simbio.diagram.setBlock(x,'Position',[260 130 30 15])

You can also configure multiple properties.

simbio.diagram.setBlock(x,'FaceColor','yellow','FontSize',20,'TextLocation','center')

Configure Cloned Species Block Properties

When you have multiple cloned blocks for the same species in a SimBiology diagram, you can programmatically adjust the position and visibility of a specific clone by specifying the expression block that the cloned species is connected to. In other words, you can change the Position, Pin, and Visible properties specific to an individual clone. All the other properties have the same values across all clones of the same species.

Open the gprotein model in SimBiology Model Builder.

simBiologyModelBuilder('gprotein.sbproj');

The app opens and shows the model in the Diagram tab.

On the Home tab of the app, select Export > Export Model to MATLAB Workspace. In the SimBiology Model Export dialog, click OK to export the model with the variable name m1.

Go to the MATLAB command line and confirm that the model m1 is in the workspace. Get a list of species of the model.

m1.Species

ans = 

   SimBiology Species Array

   Index:    Compartment:    Name:    Value:       Units:
   1         unnamed         G        7000               
   2         unnamed         Gd       3000               
   3         unnamed         Ga       0                  
   4         unnamed         RL       0                  
   5         unnamed         L        6.022e+17          
   6         unnamed         R        10000              
   7         unnamed         Gbg      3000 

The species block Gbg is cloned and connected to two reactions: G protein activation and G protein complex formation. Get the current position of the cloned block connected to the second reaction.

Gbg = m1.Species(7);
r2 = m1.Reaction(2);
simbio.diagram.getBlock(Gbg,r2,'Position')

ans =

   393   307    30    15

Unpin the cloned block and move it to another position.

simbio.diagram.setBlock(Gbg,r2,'Pin',false,'Position',[391 340 30 15])

Input Arguments

sObj — SimBiology object

Compartment object | Species object | Reaction object | Rule object | Parameter object | array of objects

SimBiology object, specified as a Compartment, Species, Reaction, Rule, or Parameter object, or as an array of objects.

propertyName — Property name

character vector | string

Property name of the block, specified as a character vector or string. You can specify only one property name.

Example: 'FontName'

Data Types: char | string

propertyNames — Names of block properties

character vector | string | string vector | cell array of character vectors

Names of block properties, specified as a character vector, string, string vector, or cell array of character vectors. You can specify multiple property names as an 1-by-N or N-by-1 cell array of names.

Available block properties follow.

Property Name	Description
Connections	Read-only property that lists the objects connected to the input block
Cloned	Read-only flag indicating if more than one block exists for the input object. You can clone only species blocks.
EdgeColor	Block edge color, specified as one of these values: RGB triplet, such as [1 1 0] Character vector or string representing the color name, such as 'y' or 'yellow'
ExpressionLines	Flag to show lines from the expression block to other model components referenced by the expression, specified as 'show' or 'hide'. You can set this property for reactions or rules.
FaceColor	Block face color, specified as one of these values: RGB triplet, such as [1 1 0] Character vector or string representing the color name, such as 'y' or 'yellow'
FontName	Block text font, specified as a character vector or string. Valid options are: 'Arial' 'Arial Black' 'Arial Narrow' 'Comic Sans MS' 'Courier' 'Courier New' 'Georgia' 'Helvetica' 'Impact' 'Times New Roman' 'Trebuchet MS' 'Verdana'
FontSize	Block text font size, specified as a positive scalar
FontWeight	Block text font thickness, specified as 'plain', 'bold', 'italic', or 'bold italic'
Object	Read-only property that lists the corresponding SimBiology object of the block
Pin	Flag to indicate if a block can be moved or not. Set the property to false to allow moving the block in the diagram.
Position	Position and size of the block, specified as a four-element vector [x,y,width,height]. The position of the upper-left corner of the diagram is equal to x = 0 and y = 0. SimBiology configures all block positions relative to that corner. You can configure block positions to negative positions.
Rotate	Block rotation, specified as a scalar between 0 and 360. You cannot rotate compartment blocks.
Shape	Block shape, specified as a character vector or string. Valid options are: 'rounded rectangle' 'rectangle' 'oval' 'triangle' 'hexagon' 'chevron' 'parallelogram' 'diamond' Compartment blocks must be 'rounded rectangle' or 'rectangle'.
TextColor	Block text color, specified as one of these values: RGB triplet, such as [1 1 0] Character vector or string representing the color name, such as 'y' or 'yellow'
TextLocation	Block text location relative to the block, specified as one of the following: 'top', 'left', 'bottom', 'right', 'center', or 'none'
Visible	Flag to indicate if the block is visible in the diagram. Set the property to false to hide the block. Warning Starting in R2022a, this property for all compartment blocks is always set to 1 and you can no longer hide compartments.

Example: 'Position'

Data Types: double | char | string | cell

propertyValues — Property values

character vector | string | string vector | numeric vector | logical scalar | cell array

Property values to set, specified as a character vector, string, string vector, numeric vector, logical scalar, or cell array.

If propertyNames is a cell array of 1-by-N or N-by-1, propertyValues can be a cell array of the same length containing the corresponding values for each property in propertyNames.

If sObj is a vector and propertyNames contains a single property name and propertyValues contains a single value, the function updates the specified property of all objects to the specified value.

If sObj is a vector containing M objects, and propertyNames is a cell array of 1-by-N or N-by-1, propertyValues can be a cell array of M-by-N such that each object is updated with a different set of values for the list of properties in propertyNames.

Example: [140 210 30 15]

Data Types: double | logical | char | string | cell

S — Property names and corresponding values

structure | structure array

Property names and corresponding values to set, specified as a structure or structure array. Each field name corresponds to a property name, and the field value is the property value.

If sObj is a vector and S is a scalar structure, the function configures all objects to have the same property values.

You can specify a different set of property values for each object. To do so, specify S as an array of the same length as sObj.

Data Types: structure

speciesObj — Species object

Species object

Species object, specified as a SimBiology Species object. speciesObj must be scalar.

exprObj — Expression object

Reaction object | Rule object

Expression object, specified as a Reaction or Rule object. The rule object can be a rate rule or repeated assignment rule. exprObj must be a scalar.

Output Arguments

CV — Possible property values

cell array

Possible property values, returned as a cell array of values. CV is an empty cell array if the property does not have a finite set of possible values.

outStruct — Configurable property names and their possible values

structure

Configurable property names and their possible values, returned as a structure. Each field name is a property name and the value is a cell array of possible values or an empty cell array if the property does not have a finite set of possible values.

Version History

Introduced in R2021a