Contents
  1. Introduction
  2. Global Analysis
  3. Math Models
  4. Dct Example
  5. Software

NOTE

  1. This chapter contains very detailed explanations. The actual source code for the described routines is contained in the files:

    F77L.FIG
    FUNITS.H
    FORTRAN.BAT
    MAKEEXE.BAT
    MAKEFILE
    3SIT5NE4.FOR
    3SIT5EQ4.FOR

    You may view and save these files to your local system for future use, with possible exceptions that are explained below in detail. ( Instructions for obtaining a self-extracting zip file containing these and associated files is described at the end of this chapter).

  2. In the source code for the batch files that is listed below, none of the comments in the right column are actually in the batch files, but have been placed there for clarification. Bear in mind that most of these files can be used as is; only about one page of source code actually needs to be modified. The additional documentation is presented to illustrate for for those not familiar with programming how this was accomplished.

  3. The directory names used below are arbitrary; but, they are explicitly referred to in some of the programs that follow, so any deviations should be carried through to the other programs as well, and to any Dos environment variables that are set in autoexec.bat for running F77L.

General Considerations

For general use, it is important to realize that depending on the number of sites in the model and actual experiments that are performed, the mapping numbers in column 4 and DNA template descriptors in column 5 of the data file will vary. For example, in a 4 site model column 4 numbers would be 1-4, 5-8, 9-12 etc. Consequently, for specific applications a new fortran module may need to be written describing the model and strategy for mapping sites and titrations, and subsequently compiled with the NONLIN statistics modules to create object code for linking into an executable prrogram. This can be accomplished on many computer platforms, and describing how in all environments is beyond the scope of this article. Below follows a complete description of the Dos batch files that I used to create such a program for this analysis on a 386 IBM-PC clone using MS-Dos 5.0, Lahey fortran F77L, NONLIN, and a modification of the fortran module Fx7dGDim21iEp.Ftn.

The F77L fortran suite was installed in the directory C:\F77L.

The NONLIN files were installed in C:\NONLIN.

Default settings in the one line file F77L.FIG were: 


/N0/N2/N3/N7/NA/A1/NA2/NB/NC/C1/ND/NE/NF/NH/NI/NK/NL/O/P/NQ1/R/S/NT/NV/W/NX/NZ1.
These flags determine specific features of the F77L environment (see manual for details; see also CFLAGS line in makefile described below, where it is possible to indicate if the final program is to be run on a 286 or higher cpu).

For a 3 site model, to increase the number of allowed parameters that could be estimated by NONLIN from the original 20 to 52, lines 39 and 45 in the file c:\nonlin\funits.h was modified to increase array_size and data_size definitions: 


line 39: #define array_size 52
line 45: #define data_size 52000

ASCII text files containing the modified Fx7dGDim21iEp.Ftn source code were stored in the directory C:\NONLIN\SOURCE. These were called 3SIT5NE4.FOR and 3SIT5EQ4.FOR for versions where dG5 was set not equal or equal to dG4, respectively (see "Fortran Module" section below for detailed explanation of these two programs).

Compiling and linking of these fortran modules with those of NONLIN was initiated from the Dos prompt in the directory C:\NONLIN\SOURCE by running the batch program fortran.bat. This program was created with an ASCII text editor, such as that invoked by the "edit" command from the Dos prompt. It calls for two names to be passed to it on starting the batch program, so:

fortran.bat filename.for filename.exe

was actually typed to start the program. "filename.for" contained the modified source code to be compiled and linked with the NONLIN modules, and "filename.exe" was the desired name for the final executable file that was to be created. The batch program C:\NONLIN\SOURCE\FORTRAN.BAT contained the following lines: 

        code                                       comment

cd c:\nonlin		        rem to switch to the directory c:\nonlin
copy c:\nonlin\source\%1	rem to place a copy of the source code in the c:\nonlin directory
call makeexe.bat %1 %2          rem to run makeexe.bat using names filename.for and filename.exe
copy %2 c:\nonlin\source        rem to copy the resulting filename.exe file to c:\nonlin\source
del %2.exe                      rem to remove the resulting filename.exe file from c:\nonlin
cd c:\nonlin\source             rem to swtich back to the directory c:\nonlin\source


