Mathworks SIMBIOLOGY 3 Installation Guide

Download

SimBiology

Getting Started Guide

How to Contact The MathWorks

www.mathworks. comp.soft-sys.matlab Newsgroup www.mathworks.com/contact_TS.html Technical Support

suggest@mathworks.com Product enhancement suggestions

bugs@mathwo doc@mathworks.com Documentation error reports service@mathworks.com Order status, license renewals, passcodes

info@mathwo

com

rks.com

Web

Bug reports

Sales, prici

ng, and general information

508-647-7000 (Phone)

508-647-7001 (Fax)

The MathWorks, Inc. 3 Apple Hill Drive Natick, MA 01760-2098

For contact information about worldwide offices, see the MathWorks Web site.

SimBiology

The software described in this document is furnished under a license agreement. The software may be used or copied only under the terms of the license agreement. No part of this manual may be photocopied or reproduced in any form without prior written consent from The MathW orks, Inc.

FEDERAL ACQUISITION: This provision applies to all acquisitions of the Program and Documentation by, for, or through the federal government of the United States. By accepting delivery of the Program or Documentation, the government hereby agrees that this software or documentation qualifies as commercial computer software or commercial computer software documentation as such terms are used or defined in FAR 12.212, DFARS Part 227.72, and DFARS 252.227-7014. Accordingly, the terms and conditions of this Agreement and only those rights specified in this Agreement, shall pertain to and govern theuse,modification,reproduction,release,performance,display,anddisclosureoftheProgramand Documentation by the federal government (or other entity acquiring for or through the federal government) and shall supersede any conflicting contractual terms or conditions. If this License fails to meet the government’s needs or is inconsistent in any respect with federal procurement law, the government agrees to return the Program and Docu mentation, unused, to The MathWorks, Inc.

Trademarks

MATLAB and Simulink are registered trademarks of The MathWorks, Inc. See

www.mathworks.com/trademarks for a list of additional trademarks. Other product or brand

names may be trademarks or registered trademarks of their respective holders.

Patents

The MathWorks products are protected by one or more U.S. patents. Please see

www.mathworks.com/patents for more information.

Getting Started Guide

Revision History

September 2005 Online only New for Version 1.0 ( Release 14SP3+) March 2006 Online only Updated for Version 1.0.1 (Release 2006a) May 2006 Online only Updated for Version 2.0 (Release 2006a+) September 2006 Online only Updated for Version 2.0.1 (Release 2006b) September 2006 Online only Updated for Version 2.1 (Release 2006b+) March 2007 Online only Rereleased for Version 2.1.1 (Release 2007a) September 2007 Online only Rereleased for Version 2.1.2 (Release 2007b) October 2007 Online only Updated for Version 2.2 (Release 2007b+) March 2008 Online only Updated for Version 2.3 (Release 2008a) October 2008 Online only Updated for Version 2.4 (Release 2008b) March 2009 Online only Updated for Version 3.0 (Release 2009a) September 2009 Online only Updated for Version 3.1 (Release 2009b) March 2010 Online only Updated for Version 3.2 (Release 2010a)

Introduction

Product Overview ................................. 1-2

Integrated Environment Expected Users Required Software Optional Software Related Softw are

Integrating SimBiology Models into Your Existing

Workflow

Existing Workflow in Experimental Research Workflow Incorporating Mathematical Modeling Workflow Using SimBiology Models for Mathematical

Modeling

................................... 1-3

.................................. 1-4

....................................... 1-5

...................................... 1-8

............................ 1-2

................................. 1-4

.......... 1-5

........ 1-6

Contents

Getting Started in the SimBiology Desktop

Overview Creating or Opening a Model Using the New Project

Wizard

Opening a SimBiology Project

Features and Functions

Using the Command Line versus the SimBiology

Desktop Graphical User Interface Command-Line Interface Data Formats and Projects Modeling Simulation Analysis

SimBiology Support and SBML

What Is SBML? SBML Support Importing SBML Files

........................................ 1-10

....................... 1-14

............................ 1-15

....................................... 1-15

........................... 1-16

........................... 1-21

.......................... 1-21

........................................ 1-22

....................................... 1-23

......................................... 1-24

..................... 1-25

................................... 1-25

.................................... 1-25

............................. 1-26

.......... 1-10

Converting a SimBiology Model to SBML Format ....... 1-26

Building SimBiology Models

Gene Regulation Model ............................ 2-2

Model Diagram Model Reactions Opening the Gene Regulation Model in the SimBiology

Desktop

Modeling Using the Sim Biology Graphical User

Interface

About the Model Used in This Tutorial Creating a Model Saving Your Work as a SimBiology Project File Adding Reactions to a Model Simulating a Model

................................... 2-2

.................................. 2-3

....................................... 2-6

........................................ 2-8

................ 2-8

.................................. 2-8

......... 2-9

........................ 2-10

................................ 2-15

vi Contents

Modeling Using the SimBiology Diagram

About This Example Creating a Model Saving Your Work as a SimBiology Project File Adding Reactions to a Model Diagram Simulating a Model Setting Block Appearance and Diagram Layout Printing and Exporting the Diagram

Modeling Using the Command-Line Interface

About This Example Creating a SimBiology Model Adding the Reaction for Transcription Adding the Reaction for Translation Adding the Reactions fo r Gene Regulation Adding the R eactions for mRNA and Protein

Degradation Simulating the Model Simulating the Model with a Stochastic Solver

............................... 2-16

.................................. 2-16

................................ 2-24

.................. 2-36

............................... 2-39

........................ 2-39

.................. 2-42

.................................... 2-43

.............................. 2-44

............ 2-16

................. 2-20

................ 2-41

............. 2-42

......... 2-20

......... 2-25

........ 2-39

......... 2-46

Index

vii

viii Contents

Introduction

This chapter introduces SimBiology®functions and features to help you develop a conceptual model for working with the software and your biochemical data.

• “Product Overview” on page 1-2

• “Integrating SimBiology Models into Your Existing Workflow” on page 1-5

• “Getting Started in the SimBiology Desktop” on page 1-10

• “Features and Functions” on page 1-15

• “SimBiology Support and SBML” on page 1-25

1 Introduction

Product Overview

Integrated Environment

SimBiology software provides an integrated environment for modeling biological processes, simulating the dynamic behavior of these processes, and analyzing the model with simulation and experimental data. Biological processes include metabolic, genetic, and signaling pathways with transform, binding, and transport reactions.

In this section...

“Integrated Environment” on page 1-2

“Expected Users” on page 1-3

“Required Software” on page 1-4

“Optional Software” on page 1-4

“Related Software” on page 1-4

1-2

You can also create and analyze pharmacokinetic models. For more information see “Pharmacokinetic Modeling” in the SimBiology documentation.

• Model — Design and build models by entering reactions, species,

parameters, kinetic laws, rules, and events with a graphical user interface , a block diagram editor, or using the MATL AB that the model can be simulated, and use the verification results to fix any incompatibilities in the model.

Import SBML models created w ith the SimBiology software or other modeling software that is compliant with the Systems Biology Markup Language (SBML) standard.

Export models created with the SimBiology desktop to M ATLA B and continue your simulations and analysis with command-line functions. For more information, see “Modeling” on page 1-22.

• Simulate — Observe changes in species amounts and parameter values

over time. Convert your model to a system of differential equations and simulate the model numerically with v arious differential equation solvers.

Command Window. Verify

Product Overview

The deterministic solvers include stiff and nonstiff ordinary differential equation (ODE) solvers. The stochastic solvers include a stochastic simulation algorithm with implicit and explicit tau variations. Perform multiple stochastic ensemble runs. For more information, see “Simulation” on page 1-23.

• Analyze — Save data from a simulation, compare simulation and

experimental data, perform sensitivity analysis, species or parameter scans, parameter estimation, and search for conserved moieties. For more information, see “Analysis” on page 1-24.

Expected Users

ThepeoplewhouseSimBiologysoftwarecomefromawiderangeofareas including biology, systems biology, pharmacology, computer s cience, and engineering. This product is intended for research scientists, computational biologists, and students who need to develop and study biological pathways at the molecular and systems level, develop custom analysis applications, or implement published ones, and visualize results.

Industry and Professional — SimBiology software allows you to model, simulate, and analyze biochemical and system pathways for applications in drug discovery and design, target identification, and pharmacokinetic modeling.

Modeling, simulating, and analyzing a biological system can test hypotheses for a pathway, identify side effects causedbydruginteractionswithatarget compound, and identify biochemical pathways that lead to disease.

Academia — Build rigorous, dynamic, quantitative models that allow you to understand and predict system behavior at the molecular level. Build models toexploreenzymekinetics. LeveragetheMATLABfoundationtoeasily manipulate large data sets.

Simulating the dynamic behavior of a model can confirm the validity of the models and identify behaviors and control mechanisms not apparent from studying static models. Validate models experimentally and use the model to predict in vitro and in vivo behavior.

1-3

1 Introduction

Required Software

To use SimBiology software, you must first install the following product from the MathWorks™:

MATLAB Provides a command-line interface and

an integrated software environment. For instructions, see the MATLAB installation documentation for your platform.

If you have installed MATLAB and want to check which other MathWorks products are installed, enter MATLAB Command Window.

ver in the

Optional Software

1-4

Statistics Toolbox™ (Version

7.0 (R2008b) or greater)

Global Optimization Toolbox Solve optimization problems using

Optimization Toolbox™ Optimization Toolbox extends the

Provides fitting tools including functions used to analyze non-linear mixed effects.

Note This toolbox is require d for analyzing non-linear mixed effects.

genetic and direct search algorithms. If this toolbox is installed, you can use various genetic and direct search algorithms for parameter estimation. If this toolbox is not installed, the software uses the optimization alg orithms available in MATLAB.

MATLAB technical computing environment with tools and widely use d algorithms for standard and large-scale optimization. These algorithms solve constrained and unconstrained continuous and discrete problems. If the Optimization Toolbox product is installed, you can use some algorithms included this product for parameter estimation in SimBiolo gy software. If

Integrating SimBiology®Models into Your Existing Workflow

Integrating SimBiology Models into Your Existing Workflow

In this section...

“Existing Workflow in Experimental Research” on page 1-5

“Workflow Incorporating Mathematical Modeling” on page 1-6

“Workflow U sing SimBiology Models for Mathematical Modeling” on page 1-8

Existing W

Consider t shows thes

1 Use preli

hypothes

2 Validate your model by making predictions and designing experiments

to test your model and hypothesis.

3 Make further predictions based on your model.

4 Publis

5 Continue to test predictions experimentally.

h results and predictions.

orkflow in Experimental Research

he following typ ical workflow in research. The subsequent figure

e general steps in experimental research.

minary results and published data to develop a model and

is in your area of interest.

1-5

1 Introduction

Typical Workflow in Experim ental Research

Workflow Incorporating Mathematical Modeling

Mathematical modeling integrates into the preceding workflow by providing the means to:

1-6

• Consolidate quantitative data into the model.

• Represent large pathways and networks and lay them out in meaningful

ways using a software application.

• Study emergent properties of pathways and use these predictions to guide

the direction of experimental research in ways that can save time and development costs.

Integrating SimBiology®Models into Your Existing Workflow

1-7

1 Introduction

Workflow Using SimBiology Models for Mathematical Modeling

The SimBiology software provides an integrated environment for mathematical modeling and analysis of biological and biochemical pathways. The following diagram shows you an overlay of features and tasks in the product pictured in the context of the complete w orkflow in experimental research.

1-8

Integrating SimBiology®Models into Your Existing Workflow

1-9

1 Introduction

Getting Started in the SimBiology Desktop

In this section...

“Overview” on page 1-10

“Creating or Opening a Model Using the New Project Wizard” on page 1-10

“Opening a SimBiology Project” on page 1-14

Overview

Depending on your application area and the extent of the existing knowledge base for your area of interest and ease of data availability, you might choose various different paths into, within, and out of the product. For example:

• Build the model using SimBiology software; use published or unpublished

kinetic data that you directly enter into the product or import the kinetic data using Microsoft and analysis.

Excel®or text files, and then perform simulation

1-10

• Build a pharmacokinetic model using the New Project Wizard, and analyze

the model.

• Open and work with a SimBiology model (project) that you have obtained.

• Import an SBML format model into the product and perform simulation

and analysis.

Creating or Opening a Model Using the New Project Wizard

The New Project Wizard lets you import data, add a model, and select the analysis tasks you want to add to the model:

1 In the MATLAB Command Window, type:

simbiology

The SimBiology desktop opens.

2 Select File > New Project. The New Project Wizard opens.

Getting Started in the SimBiology®Desktop

3 ChoosetoadddatausingtheAdd Data pane, or click Next. To add data:

a In the Add Data pane, from the Source list, select File or MATLAB

Workspace

b Depending on the selection in the previous step, specify the name of the

file or the MATLAB variables to import and click Next.

4 In the Add Model pane, from the Select a model to add list, select one

of the following:

Model Selectio n

Create new blank model

Create PK model

Load model from file

Import model from MATLAB workspace

Do not add a model

Description

Creates a model containing one compartment (at least one compartment is required for all models). You can later add model components such as species, reactions, rules, and events to the model.

Automatically generates pharmacokinetic (PK) models by specifying number of compartments, dosing type, andmethodofelimination.

Open a model from another project, or open an SBML mode l.

Imports a model already in the MATLAB workspace.

Letsyouworkwithimporteddata without adding a Model Session .

1-11

1 Introduction

5 Depending on the selection in the previous step, do one of the following:

1-12

If you chos

Create ne

Create

Load

ort model from MATLAB

Imp

kspace

wor

not add a model

ick Next.

6 Cl

e...

w blank model

PK Model

model from file

Do the foll

(Optiona the Model for the m

Specify dosing elimin see, “F Model P SimBi SimBi

se to, or specify the name of

Brow

roject or SBML file.

the p

ect from a list containing models

Sel

mtheworkspace.

fro

othenextstep.

Go t

owing ...

l, but recommended) In

Name box enter a name

odel.

number of compartments,

type, and m ethod of

ation. For m ore information

itting Pharmacokinetic

arameters in the ology Desktop” in the ology User’s Guide.

Getting Started in the SimBiology®Desktop

7 In the Choose analysis pane, select the analysis tasks to add to the model

and click Finish.

A new project with the selected specifications opens.

1-13

1 Introduction

Opening a SimBio

To open a SimBiol

1 In the MATLAB Co

simbiology

The SimBiolog

2 Select File > Open Project to open the Open SimBiology Project dialog

box.

3 Browse to and select the .sbproj format file containing the project.

ogy project that you received:

y desktop o pe ns.

logy Project

mmand Window, type:

1-14

Features and Functions

In this section...

“Using the Command Line versus the SimBiology Desktop” on page 1-15

“Graphical User Interface” on page 1-16

“Command-Line Interface” on page 1-21

“Data Formats an d Projects” on page 1-21

“Modeling” on page 1-22

“Simulation” on page 1-23

“Analysis” on page 1-24

Using the Command Line versus the SimBiology Desktop

SimBiology extends MATLAB and lets you access functionality at the MATLAB command line and the graphical SimBiology desktop.

Features and Functions

Use the command line to write and save scripts for batch processing, and to automate your workflow.

Use the SimBiology desktop to interactively change and iterate through the model workflow. The SimBiology des ktop also lets you en capsulate models, data, tasks, task settings, and diagnostic plots into one convenient package, namely a SimBiology project.

Further, if you are using t he SimBiology desktop and want to learn about working at the command line the code capture feature in the desktop lets you visualize the commands and export files for further scripting in the MATLAB editor.

Two tutorials in the Getting Started Guide walk you through building models through the desktop:

• “Modeling Using the SimBiology Graphical User Interface” on page 2-8

• “Modeling Using the SimBiology Diagram” on page 2-16

1-15

1 Introduction

Another tutorial in the Getting Started Guide walks you through building models at the command line:

• “Modeling Using the Command-LineInterface”onpage2-39

If you want to learn about pharmacokinetic modeling features see .

There are video demos that show you how to work in the desktop and demos that show you how to programmatically build a model, simulate, and analyze. To access SimBiology demos, type the following at the MATLAB command line:

demo matlab simbiology

Graphical User Interface

The SimBiology desktop provides access to command-line functionality through a graphical user interface. The interface lets you model, simulate, and analyze biological pathways and reactions. Export your model to the MATLAB workspace and perform further analysis using the command line.

1-16

Features and Functions

The graphical user interface (SimBiology desktop) is organized with the following set of integrated tools:

• Project Explorer — View projects and the organization of models, and

navigate to components and subcomponents using a hierarchical tree view. The project branch is divided into separate model sessions.

• Library Explorer — View and modify libraries, which contain built-in

and user-defined components, namely kinetic laws, plot types, units, unit prefixes, and blocks.

• Component Palette — View all available parameters, species, and

compartments. You can drag and drop components from the Component Palette to panes in the SimBiology software.

1-17

1 Introduction

• Diagram — Enter model data using block representations for species,

and reactions. Use the Plot block to visualize simulation data d uring a simulation.

- Block Library Browser — View and use blocks from the built-in

Basic library, and add custom blocks to user-defined block libraries for use in the diagram.

- Alignment Tool — Align blocks in a diagram.

• Table View of Model Com ponents — Enter data for model components

such as reactions, species, or parameters, using a familiar spreadsheet format, forms, comma-separated files, or previously saved SBML models. Model and simulate bio logical processes as reactions with reactants, products, and reaction rates. Reactions include processes that transform species, and processes such as transport, and binding.

• Verify Models — Verify that the model does not generate any warnings or

errors that would prevent simulation or analysis.

• Simulation — Simulate a model with deterministic or stochastic solvers,

save simulation data, and export data to the MATLAB workspace.

1-18

• Analysis Tasks — Calculate sen s i t ivities, scan species or parameters, fit

