CompuCell3D Workshop: Module 3.3: Introduction to Network Modeling In CC3D

James A. Glazier

Biocomplexity Institute and Dept of Intelligent Systems Engineering

Indiana University

Bloomington, IN 47408

USA

References: Herbert Sauro, Systems Biology: Introduction to Pathway Modeling, for help with Tellurium visit https://tellurium.readthedocs.io/en/latest/index.html

Slides, cheat-sheets and demos available at: https://drive.google.com/open?id=1y4-EDktaZ6-e2F-8_UHtXpQlDrZW9RCp&authuser=jaglazier%40gmail.com&usp=drive_fs

Support: NIH NIBIB-U24EB028887, NIGMS-R01GM122424, NSF-2120200, NSF-2000281, NSF-1720625, NIGMS-R01GM076692, NIGMS-R01GM077138

Workshop is live-streamed, recorded and distributed

Please Upload the Telluriumv3.zip file to nanoHUB now and open it in Twedit++

Hayden emailed it to you earlier this afternoon

​

Or download it from

Student Materials\Demos\Module 3_3\Telluriumv3

​

https://drive.google.com/file/d/1j89GmLd5h_KQpwOjjuSE2wa7O95t0n3x/view?usp=sharing

​

Please get it running while I go through the next few slides

Resources for Network Modeling and Antimony

• The manuals for Tellurium/Antimony serve as a great quick tutorial: https://tellurium.readthedocs.io/en/latest/quickstart.html

​

• Herbert Sauro’s textbook: Systems Biology: Introduction to Pathway Modeling

​

​

• The Tellurium/Antimony Cheat Sheet:

There are MANY textbooks on dynamical systems, network modeling and the basic mathematical biology

Wikipedia is a great resource

Today we will very briefly review a few key ideas and start exploring some very simple models in CC3D

• https://drive.google.com/open?id=1Wp3Ri1m6rPlXc9Y8y8f6MLI421sxatFK&authuser=jaglazier%40gmail.com&usp=drive_fs

Learning Objectives

• Biology
• Types of Networks—Metabolic/Reaction, Signaling, Gene-Regulatory and Physiologically Based Pharmacokinetic Models
• Basics of Interpreting Networks as Mathematical Rate Equations
• Antimony Usage and Syntax
• Running Antimony Models in nanoHUB CC3D
• Basic Syntax of Antimony Models
• Chemical Reactions and Rate Laws
• ODE Model Specification
• Hints for Debugging Antimony

Biological Networks

• Four Main Types
• Chemical Reaction and Metabolic Networks that create and destroy chemical components of cells and tissues
• Signaling Networks that transfer information between and within cells
• Regulatory Networks that control the expression of genes and change cell types and behaviors
• Physiologically-Based Pharmacokinetic Networks that describe the transport and processing of molecules throughout the body

milliseconds to seconds

seconds to minutes

minutes to hours

minutes to hours

Chemical Reaction Networks—Representation

Chemical Reaction Formula

Chemical Reaction Diagram

Chemical Reaction Formula

Chemical reaction networks conserve mass

Real metabolic reaction rates are often faster than other network-modeled processes in cells

Mathematics of Chemical Reactions—Ordinary Differential Equations (ODE) and Reaction Kinetics

Protein Signaling Networks Function to Describe the Flow of Information and Control in the Cell

Signaling networks primarily change the states in a network of fixed structure

​

Inputs are usually one or more molecular concentrations, but the output can be a complicated phenomenon like a cell behavior

​

Signaling networks often transduce chemical concentrations outside cells into responses inside cells via transmembrane receptors

​

Receptors may or may not transport external molecules into the cell cytoplasm

​

A kinase is a molecule that attaches a phosphate group to another molecules. Often phosphorylation switches a molecule from an inactive to an active state or vice versa

​

Signaling networks usually operate faster than genetic regulatory networks and slower than metabolic networks

Protein Signaling Networks—Questions

Typical questions :

1. Does an increase in the level of a growth factor in the cell’s environment lead to the cell proliferating or dying?
2. Does changing the number of cell receptors for a signal increase or decrease the cell’s ability to migrate?
3. Does a mutation which affects the amount or binding affinity of a component of a signaling network increase or decrease the strength of the output for a given input strength?
4. How does a mutation in a network lead to changes in cell behaviors that lead to disease states?

Protein Signaling Networks

Regulatory links may be activating (excitatory), in which case a larger amount of the species at the node increases the rate of the reaction or the level of the response. Note the alternative notation, which is ambiguous

