IngeneueInMathematica

IngeneueInMathematica is a set of Mathematica functions that allow you to build & analyze Ingeneue networks (net files) in Mathematica.

Download:

Installation instructions:

You must have Mathematica 5 or higher installed on your computer. Mathematica is available from Wolfram Research:

IngeneueInMathematica works with Mathematica 5.2. I have not tested it under Mathematica 6+, so compatibility is not guaranteed. You should be familliar with Mathematica to use IngeneueInMathematica.

Unzip the package:
Unzip IngeneueInMathematica.zip to the directory of your choice.

Using the program:

It is helpful (but not necesisary) to be familiar with Ingeneue, upon which IngenueInMathematica is based. A manual and tutorials for Ingeneue are included with IngeneueInMathematica.

Start Mathematica. Then, load the BuildIngeneueNetwork.m and IngeneueAffectors.m files by typing the following:

<< "BuildIngeneueNetwork.m"

<< "IngeneueAffectors.m"

If these are successfully loaded, you should see a message after each is loaded:

Loaded BuildIngeneueNetwork.m
Loaded IngeneueAffectors.m

The files you have loaded contain many functions that allow for network construction and analysis. These are all in the global namespace (not part of a context) as I have found contexts require
extra unneeded typing.

To load a net file, type the following:

BuildNetwork[LoadNetwork["spg1_01_4cell.net"]];

This loads the net file spn1_4cell.net and build the system of differential equations. Ignore the Error message about the KUPTCUHH (this is a warning that the current value lies outside of the range of the specified random search). This network is a 4-cell network of the segment polarity network, as described in Tutorial 1 on using Ingeneue:

BuildNetwork sets several (usually protected) global variables that describe the network. The system of equations is in the global variable f, the node names in nodenames, etc. See the comments in the BuildIngeneueNetwork.nb file for a complete list of global variables, and list of all functions.

Parameters values & initial conditions are set to values specified in the net file.

Overview & Nomenclature

Networks are systems of ODEs (though IngeneueInMathematica can be easily extended to other types of systems) that typically describe the concentrations of the relevant biomolecules in a 1 or 2-D field of cells. The network is constructed from a network file (.net file) that specifies the biomolecules (nodes), interactions, model parameters, initial conditions, and geometry of the cell field. See the tutorials on Ingeneue for a walkthrough of the net file at:

Dependent variables (nodes) are the concentrations of the relevant biomolecules in each cell or cellular compartment. These could be mRNA, protein, or a complex. Concentrations can be either
cytoplasmic (1 compartment per cell) or membrane-bound (several compartments per cell). Parameters quantify the rates of various processes. The differential equations describe how a molecular concentration changes with time due to the influence of other regulatory partners, and is of the form:

d[node]/dt = synthesis +/- conversion +/- transport - decay

Most molecular concentrations change as the result of several processes that are independent and additive. For example, an mRNA changes as the result of transcriptional synthesis minus degradation. Most biological processes (transcriptional regulation, decay, diffusion, enzymatic activity) follow kinetics, and we provide a set of predefined functions, called affectors, that allow you to rapidly piece together a network from predefined functions. See the Ingeneue manual and tutorial 3 for an overview of nodes & affectors.

Solving & Plotting model results

Solving the system of differential equations is done through Mathematica's NDSolve. To solve the system of equations, type:

sol = SolveNetwork[];

The variable sol now contains the InterpolatingFunctions returned by NDSolve. To plot the engrailed in the leftmost cell, type the following:

Plot[Evaluate[{enC1R1[t]}]/.sol,{t,0,tend},PlotRange->All];

This will generate the plot shown below:

graph1

Nodes in different cells have the format nodenameCcolRrowSside, so enC1R1 indicates the en concentration of column 1 row 1. Indexes start at 1 in Mathematica, so this corresponds to the top left cell. The side value is used for membrane-bound nodes, it is not used for cytoplasmic nodes (such as en). Thus, to plot EWG on column 1 row 1 side 3, type:

Plot[Evaluate[{EWGC1R1S3[t]}]/.sol,{t,0,tend},PlotRange->All];

graph2

IngeneueInMathematica comes with some more advanced visualization commans similar to that in Ingeneue.

PlotCell

This command plots the concentration of all nodes in a specified cell, with colors set according to the net file. Useage:

PlotCell[solution, cell column # to plot, cell row #]

So, the following command will plot the values of all nodes in column 2 row 1:

PlotCell[SolveNetwork[], 2, 1];

graph3

DrawNetwork

This command gives a graphical indication of a node value in each cell at a specific time, similar to Ingeneue's Cell Viewer pane. Useage:

DrawNetwork [solution, nodename, time]

So, to visualize the pattern of wg at time = 500, type:

DrawNetwork[SolveNetwork[], "wg", 500];

graph4

Or, to make a movie of the pattern every 10 time units:

sol=SolveNetwork[];
Scan[DrawNetwork[sol,"cid",#]&,Range[0,500,10]];

Here are the first few graphs produced by the above line:

panels

DrawAllShown

This command calls DrawNetwork on all nodes in the system. Useage:

DrawAllShown[solution, time];

To get a snapshot of the system at time = 500, type:

DrawAllShown[SolveNetwork[],500];

graph5

Changing parameter values:

All parameters are global variables that you can change at any time. To see the current value of any parameter, just type its name. In Mathematica (unlike Java), underscores are not allowed in variable names, so underscores are replaced with U (capitol u). For example, the current value of the H_en parameter, type:

HUen

and its current value is displayed.

To display the current values of all parameters, type:

PrintParamValues[ReadParamValues[]];

graph6

To change a parameter value, just set it normally. The following command sets H_en to 100:

HUen=100;

To randomize all parameters over the range set in the net file, type:

RandomParamValues[];

Note this function is destructive: it changes all parameter values immediately upon execution. If you print the parameter values again, you'll see something different:

PrintParamValues[ReadParamValues[]];

graph7

You can read & write all parameter values simultaneously as list:

ReadParamValues[] returns the values of all parameters in the order they are specified in the net file

WriteParamValues[list of parameters] sets the values of all parameters. Again, the order of the parameters is the same as the net file.

Changing integration time & integration conditions:

The integration time is set in the global variable tend. So, to integrate to 2000 time units, type:

tend=2000;

From then on, SolveNetwork will integrate to 2000.

For very stiff systems or long times, you may need to change options to NDSolve. SolveNetwork will take options to NDSolve as optional parameter(s). If you are getting errors such as the maximum number of steps has been reached, you need to increase the max number of integration steps for NDSolve:

sol=SolveNetwork[MaxNumSteps->100000];

Will call SolveNetwork with 100000 steps (10x the default).

Writing Affectors

The affectors are Mathematica functions and are contained in the IngeneueAffectors.m file. These functions take a list of nodes, parameters, and the current cell column, row, and size (for membrane-bound affectors) They return a function that is the equation representing the rate of the process the affector represents. Affectors are called automatically by BuildNetwork[], and all affectors in a net file must be defined before the network can be solved.

It is easy to write affectors in Mathematica. See the existing affectors in the IngeneueAffectors.nb file for examples. Writing affectors in Mathematica is much faster & more flexible than Java.

Each affector takes 6 arguments as input and returns a function. The arguments are:

  1. List of strings indicating nodes used by affector
  2. List of strings indicating parameters used by affectors
  3. Integer indicating the column # of the cell being calculated
  4. Integer indicating the row # of the current cell
  5. Integer indicating the membrane side (ignored for cytoplasmic affectors)
  6. The name of the node affected.

Here is a walkthrough of the DecayAff affector, which implements 1st order decay. Suppose we're simulating decay of the EN protein (and EN is the node name), and the mean lifetime is in the parameter HUEN. This affector should return:

-ENC1R1 / HUEN

For the cell in row 1 column 1, and

-ENC2R1 / HUEN

For the cell in row 1 column 2, etc.

To do this, the affector is called with arguments that allow it to return the proper node (in the proper cell and compartment), and the relevant parameters. Basically, this function returns:

-ThisNode[#1[[1]],col, row,side]/ToExpression[#2[[1]]]

The function ThisNode[] generates the appriate node position (ENC1R1 or whatever) based on the column, row, and side information. ToExpression is called on the parameter name since it is a string, not the parameter value itself.

Depending on the affector you're writing, you may need multiple parameters and nodes, and sometimes need to find the concentrations of nodes in adjaent cells. The OppositeNode[nodename, col, row, side] returns the node value on the membrane compartment in the cell face adjacent to the specified location, useful for diffusion or intracellular signaling.

Implementation:

IngeneueInMathematica does not implement all features of Ingeneue. Iterator files are absent, but Mathematica has a powerful programming language that allows you to perform searches more complex (and with much less code) than any iterator file allows. Additionally, you have access to Mathematica's huge built in functionality: 3-D graphics, powerful statistics, eigensystem solver, etc.

IngeneueInMathematica is a fairly straightforward set of functions. It loads the net file, then parses the node names, initial conditions, parameters, and interactions. These are checked for correct
formatting. Then, the interactions section of the net file is transformed into a series of Mathematica function calls that connect affectors (mathematical function forms) and correct nodes (work out node neighbors, and instantiate all cells). Finally, ToExpression is called on the transformed string to generate the system of equations. IngeneueInMathematica is thus a bridge that transforms the Ingeneue net files into Mathematica syntax, and the remaining functions implement a task-specific language called by the transformed net file.

Global variables are used throughout this package because I found changing the namespace context led to more typing which was an obstacle to rapidly exploring & modifying networks. Experienced Mathematica users can easily wrap the functions in a context to avoid namespace collisions.

Author:

This is the work of Dr. Kerry J. Kim at the Center for Cell Dynamics. He has used this to construct numerous networks for research & teaching: Drosophila endocycle, C. elegans vulval induction network, switches, and oscillator networks. IngeneueInMathematica has also been used in large-scale simulations of evolution of the segment polarity network, where parameter values were derived from digital genotypes that were subject to mutation.

Kerry Kim can be contacted at kjkim@u.washington.edu

If you have any questions/comments/suggestions, feel free to contact the author at the address above.