parameters (analyze nonlinear mixed effects), find conserved moieties, perform e nsemble simulations, or create custom analysis tasks.

• Plotting — Generate plots to visualize simulation and analysis results,

and create and save custom plots.

• Block Library Browser — Use the Basic library for blocks in th e diagram.

• Diagram Overview — Pan through large models using the miniaturized

view of the model in this too l.

• Diagram Table View — Tools like hiding, p inning, splitting, and cloning

for model layout in the Diagram, and generate a histogram for d eg ree of connectivity of species in a model.

• Searches — C reate custom searches for object properties with specific

values within a project.

• Find —UsetheFind feature for simple searches within a project. The

results are shown in the Search Results pane.

Features and Functions

• Generate Reports — Create reports for your project, include diagrams,

figures, and data i n the reports, and save them as HTML files.

• Kinetic Law Manager — View built-in kinetic laws and define your own

kinetic laws.

• Unit Manager — View built-in units or define your own units composed

from basic physical quantities.

• Table Column Manager — Customize the desktop spreadsheets using

the Table Column Manager to display or hide the properties you are interested in viewing or editing.

• Code capture — Convert interactive GUI actions with the SimBiology

desktoptoMATLABscripts,andloadthemintoMATLAB.

• Embedded help — The embedded help pane is context sensitive to the

tasks you are performing while you build, simulate and analyze your model. As you select component branches in the Project Explorer pane or optional panes, the topics that support your current tasks appear in the embedded help pane on the right.

The Help browser supplements the embedded help information with detailed reference material for command-line functions; object methods and properties; tutorials to help you get started; and more details about modeling, simulation, and analysis.

Customizing Desktop Views and Preferences

You can arrange the desktop layout according to your preferences.

• Changing preferences –SelectFile > Preferences to open the

SimBiology Preferences dialog box. You can change preferences for the following:

- Desktop Display — Specify which toolbars to display and which

properties to display in model component tables.

- Project Explorer — Specify whether to double-click or single-click to

open each pane from the Project Explorer.

- Diagram —SpecifyIndicator options, and whether to always warn

when there are disallowed block actions.

1-19

1 Introduction

- Search — Specify whether double-clicking a search result should open

the se lected component in the table view or the diagram.

- Report Generator — Specify the default format for report output,

stylesheet to use when generating the report, default image formats, size, and location.

- History — Specify the number of recently used models, projects, help

queries, searches, and libraries to display.

- Confirmation Dialogs — Specify whether dialog boxes should open for

confirmation of vario us deletions, parameter reordering, or defining undefined variables.

• Changing pane location — Click the title bar of a pane, drag it to the

desired location, and drop. The diagram shows you an outline of the pane during drag and drop. If the dropped location is on top of another pane, click the tabs at the bottom to navigate between the panes.

• Obtaining default layout —FromtheDesktop menu, select Desktop

Layout and select Default Layout.

1-20

• Organizing tables — You can also add or delete the properties listed in

the t able columns on each pane using the Table Column Manager.

If the Table Column Manager does not appear on your SimBiology desktop, from the Desktop menu, select Table Column M anager.The Table Column Manager opens in the desktop, and if the context-sensitive help pane is open, the help updates with m ore information.

• Changing pane title bar position — You can open multiple panes from

the Project Explorer. Each pane has a title bar in the Project Settings pane. You can change the location of the title bar. Right-click the title bar and then select Alphabetize or select Bar Position and select the location.

Features and Functions

Command-Line Interface

You can access all features interactively or programmatically.

You can either create your models in the SimBiology desktop and export to the w orkspace or create your models directly in MATLAB.

• Functions — Use functions to create projects, manage the unit and kinetic

law libraries, and simulate and analyze models.

• Methods — Use methods to create objects and specify object property

values.

• Code capture — In the SimBiology desktop, you can record and save your

actionsasascript. Afterloadingthescript into MATLAB, you can then run the script programmatically and observe what you created interactively.

Data Formats and Projects

Store your models in project files. Projects group related models and simulation data into project files.

• Projects — Organize projects with related models, simulation data, and

analysis results.

A project combines models, simulations, analysis, and results. Each project is divided into one or more model sessions.

• Model session — In the SimBiology desktop, a project can contain one

or more model sessions. Each model session contains a model, all its configuration settings, and any saved data.

1-21

1 Introduction

The configuration settings include simulation settings, units, kinetic laws, tags, notes, and annotations.

• Kinetic Law library — Use built-in kinetic laws or create your own

kinetic laws for defining reaction rates.

• Units library — Use built-in units or create your own units for species

and parameters.

In addition, SimBiology softw are supports SBML Level 2 Version 1. Systems Biology Markup Language (SBML) is becoming the standard language for documenting and sharing mathematical models for biological systems. You can save your models to an SBML-formattedfileorreadanSBMLfilecreated with SimBiology or other modeling software. For more information, see “SimBiology Support and SBML” on page 1-25.

When you save a project, the model definition is sav ed with the project. However, you can inde pe n dently export a SimBiology model to an SBML file. Use this SBML file to import your mo de l into SBML Level 2 Version 1-compliant modeling and simulation software.

1-22

When you import an SBM L file created with other software, the model definition is translated into SimBiology objects.

Modeling

You can use SimBiology software to design and build pathway models.

• Model — A SimBiology model is a collection of interrelated reactions,

rules, and events that transform, transport, and bind species. The model components are compartments, species, reactions, parameters, rules, and events. After creating a model, add a compartment. Then you can add reactions to the model, define a kinetic law for each re action, and add the parameters for the reaction.

• Model properties — Properties define the characteristics of a component.

For example, a reaction includes properties for reactions such as reaction rates, and links to associated species, parameters, and kinetic laws. You can interactively change these properties in the graphical user interface.

Features and Functions

At the command line, all model components are represented as objects. Use the values at the command line.

• Notes —TheNotes property allows HTML-formatted text. This p roperty

lets you link to journal articles in PDF and other formats, Web pages, databases, graphic files, experimental data, and verbose project notes that donotfitintoatextbox.

get and set commands to list object properties and change their

Simulation

SimBiology software includes both stochastic and deterministic solvers.

• Stochastic simulation — G enetic and signaling pathways often have

a small number of molecules that are simulated more accurately with stochastic algorithms. The stochastic solvers are based on Daniel Gillespie’s exact solution algorithm with variations for implicit and explicit tau leaping.

Gillespie, D., (1977), “Exact Stochastic Simulation of Coupled Chemical Reactions,” The Journal of Physical Chemistry, 8(1):2340–2361.

The implicit tau-leaping solver works optimally with large, numerically stiff systems. When solving numerically stiff systems, this solver remains stableforlargetimeintervals(tau)wheretheexplicittau-leapingsolver might not.

While stochastic simulations might accurately reflect the actual processes in a cell, they might not be practical for models with a large number of reactions or higher species amounts. Metabolic and signaling transduction pathways fall into this category. In this case, mass-action kinetics and ODE solvers can be a reasonable approximation.

• Deterministic simulation — You can choose from the list of stiff and

nonstiff deterministic simulation solvers that are included with MATLAB. Thesesolversarereliableandrobust.

• Dimensional analysis and unit conversion — Dimensional analysis

compares the physical quantities for parameters and species in mathematical expressions (reaction rates, algebraic rules, assignment rules, and rate rules) and verifies that they are in consistent dimensions. Unit conversion scales the parameter values and species amounts to have the same units before simulation.

1-23

1 Introduction

• Plotting simulation results — At the end of the simulation, the software

plots the results in a figure window, or you can change plot settings and replot selected species yourself. In the SimBiology desktop, insert and configure a Plot block in the Diagram pane to view the results in a plot while the simulation runs.

• Simulations settings — Configuration set objects define the properties

needed for simulation. These properties include the simulation time, absolute and relative tolerances, and controls for dimensional analysis and unit conversion.

Analysis

SimBiology softw are is closely integrated with MATLAB.

• Getting simulation data into MATLAB — During a simulation, the

softwaresaves(logs)thevaluesforparametersandtheamountsofspecies to the M ATLA B workspace.

• Plotting simulation data and analyzing results — Using the functions

in MATLAB, you can select and scale species for plotting.

1-24

• Parameter estimation and optimization — E stimate parameters that

are unknown in the model.

• Sensitivity analysis — Calculate sensitivities of species with respect to

species and parameter input factors.

• Moiety conservation — Calculate a complete set of linear conservation

relations for the species in a SimBiology model.

• Ensemble runs — Perform iterative simulation runs to compare and

analyze simulation results from stochastic solvers. Find the mean and variance as a function of time.

SimBiology Support and SBML

In this section...

“WhatIsSBML?”onpage1-25

“SBML Support” on page 1-25

“Importing SBML Files” on page 1-26

“Converting a SimBiology Model to SBML Format” on page 1-26

What Is SBML?

Systems Biology Markup Language (SBML) is an information standard for sharing, evaluating, and developing systems biology models cooperatively.

Its purpose is to provide a structure for creating models and sharing those models among various modeling and simulation software tools. The current specification is available on the Web at

