1. Requirements

ChemChains is a platform independent command-line software written in C++, that has been tested on Linux and Windows platforms.

To run ChemChains in Windows, a Linux-like environment is necessary. You can use a freely available Cygwin (see below).

2. Installation

2.1. Download

1. Download ChemChains package from here and save it to your desktop.
2. Unzip the package to your desktop (you can unzip the package anywhere on your computer, but this tutorial assumes the location of the ChemChains directory on your desktop)

2.2. Linux

1. Open a new terminal window
2. Change to the unziped ChemChains directory on your desktop
3. Type "make" to compile ChemChains (This should create an executable file called ChemChains)

2.3. Windows

2.3.1. Installing Cygwin

1. Go to here and click on "Install or update now!" link. (The Cygwin installation wizard will come up)
2. File download manager will pop up. Select Run.
3. Select Install From Internet and hit next
4. Select the root directory. For this tutorial, select a directory on your Desktop as the root directory. E.g., "C:\Documents and Settings\yourUsername\Desktop\cygwin" (A message will pop up, saying that you should not choose a path that contains spaces. Proceed anyway. Once you're familiar with Cygwin, you can reinstall Cygwin in a different directory)
5. Select the package directory (this is where it the installation files are kept); for this tutorial, use your Desktop location (which should be selected by default). Click next.
6. Select your connection type (Direct connection should suffice). Hit next.
7. Select the location to download packages from (you can use ftp://ftp/gtlib/gatech.edu which has been faster than others in our case).
8. The package list interface will come up to select packages to install. To compile and run ChemChains the following packages are necessary from the Developer package IN ADDITION TO the ones preselected by Cygwin: binutils, gcc-g++, and make packages
9. Hit next. The installer will download and install the selected packages. This may take a while, depending on your Internet connection speed. (If anytime in the future a new package needs to be added the Cygwin installer can be re-run and additional package(s) selected.)
10. Click Finish once the installation is completed. This will create a shortcut on your Desktop.

2.3.2. Running Cygwin & Setting up ChemChains

1. Unpack ChemChains onto your Desktop and copy/move the ChemChains directory into the Cygwin\home\username\ directory (the cygwin directory should be on your Desktop as the instructions above suggested). This is also where your simulation results will be stored.
2. Start Cygwin by clicking on the Cygwin shortcut on your Desktop. When Cygwin is launched you will begin in the default directory, /home/yourUsername/.
3. Type in 'cd ChemChains1.0_clean' and press ENTER to get to the ChemChains directory
4. Compile ChemChains by typing 'make' and pressing ENTER.

Congratulations!! ChemChains is now installed and ready for your first simulation!

Some basic Unix commands
There are a couple useful commands for working in a Unix environment:

1. ls - shows the contents of the current directory
2. mkdir [name] - makes a new directory named [name]
3. cd [name] - changes directory to [name], if you use .., it will take you up a directory

3. Basic How-to

3.1. Introduction

This section will provide you with the most basic ways of simulating your first network model using ChemChains.

To run ChemChains, users must provide several input files. Once simulations and/or analysis are initiated, ChemChains will create several types of output file formats. Both the input files, as well as the desired output format and the output files must be specified by users in the form of command-line parameters provided to ChemChains at the time of program initiation. To see all available options and command-line parameters run ChemChains with the -h flag. All flags available in the most recent version of ChemChains are described in Table 1.

3.2. Input Files

To simulate logical networks with ChemChains, two input files are required: the network descriptor file and simulation specification file (additional input files may be required for individual running modes.

3.2.1. Network Descriptor

Network descriptor is a syntax-specific text file that stores the network, and logic for each node.

(The following example of a simple toy network is included with the current ChemChains release and can be found in "inFiles/CChain/logic/sampleNet.txt" file in the ChemChains directory)

Figure 1: Sample network.

As an example, let's assume a toy network (Figure 1) consisting of nodes A, B, C, and external input IN1, where green line (with an arrow) denotes positive regulation (e.g., activation) and red line (with a stop line) denotes negative regulation (e.g., inhibition). Because we're dealing with a boolean network, each node has an activation mechanism (represented by truth tables) associated with it. As an example, the activation mechanisms for the nodes of this network are as follows:

• Node A: Node A is activated by node C.
• Node B: Node B is inhibited by node A and activated by node C. In addition, node C is a required positive regulator. The negative regulation is dominant over the positive one.
• Node C: Node C is activated by input node IN1 and node B.
• Input node IN1: this node is an input node and hence has no input.

These activation mechanisms can be expressed as individual truth tables (Figure 2).

Figure 2: Truth tables for nodes A, B, and C, representing the sample network in Fig. 1

Once the network and truth tables are established, they can be used to create the network descriptor file. Use the following syntax to create the file:

Bool:name:initial state[True|False]:input1,input2..inputN:list of 
states of input nodes for non-initial state(separated by comma)

Thus, the network descriptor for our toy network can look like:

Note: The declaration of each node is on a new line.

Once finished, save the file as inFiles/CChain/logic/myNetwork.txt or just use the sample network descriptor provided in the current release as mentioned above.

3.2.1.1. Flag to Specify the Network Descriptor File

The next section describes how to create the simulation specification file.

3.2.2. Simulation Specification file

ChemChains is a feature-rich logic network simulation software, which offers users many advanced simulation options. These options are specified by users in the specification file, the second of the required input files, that is loaded into the program before each simulation experiment.

(The following example of a simple simulation specification file is included with the current ChemChains release and can be found in "inFiles/CChain/specs/sampleSpecs.txt" file in the ChemChains directory)

The following describes the various options contained within this file:

• Runtime - specifies the overall length of each simulation, as well as the number of iterations (transient time) before any analysis is conducted.

Syntax: RunTime:TransientTime:TotalTime

For our example, we'll set the total time to 100 iterations and transient time to 70 as follows:

• Inputs - external inputs (IN1 in the above toy network)

Syntax to declare an input:

Input:name:initial/default value:random(R)/fixed(F):
noise(N)/fixed/(F):time to be introduced:dose (in percentage):
duration of the dosage

Note: Each input needs to be declared on a new line.
Note: All parameters are case sensitive.

• Name -self-explanatory
• Initial/Default value - True or False
• Random(R)/Fixed(F) - this parameter specifies whether the percentage ON should be as specified by the user or generated randomly
• Noise(N)/Fixed(F) - specifies whether the input will be set on a periodic cycle or randomly bounce around within a given range (see Noise below)
• Time to be introduced - time when a given percentage ON will come into an effect
• Dosage - specified percent ON for a given input (integer from 0 to 100)
• Duration of the dosage - the number of iterations the dosage amount will be exerted on the input (note that if the duration is shorter than the total runtime, the input will be set to 0% ON once the duration period is achieved)

To declare input IN1, with True as the initial condition, fixed percentage activity on a periodic cycle set to 10%, and effective for the entire simulation length add the following line in the specification file:

• Noise

To measure the current level of activity for each input during a simulation, ChemChains uses a sliding window (user pre-defined length) approach which allows the program to know whether the activity is within the desired percentage ON. In this example we'll set the sliding window to 5. Syntax: Noise:Window size:noise level To set the noise level as specified above, add the following line to the specification file:

• Mutation

The mutation parameter enables users to turn ON/OFF any node in the network to perform mutagenesis studies. When the node(s) is mutated, the corresponding truth table is ignored by the simulation engine and the activity of the node becomes fixed for the entire course of the simulation. For example, to turn off node A, you would add the following line to the specification file:

To mutate node A to be constitutively active, replace 'OFF' with 'ON'.

Note: The name of the delay, sustain, and output nodes has to differ from the names of their inputs.

• Delay Nodes

To create a delay node, use the following syntax:

• Sustain Nodes

To create a sustain node, use the following syntax:

• Output Nodes

Output nodes are nodes that will be printed out via ChemChains' visual mode.

To create a new output node, use the following syntax:

3.2.2.1. Flag to Specify the Simulation Specification File

3.3. ChemChains Output

Depending on which mode ChemChains is run in, different output will be generated. In general, both the visual and calculation modes will create and save their output in a directory called 'CCOutput' that will be created (if it already doesn't exist) in a directory directly above the directory with ChemChains software. Refer to the Running Modes section on detailed description of output generated by ChemChains.

3.4. Running Modes

The most recent version of ChemChains can be ran in three modes, one of which is a network construction mode (or File Conversion) and the remaining two are simulation modes.

3.4.1. File Conversion Mode

As mentioned above, to run ChemChains, a file with the network description is required. This file can be created manually as described in the previous section, or automatically from a provided set of truth tables for individual nodes.

These truth tables need to be in the form of a tab-delimited text file. Each table must be in a separate file which should be named the same as the name of the node of interest.

Thus, for the toy network (Figure 1) with truth tables as shown in Figure 2, create a new directory called "sampleNet" in "inFiles/exts/FileConverter", and three text files (A.csv, B.csv, and C.csv) with the truth tables in tab-delimited format and save them in the "inFiles/exts/FileConverter/sampleNet" directory.

In addition, we need to create another file with the list of nodes comprising our network. In this file, each node has two properties, nodeID and initial value, associated with it. Each node and its properties need to be on a new line. The mentioned node properties need to be tab-separated.

The syntax is as follows:

Note: If the initial value is False (i.e., 0 ) we can leave the third column empty.

Sample node list for our network will look like:

Save the file as sampleNodelist.txt.

To create the Network Descriptor file from existing truth tables, run ChemChains with the following parameters:

./ChemChains -TT2ND 
-inodelist inFiles/exts/FileConverter/sampleNodeList.txt 
-itables inFiles/exts/FileConverter/sampleNet
-o outputFileName.txt

3.4.2. Visual Mode

Although, ChemChains is a command-line program, it can output visual simulation results via its visual mode. To run ChemChains in visual mode, use the “-vis” flag. To simulate the toy network using the simulation specification file both created in the previous sections run ChemChains as follows:

./ChemChains -ilogic inFiles/exts/CChain/logic/sampleNet.txt 
-ispecs inFiles/exts/CChain/specs/sampleSpecs.txt 
-vis myFirstSimulation.txt 

Note: Make sure that you have created at least one output node in the simulation specification file!

Once the simulation finishes, a new file will be created in the ChemChains output folder, in a text file called “myFirstSimulation.txt”.

Open the text file and we should see output similar to the Figure 3. ('*' denotes the active state of the node, while '.' represents the OFF state)

Note: When running in the visual mode, ChemChains can run only one simulation at a time. To run multiple simulations in an automated fashion, run ChemChains in calculation mode.

3.4.3. Calculation Mode

Calculation mode provide ChemChains users the ability to run thousands of automated simulations and subsequently use the generated data to analyze the dynamics of the simulated model.

To run ChemChains in the calculation mode, use the '-calc' flag.

You can run ChemChains (using our previously created network descriptor and simulation specification files) in the calculation mode in the most basic way (without the use of any extensions) as follows:

./ChemChains -ilogic inFiles/CChain/logic/sampleNet.txt 
-ispecs inFiles/CChain/specs/sampleSpecs.txt 
-n 5 -calc myFirstCalcSimulation 

This command will simulate our toy network five times and will save all output in CCOutput/stats/myFirstCalcSimulation folder.

The following table describes the structure and contents of the output folder.

3.4.3.1. Patterns Analysis

To perform patterns analysis, ChemChains must be initiated in the calculation mode (as described above), and using '-patterns' flag. When using patterns to perform analysis, two additional input files are required: i) the settings file and ii) a text file with a list of nodes that will undergo the pattern analysis.

• Settings File

The patterns settings file defines activity ranges that will form patterns.

For your convenience, a sample settings files has already been created. You can find it and edit it in inFiles/exts/Patterns/settings.txt. The file contains two groups of settings: i) default settings that are applied on all nodes subjected to patterns analysis and ii) node specific settings that apply to only one node at a time. The syntax is as follows:

