cpRivals: Model of the regulation by competing promoters. Copyright (C) 2009-2014 Lev Rubanov Copyright (C) 2009-2014 Institute for Information Transmission Problems of the Russian Academy of Sciences (Kharkevich Institute) This model has been proposed and implemented in the Laboratory of Mathematical Methods and Models in Bioinformatics of the above Institute. Head of the Laboratory, Prof. Vassily Lyubetsky This file is part of cpRivals. cpRivals is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. cpRivals is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with cpRivals. If not, see . ReadMe for cpRivals version 1.5.3.3a, released 01/05/2014 ========================================================================== This readme accompanies cpRivals, an algorithm for modeling the transcription of a locus where RNA polymerases on different DNA strands compete with each other. Such kind of regulation occurs in eg. plastome of plants and algae. This is the first release, and the model itself was not published in English yet. However, there are papers in preparation, which will be added later. cpRivals is a command line utility intended for scripting and mass modeling. It also takes advantage of MPI 1.2 (or above) for parallelization if present. Another free option at our Web page (http://lab6.iitp.ru/en/rivals/) is Rivals, user-friendly GUI application for Microsoft Windows, available as executable. You are welcome to download it too, because the application can be helpful for input data preparation and testing as well as for one-off experiments. The application also works fine on Linux under WINE after you install 'dotnet20' (MS .NET 2.0 framework), 'vcrun2005' (MS Visual C++ 2005 sp1 libraries) and 'corefonts' packages by winetricks script. Both programs have common user's manual also available at the above Web page (for the moment, only in Russian). To build cpRivals, you must have an MPI implemented in your system. In Linux environment, edit the included makefile to specify your C++ compiler with MPI support (the default is mpiCC) and run make. For Windows environment, we recommend to use Microsoft Visual C++ 2005 SP1 compiler. Create new project from existing code and add MPI include and library directories to that project. Exact operations depend on the MPI implementation you choose. To check the newly built utility, run it from the command line: cprivals -h This results in help screen describing command line parameters allowed. Such simple check does not need for working mpi environment. Both cpRivals and Rivals rely on three input data files decribed in detail in the manual. Examples of these files are included. By default, cpRivals assumes that the files sit in the program directory; you may also specify pathnames in the command line parameters. All three files are in text format; the lines starting with a semicolon or a slash are comments. These files are: 1) configuration file (.ini, default rivals.ini) contains general settings of the utility; in most cases you either should not modify them or can do that via other files and/or command line parameters; 2) task file (.tsk) contains DNA sequence and parameters of various objects located on it, such as gene, PEP and/or NEP promoter, repression site, terminator, external source of polymerases, etc. The sequence uses the same format as in NCBI GenBank (.gbk) files. We greatly recommend to use Rivals GUI application for creating and editing the task files; 3) job file (.rjb) specifies the task parameters which will be varied in the series of running cpRivals. For instance, user can try different combinations of promoter binding intensities or repression frequency or whatever. The desired record of the output file can be also specified here. The job file may include any number of lines (i.e. jobs). By default, cpRivals marks the processed job with a semicolon in the first column, thus making it a comment. Therefore, if cpRivals is cancelled (eg. because of exhausted time or a hardware failure), simply repeat the last command line - execution will be continued from the first incomplete job. cpRivals writes two output files (.log and .csv). By default, it uses the task file name for these files, but different name may be specified in the command line or the job file. The .log file contains one line per job (final outcome and time). The .csv file contains one line per trajectory (ie. run of cpRivals). This line is in CSV (comma separated value) format, but the delimiter does not need to be a comma (default is a semicolon). The values in the record are as specified in the job file. For instance, those can be transcription count for each gene of the locus under consideration. There are also options for a job file to suppress output of trajectory lines and/or to print a line per job that contains mean and/or std deviation values over whole sample of repeats. To obtain more precise results, cpRivals should be run multiple times with the same parameters, in which case each job produces multiple lines in .csv. The desired number of trajectories can be specified in the job file or the command line. It is the user choice how to post-process the output file(s). For example, in some situations he/she can directly import the .csv file into a spreadsheet. To test cpRivals in a single CPU mode with the example included, use 'make test' option, or simply run: cprivals -nompi -rjob3.rjb --j Upon completion (about 5 minutes), compare produced output files AT1*.* with included files AT1*_chk.*. Only time data in the .log may differ. To test cpRivals in a working MPI environment, use 'make testmpi' option, or run something like this: mpirun -np 8 cprivals -rjob3.rjb -runs10 -step0 -seed0 --j Here we require 8 cpu to run 10 trajectories per job (instead of 3 above), but exclude intermediate result output in the middle of a trajectory. We also stop using fixed seed value for random number generator, so several attempts may produce different results. If you have any troubles with cpRivals, please email to Lev Rubanov: rubanov@iitp.ru Sorry for having no time to translate the entire 100 pp. manual.