SimBiology®Support and SBML

http://sbml.org/documents/.

SBML Support

SimBiology software supports a subset of the SBML Level 2 Version 1 specification. You can import from and export to SBML-compatible

Unsupported features include:

• Piecewise kinetics — Models with piecewise kinetics are loaded in, but the

definitions for piecewise kinetics are ignored.

• Function definitions — Models containing functional definitions are loaded,

and you see a warning and the function definitions are ignored.

• MATLAB incompatible variable names in

have variable names incompatible with MATLAB in not loaded and you see an error message.

• The

hasOnlySubstanceUnits field does not have a corresponding property

in the SimBiology species object. For more information on dimensions for SimBiology species, see

DefaultSpeciesDimension.

UnitDefinition — Models that

UnitDefinition are

.xml files.

1-25

1 Introduction

Importing SBML F

To import an SBML

iles

file in the SimBiology desktop, u se the New Project

Wizard.

1 In the MATLAB Co

simbiology

The SimBiolo

2 Select File > New Project. The New Project Wizard opens.

3 ChoosetoadddatausingtheAdd Data pane, or click Next.

4 In the Add Mo

model from

5 Browse to, or specify the name of the project or SBML file.

6 Click Next.

7 In the Ch

and clic

file

oose analysis pane, select the analysis tasks to add to the model

k Finish.

mmand Window, type:

gy desktop opens.

del pane, from the Select a model to add list, select

A new project with the selected specifications opens.

Load

1-26

Converting a SimBiology Model to SBML Format

To convert a SimBiology model to SBML format,

1 Select File > Export Model to SBML. The Save Systems Biology Markup

Language File (SBML) dialog box opens.

2 Enter a path and file name.

k Save.

3 Clic

SimBiology®Support and SBML

The following information is included in the saved SBML format file:

• Compartments, events, parameters, reactions, rules, and species that are

defined in the model.

Note Rules, reactions, and events that have their Active property set to

false (inactive) are not exported.

• All unit definitions in SBML-compliant form

• The reaction rate equation, but not the kinetic law definition

Example

In SimBiology kinetic laws, the Henri-Michaelis-Menten equation,

Vm*S/(Km+S) is a kinetic law definition stored in the kinetic law library.

Specifically, for a one-substrate enzyme-catalyzed reaction, if you assign

Vm=Va,Km=Ka,andS=A, the reaction rate equation is Va*S/(Ka+A)

• Model component properties with SBML equivalents, such as Annotation,

species, and parameter unit values will be exported. Features and properties specific to SimBiology software, such as Tag and Active,cannot be exported.

The following SimBiology features are not supported by SBML and not included in the saved SBML format file:

• Projects — SimBiology software creates and stores all your models in

project files with the

.sbproj extension. You can store multiple models in

one project file.

• Kinetic law — You can store kinetic law information such as the kinetic

law name and a kinetic law definition.

• Dosing information — If the model contains dosed compartments, dosing

information is no t included in the SBML format file.

1-27

1 Introduction

1-28

Building SimBiology Models

• “Gene Regulation Model” on page 2-2

• “Modeling Using the SimBiology Graphical User Interface” on page 2-8

• “Modeling Using the SimBiology Diagram” on page 2-16

• “Modeling Using the Command-LineInterface”onpage2-39

2 Building SimBiology

Models

Gene Regulation Model

In this section...

“Model Diagram” on page 2-2

“Model Reactions” on page 2-3

“Opening the Gene Regulation Model in the SimBiology Desktop” on page 2-6

Model Diagram

You can visualize a systems biology model with various levels of detail. O ne view sketches only the major species and processes. This model is an example of simple gene regulation, where the protein product from translation controls transcription. You could create a more complex model by adding the enzymes, coenzymes, cofactors, nucleotides, and amino acids that are not included in this model. The gene regulation example simplifies the regulatory mechanism by not showing the contributions of RNA polymerase and any cofactors. The protein product from gene expression binds to a regulatory region on the DNA and represses transcription.

2-2

her way of looking at a systems biology model is to list the reactions in a

Anot

el with the processes they represent.

mod

DNA -> DNA + mRNA (transcription) mRNA -> mRNA + protein (translation) DNA + protein -> DNA_protein (binding) DNA_protein -> DNA + protein (unbinding) mRNA -> null (degradation) protein -> null (degradation)

Gene Regulation Model

Drawing the reaction pathways will help you visualize the relationships between reactions and species. In the gene regulation example, as the amount of a protein increases, the protein forms a complex with the gene responsible for its expression, and slows down protein production.

Model Rea

Reactio for a sof followi descri about t

n equations define a systems biology model at the level of detail needed

tware program to simulate the dynamic behavior of the model. The

ng reactions for transcription, translation, binding, and degradation

be a simple gene-regulating mechanism. For additional in formation

his model, see “Gene Regulation Model” on page 2-2.

ctions

Transcription

cription is where RNApolymerase and cofactors bind with a DNA

Trans

ule. The RNApolymerase then moves along the DNA and combines

molec

otides to create mRNA. A simple model of transcription shows only the

nucle DNA a

nd mRNA.

2-3

2 Building SimBiology

Models

This model simplifies the transcription and the synthesis of mRNA by using a single reaction.

Reaction: DNA -> DNA + mRNA

Reaction rate: v = k1*DNA molecule/second

Species: DNA = 50 molecule

mRNA = 0 molecule

Parameters: k1 = 0.2 1/second

Translation

After the mRNA moves from the nucleus to the cytoplasm, it can bind with ribosomes. The ribosomes move along the mRNA and create proteins with thehelpoftRNAsboundtoaminoacids.Asimplemodeloftranslationshows only the mRNA and protein product.

2-4

The synthesis of the protein is mod e led as a single reaction.

Reactio

Specie

Parame

n: mRNA -> mRNA + protein

n rate: v = k2*mRNA molecule/second

s: mRNA = 0 molecule

protei

ters: k2 = 20 1/second

n = 0 mol ecu le

Gene Repression

cription of DNA to mRNA is re gu lated by the binding of the protein

Trans

ct from translation to the DNA. As more protein is p roduced, the DNA is

produ

d w ith the protein more often and less time is available for transcription

boun

the unbound DNA.

with

Gene Regulation Model

Forward Reaction (Binding)

Reaction: DNA + protein -> DNA_protein

Reaction rate: v = k3*DNA*protein molecule/second

Species: DNA = 50 molecule

protein = 0 molecule

Parameters: k3 = 0.2 1/(molecule*second)

Notice how the units are described f or the parameter k3. In the literature, some of the common ways to display second-order rate constants are

-1

mole

second-1or 1/mole-second. However, software evaluations of these

common ways are sometimes ambiguous.

Reverse Reaction (Unbinding)

Reaction: DNA_protein -> DN A + protein

Reaction rate: v = k3r*DNA_protein molecule/secon d

Species: DNA_protein = 0 molecule

Parameters: k3r = 1 1/second

For this tutorial, model the binding and unbinding reactions as one reversible reaction.

Reaction: DNA + protein <-> DNA_protein

Reaction rate: v = k3*DNA*protein - k3r*DNA_protein molecule/second

Species: DNA = 50 molecule

protein = 0 molecule

Parameters: k3 = 0.2 1/(molecule*second)

k3r = 1 1/second

Degradation

Protein and mRNA degradation are important reactions for regulating gene expression. The steady-state level of these compounds is maintained by a balance between synthesis and degradation reactions. Proteins are hydrolyzed to amino acids with the help of proteases, and nucleic acids are degraded to nucleotides.

2-5

2 Building SimBiology

Models

mRNA degradation is modeled as a transformation to the null species.

Reaction: mRNA -> null

Reaction rate: v = k4*mRNA molecule/second

Species: mRNA = 0 molecule

Parameters: k4 = 1.5 1/second

Likewise, pro te in degradation is also modeled as a transformation to the null species. The species null is a predefined species name i n SimBiology models.

Reaction: protein -> null

Reaction rate: v = k5*protein molecule/second

Species: protein = 0.0 molecule

Parameters: k5 = 1.0 1/second

Opening the Gene Regulation Model in the SimBiology Desktop

A project containing the model built in the gene regulation example is available with the product. To skip the sections on model building and to learn about simulations in the SimBiology desktop, you can access the completed model in the SimBiology desktop.

2-6

1 In the MATLAB Command Window, type:

simbiology

The SimBiology desktop opens.

2 Select File > Open Project to open the Open SimBiology Project dialog

box.

3 Navigate to:

matlabroot/toolbox/simbio/simbiodemos

4 Select gene_reg.sbproj,andclickOpen.

Gene Regulation Model

The project opens with two models: cell and cell2. These two m odels are identical except for the graphical representation of the blocks in the Diagram View pane.

5 To explore the m o dels, click an item in the Project Explorer to open

individual panes.

6 See “Simulating a Model” on page 2-15 for procedures on simulating a

model in the SimBiology desktop.

2-7

2 Building SimBiology

Models

Modeling Using the SimBiology Graphical User Interface