Default settings:

default:lower_limit1 higher_limit1 code1,
lower_limit2 higher_limit2 code2

The sample settings provided should have the following:

which means the activity of all nodes being analyzed will be categorized into three ranges: 0-9% (all nodes in this range will be coded “0”), 10-29% (all nodes in this range will be coded “1”), and 30-100% (all nodes in this range will be coded “2”)

Node specific settings:

NodeName:lower_limit1 higher_limit1 code1,
lower_limit2 higher_limit2 code2 

• List of nodes to be analyzed

An example of this file is also supplied with the latest ChemChains release, and is located in inFiles/exts/Patterns/sampleOutNodes.txt. In this file, each node to be analyzed with the patterns extension is entered on a new line.

To run ChemChains using these input files, type in the following command:

./ChemChains -ilogic inFiles/CChain/logic/sampleNet.txt 
-ispecs inFiles/CChain/specs/sampleSpecs.txt
-patterns -isettings inFiles/exts/Patterns/settings.txt 
-inodes nFiles/exts/exts/Patterns/sampleOutNodes.txt
-n 5 -calc myFirstCalcSimulation 

3.4.3.2. Random Initial Conditions

ChemChains can be run with randomly generated conditions for every simulation. To run ChemChains with random initial conditions enabled, use the '-randInit' flag.