README file of GeneMark Suite

#====================================================================
# Copyright Georgia Institute of Technology, Atlanta, Georgia, USA
# Distributed by Gene Probe Inc., Atlanta, Georgia, USA
#====================================================================

January 2011

GeneMark Suite includes software designed for protein coding gene finding in:
	1.	Prokaryotic genomes
	2.	Metagenomes
	3.	Phages
	4.	Viruses
	5.	Intronless eukaryotic genomes
	6.	EST(or transcriptome)

GeneMark Suite was created for a large number of user  with
anticipation that the users could be interested in different functions of the package.

The major gene finding programs - GeneMark [1] and GeneMark.hmm [2]
- are included in the package as well as the programs generating
statistical models from precompiled sets of coding and non-coding
regions (MakeMat and Probuild).

The GeneMark program generates genes predictions along with
predictions of frameshifts in protein-coding regions.

Before running GeneMark one should run either MakeMat or GeneMarkS to
generate GeneMark model or download the genome specific model from 
our web site:
http://opal.biology.gatech.edu/GeneMark/modelDownload.html

The GeneMark.hmm program can be run with the models generated by
Probiuild or by GeneMarkS or with models downloaded from our web site:
http://opal.biology.gatech.edu/GeneMark/modelDownload.html

The GeneMarkS program [3] is an extension of the GeneMark.hmm program.
In addition to gene predictions GeneMarkS generates statistical models
for GeneMark.hmm (as well as for GeneMark) while using as an input
just unannotateed anonymous genomic sequence. 

GeneMarkS can be used in two modes
A/ as a statistical model generating and gene finding program 
B/ as a statistical model generating program

Option A is a convenient one for including GeneMarkS in genome annotation pipeline

The GeneMark.hmm (GeneMarkS) program is the preferred one to use 
for whole genome annotation as it has improved algorithm for predicting gene starts.

Working with short genomes:
We have developed a heuristic approach [4] for approximation of
parameters of statistical models for GeneMark and GeneMark.hmm. This
approach is used in the case when there is not enough sequence (as in
a short viral genome or in a metagenome read) for conventional
estimation of parameters of high order models. 

The set of heuristic models is provided in a separate directory and
the user has to select the heuristic model matching the G+C content
of a sequence in hand.


[1]
Borodovsky M. and McIninch J.
"GeneMark: parallel gene recognition for both DNA strands."
Computers & Chemistry, 1993, Vol. 17, No. 19, pp. 123-133
[2]
Lukashin A. and Borodovsky M.
"GeneMark.hmm: new solutions for gene finding."
Nucleic Acids Research, 1998, Vol. 26, No. 4, pp. 1107-1115
[3]
Besemer J., Lomsadze A. and Borodovsky M.
"GeneMarkS: a self-training method for prediction of gene starts in
microbial genomes. Implications for finding sequence motifs in
regulatory regions."
Nucleic Acids Research, 2001, Vol. 29, No. 12, 2607-2618
[4]
Besemer J. and Borodovsky M.
"Heuristic approach to deriving models for gene finding."
Nucleic Acids Research, 1999, Vol. 27, No. 19, pp. 3911-3920


More specific instructions on using the programs described above follow below.

Further details on the data file formats and definitions are available at the site 
http://www.geneprobe.net/products.htm

#====================================================================

GeneMark version 2.5m