In this section...

“About the Model Used in This Tutorial” on page 2-8

“Creating a Model” on page 2-8

“Saving Your Work as a SimBiology Project File” on page 2-9

“Adding Reactions to a Model” on page 2-10

“Simulating a Model” on page 2-15

About the Model Used in This Tutorial

This section shows how to mathematically model a simple gene-regulation pathway using the SimBiology desktop. The example uses the model described in “Gene Regulation Model” on page 2-2 and shows you how to build this model using a spreadsheet-s tyle interface in the SimBiology desktop.

2-8

If you prefer to interact with diagrammatic representations of pathways, see “Modeling Using the SimBiology Diagram” on page 2-16.

Alternatively, you can use the MATLAB command-line interface (see “Modeling Using the Command-Line Interface” on page 2-39). A comparison of these methods will help you understand the model objects that MATLAB creates behind the SimBiology desktop, and how to access and edit a model through the MATLAB Command Window.

Creating a Model

A SimBiology model is a collection of objects that are structured hierarchically. At least one mo de l object is needed to contain all the other objects.

1 In the MATLAB Command Window, type:

simbiology

The SimBiology desktop opens.

2 Select File > New Project. The New Project Wizard opens.

Modeling Using the SimBiology®Graphical User Inter face

3 Skip the Add Data step for this example and select Add Model.

4 In the Add Model pane, from the Select a model to add list, select

Create new blank model. This selection creates a Model Session

containing one compartment (at least one compartment is required for all models). You will later add model components such as species, reactions, rules, and events to the model.

5 In the Model Name box, type the name for your model.

cell

6 Click Next.

7 In the

model

Choose Analysis pane, leave the default selection (Simulate

) selected for the analysis tasks to add to the model and click Finish.

A new project with the selected specifications opens.

Saving Your Work as a SimBiology Project File

Project is the file format that the SimBiology software uses to save one or more model sessions . The file extension is

.sbproj. Projects let you save

2-9

2 Building SimBiology

Models

custom settings, notes, and data associated with your models. For more information on projects, see “Data Formats and Projects” on page 1-21.

Save your work as a project now so that you can access this file later.

1 Select File > Save Project as to open the Save SimBiology Project dialog

box.

2 Browse to the folder in which you want to save your projects, and enter a

name for the project file, such as:

gene_regulation.sbproj

3 Click Save.

Adding Reactions to a Model

SimBiology models are defined by connected reactions representing transformation,binding,andtransport.

2-10

1 In the Project Explorer,expandSimBiology Model and click Reactions

to open the Reactions pane.

2 In the Enter Reaction box, enter the reactants and products, s eparated

by a hyphen and right angle bracket. For example, enter the following simple reaction for transcription:

DNA -> DNA + mRNA

3 Click Add.

A red indicator appears to the right of the table (and in the Project Explorer). Move the pointer over the indicator for the reaction to get more

information about the reason for the indicator. In this case, the indicator shows that the reaction rate is as yet undefined. Beginning in step 5, you will learn how to define the reaction rate.

4 Double-click the Name cell, enter a name for the reaction and press Enter.

For example, enter the following:

Transcription

Modeling Using the SimBiology®Graphical User Inter face

5 From the KineticLaw list, select MassAction. Your screen should

resemble this one.

Note Species names are automatically populated for Mass Action. In this example notice that MassAction Species lists

6 In the Map between KineticLaw Parameters and Parameter Names

DNA.

section, locate the Forward Rate Parameter row, double-click the Parameter Name cell, type

k1 and press Enter.

The SimBiology desktop updates ReactionRate for the reaction to show

k1*DNA.

Your reaction table should resemble the following.

2-11

2 Building SimBiology

Models

The indicator is red indicator i

7 Double-click the Value cell and enter a new value.

0.2

8 From the ValueUnits lis t, select the units for this paramet er. The rate

constant

k1 is a first order constant with units 1/second.

green, showing that the reaction rate is now defined. The

ntheProject Explorer also disappears.

Your parameters table should resemble the following.

About Scope

Notice that the Scope box for the parameter lists the reaction, indicating that the parameter is only available for reference at the level of the reaction.

If you set the scope of a parameter to the model (

Model Name), you can use

this parameter in rules, other reactions, and events. All the parameters for this example are scoped to their respective kinetic laws.

2-12

Scoping lets you overload parameters, that is you can have parameters with the same name at the kinetic law and at the model level. Because the desktop searches up from the kinetic law to the model level, when a parameter is overloaded, a reaction uses the parameter and parameter value in its kinetic law; howev er rules and events use the parameter value at the model level.

A reaction u ses a parameter at the model level only if a corresponding parameter is not defined at the kinetic law level for the reaction.

Modeling Using the SimBiology®Graphical User Inter face

9 In the Map between KineticLaw Species and Species Names section,

locate the MassAction Species row ( cell, type

10 From the InitialAmountUnits list, select molecule.

50 and press Enter.

DNA), double-click the InitialAmount

The Scope of the species indicates the co mpartmentthatthespeciesis within, and this is still

unnamed. The next steps show you how to name

the compartment.

11 In the Project Explorer,clickCompartments to open the

Compartments pane.

In the SimBiology desktop, models contain a compartment by default. The process of adding a reaction automatically adds the reaction species to a compartment in the model. If there are multiple compartments in the model, you must specify the reactants and products using qualified names (

compartmentName.speciesName). For example, nucleus.DNA denotes the

species

DNA in the compartment nucleus.

12 This example contains only one compartment. Rename the compartment

by doing the following:

In the Name cell, double-click and type a name such as

contents for the

compartment and press Enter. The compartment table updates with the new entry.

13 From the Capacity Units list select liter.

Leave other compartment p roperties such as Owner and Capacity in the default settings, for the purpo ses of this example.

14 In the Project Explorer,expandCompartments and click contents

Species. The species you entered in the reaction are automatically added

to the species table.

The default value for a species is

15 In the row containing mRNA,fromtheInitialAmountUnits list, select

molecule.LeavetheInititalAmounts value at 0.0.

0.0.

2-13

2 Building SimBiology

Models

16 Enter the remaining reactions. For a list of r eactions and parameters,

see“ModelReactions”onpage2-3.

Notice that the default unit in the list. However,

ValueUnits for the second-order rate constant k3 is not a

molecule and second are default units

and y ou can enter this unit directly by ty p in g the following:

1/(molecule*second)

Your reaction, species, and parameter panes should resemble the following ones.

2-14

For m ore detailed i nformation about the reactions in this model, see “Gene Regulation Model” on page 2-2.

Modeling Using the SimBiology®Graphical User Inter face

Simulating a Mod

After you enter t behavior and plo

• Click

The simulation uses the default configuration settings, runs to completion, and then plots the results in a figure window. You can annotate your plot in the figure window. The following figure shows you an annotated version of the plot:

he reactions for your model, you can simulate its dynamic t the results.

(Run).

2-15

2 Building SimBiology

Models

Modeling Using the SimBiology Diagram

In this section...

“About This Example” on page 2-16

“Creating a Model” on page 2-16

“Saving Your Work as a SimBiology Project File” on page 2-20

“Adding Reactions to a Model Diagram” on page 2-20

“Simulating a Model” on page 2-24

“Setting Block Appearance and Diagram Layout” on page 2-25

“Printing and Exporting the Diagram” on page 2-36

About This Example

2-16

If you prefer to interact with a tabular representation of reaction pathways, see “Modeling Using the SimBiology Graphical User Interface” on page 2-8.

Alternatively, you can the MATLA B command-line interface (see “Modeling Using the Command-Line Interface” on page 2-39). A comparison of these methods will help you understand the model objects that M ATLA B creates behind the SimBiology desktop, and how to access and edit a model through the MATLAB Command Window.

Creating a Model

This section shows how to model a simple gene-regulation pathway using the SimBiology Diagram interface. For more information about this model, see “Gene Regulation Model” on page 2-2.

A SimBiology model is a collection of objects that are structured hierarchically. At least one model object is needed to co ntain all the other objects. The

Modeling Using the SimBiology®Diagram

SimBiology Diagram lets you work with the familiar graphical representation of biological pathways and processes.

This section shows you how to build your model using block representations for each compartment, species, and reaction. The model reactions are shown in “Gene Regulation Model” on page 2-2.

1 In the MATLAB Command Window, type:

simbiology

The SimBiology desktop opens.

All the procedures in this section refer to the SimBiology d esktop in the default layout. To set the desktop to the default layout, select Desktop > Desktop Layout > Default Layout.

2 Select File > New Project. The New Project Wizard opens.

3 Skip the Add Data step for this example and select Add Model.

4 In the Add Model pane, from the Select a model to add list, select

Create new blank model. This selection creates a Model Session

containing one compartment (at least one compartment is required for all models). You will later add model components such as species, reactions, rules, and events to the model.

2-17

2 Building SimBiology

Models

5 In the Model Name box, type the name for your model.

2-18

cell

6 Click Next.

