RNhelp.1f            October 16, 1997        Kurt W. Kohn

These directions explain how to run the reaction network simulation program (RNfb) and the graphics display program (Plotout) for the purpose of generating and displaying the data presented in Kohn KW, "Functional capabilities of molecular network components controlling the mammalian G1/S cell cycle phase transition," Oncogene,  in press (expected publication date: Dec. 1997).

------------------------------------------------------------------------------------
The RNfb and Plotout programs were written by 
   Kurt W. Kohn, Laboratory of Molecular Pharmacology,
   Division of Basic Sciences, National Cancer Institute,
   Building 37, Room 5068, NIH, Bethesda, Maryland, 20892
   Telephone:  301-496-2769    FAX:  301-402-0752
   E-mail  kohnk@dc37a.nci.nih.gov

The author hereby gives permission for free use or modification of these programs, provided that the origin of the programs is acknowledged in any future use or application, and that the author is notified of any such future modification, use, or application.  No warrantee is given or implied regarding any future use of this software.
--------------------------------------------------------------------------------

The programs run on a Macintosh computer under system 7 or higher.  An annotated copy of the RNfb program code is included.

	The program RNfb reads a reaction file that defines the reaction network to be simulated.  The reaction file also contains instructions to the program that allow several simulations to be run automatically in a single computer run.  RNfb calculates the simulations and writes the results to a file named RNtout (which the program creates).  RNfb also displays preliminary plots on the screen; in multi-plot graphs, each plot is scaled to maximum at full-scale on the same graph.
	In order to obtain properly scaled multi-plot graphs, another program, called Plotout, is run.  Plotout reads an RNtout file generated by RNfb and a DList file that contains instructions that determine which curves are to be plotted together on each graph.  The curves are plotted on the screen and the image can be saved as a PICT file.  Alternatively, the image can be saved using screen capture software.  In addition, Plotout creates a file called DLout that contains the full data for the run.  DLout also contains the values of the maxima of the plots, so that numeric values can be marked on the vertical axes of the final graphs that can be prepared by using a drawing program.

Creating a reaction file:

Following is an example that can  serve as a template for the reaction file required by the RNfb program:

---------------------------------------
Lines of text placed here are
ignored by the program. The program
begins to pay attention after a line
consisting of * is read.
*
.625, 320,60 
  1, 17,  0,  0,  1,  0,  0,  0, .05, +
  2,  1,  0,  0, 19,  0,  0,  0, 4  , +
  3,  1,  2,  0,  3,  0,  0,  0, 1  , +
  4,  3,  0,  0,  1,  2,  0,  0, 4  , +
  5,  3, 10,  0,  6,  0,  0,  0, .05, +
  6,  6,  0,  0,  3, 10,  0,  0, 10 , +
  7,  6,  0,  0,  3,  5,  7,  0, 1  , + 1
  8,  4,  5,  0, 10,  0,  0,  0, 1  , k 1
  9, 10,  0,  0,  4,  5,  0,  0, 0  , k_
 10,-18,  0,  0,  4,  0,  0,  0, 0  , s
 11,  4,  0,  0, 19,  0,  0,  0, 0  , d
 12, 12,  0,  0, 19,  0,  0,  0, 0  , d2
 13, 11, 12,  0, 13,  0,  0,  0, 1  , k1 1
 14, 13,  0,  0, 11, 12,  0,  0, 1  , k_1 1
 15, 10, 13,  0, 14,  0,  0,  0, .05, b  0.1
 16, 14,  0,  0, 10, 13,  0,  0, 10 , + 10
 17, 14,  0,  0,  5,  7, 13,  0, 1  , + 1
 18,-20,  0,  0,  5,  0,  0,  0, 1  , s1 1
  .
  .
  .
 29,  4, 13,  0,  8,  0,  0,-15, 1, =k15
 30,  8,  0,  0,  4, 13,  0,-16, 1, =k16
 31,  8,  0,  0,  7, 13,  0,-17, 1, =k17
  .
  .
  .
  0,  0,  0,  0,  0,  0,  0,  0,  0, end
   1, 0   , 0, cyD
   2, 0   , 0, cdk4
   3, 0   , 0, cyD.cdk4
   4, 200 , 0, Rb
  -5, 0   , 0, E2F
   6, 0   , 0, cyD.cdk4.Rb.E2F
   .
   .
   .
   0,  0,  0, end