The file C:\NONLIN\MAKEEXE.BAT, called in line 3 of FORTRAN.BAT, consisted of:




	code					comment

pause 'requires two arguments: file.for and file.exe'	rem reminder of the need for passing two arguments
del subs.for				rem to remove temporary files from prior compilations
del subs.exe				rem to remove temporary files from prior compilations
copy %1 subs.for			rem to create a temporary copy of source code to be compiled
del nonlin.obj				rem to remove temporary files from prior compilations 
del subs.obj				rem to remove temporary files from prior compilations
del nonlin.for				rem to remove temporary files from prior compilations
del subs.sld 				rem to remove temporary files from prior compilations
del nonlin.sld				rem to remove temporary files from prior compilations
call make -f makefile			rem to compile and link the source code with NONLIN mdoules
pause 'Continue?			rem notification of compiling and linking completion
ren subs.exe %2				rem to rename temporray executalbe to desired name
del nonlin.obj 				rem to remove temporary file
del subs.obj				rem to remove temporary file
del nonlin.for				rem to remove temporary file
del subs.sld 				rem to remove temporary file
del nonlin.sld				rem to remove temporary file
del subs.for				rem to remove temporary file



The file C:\NONLIN\MAKEFILE, called in line 10 of MAKEEXE.BAT, was provided with NONLIN, and consisted of:




	code				        comment

all : subs.exe				        rem See Lahey discussion of make files to fully understand this file.
CFLAGS = /W /nE /nA1 /B /I /L /nR /Z1 /O /N2 /3	rem These flags tell F77L what features to inlcude in the executable program; 
clean : 					rem for example, /3 means it will run on a 386 cpu.  See the F77L manual for
	- del nonlin.obj 			rem details.  The next lines are intended to insure a clean directory for
	- del subs.obj			        rem temporary files; the don't appear to be recognized, so similar commands
	- del nonlin.for			rem were placed in the batch file makeexe.bat described above.
	- del test.lst
	- del subs.sld 
	- del nonlin.sld
subs : subs.exe
subs.obj : subs.for makefile
	f77l subs.for $(CFLAGS)
subs.exe : subs.obj nonlin.obj
	optlink subs+nonlin,subs,nul,\f77l\graph ;
nonlin.for : nonlin.mpf nonl.mpf nonl2a.mpf nonl2b.mpf \
             tek.mpf tkplot.mpf grstra.mpf \
             ds.mpf dsplot.mpf hp.mpf hpplot.mpf \
             defalt.h funits.h opsys.h \
             makefile
	fpp -Dpc_lahey nonlin.mpf nonlin.for
nonlin.obj : nonlin.for
	f77l nonlin.for $(CFLAGS)




Fortran Module for Three Site System



The fortran module accomplishing the necessary tasks for modeling a three site system was previously developed for NONLIN to analyze the repressor / operator system of bacteriophage lambda.  These programs were written in VAX Fortran 77, for running on a mainframe computer.  Source code for the three site model, kindly provided as Fx7dGDim21iEp.Ftn by Dr. Donald Senear, University of California, Irvine, CA, was used as a template for defining models for one, two and three site systems for the Dos version of NONLIN (a subset of a four site system was also developed, but it is not described here).  The source code had to be modified to interface with the Dos version of NONLIN and to have all commands function properly in the Lahey F77L implementation of fortran.  The steps taken to make these changes and compile and link the resulting files with NONLIN will be described in detail below, so that the reader can understand exactly how he or she might similarly adapt Fx7dGDim21iEp.Ftn for his or her own research.


The module Fx7dGDim21iEp.Ftn contains the following subroutines and functions:


FUNCTION FX - defines the model to be used, reduces the number in column 4 to the lowest series to identify which site the data point describes,  maps the data point to a given titration for estimating upper and lower limits for that isotherm, and calling subroutines CROCC,  GINIT, and YBAR, selects the proper equation for Y that is to be used in analyzing the titration to which the data point belongs.