7 In the Choose Analysis pane, leave the default selection (Simulate

model) selected for the analysis tasks to add to the model and click Finish.

Anewpr

8 In the Project E xp lorer,expandSimBiology Model and click Diagram

oject with the selected specifications opens.

View.TheDiagram View pane opens.

Modeling Using the SimBiology®Diagram

Notice the Compartment block (unnamed) in the model. In the desktop, all models contain a compartment by default.

9 Select Di

Tip The B

proper

Block P

All mo proce the co mode (

com

spec

10 Select the model’s compartment. The Block Property Editor updates to

agram > Tools > Block Property Editor.

lock Property Editor allows you to enter or change block

ties. Select a block in the diagram to access its properties in the

roperty Editor

dels created in the desktop contain a compartment by default. The

ss of add in g a reaction automatically adds the reaction species to

mpartment in the model. If there are multiple compartments in the

l, you must specify the reactants and products using qualified names

partmentName

ies

DNA in the compartment nucleus.

.speciesName). For example, nucleus.DNA denotes the

show the compartment properties.

11 In the Name box, type a name such as contents for the compartment

and press Enter.

2-19

2 Building SimBiology

Models

12 From the Capacity Units list select liter.

Leave other compartment p roperties such as Owner and Capacity in the default settings, for the purpo ses of this example.

Saving Your Work as a SimBiology Project File

Projectisthefileformatthatthesoftwareusestosaveoneormoremodel sessions; the file extension is notes, and data associated w ith your models. For more information on projects, see “Data Formats and Projects” on page 1-21.

Save your work as a project now so that you can access this file later.

1 Select File > Save Project as to open the Save SimBiology Project dialog

box.

2 Browse to the folder in which you want to save your projects, and enter a

name for the project file, such as:

.sbproj. Projects let you save custom settings,

2-20

gene_regulation.sbproj

3 Click Save.

Adding Reactions to a Model Diagram

SimBiology models are defined by connected reactions representing transformation, binding, and transport. You can graphically represent the reactions in the diagram. This section shows you how to add, connect, and configure blocks in a diagram. For this example, use the ModelBuilding block library.

1 From the Block Library Browser, click and drag a species block into

the compartment in the diagram.

2 Select the newly added species block to view the properties in the Block

Property Editor.

Modeling Using the SimBiology®Diagram

3 In the Name bo x, enter the species name. For this example, enter DNA.

4 In the InitialAmount cell, enter a new value.

5 From the InitialAmountUnits list, select the units for this species.

molecule

6 From the Block Library Browser, click and drag another species block

into the diagram. Name this species the default (

0.0). From the InitialAmountUnits list, select molecule as

mRNA.TheInitialAmo unt for mRNA is

units for this species.

7 From the Block Library Browser, click and drag a reaction block into

the diagram.

Note The newly added reaction has a red X icon, indicating the reaction has not been fully defined. Once the reaction has been defined, as shown later in this example, the icon s hould disappear.

8 Hold down the Ctrl key (Windows

key (Macintosh

) while clicking the DNA species block. Drag the line to the

reaction and release the mouse. The diagram assigns

and Linux®platforms) or the Option

DNA as a rea ctan t.

2-21

2 Building SimBiology

Models

Since DNA is also a product of the reaction, connect a line from the reaction block to

DNA. The diagram draws a dashedline,indicatingthatDNA is

a modifier for the reaction.

9 Draw a line from the reaction block to the mRNA species block.

10 Select the reaction block to view the block properties in the Block

Property Editor.NoticethattheReaction box shows the reaction (

-> mRNA + DNA

11 In the Name box, enter a reaction name. For example, enter

Transcription.

12 From the KineticLaw list, select MassAction. The Block Property

)towhichtheblockapplies.

Editor should resemble the following:

DNA

2-22

Note Species names are automatically populated for Mass Action. In this example notice that MassAction Species lists

DNA.

Modeling Using the SimBiology®Diagram

13 In the Map between KineticLaw Parameters and Parameter Names

section, locate the Forward Rate Parameter row, double-click the Parameter Name cell, type

k1 and press Enter.

The SimBiology desktop updates ReactionRate for the reaction to show

k1*DNA.

The indicator is green, showing that the reaction rate is now defined.

14 Double-click the Value cell and enter a new value.

0.2

15 From the ValueUnits list, select the units for this paramet er. The rate

constant

k1 is a first order constant with units 1/second.

Your parameters table should resemble the following.

Your diagram should resemble this one:

2-23

2 Building SimBiology

Models

16 Add the other species and reactions blocks, and create parameters for

each reaction as shown in the previous steps. For a list of reactions and parameters, see “Model Reactions” on page 2-3. Verify that the reaction rate is determined for each reaction.

Notice that the default unit in the list. However,

ValueUnits for the second-order rate constant k3 is not a

molecule and second are default units

and y ou can enter this unit directly by ty p in g the following:

1/(molecule*second)

After creating the model, the diagram should resemble this one.

Notice the use of dashed lines for species that are both reactants and products in a reaction (modifiers). Note the indicator for a reversible reaction associated with the Binding/Unbinding reaction.

2-24

You can change the layout and appearance of the blocks any time. Double-click a block and click the Appearance tab to change the color, text font, size, and location. See “Changing Block Appearance” on page 2-26 for more information.

Simulating a Model

After you enter the reactions for your model, you can simulate its dynamic behavior and plot the results.

Modeling Using the SimBiology®Diagram

• Click (Run).

Settin

This s SimBi

• “Cha

• “App

• “Cha

• “Ch

• “Ho

g Block Appearance and Diagram Layout

ection shows you how to change the appearance and layout of a

ology diagram.

nging Block Appearance” on page 2-26

lying Block Ap pearance Styles” on page 2-28

nging the Diagram Layout Manually” on page 2-29

anging the Diagram Layout Automatically” on page 2-32

wtheSimBiologyDesktopDoesDiagram Layout” on page 2-35

2-25

2 Building SimBiology

Models

Changing Block Appearance

You can change the appearance of blocks, text, lines, and indicators in the diagram. The following figure is one example.

This example uses the DNA species block and the Binding/Unbinding reaction block to show you how to change the color of the blocks, the location of the text, the appearance of the reversible indicator, and line appearance as shown in the previous figure.

2-26

1 Select Diagram > Tools > Block Property Editor.TheBlock

Property Editor opens.

2 Select the species block or the reaction block to view the selected block

property in the Block Property Editor. Perform the next steps in the Appearance section.

3 Change the following values to affect position and size of the block:

• X– Position of block relative to the X axis of the diagram. For example,

for the reaction block, try

260

• Y– Position of block relative to the Y axis of the diagram. For example,

for the reaction block , try

• Width and Height– Horizontal and vertical size of the block respectively.

For example, for the reaction block, try

25 and 40 respectively

Modeling Using the SimBiology®Diagram

4 From the Text Location list, select where the text should be positioned in

the diagram. The default is

bottom. For example:

• For the

DNA Species block, select center to position the text within the

center of the Species block.

• For the

5 From the Text Font, Block Appearance, Text Color, Edge Color,and

Binding/Unbinding Reaction block, select top.

Face Color lists, select the text font, block appearance, text color, edge color, and block fill color.

Tip Select Face Color > No Face Color to obtain the result shown for reaction blocks in the diagram figure above.

Tip Select Block Appearance > Image to insert an image for the block. The SimBiology desktop opens a dialog box that lets you browse to the

image location. If you change the image, click

(Refresh) to reload

the updated image.

6 Double-click a line to open the Line Properties dialog box. The default line

width is

7 Select File > Preferences. The SimBio log y Preferences dialog box opens.

1.0 pixels. The line width in the previous example diagram is 2.0.

8 Select Diagram.

2-27

2 Building SimBiology

Models

9 Clear or select an indicator check box to turn off or turn on the display of

the indicato r in the diagram. For example, clear the Reversible property indicator, and click Close.

2-28

Notice that the r eversible indicator is now off for the

Binding/Unbinding

Reaction block in the diagram.

10 Right-click the diagram and select Layout Diagram to automatically

change the layout of the diagram. You can manually lay out the diagram using the pin, split, clone, and hide features in the diagram.

For more information on the p in, split, clone, and hide features in the diagram, see “Changing the Diagram Layout Manually” on page 2-29. For information on automatic layout in the S imB iology desktop, see “Changing the Diagram Layout Automatically” on page 2-32.

Applying Block Appearance Styles

To replicate the appearance style of a block to other blocks by copying and applying the style on selected blocks:

1 Select a species block, for example, the DNA specie s block.

Modeling Using the SimBiology®Diagram

2 Right-click the block and select Copy Block Style.

3 Select another block, for example, the DNA protein species block.

You can also select multiple blocks to apply the style to all selecte d blocks.

4 Right-clicktheblockandselectApply Block Style. The SimBiology

desktop changes the appearance of the block to match the selected style.

Changing the Diagram Layout Manually

You can manually lay out the diagram using the pin, split, clone, and hide features in the diagram. Use the Diagram Table View pane or a block’s right-click context menu to change the properties discussed next. To access Diagram Table View, select Diagram > Tools > Diagram Table View.

