Instructions for installation and running of Los Alamos Signaling Team network modeling package for linux/unix systems.
Download the code
License
James Faeder
faeder@lanl.gov
- Unpacking the archive file
Download the archive network.tgz and unzip in a suitable directory.
gzip -dc network_xx.tgz | tar xvf -
This will create the directory "network_xx", where xx is the version number.
- Compiling the program
cd to network/src. If you are running on a linux system and have the
lapack and blas libraries installed, you can simply type "make" and
the executables will be placed in ../bin. Makefiles for other systems
may be provided. As of this writing there is a Makefile for the
unix-like environment Cygwin (http://www.cygwin.com), that runs under
Microsoft Windows. You should try copying the appropriate file to
Makefile and then running make. The source for blas and lapack can be
easily downloaded from the net and compiled. You just need to set the
LIBS variable in the Makefile to link to whatever libraries you make
or have that contain the blas/lapack functions. On other UNIX
systems, some of the other compilation options will also need to be
modified. You are welcome to contact the author if you run into
problems.
- Running the 354state example.
Once the executables have been created, you can cd to the examples directory to
run the model. The program eqgen_354 generates the network input file
network.net, which contains parameters, rate constants, and initial
concentrations. It is not necessary to run this program or the related
signal_groups, since the text files generated by these programs are in
Models/354state, which refers the the model published in Refs. 1 and 2. The
easiest way to run the run_network program is through the Perl script
"netrun.pl". (Perl should be installed on an respectable Unix system.) Using
this script makes it very easy to modify input parameters and to perform more
complicated tasks. The interface to the run_network program itself is more
primitive, and you will have to look at the source code if you want to see
what options are available through command line arguments. To do a test run
of the 354 state model with the parameters given in Ref. 2, simply type
./netrun.pl 354state.in
This produces the output files
354state_start.net the initial network file generated by netrun.pl
354state_conc.dat concentrations of all 354 species at each time requested
354state_lyn.dat concentrations of Lyn-containing species
354state_rec.dat concentrations of receptor-containing species
354state_syk.dat concentrations of Syk-containing species
These should match with the output in the files 354state_check_*. If not, there may have been an error in the compilation, and the results of the program may not be reliable.
- Simulation basics
Let's now look more closely at the files and programs that were involved in
running the simulation. By modifying the contents of these files it is
possible to have control over virtually all aspects of the simulation.
Here are the files that are used:
netrun.pl
run_network
354state.in
network.net *.groups
Here are the files that are created:
354state.log
354state_start.net
354state_conc.dat
354state_{rec/syk/lyn}.dat
There are quite a few files, so I will go over each of them in turn to describe how they are used and what data they contain.
The netrun.pl script
netrun.pl is the perl script that reads the primary input file, 354state.in, and sets up input to the simulation program run_network, which is assumed to be contained in the directory ../bin. It is easy to change this location by modifying the $program variable in netrun.pl or in the .in file. After reading the primary input file, netrun.pl writes the network file, named by default ${prefix}_start.net (${prefix} for our example is 354state), and then runs run_network setting all of the various input flags and parameters. The key advantage to the user in using netrun.pl instead of directly running run_network is that it makes it much easier to modify input parameters and control the simulation.
The netrun.pl input file (354state.in)
The input file 354state.in is itself a perl script that is read as input to the netrun.pl script. It is not necessary to understand much perl to modify the input file in order to do a number of different things. The key points to know are that scalar variable names in perl start with a '$', while array names start with '@'. Every statement must end with a semicolon (like in C). The '#' character indicates a comment, and everything that follows on a line will be ignored. Variables that are set in the input file will be retained in netrun.pl, so it is possible to change all of the control parameters in the netrun.pl script that are listed above the line "# Read command line options" in the script. There are two basic types of parameters that can be set in the input file: parameters that affect netrun.pl and parameters that are defined inside the network file network.net. The first type are general to all simulations, while the second are specific to the chemical network being simulated. Note that no care has been taken to avoid conflicts in the name space of the two parameter types, so in setting up the network file one must take care to avoid using parameter names for the rates or concentration parameters that are used in netrun.pl. Examples of the first type include @sample_times, $netfile, and @groups, while some parameters specific to the 354state simulation are $rtot, $ligtot, and $recstart. Parameters controlling netrun.pl are described further either in 354state.in or in the netrun.pl script itself. I will now describe in more detail how to set network parameters in the netrun.pl input file in the course of describing the structure of the network file itself.
The network file (network.net)
The network file consists of four block that specify (in order) parameters, species, rates, and reactions. Each block begins with a "begin x" command and ends with an "end x" command, where x is one of the four components. Any characters outside of the blocks are ignored and can be used for comments. Within each block, each entry is listed on a separate line and spaces or tabs are used to separate the entry columns.
parameters
The parameters list is optional and can be used to make it easier to control the way species concentrations are specified. Each parameter declaration takes the form
index parameter_name value
where the index is optional, but often useful for editing purposes, parameter_name can contain any non-whitespace characters (but avoid '$' and '@' for obvious reasons), and value is a numerical value. In the 354state simulation the total number of each of the four basic components, ligand, receptor, lyn and syk is specified by a parameter, i.e. rtot, lyntot, etc. Three additional variables set the initial equilibrium partitioning of lyn among free and bound (to receptor) states. The values of these variables given in the network file can be overriden in the netrun.pl input file. For example, the declaration
$lynstart= 1.0 - $x/$lyntot;
in 354state.in supercedes the value of 1 in network.net, as can be seen by examining the parameters block 354state_start.net, where lynstart is set to 5.087473219525526e-01.
species
The species list is required and both defines the chemical species in the network and sets their initial concentrations. Species may be declared in two ways
index species_name abolute_concentration
or
index species_name relative_concentration normalization
where the values of the initial concentrations and normalization may be either numerical or parameter names. The index is not strictly required, but is highly recommended since the index assigned to each species is used to reference that species in the reaction list. Note that the definition of units is completely the responsibility of the user, any consistent set of units may be used. For the 354state simulation, all concentrations are given in terms of the number of molecules per cell. In this simulation all of the species are normalized depending on the compartment to which they belong, ligand, lyn, syk, or receptor. Keep in mind that the output files 354state_conc.dat, etc. report the absolute concentration values, i.e. the relative concentration times the normalization, which in the case of the 354state simulation gives the number of molecules per cell. When numerical values are used to set the initial concentration or normalization these values cannot be modified in the input file to the netrun.pl script.
rates
The rates list is required and defines the values of the rate constants used in specifying the reaction network. Rate declarations have the following format
index rate_name value
where index is again optional, rate_name is the name of the rate constant, and value is a numerical value only. Parameters are not used in rate constant declarations, since rate constants themselves are considered parameters. Rate constant values can be modified within the netrun.pl input file either by setting a perl variable with the same name, e.g.
$kp1= 2e-10;
or by setting a line in the variable $rates. To see how this is done in perl, see 354state.in.
reactions
The reactions list is required and defines the chemical reactions and their governing rate constants that make up the chemical reaction network. The format is
index reactant_list product_list rate_constant
where index is again optional, the reactant and product lists are comma delimited lists of chemical species indices, and the rate_constant can be referenced either by name or by index. In addition, a prefixed numerical value followed by a '*' can be used to multiply the rate constant. This is useful, for example, when there is a symmetry factor that governs a reaction. For example, the declaration in network.net
1 1,7 8 2*kp1
specifies the reaction between a free bivalent ligand (species 1) and a free receptor (species 7), creating a complex of recptor and singly-bound ligand (species 8). Since there are two equivalent sites on the ligand, the rate of this reaction is double the elementary rate kp1.
The group files (*.groups)
The groups files specify groups of chemical species to be summed over in computing various quantities, e.g. the number of phosphorylated beta subunits. Groups are defined a block that begins with the line "begin groups" and ends with the line "end groups". The format of each group entry is
index(optional) group_name species_list
The species list is a comma-separated list of species indices that define the group. Multipliers may be added in the same format used for reaction rate constants. See any of the group files for examples. Group files are quite useful because it would otherwise be tedious to compute most of the observable quantities of interest from the simulation. Group concentrations are computed automatically by netrun.pl using the script get_group_conc.pl to process the concentrations stored in 354state_conc.dat. The prefix of the group file, e.g. rec for rec.groups, is used in assigning a suffix to the group output file, which in this case would be 35state_rec.dat. Each line of the output provides the concentration of each group at one of the sample times. The format is time conc_group_1 ... conc_group_n Now we will look in a bit more detail at the output files.
The .log file
Details about the simulation run are printed to the .log file. It provides information about the network read from the .net file, the propagation of the ODE's arising from the network, and CPU times. In case of a crash, it also provides some information about the errors that occured (hopefully).
The _start.net file
After netrun.pl processes the input file, it rewrites the contents of the network file to $prefix_start.net, which is the file that is read by the run_network program. This allows netrun.pl to change parameter values as requested, and to do other things like remove or modify reactions and chemical species. If the results of a simulation are unexpected, this is a good place to check to make sure that the parameters you thought you had set are in fact set correctly.
The _conc.dat file
The key results of the simulation is the time course of the concentrations of the chemical species, which is output to this file in a very simple format (same as the group concentration files)
time conc_spec_1 ... conc_spec_n
The output times are the ones requested by setting either @sample_times or $n_steps and $step_length (see 354state.in). The concentrations are output in whatever units the user has used in specifying the network, and it is important to remember that absolute concentrations are used.
The group concentration files
Concentrations are also written out to files for each group listed in the @groups array (see 354state.in for syntax). In the 354state example, output is requested for rec, lyn, and syk, groups all of which have corresponding files called rec.groups, etc. The group concentrations are printed to the files $prefix_$group.dat. That's pretty much it for basic operations. After going through this example you should know how to- Construct and run a basic chemical network simulation.
- Change the values of simulation parameters in the input file for the netrun.pl script.
- Define groups of species whose concentrations are summed and output in separate files.
- Look at the simulation output in the _conc.dat and _group.dat files.
- Scanning input parameters
Using the input file to netrun.pl it is possible to change the value of any
concentration or rate parameter. Sometimes it is useful to scan a single
variable over a range of values, and doing so by hand becomes tedious. The
scripts scan_var.pl and process_var.pl help to automate this procedure.
scan_var.pl is just an augmented version of netrun.pl that takes as additional
control variables, $var, $var_start, $var_end, and $n_var, which control how
the variable is scanned. As currently implemented, scan_var.pl scans evenly
in log space of the variable, i.e. it samples the interval [log($var_start),
log($var_end)] $n_var times with even spacing starting at log($var_start) and
ending at log($var_end). This can be modified in the scan_var.pl script.
As an example, let's say we want to vary the ligand concentration from 0.1 M to 1.0 M. We could copy 354state.in to a file called scan_ligand.in, and add the follwing lines to scan_ligand.in
$var="ligtot";
$var_start=6e4;
$var_end= 6e6;
$n_var= 10;
In the scan_ligand.in file in the examples directory I also decreased the integration tolerances to make the example run faster. You can then run scan_var.pl with
scan_var.pl scan_ligand.in
which will produce a log file for the overall run and 4 output files (one _conc.dat and four group concentration files) for each value of ligtot, which is the total ligand concentration. To create a file with the ligand dose-response response curves measured at 1200 seconds, you would then type
process_var.pl scan_ligand 1200 rec lyn syk
This script assembles all of the data from the time courses produced at each ligand concentration into a single file for each group. So this command produces three files, scan_ligand_1200_rec.dat, etc., each containing the dose-response curves at 1200 s for each of the species groups defined in the groups files. The format of a line in each file is
param_value conc_group_1 ... conc_group_n
where param_value here is the ligand concentration.
An example of scanning a rate constant is given in the file scan_kmL.in, which is also an input file for the scan_var.pl script. scan_kmL.in actually scans the variable kmL*, the rate at which Lyn bound to the phosphorylated beta ITAM dissociates. It is interesting to plot the amount of autophosphorylated syk (sykPS* in _syk.dat or RecSykPS in _rec.dat) against the dissociation rate. Over about a decade range of values near the model default value (0.12 s^(-1)), the amount of SykPS increases with increasing dissociation rate. This effect is discussed in more detail in Ref. 2 under the heading "The beta ITAM can act as an amplifier or inhibitor."
References
[1] B. Goldstein, J. R. Faeder, W. S. Hlavacek, M. L. Blinov, A. Redondo, and C. Wofsy. "Modeling the early signaling events mediated by aggregation of FceRI." Mol. Immunol., 38, 1213-1219 (2002).
[2] J. R. Faeder,W. S. Hlavacek, I. Reischl, M. L. Blinov, H. Metzger, A. Redondo, C. Wofsy, and B. Goldstein, "Investigation of Early Events in FceRI-Mediated Signaling using a Detailed Mathematical Model", submitted to J. Immunol.
