Main Content

simbio.diagram.getBlock

Get SimBiology diagram block properties

Since R2021a

Description

simbio.diagram.getBlock returns properties of diagram blocks shown in SimBiology Model Builder.

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.

example

SV = simbio.diagram.getBlock(sObj) returns the names and current values of the block properties of a SimBiology object or array of objects sObj as a structure or structure array SV.

example

SV = simbio.diagram.getBlock(speciesObj,exprObj) returns the names and current values of the block properties of the species object speciesObj that is connected to an expression (reaction, rate rule, or repeated assignment rule) object exprObj. You can 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.

example

QV = simbio.diagram.getBlock(sObj,propertyNames) returns the values of the specified block properties propertyNames of a SimBiology object sObj.

example

QV = simbio.diagram.getBlock(speciesObj,exprObj,propertyNames) returns the names and current values of the specified block properties propertyNames of the species object speciesObj that is connected to an expression object exprObj.

example

simbio.diagram.getBlock(___) displays the names and values of block properties. Use this syntax with any of the input arguments in the previous syntaxes.

Examples

collapse all

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

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 the SimBiology Model Builder app.

simBiologyModelBuilder('gprotein');

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

collapse all

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

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 NameDescription

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

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

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

collapse all

Values of queried properties, returned as a numeric vector, character vector, logical scalar, SimBiology object, or cell array.

If sObj is an array of objects, QV is an M-by-1 cell array of values where M equals to the length of sObj.

If you also specify an N-by-1 or 1-by-N cell array for propertyNames, QV is an M-by-N cell array of values, where N is the number of properties.

Structure of property names and values, returned as a structure or structure array. The field names are the object property names and values are the current values of the corresponding properties.

If sObj is an array of objects, SV is an array of structures. The function returns one structure per block. If sObj has multiple cloned blocks, SV contains a structure for each cloned block.

Version History

Introduced in R2021a