Regulatory links may be inhibiting, in which case a larger amount of the species at the node decreases the rate of the reaction or the level of the response. Note the alternative notation, which is ambiguous.

​

​

Which we interpret as

Which we interpret as

Chemical reaction links use up their substrates, while regulatory links do not

Nodes can represent molecular species or complex behaviors. Node states represent the amount or concentration of a species or the level of activity of a behavior

​

​

Links: 1) transformations of molecular species. 2) links between nodes and chemical reaction links represent regulation

​

A regulatory link indicates that the rate of the reaction link depends on the concentration or amount in the source node

​

​

Gene Regulatory Networks Describe How Cells Turn Gene Transcription On and Off

http://scienceblogs.com/pharyngula/2006/06/modules_and_the_promise_of_the.php

Gene regulatory networks change the structure of the signaling and metabolic network available to the cell

​

GRNs often control long term cell behaviors like differentiation from stem cells to differentiated cell types like neurons, or major decisions like transitions between the phases of the cell cycle

​

​

Gene Regulatory Networks—Questions

http://scienceblogs.com/pharyngula/2006/06/modules_and_the_promise_of_the.php

1. The rate of production of key molecules in different cell types or between species
2. The effect on the cell of knocking in or out or mutating a specific gene or changing gene regulation or expression
3. The existence of and changes between stable cell types by differentiation during embyogenesis, healing or cancer
4. The effect of a drug on cell type, behavior or molecular levels, e.g. to design a chemotherapeutic drug
5. The effect of a molecule on cell type, behavior or molecular levels, e.g. to predict the toxicity of a new industrial chemical

Gene Regulatory Networks—Notation

Models (and graphical notation) for GRNs focus on the transcription factors, RNAs and other molecules that turn genes on and off by binding to the DNA

https://www.thinglink.com/scene/616264922585628674

Binding of an Inducer I to the DNA for Gene P produces mRNA, which is translated into protein P. Neglects editing, transport and post-translational steps

Binding of an Inducer I to the DNA for Gene P produces protein P. Neglects translation, editing, transport and post-translational steps

Based on biotapestry standard http://www.biotapestry.org/

Analyzing Gene Regulation in Terms of Hill Functions

Often the rate of production of a gene product follows a Hill function of the level of the regulator

Gene Regulatory Networks—Motifs

Certain regulatory network structures (motifs) occur frequently and have (relatively) predictable effects

Often genes are either on (transcribed at a standard rate) or off (transcribed at a very low rate) so network behavior is approximately boolean (CC3D allows you to simulate Boolean networks using MaBoSS)

Cell differentiation states in early development of sea urchins

Physiologically Based Pharmacokinetic (PBPK) Network Models

PBPK models describe the entry of molecules into the body, their transport by the heart and circulatory system within and between organs and their transformation and elimination

PBPK Network Models—Questions

1. What is the times series of concentration of a particular molecule in a particular organ, especially in blood?
2. How does the concentration of a drug in an organ depend on weight, age, sex, cardiovascular disease?
3. How does the level of the drug differ if we swallow it or inject it?
4. How rapidly is a drug or toxin eliminated from the body?

E.g. we might want to design a cancer therapy that achieved high levels of concentration in tumors, but avoided the liver because of its toxicity. Would binding the molecule to a transporter or giving it by injection or orally, on a specific schedule help?

PBPK Mathematics

• Transfer is based on concentrations;

​

​

• Convert to mass units, transfer from blood to body;

​

​

​

​

​

18

Structurally, PBPK equations for transport are the same first-order rate equations as for Chemical Reactions, Signaling and Gene Regulation

Most Biological Problems Require Multiple Kinds of Network Working Together

Even within a single cell, most abstractions of biological process combine aspects of the four categories of network we have just discussed:

1. They include chemical transformation, like metabolic networks
2. They include activation and inhibition like signaling networks
3. They change gene activity, like genetic regulatory networks
4. They require transport of material between locations like PBPK networks

By cybertory - http://en.wikipedia.org/wiki/File:Signal_transduction_v1.png, CC BY-SA 3.0, https://commons.wikimedia.org/w/index.php?curid=12081090

Using Antimony Model Specification to add Dynamic Networks into CompuCell3D

Antimony is a model-specification language for biochemical networks that provides an extremely easy-to-learn way to specify and run network-dynamics models

​

