%Id: README,v 1.0 2003/09/29 17:02 sugi Exp %



=== About ===

This is a sample of Genetic Algorithm (GA) written as an ESM script.

In this  sample the parameters Process:/E:Kms and Process:/E:/KcF
are estimated from observable time-courses of quantities S and P.
To consider the generalization ability of estimated parameters
two different data whose initial conditions is different are
considered simultaneously as observable time-course.


The algorithm of this sample is based on the following paper.

Kikuchi S, Tominaga D, Arita M, Takahashi K, Tomita M.
Dynamic modeling of genetic networks using genetic algorithm and S-system.
Bioinformatics. 2003 Mar 22;19(5):643-50. 


=== Files and directories ===

README                      This file
Data/						Training time-course
ga.py                       EMS file of GA
runsession.py               ESS file that is used by GA
setting.txt:                Setting file for ga.py
simple.em                   Model file (EM file) 


=== Running this script ===

1. (If necessary) Modify setting.txt file.

   Refer to the following chapter for details.


3. Run ga.py file.

     [%] ecell3-session-manager ga.py
     GA on E-Cell3 ........ start
     (10/10) .....[1]        0.235249363621
     (10/10) .....[2]        0.0452879749744
     (10/10) .....[3]        0.0452879749744
     (10/10) .....[4]        0.0038009053269
     reached max generation
     ----------------------------------------
     |   Result                             |
     ----------------------------------------
     (Evaluated Value)       = 0.0038009053269
     _KmS_   = 11.7246732589
     _KcF_   = 3.92000748822
     job id = [34]



   ga.py tries to 'setting.txt' in current working directory.
   If you'd like to use other setting file, do as below.

   % ecell3-session-manager -DSETTING=otherfile ga.py


4. See results.

   - The parameter sets of elite individual are written in 
     elite.txt. The connected files to elite individual are
     copied under elite directory. You can see the observable
     time-course data and predicted ones using gnuplot like
     as below.

     % cd elite/34
     % gnuplot gnuplot.dat

   - The transitions of evaluated value or mutation ratio are
     written in value.txt and mutation.txt respectively.
     You can see them using gnuplot as below.

     % gnuplot value.gnu


=== Detail of Setting File ===

   The properties of ga.py is written in setting.txt.
   In the file, the format of items follows, 

   KEY = VALUE

   When multiple values are specified,

   KEY = VALUE1
         VALUE2
         VALUE3

   (example) 
   TMP DIRECTORY           = work


   Only the format of the value of PARAMETERS follows,

   PARAMETERS = PARAMETER1 min max type
                PARAMETER2 min max type
                PARAMETER3 min max type

   For example, the following lines specifies the 
   
   (example)
   PARAMETERS              = _KmS_ 0.1 20.0 float
                             _KcF_ 0.1 20.0 float


=== Detail of ESS File ===

   ga.py requires ESS file to run E-Cell3 and evaluate
   the given parameters. In this sample, runsession.py is
   already prepared.
   In this file, the following procedure should be
   executed.

   1. read model file (eml).
   2. set parameters to the model.
   3. run E-Cell.
   4. evaluate the result.
   5. written evaluated value to file.

   When this script is executed by ga.py, the following
   items are replaced.

   EML KEY     -> EML FILES
   DIR KEY     -> EXTRA DIRS
   PARAMETERS  -> value

   And the evaluated value must be written as float value
   in result.dat file. After this script is executed, 
   ga.py tries to read result.dat file.

=== Resume ===

   To restart GA with pre-existing data, you should prepare
   the following file.

   PARAMETER1 = VALUE1
   PARAMETER2 = VALUE2
   ...

   (example)
   _KmS_   = 12.0
   _KcF_   = 8.2

   And you specify file name for "RESUME FILE" parameter in
   setting file.

   (example in setting.txt)
   RESUME FILE = resume.txt

   
   Finally, execute the following command.

     [%] ecell3-session-manager ga.py
     GA on E-Cell3 ........ start
     Reading resume file ... resume.txt
      [_KmS_] <--- [12.0]
      [_KcF_] <--- [8.2]
     (10/10) .....[1]        0.235249363621
     (10/10) .....[2]        0.161928244491
     (10/10) .....[3]        0.161928244491
     (10/10) .....[4]        0.122347093743
     reached max generation
     ----------------------------------------
     |   Result                             |
     ----------------------------------------
     (Evaluated Value)       = 0.122347093743
     _KmS_   = 12.0990347731
     _KcF_   = 4.37625454902
     job id = [34]


=== Debugging ===

   When you debug runsession.py, delete # in the following lines.
   
   ---- beginning of runsession.py ----
   from ecell.ECDDataFile import *
   import os

   #_KmS_ = 0.2
   #_KcF_ = 1.0
   #_DATA_ = 'Data'
   #_EML_ = 'simple.eml'
   ------------------------------------

   And execute the file with ecell3-session;

   [%] ecell3-session runsession.py


# end of README