USAGE:
        gm [-opt1, [-opt2, ...]] <sequence-name>

   -m <filename>
      Name of parameter matrix file to use
   -R <filename>
      Name of the RBS model file to use
   -t <number>
      Threshold value for coding potential to include ORFs/Regions into listings
      and to indicate selected regions in the PS graph by horizontal grey bars
   -s <number>
      Step size (nt) for shift of sliding window
   -w <number>
      Sliding window size (nt)
   -D data from graph and listing output in easily parseable form <*.gdata> and <*.ldata>
   -c <filename>
      Alternative genetic code (codon encoding definition file)
   -l {0,o,r,x,q}
      0: Don't create feature listing (clear flags/defaults)
      o: List open reading frames
      r: List regions
      x: List putative eukaryotic splice regions
      q: Quiet (suppress header info)
   -o {0,p,n,q}
      0: Don't write out ORFs (clear flags/defaults)
      p: Write protein translations of ORFs
      n: Write nucleotide transcripts of ORFs
      q: Quiet (suppress header info)
   -r {0,p,n,q}
      0: Don't write out regions (clear flags/defaults)
      p: Write protein translations of regions
      n: Write nucleotide transcripts of regions
      q: Quiet (suppress header info)
   -x {0,p,n,q}
      0: Don't write out putative exons (clear flags/defaults)
      p: Write protein translations of putative exons
      n: Write nucleotide transcripts of putative exons
      q: Quiet (suppress header info)
   -g {0,k,n,o,r,s,x,l}
      0: Don't produce graphic output (clear flags/defaults)
      k: Use alternative scale for graph
      n: Mark stop codons on graph
      o: Mark open reading frames on graph
      r: Mark regions on graph
      s: Mark start codons on graph
      x: Mark putative exon splice sites
      l: Print graph landscape
      f: Mark putative frameshift errors
   -e Set eukaryotic PS graph format
   -p Set prokaryotic PS graph format
   -z <number>
      Zoom factor for graph
   -v Verbose

#====================================================================

-------------------------------------------------------
Genetic Code |      11     |      4      |     1
--------------------------------------------------------
Start codon  | ATG GTG TTG | ATG GTG TTG |     ATG
(F-metionin) |             |             |
--------------------------------------------------------
Stop codon   | TAA TAG TGA | TAA TAG     | TAA TAG TGA
(translation |             |             |
terminationa)|             |             |
--------------------------------------------------------
   
#====================================================================

prokaryotic GeneMark.hmm version 2.8

Usage:
        gmhmmp [parameters ...] [sequence filename]
                Sequence file in FASTA format can have multi-FASTA sequence

Required parameters:
        -m      [filename] File with gene finding parameters

Optional parameters:

*** Output options

        -o      [filename] Output file name
                default = [sequence filename].lst
        -a      Show protein sequence of predicted genes
        -d      Show nucleotide sequence of predicted genes
        -f      [L|G] Output format: [L] LST or [G] GFF2
                default = L
        -k      Show RBS scores; this option must be first in command line

*** Prediction options

        -r      Use RBS for gene start prediction
        -s      [d|r|.] Strand to predict genes on
                default = '.' predict genes on both strands
        -p      [1|0] Gene overlap are allowed [1] or prohibited [0]
                default = 1
                [0] is used for gene finding in intron-less eukaryotic genomes

*** Developer options

        -i      [number] Probability of initiation and termination in non-coding state
                default = 0.5
        -n      Turn OFF prediction of the incomplete genes
                at sequence gaps: strings of unknown letters 'N'

Examples:
        gmhmmp -r -m bsub.mod -o sequence.lst sequence.fasta
        gmhmmp -r -p 0 -m yeast.mod -o sequence.lst sequence.fasta


#====================================================================

GeneMarkS  version 4.6b

Usage: gmsn.pl [options] <sequence file name>

input sequence in FASTA format

Output options:
(output is in current working directory)

--name      <string> name of output model file generated for GeneMark.hmm
            (default: 'GeneMark_hmm.mod'; otherwise: '<name>_hmm.mod')
--combine   combine the GeneMarkS generated (native) and Heuristic model parameters into one integrated model
            (default name of output: 'GeneMark_hmm_combined.mod'
            if option --name is specified then the name of the output is: '<name>_hmm_combined.mod')
--gm        generate model file for GeneMark
            (default name of output: 'GeneMark.mat'
            if option --name is specified then the name of the output is: '<name>_gm.mat')
--species   <string> name of a species in a model file
            (default: is set in --par file; no white space in the name!)
--clean     delete all temporary files
            (if not specified: keep temporary files in current working directory)

Run options:

--order     <number> markov chain order
            (default: 2; supported in range: >= 0)
--gcode     <number> genetic code
            (default: 11; supported: 11, 4 and 1)
--shape     <string> sequence organization
            (default: partial; supported: linear, circular and partial)