UNPAK - using the decimal in column 5 of the data file, this routine creates an array IDEST whose elements define the DNA template, indicating the presence or absence of sites 1, 2, and 3.  This array is used  by subroutine CROCC (create occupancy) to select from among all possible system states those that are relevant to the indicated DNA template (to allow building the numerator portion of the equation for Y). 


CROCC - calls UNPAK, BMULT and ICMPL to determine which sites are occupied on the indicated DNA template


GINIT - calls DIMER to calculate the concentration of dimers given the total concentration of monomers listed in column 3 of the data file,  calls CREXP to get the exponent for Y terms, and determines individual Y terms.


YBAR - determines numerator and denominator portions of Y.


DIMER - calculates concentration of dimers given equilibrium constant and momomer concentration from data file.


For  use with Lahey fortran F77L, the definition MASK in subroutine UNPAK was rewritten in code that would be understood by any implementation of fortran (originally entered as octal numbers for which a nonstandard fortran syntax was called for by VAX Fortran 77), and an additional routine for passing information about the model parameters to the Dos version of NONLIN was created.  (Changes were also made in FUNCTION FX to alter the existing three site model to a subset of a four site model that describes all possible states for including in the global analysis yet an additional point mutant that reduced but did not eliminate site 1 from the DNA template.  This work is not described here, but mentioned to indicate the feasibility of using a four site model.)  In what follows, first listed are the actual changes that were made in the fortran module, followed by a complete listing of the original and modified codes.

Changes to Fx7dGDim21iEp.Ftn



1 - Original code modified to be machine independent:



      Data Mask /1,2,4,8,16,32,64,128,256,512,1024,2048,4096,

      8192,16384,32768/




2 - Line inserted to allow equating dG13 with dG12.  If the "*" is removed prior to compilation, this command takes effect.  It assigns ANS(5) to be equal to ANS(4), which means that dG13 is being set equal to dG12, and only the latter is to be estimated from the data.  If this definition is placed into the source code, then requesting a fit to ANS(5) will result in an error in NONLIN.  When fitting the data (see below) the fitting vector should indicate ANS(5) is not to be fitted.  Likewise, ANS(6) and ANS(7) should not be fitted:



*      ANS(5)=ANS(4) 