Tip While you are working on the diagram layout, remem ber to sele c t File > Save Project to save the desired layout of your diagram. The SimBiology

desktop saves the layout in the project.

To manually lay out the model diagram:

1 Right-click a species block, and select Split Block. For example, split

the

protein Species block.

The SimBiology desktop provides a representation of the split block for each instance of the species in the model. Notice that although there could be multiple split blocks, there is only one species.

If you change any block properties for any of these split blocks, the change will propagate to each split block. For example, if you change the appearance of the block, the change affects all split blocks.

Note You can split only species blocks.

2 Manually move the split blocks to the desired position.

2-29

2 Building SimBiology

Models

3 From the Diagram menu, select Tools > Diagram Table View to open

the Diagram Table View pane.

2-30

am Table View is a tool that lets you hide or show blocks, split or

Diagr

ne blocks, and pin or unpin blocks. You can select a single block or

combi

rm the action on multiple selected blocks. Diagram Table View also

perfo shows ahis

4 In the row for the protein Species block, clear the Split check box. The

you the degree of connectivity in your diagram and also lets you view

togramofthedegreeofconnectivity.

diagram combines the split blocks. Alternatively, you can right-click the Species block and select Combine Split Blocks.

5 Select the row for the Transcription Reaction block a nd press

Ctrl+left-click to select the row for the

mRNA Species block. Ctrl+click lets

you select discontinuous rows.

Modeling Using the SimBiology®Diagram

6 Right-click and select Pin Selected Blocks. The diagram pins the blocks.

You cannot move pinned blocks manually or with automatic layout. Note the indicator for p inned blocks in the following diagram.

7 Select the row for the Protein Degradation reaction and press

Shift+left-click to select the row for the

8 Right-click and select Hide Selected Blocks.Thediagramhidesthetwo

mRNA Degradation reaction.

reactions in the diagram. The reaction rows are visible in the Diagram Table View pane.

Note Hiding a block only hides it graphically. The block is still represented in the mathematical model.

9 Select a block, right-click and select Rotate Clockwise to rotate the

selected block.

10 Select Diagram > Show All Hidden Blocks and Lines to see all blocks.

11 Click in the Diagram Table View toolbar.

The SimBiology d esktop opens a figure window with a histogram of the degrees of connectivity plotted as the number of connections versus the number of blocks.

2-31

2 Building SimBiology

Models

You can als

oseethedegreeofconnectivityintheDegree column.

Changing the Diagram Layout Automatically

From the D Selected

use the au diagram

Automat and sel if you d

This ex

The de You ca

top.

desk

To ch

1 Rig

Pro

iagram menu, select Layout All Elements or Only the

Elements to use the automatic layout feature. Select blocks and

tomatic layout feature to lay out only the selected blocks in the

ic layout works only on blocks that are not pinned. You can right-click

ect Unpin Block if you want to lay out all blocks. Leave blocks pinned

o not want the position of the block to change during layout.

ample starts with the blocks for

mRNA and Transcription pinned.

fault settings for automatic layout should work well for many models.

n optionally change the automatic layout settings in the SimBiology

ange the settings for automatic layout:

ht-click the diagram background and select Properties.TheDiagram

perties dialog box opens.

2-32

2 Click the Layout Diagram tab.

Modeling Using the SimBiology®Diagram

3 In the Number of Layout Iterations box, enter the number of iterations

to include in the layout. The default is better layout, but also take more time. For example, enter

4 In the Timeout box, enter the maximum amount of time available for

layout. The default is

5 In the

one it slow ente

6 In the Line Spring Constant box, specify the strength with which the

Maximum Distance box, specify the distance that a block moves in

eration. The default is er. Large values can also cause oscilla t ion in the layout. For example, r

50.

10000.0 milliseconds.

1000.0.Ifyouenterasmallervalue,layoutis

lines between blocks pull blocks together. The default is

500. More iterations give you a

700.

3.0E-5. Increasing

the spring constant creates more compact diagrams by increasing the spring attraction. For example, e nter

2.0E-6 and click Layout Diagram

to apply the settings.

2-33

2 Building SimBiology

Models

The layout should resemble the following diagram.

7 In the Lin

default i Compress

10.

8 In the Repulsion Limit box, specify the maximum repelling distance that

limits the distance at which blocks repel each other. The default is

eSpringLengthbox, specify the length for each line. The

0.0, indicating that force due to the spring is 0 at this length.

this length to push the blocks further apart. For example, enter

400.0.

Settingthistoalargedistancecauses all blocks to repel each other. This spreads the diagram out. A smaller value allows on ly nearby blocks to repel, creating a more uniformly filled diagram. For example, enter

9 In the Refresh Rate box, enter t h e rate (in milliseconds) at which the

diagram is updated during layou t. The default is

500 and click Layout Diagram to apply the settings.

10 Clic

11 In the Diagram View pane, right-click the DNA species blo ck and select

k Close to close the Diagram Properties dialog box.

1000. For example, enter

200.

Split Block.

12 In the Diagram Table View pane, clear the Pin check b ox es for the

Transcription Reaction block and the mRNA Species block.

2-34

Modeling Using the SimBiology®Diagram

13 From the Diagram menu, select Layout All Elements or Only the

Selected Elements. Your diagram should resemble the followin g diagram,

but may be different depending on the diagram layout before you applied automatic layout.

How the SimBiology Desktop Does Diagram Layout

The automatic layout feature in the SimBiology desktop arranges blocks using a simple “force directed” algorithm.

Every block is affected by three forces:

• Edges of the diagram repel blocks.

• Blocks repel each other.

• Lines between blocks act as springs that draw blocks toward each other.

The a lg orithm tries t o minimize the sum of these f orce s. In each iteration, the SimBiology desktop calculates the total force on each block. The diagram then moves each block in the direction of and proportional to the force acting on it. Two adjustable parameters control the dynamics of the layout:

2-35

2 Building SimBiology

Models

• The number of iterations that are taken determines how long the layout

takes and thereby how well it can do.

• The maximum distance constrains the distance that any block will be

moved in one iteration. A small value makes layout progress go slowly. A large value may cause oscillation in the layout.

Three adjustable parameters influence the layout of the diagram:

• The spring constant controls how strongly the lines between blocks pull

blocks together. Increasing the spring constant creates more compact diagrams as the spring attraction dominates the repulsion between blocks.

• The spring length controls the “natural length” of the lines between

blocks. The force due to the spring is zero at this length. W hen a spring is compressed to less than this length, it pushes the blocks apart.

• The maximum repelling distance limits the distance at which blocks repel

each other. Setting this value to a large distance causes all blocks to repel each other. This spreads the diagram out. A smaller value allows only nearby blocks to repel, creating a more uniformly filled diagram.

2-36

Printing and Exporting the Diagram

You can annotate and print your pathway d iagram, or you can export the diagram to the diagram with the name of the author, the date, notes, and name of the organization. You can choose to place the content as a header or footer o n the diagram page.

Printing a Diagram

Right-click in the SimBiology diagram and select Print to open the Print dialog box and print the diagram. By default there are no annotations. However, if you previously annotated the diagram using Diagram Print

Setup, the printed document contains the annotations. You can access Diagram Print Setup from the d iagram’s right-click (context) menu.

To annotate and print a diagram:

1 In the Diagram View pane, right-click the background of the diagram

and select Diagram Print Setup.

.svg, .jpeg,or.pdf file formats. For example, you can annotate

Modeling Using the SimBiology®Diagram

The Diagram Print Setup dialog box opens.

2 In the Diagram Options tab, do the following:

a In the Scale box,selectthesizetoadjustthediagramto(100%isthe

default size). Alternatively, click the Fit diagram to button and specify the desired width and he ig ht.

b Clear the Print frame around diagram check box if you do not want

a frame in the printed document.

3 Click the Page Annotation tab.

4 Click Edit. The Customize Page Annotation dialog box opens. This dialog

box lets you enter and store customized informatio n for print annotation.

a In the relevant fields, enter the name of your organization and your

name.

b From the Date Format and Page Format lists, select the date and

page formats respectively.

c Click OK.

5 Place the cursor in a Header or Footer box and click Author,

Organization, Model,orDate.

The SimBiology desktop inserts the information entered in the Customize Page Annotation dialog box. Alternatively, you can type information into each field.

6 In the Diagram Notes box, enter notes to be included.

7 From the notes location list, select whether to include notes in the printout,

and the location. You can also choose to include the notes only on the first page.

8 Click Close to exit the Diagram Print Setup dialog box.

Alternatively, click Print to open the Print dialog box and print the diagram.

2-37

2 Building SimBiology

Models

Exporting a Diagram Image

You can export the image of a pathway diagram in a portable file format for use by other software such as the Microsoft SimBiology desktop exports the graphical representation of the model.

1 In the Diagram View pane, right-click the background of the diagram and

select Export Diagram As.

The Export Diagram As dialog box opens.

2 From the File type list,specifythetypeoffiletoexport.