--motif     <number> iterative search for a sequence motif associated with CDS start
            (default: 1; supported: 1 <true> and 0 <false>)
--width     <number> motif width
            (default: 6; supported in range: >= 3)
--prestart  <number> length of sequence upstream of translation initiation site that presumably includes the motif
            (default: 26; supported in range: >= 0)
--identity  <number> identity level assigned for termination of iterations
            (default: 0.99; supported in range: >=0 and <= 1)
--maxitr    <number> maximum number of iterations
            (default: 10; supported in range: >= 1)
--fixmotif  option indicating thatr the motif is located at a fixed position with regard to the start; i.e. motif could overlap start codon
            (if this option is on, it changes the meaning of --prestart option (see example below) which in this case will define the 
            distance from start codon to motif start)
--offover   prohibits gene overlap
            (if not specified: overlaps are allowed)
--strand    <string> sequence strand to predict genes in
            (default: 'both'; supported: direct, reverse and both )

Combined output and run options:

--prok      to run program on prokaryotic sequence or phage with building models for both GeneMark and GeneMark.hmm
            (this option is the same as:  --combine --clean --gm )
--euk       to run program on eukaryotic intron-less sequence (i.e. low eukaryote)
            (this option is the same as:  --offover --gcode 1 --clean --fixmotif --prestart 6 --width 12 --order 4 --gm)
--virus     to run program on a eukaryotic viral genome
            (this option is the same as:  --combine --gcode 1 --clean --fixmotif --prestart 6 --width 12 --gm)
--est       to run program on EST sequence
            (this option is the same as:  --par par_EST.default --clean --motif 0 --order 4)

Test/developer options:

--par      <file name> custom parameters for GeneMarkS
           (default is selected based on gcode value: 'par_<gcode>.default' )
--imod     <file name> custom initiation model for GeneMarkS
           (default: heuristic model derived from GC composition of input sequence
           if option --combine is specified, custom model will be combined with GeneMarkS )
--test     installation test
--verbose

#====================================================================

MkMat version 1.5b

USAGE: mkmat [-x] <coding file> <noncoding file> <order> <output file>

   The '-x' option to mkmat generates matrix files in portable data format

#====================================================================

Probuild version: 2.10

Usage:
--par <filename> Use one of following files: par_1.default, par_11.default or par_4.default
                 for setting species independent parameters

--mkmod <filename> Name of output model file
  --cod <filename> Name of file with protein coding sequences 
  --non <filename> Name of file with intergenic sequences
  --ORDM <number> Markov chain order
  --MKCHAIN_PSEUDOCOUNTS <number> Pseuodocounts in estimation of probabilities; optional

#====================================================================

computing G+C content - program "gc"

USAGE: gc <sequence-file> [ <sequence-file2> ... ]

#====================================================================

viewing the matrix of GeneMark parameters in convinient format - program "viewmat"

USAGE: viewmat <matrix-file> [ <matrix-file2> ...]

#====================================================================

viewing specifications of the GeneMark matrix of parameters
program "matinfo"

USAGE: matinfo <matrix-file> [<matrix-file2> ...]

#====================================================================

Heuristic Model parameter files (version 2.0)

We use following notation:   
heu_X_Y.mod (for Genemark.hmm), or heu_X_Y.mat (for GeneMark) where
        X -> genetic code
        Y -> GC composition

How to use heuristic models:

Step 1: Find G+C composition of sequence, for example:
        prompt> probuild --gc --seq  sequence
        prompt> 45.2% 
Step 2: Select a heuristic model generated for a sequence with given (or close) G+C content
        heu_11_45.mod
Step 3: Run GeneMark.hmm (or GeneMark) with this heuristic model
        prompt> gmhmmp -m heu_11_45.mod sequence 

        prompt> gm -m heu_11_45.mat sequence
 
As a sequence as short as 400 nt is long enough to determine its G+C content - such a sequence can be analyzed by GeneMark.hmm (GeneMark) with appropriate heuristic model  

Note: heuristic models do not include parameters for RBS (ribosomal binding

#====================================================================