3 - Originally, IPOINTS ran from 1 to 21; they were changed to reflect the sites titrated in this set of DNA templates. Note that IPOINT values are those found in column 4 of the data file and ans(#)'s are parameter pairs starting just after those for free energies of intrinsic and cooperative binding, plus monomer-dimer equilibrium.  These pairs thus represent the lower and upper limits for each titration, which can later be used to convert titrations to isotherms via Protection = (U-L)*Y + U, which rearranges to Y = (Protection - U) / (U-L).  To modify for a different model, the IPOINT #'s should be changed to include those of the data file, and ANS(#)'s should be changed to reflect the model being used (allow the first answers for the intrinsic and cooperativity parameters, plus one more for the monomer-dimer equilibrium constant; hence, in this case 3 intrinsic binding constants, 4 cooperativity constants, and 1 equilibrium constant means the first titration would be characterized by lower limit ANS(9) and upper limit ANS(10); ... and the 18th or last site titration by ANS(43) and ANS(44).  See also the subroutine START below.



  103  FX=YBAR(SPECIE,NSPECI,NDELG,OCCUP,ETOGR,SITE)

      IPOINT=X(2)+0.01

  IF(IPOINT.EQ.1) FX = ANS(9) + (ANS(10)-ANS(9))*FX
  IF(IPOINT.EQ.2) FX = ANS(11) + (ANS(12)-ANS(11))*FX
  IF(IPOINT.EQ.4) FX = ANS(13) + (ANS(14)-ANS(13))*FX
  IF(IPOINT.EQ.5) FX = ANS(15) + (ANS(16)-ANS(15))*FX
  IF(IPOINT.EQ.7) FX = ANS(17) + (ANS(18)-ANS(17))*FX
  IF(IPOINT.EQ.8) FX = ANS(19) + (ANS(20)-ANS(19))*FX
  IF(IPOINT.EQ.10) FX = ANS(21) + (ANS(22)-ANS(21))*FX
  IF(IPOINT.EQ.11) FX = ANS(23) + (ANS(24)-ANS(23))*FX
  IF(IPOINT.EQ.13) FX = ANS(25) + (ANS(26)-ANS(25))*FX
  IF(IPOINT.EQ.15) FX = ANS(27) + (ANS(28)-ANS(27))*FX
  IF(IPOINT.EQ.16) FX = ANS(29) + (ANS(30)-ANS(29))*FX
  IF(IPOINT.EQ.18) FX = ANS(31) + (ANS(32)-ANS(31))*FX
  IF(IPOINT.EQ.19) FX = ANS(33) + (ANS(34)-ANS(33))*FX
  IF(IPOINT.EQ.21) FX = ANS(35) + (ANS(36)-ANS(35))*FX
  IF(IPOINT.EQ.22) FX = ANS(37) + (ANS(38)-ANS(37))*FX
  IF(IPOINT.EQ.24) FX = ANS(39) + (ANS(40)-ANS(39))*FX
  IF(IPOINT.EQ.26) FX = ANS(41) + (ANS(42)-ANS(41))*FX
  IF(IPOINT.EQ.29) FX = ANS(43) + (ANS(44)-ANS(43))*FX





4 - This routine is required by Dos NONLIN to interface between the user data file and the executible program.  It tells how many parameters there are (44), and names them, in the two arrays NAME and NAMES.  Parameters 1-3 are for intrinsic free energies of binding, parameters 4-7 are for cooperativity free energies, parameter 8 is for monomer-dimer equilibrium, parameters 9 and 10 for lower and upper limits on titration 1, parameters 11 and 12 for lower and upper limits on titration 2, etc, so that parameters 43 and 44 are for lower and upper limits on titration 18.



 SUBROUTINE START(NAME,MAXP,MAXV)
  CHARACTER*4 NAME(44),NAMES(44)
      DATA NAMES /
     &' dG1',' dG2',' dG3',
 &' G12',' G13',' G23','G123',
     &'KDSN',
     &'lo1 ','up1 ',
     &'lo2 ','up2 ',
     &'lo3 ','up3 ',
     &'lo4 ','up4 ',
     &'lo5 ','up5 ',
     &'lo6 ','up6 ',
     &'lo7 ','up7 ',
     &'lo8 ','up8 ', 
     &'lo9 ','up9 ',
     &'lo10','up10',
     &'lo11','up11',
     &'lo12','up12',
     &'lo13','up13',
     &'lo14','up14',
     &'lo15','up15',
     &'lo16','up16',
     &'lo17','up17',
     &'lo18','up18'/

     MAXV=3			
     MAXP=44
     DO 10 I=1,MAXP
  10  NAME(I)=NAMES(I)
     RETURN
     END




Obtaining the Software


The source code for the modified fortran module can be viewed:

3sit5ne4

3sit5eq4


The associated NONLIN executibles have been packaged into a self-
extracting zip file called dnaseexe.zip (using 
the PKZIP software zip2exe.exe).  So that my server will allow you to download the file, I have had to name it something other than xxx.exe, hence the name dnaseexe.zip. (From MOSAIC, select 'Load to Disk' under the Options' menu before clicking on "dnaseexe.zip"; from Netscape, you will be prompted for saving the file to disk, provided that you do not have a helper application set up to launch on downloading *.zip files.) After you have downloaded the file, you should rename it to dnasezip.exe before attempting to execute it in a new directory of your choice on your local computer. By executing it one time, you will have expanded the zipped files into your directory. In addition to the NONLIN executibles, a readme.txt file and sample data files have been placed in dnaseexe.zip. The readme file is in ASCII text format, and should be read before attempting to use the programs.  These programs were compiled and linked for running on an i386 or higher PC type CPU.  For modification, or use on other platforms, the appropriate source code for NONLIN must be obtained from Michael Johnson,  Dept of Pharmacology, University of Virginia, Charlottesville, VA 22908, and then compiled and linked to an appropriate module defining the system.  


Prior Chapter