You will often see the name “Antimony” paired with “Tellurium” or “libRoadRunner”—Antimony is the model specification language, Tellurium and libRoadRunner are software frameworks that read and execute models written in Antimony

​

In CC3D we write Antimony model descriptions in Python Steppables using Twedit++ or import them from outside sources

​

Once loaded, the models are converted into ODEs and solved by the libRoadRunner library in CC3D

​

You can also run Antimony models in Jupyter Notebooks on your desktop or nanoHUB

​

​

Help and References for Antimony

• Have documentation open in a separate window
• https://tellurium.readthedocs.io/
• Handout (“TellRoadCheatSheet”)

​

August 3, 2022

Exercise 3.3.1—Writing and Solving a Simple Chemical Reaction in Tellurium/Antimony

Note that all your simulations will have a mixture of three languages (CC3DML, Python and Antimony)

Please take a moment to download this file

​

If you are running on desktop, please open the Tellurium file, unzip it and do a “Save As” to a convenient location

​

If you are using nanoHUB, please open Jupyter Notebook

Exercise 3.3.1—Uploading Demo to Run Antimony Models Inside CC3D

We will start with a demo that allows us to very easily define run and plot Antimony models

​

We won’t discuss exactly HOW this simulation works outside of the Antimony now, so please be patient

​

You will find this zipped simulation “Telluriumv3” in the google drive in the folder

​

Student Materials\Demos\Module 3_3\Telluriumv3

https://drive.google.com/file/d/1icuPGs12HfqEMY1jAeAh8Do7L0wZ4Xdc/view?usp=sharing

Select Upload

​

Find your file Teluriumv3.zip

​

Hit Upload Again

​

​

​

​

Return to CC3D and Switch to/Launch Twedit++

​

​

Select Open Project

​

​

Exercise 3.3.1—Uploading Demo to Run Antimony Models Inside CC3D

Open Telluriumv3.zip

​

Confirm the unzip

​

Open the Telluriumv3 Simulation (it may be inside an extra layer of folder also called Telluriumv3)

​

Double click on Telluriumv3.cc3d to display the simulation code

​

​

​

​

​

​

Exercise 3.3.1—Unzipping the Code to Run Antimony Models Inside CC3D

Open Telluriumv3.zip

​

Confirm the unzip

​

Open the Telluriumv3 Simulation (it may be inside an extra layer of folder also called Tellurium)

​

Double click on Telluriumv3.cc3d to display the simulation code

​

​

​

​

​

​

Exercise 3.3.2—Using the Demo to Run Antimony Models Inside CC3D

Let’s look at the beginning of the code (Please do not worry about the details of how the rest of the code works at this point)

​

For the next few exercises, just change the Antimony code between lines 5 and 15

​

Select the variable you want to display and the colors for each variable in line 18

​

Try running the simulation and see what happens

​

​

​

​

​

Exercise 3.3.2—Using the Tellurium Demo to Run Antimony Models Inside CC3D

Let’s look at the beginning of the code (Please do not worry about the details of how the rest of the code works at this point)

​

For the next few exercises, just change the Antimony code between lines 5 and 15

​

Select the variable you want to display and the colors for each variable in line 18

​

Try running the simulation and see what happens

​

Select the Tellurium.cc3d in the navigation bar, right click and select “open in player

​

​

​

​

​

Exercise 3.3.2—Using the Tellurium Demo to Run Antimony Models Inside CC3D—Running

Switch to the Player Tab

Close the “Graphics 0” window (there are no cells to display)

​

Select “Tile” from the Windows Pull-down menu

​

​

​

​

​

​

​

​

As usual, you may have to resize the windows and joggle the bottom right corner to make nanoHUB redraw

Then run the simulation again: you should see the time series plot

We will change the Antimony code and run it in Player

​

​

​

​

​

​

​

Exercise 3.3.2—Using the Tellurium Demo to Run Antimony Models Inside CC3D—Display

Note that the cell field will be blank (since our model is not attached to any cells)

If the timescale or dot size is different, you may be running a slightly different version, don’t worry

We will look at the details of the CC3D code later, but if the version of the code you are running has a different time scale or dot size you can make the following changes

​

To match time scales:

In line 25 make sure step_size=1.0

​

​

​

​

​

To adjust the size of your dots:

​

In line 36 make sure size=8

​

​

​

​

​

WE WILL NOT DISCUSS THE DETAILS OF THE CC3D CODE NOW

​

​

​

​

​

​

Changing Dot Size and Time Scale in the Example