3 Click ... (Browse) to choose the file location.

4 In the File name box, specify the file name.

5 Keep the default selection for the Preserve aspect ratio check box to

preserve the width and height ratio of the diagram.

6 (Optional) Specify the desired width and height of the image in inches, in

the Width and Height boxes respectively.

PowerPoint®application. The

2-38

7 Click OK to export the file.

Modeling Using the Command-Line Interface

Modeling Using the Command-Line Inter face

In this section...

“About This Example” on page 2-39

“Creating a SimBiology Model” on page 2-39

“Adding the Reaction for Transcription” on page 2-41

“Adding the Reaction for T ranslation” on page 2-42

“Adding the Reactions for Gene Regulation” on page 2-42

“Adding the Reactions for mRNA and Protein Degradation” on page 2-43

“Simulating the Model” on page 2-44

“Simulating the Model with a Stochastic Solver” on page 2-46

About This Example

This section shows how to model a simple gene-regulation pathway using the command-line i nterface. For more information about this model, see “Gene Regulation Model” on page 2-2.

You can also use a graphical user interface (see “Modeling Using the SimBiology Graphical User Interface” on page 2-8 and “Modeling Using the SimBiology Diagram” on page 2-16). A comparison of the three methods will help you understand the model objects that are created, how to access and edit a model through the MATLAB Command Window, and enable you to determine the workflow of your preference .

Creating a SimBiology Model

A SimBiology model is a collection of objects that are structured hierarchically. At least one mo de l object is needed to contain all the other objects.

1 Create a model object. For example, to create a model with the name cell,

in the MATLAB Command Window, type

Mobj = sbiomodel('cell')

2-39

2 Building SimBiology

Models

MATLAB creates a model object (Mobj) in the workspace and displays a summary of the objects in the model.

SimBiology Model - cell

Model Components:

Compartments: 0 Events: 0 Parameters: 0 Reactions: 0 Rules: 0 Species: 0

2 Display all the model object properties by typing

get(Mobj)

MATLAB displays a list of properties for the model object and their current values.

2-40

Annotation: ''

Events: [0x1 double]

Name: 'cell'

Notes: ''

Parameters: [0x1 double]

Parent: [1x1 SimBiology.Root]

Species: [0x1 handle]

Compartments: [0x1 double]

Reactions: [0x1 double]

Rules: [0x1 double]

Tag: ''

Type: 'sbiomodel'

UserData: []

Some of the model properties are themselves objects or arrays of objects.

3 Add a compartment named contents to the model.

compObj = addcompartment(Mobj, 'contents');

All models must contain a compartment. You can either add a compartment and specify its name (as shown here), or you can let the process of adding a

Modeling Using the Command-Line Interface

reaction automatically create a default compartment (unnamed) and add the reaction species to that compartment. You can rename the compartment later.

If there are multiple compartments in the model, you must specify the reactants and products using qualified names (

compartmentName.speciesName). For example, nucleus.DNA denotes the

species

DNA in the compartment nucleus.

This example contains only one compartment.

Adding the Reaction for Transcription

A simple model of transcriptio n shows only the DNA and mRNA. For more details, see “Transcription” on page 2-3.

1 Enter the reaction DNA -> DNA + mRNA with reaction rate equation

v=k*DNA.

Robj1 = addreaction(Mobj, 'DNA -> DN A + mRNA'); Kobj1 = addkineticlaw(Robj1,'MassAction');

The property KineticLawName is set to 'MassAction'.Becausethe reaction is enough information to determine the rate equation, the property

Expression is set to 'MassAction' and the reaction rate expression is

assumed to b e

'k*DNA'.

Since this example has only one compartment, you need not specify the compartment to which each species belongs. If there are multiple compartments, here is an example of the reaction syntax:

Robj1 = addreaction(Mobj, 'nucleus.DNA -> nucleus.DNA + cytoplasm.mRNA');

nucleus and cytoplasm are the names of the compartments.

2 Definethereactionrateconstantk1=0.2. For a first-order reaction, the

property defining. First create a parameter object named parameter object name to set the rate constant in

ParameterVariableNames has a single rate constant that needs

k1, and then use the

ParameterVariableNames

to that object.

Pobj1 = addparameter(Kobj1, 'k1', 0.2);

2-41

2 Building SimBiology

Models

set(Kobj1, 'ParameterVariableNames', 'k1');

3 Enter the initial amount for the species DNA= 50 and mRNA = 0.Selectthe

species using the function

Sobj1 = sbioselect(Mobj, 'Type', 'species', 'Name', 'DNA'); set(Sobj1, 'InitialAmount', 50);

sbioselect, which returns an object.

The value for mRNA defaults to 0.

4 Check the initial amounts for the species.

Mobj.Species

MATLAB displays a summary list.

SimBiology Species Array

Index: Compartment: Name: InitialAmoun t: InitialAmoun tUnits: 1 contents DNA 50 2 contents mRNA 0

2-42

Adding the Reaction for Translation

A simple model of translation shows only the mRNA and protein product. For more details, see “Translation” on page 2-4.

1 Enter the reaction mRNA -> mRNA + protein with reaction rate equation

v = k*mRNA.

Robj2 = addreaction(Mobj, 'mRNA -> m RNA + protein'); Kobj2 = addkineticlaw(Robj2,'MassAction');

2 Definethereactionrateconstantk2.

Pobj2 = addparameter(Kobj2, 'k2', 20.0); set(Kobj2, 'ParameterVariableNames','k2');

Adding the Reactions for Gene Regulation

Transcription of DNA to mRNA is regulated by the binding of the protein product from translation to the DNA. As m ore protein is produced, the DNA is

Modeling Using the Command-Line Interface

bound with the protein more often and less time is available for transcription with the unbound DNA. For more details, see “Gene Repression” on page 2-4.

1 Enter the forward reaction for DNA + protein -> DNA_protein with a

forward reaction rate equation

= K3r*DNA:protein

Robj3 = addreaction(Mobj, 'DNA + pro tein -> DNA_protein'); Kobj3 = addkineticlaw(Robj3,'MassAction'); Pobj3 = addparameter(Kobj3, 'k3', 0.2); set(Kobj3, 'ParameterVariableNames', 'k3');

2 Enter the reverse reaction.

Robj3r = addreaction(Mobj, 'DNA_protein -> DNA + protein'); Kobj3r = addkineticlaw(Robj3r,'MassAction'); Pobj3r = addparameter(Kobj3r, 'k3r', 1.0); set(Kobj3r, 'ParameterVariableNames', 'k3r');

v = K3*DNA*protein and a reverse rate v

Adding the Reactions for mRNA and Protein Degradation

Protein and mRNA degradation are important reactions for regulating gene expression. The steady-state level of the compounds is maintained by a balance between synthesis and degradation reactions. Proteins are hydrolyzed to amino acids with the help of proteases, while nucleic acids are degraded to nucleotides.

1 Enter the reaction for mRNA degradation to nucleotides.

Robj5 = addreaction(Mobj, 'mRNA -> n ull' ); Kobj5 = addkineticlaw(Robj5, 'MassAction'); Pobj5 = addparameter(Kobj5, 'k5', 1.5); set(Kobj5, 'ParameterVariableNames','k5');

2 Enterthereactionforproteindegradationtoaminoacids.

Robj6 = addreaction(Mobj, 'protein -> null'); Kobj6 = addkineticlaw(Robj6,'MassAction'); Pobj6 = addparameter(Kobj6, 'k6', 1.0); set(Kobj6, 'ParameterVariableNames','k6');

2-43

2 Building SimBiology

Models

Simulating the M

After you create simulate the dyn

1 Get a listing of

cs = getconfigset(Mobj)

the model, e nte r reactions, and set paramete rs, you can amic behavior of a model.

the configuration set attached to the model.

odel

The configuration set object defines the parameters needed for a simulation.

MATLAB displays a listing of the configuration set property values.

Configuration Settings - default (act ive)

SolverType: sundials StopTime: 10.000000

SolverOptions:

AbsoluteTolerance: 1.000000e-006 RelativeTolerance: 1.000000e-003 SensitivityAnalysis: false

RuntimeOptions:

StatesToLog: all

CompileOptions:

UnitConversion: false DimensionalAnalysis: true

2-44

SensitivityAnalysisOptions:

InputFactors: 0 Outputs: 0

To change simulation stop time you can use the following syntax:

set(cs, 'StopTime', 8.0);

Inthisexampleleavethestoptimeatthedefault(10.0)

2 Run the simulation.

[t_ode, x_ode] = sbiosimu late(Mobj, cs);

Modeling Using the Command-Line Interface

3 Plot the results.

figure; set(gcf, 'color', 'white'); plot(t_ode, x_ode(:,1:4)); title('Gene Regulation'); xlabel('Time (seconds)'); ylabel('Species Amounts');

MATLAB plots a figure with the simulation results. Note that you can interactively add annotations to the plot as shown in the figure below:

Mathworks SIMBIOLOGY 3 Installation Guide

Specifications and Main Features

Frequently Asked Questions

User Manual