scan2
5
0,4,0,0,401,50
0,0,0,0,0,0
stop
----------------------------------------

The 3 numbers on the first line below the * have the following meanings:
	The first (e.g. .625) is the time interval between plotted points.
	The second (e.g. 320) is the number of time points to be plotted.
	The third (e.g. 60) is the number of time steps to be calculated between successive plotted points.
	Thus the time interval for each calculated step is 0.625/60 and the total time covered by the simulation is 0.625*320.

Next there is a series of lines, each consisting of 8 integers, a floating point number, and a text string, all separated by commas.  Each of these lines represents a reaction.  
	The first integer serves as an index of the reaction. 
	Integers 2-4 are the identity numbers of up to 3 reactants.
	Integers 5-7 are the identity numbers of up to 3 product species. 
(The identity numbers of the reactant and product species of each reaction can be read off from the reaction diagrams in the paper.  The order in which the reaction steps are listed doesn't matter.)
	If a reactant is flagged by a minus sign, its concentration will not be decremented in the reaction, and its concentration will remain fixed. 
	Integer 8 can be an enzyme species (although this capability was not utilized in the simulations reported in the paper).
	If integer 8 is flagged by a minus sign, it has a special meaning that allows the rate constants of several reactions to be linked.  The integer (its absolute value) then refers to the index of the reaction whose rate constant is to be linked to the current reaction.
	Entry 9 (a floating point number) is the rate constant of the reaction, with the exception that, if this rate constant is linked in the manner just described, its value will be assigned by the program to be equal to the floating point number (always 1 in the current simulations) times the rate constant of the linked reaction.
	The text string at the end of each line serves as a comment and is ignored by the program, unless it is "end".
	The list of reaction steps terminates with a line consisting of 9 zeros followed by "end" (all separated by commas).

	The lines that follow set the initial concentrations of the molecular species.  Each line consists of an integer, 2 floating point numbers, and a text string (all separated by commas).
	The first integer is the index of the molecular species.  A negative flag indicates to the program that this molecular species is to be outputted to the RNtout file and to the plotting routine.
	The 2nd entry is a floating point number that is the initial concentration of the molecular species. 
	The 3rd entry is ignored by the current version of the program.
	The final entry on each line is a descriptor of the molecular species; it is used only for identification convenience.
	The list of molecular species is terminated by the line "0,0,0,end".

The next line is always "scan2" for the current simulations.

The next line consists of an integer whose value is irrelevant for the current simulations.

The next line instructs the program to carry out a series of simulations for a sequence of values of an initial concentration, a rate constant, or a time delay.  The line consists of 3 integers followed by 3 floating point numbers.
	The 1st integer indicates the type of item to be varied:
		0  -  an initial concentration
		1  -  a rate constant
		2  -  a time delay
	The 2nd integer is the index of the relevant molecular species or reaction.
	The 3rd integer indicates whether the steps are to be linear or exponential: 
0  -  linear;  1  -  exponential.
	The next 2 numbers are the initial and final values of the item to be varied.  The final number in the line is the step size.  For linear sequence, the step size is added; for exponential sequence the step size is a multiplier.
	
	The next line provides a nesting capability that was not utilized in the current simulations; the line therefore consists of 6 zeros.
	The final line is "stop".

	The reaction file must be saved as a text file.

Running the RNfb program:

1) Double-click on the RNfb.2T program icon
2) A requester window will appear.  Find and double-click on the reaction file to be used (it must be a text file).  The disk contains reaction files (prefixed "rf") for all of simulation figures in the paper.
3) The reaction and species lists will scroll by on the screen.  Whenever the program pauses (usually with a question mark), press RETURN.
4) The axes for the plots will then appear on the screen.  Numbers will appear showing the progress of the program.  

In initially testing the program, it is advisable to calculate only one or two plots at a time, so as to avoid lengthy runs.

The program will create (or over-write) a file named RNtout.
At the end of the run (if the results are of interest), it is advisable to rename this file for further use with the Plotout program.

Running the Plotout program:

1) Double-click on the Plotout.2Y program icon.
2) Follow the instructions given by the program.

Plotout will request the selection of an RNtout file (which must previously have been generated by running the RNfb program) and a DList file.  The DList file instructs the Plotout program regarding the graphs to be made and the plots to be included in each graph.  DList files for the simulation figures in the paper are included on the disk.