Player offers some useful features for manipulating scientific plots (not all will work on nanoHUB)

​

You can save the plot by right-clicking over the plot

​

Select Export

​

Select Copy to save image to clipboard

​

Or Export to save plot as an image or as a data file

​

​

​

​

​

​

​

​

​

​

​

​

Convenience Functions with Scientific Plots (Desktop Only)

Exercise 3.3.3—Changing Rate Constants in Antimony

Extensions: How do the final values and rates depend on the initial values of X and Y?

Exercise 3.3.3—Changing Rate Constants in Antimony—Results

Extensions: How do the final values and rates depend on the initial values of X and Y?

Antimony Model Syntax

Antimony syntax is extremely simple

​

Only need to know about 5 things!

Specifying a Network Model as an Antimony String in CC3D—Triple Quotes

Specifying a Network Model as an Antimony String in CC3D—Model Specification

The network model specification in the Antimony language is the text inside the quotes

​

​

Comments and Separators in Antimony

“//” and “#” specify a comment and can go in a separate line or at the end of a line

​

“;” specifies breaks between sections and can be used instead of a new line character

​

“Value:” specifies the name of a rate law or event, creating a variable with the value of the rate at any given time

If you declare two laws with the same NAME only the last one will be used

​

J1: X ->Y ; b*X ;

J1: Y ->Z ; c*Y ;

Will IGNORE the first line

Antimony’s Fundamental Concept is a Reaction

In Antimony:

J1 names the rate equation (and creates a variable to access its value)

X → Y specifies the structure of the transition (could involve many species on both sides of the arrow)

b*X specifies the transition rate (could be quite complex)

A more complex model would include more rate equations

Antimony: Arrows to Rate Laws

Antimony: Named Rate Laws

Relationship between Rate Laws and ODEs

Specifying Model Parameters in Antimony

We must specify the values for all parameters in our Antimony String

b is the rate of conversion of X to Y

c is the rate of conversion of Y to X

​

Good practice to include parameters’ units as comments

​

Add comments using “//” or “#”

​

​

Setting Initial Values of Variables in Antimony

We should specify the initial values for all variables (unspecified variables default to 0)

X is the initial concentration of X

Y is the initial concentration of Y

Dangling Arrows, Sources and Sinks in Antimony Syntax

Direct Specification of ODEs in Antimony Syntax

Reactions Specified in Multiple Lines in Antimony Sum Together

Exercise 3.3.5—Practice with Antimony—Writing Sequential Chemical Reactions

Our old code as an example

Exercise 3.3.5—Practice with Antimony—Writing Sequential Chemical Reactions—Results

Our old code as an example

Antimony Annoyances

Antimony has multiple reserved words which you CANNOT use as variable or parameter names

​

If you do, Tellurium will die with uninformative errors

​

In particular, “time” and “gamma” are reserved words, so it’s safer to name parameters something like gamma1 or delta1 rather than gamma or delta

​

Missing or extra parentheses, improper separators, etc… tend to cause Tellurium to die with uninformative errors

​

Hint for Debugging Antimony Syntax

If you find that your Antimony generates errors on model loading, your best strategy is to first comment out the complete model using “#” and make sure it loads without errors

​

Then uncomment a few lines at a time starting from the end of the Antimony model specification:

First uncomment the variable initializations

Next uncomment the parameter initializations

[If you are using events, uncomment them one at a time]

Finally uncomment the rate laws one at a time

​

This protocol is usually the fastest way to catch reserved words and unbalanced parentheses

Exercise 3.3.6—Practice with Antimony—Chemical Equilibrium

Extension: Explore what happens when you change the initial concentrations of A, B, C or D

Exercise 3.3.6—Practice with Antimony—Chemical Equilibrium—Results

Extension: Explore what happens when you change the initial concentrations of A, B, C or D

Complex Reactions in Antimony Syntax

Exercise 3.3.7—Practice with Antimony—Write a More Complex Chemical Reaction

Note that the exponentiation operator in Antimony is “^” and is “**” in Python!

Module 3.3 Questionnaire

Support: NIH NIBIB-U24EB028887, NIGMS-R01GM122424, NSF-188553, NSF-186890, NSF-1720625, NIGMS-R01GM076692, NIGMS-R01GM077138

Please take a minute or two to let us know about your experience with this module by filling out the brief zoom survey

​

Feel free to provide additional comments and suggestions in the slack or by email to us as well (hfennel@iu.edu)

​

​

​

​