# ==============================================================
# GeneMark-ES Suite version 4.*
#
# Last modified: January, 2020
#
# Georgia Institute of Technology, Atlanta, Georgia, US
#
# Dr. Mark Borodovsky Bioinformatics Lab
#
# Affiliation:
#  * Joint Georgia Tech and Emory Wallace H Coulter Department of Biomedical Engineering
#  * Center for Bioinformatics and Computational Genomics at Georgia Tech
#  * School of Computational Science and Engineering at Georgia Tech
#
# This eukaryotic gene prediction suite contains:
#   GeneMark.hmm,  GeneMark-ES,  GeneMark-ET,  GeneMark-EP  and  *.PLUS algorithms
#
# Name of this package:  gmes_petap.pl
#   GeneMark.hmm  -> gm
#   Eukaryotic    -> e
#   Self-training -> s
#   Plus          -> p
#   Evidence      -> e
#   Transcripts   -> t
#     And         -> a
#   Proteins      -> p
#
# ==============================================================
# Algorithms included into this package were described in the following publications:
#
# Gene prediction algorithm GeneMark-EP
#    Bruna T., Lomsadze A. Borodovsky M.
#    "GeneMark-EP and -EP+: automatic eukaryotic gene prediction
#     supported by spliced aligned proteins"
#    in preparation
#
# Gene prediction algorithm GeneMark-ET
#    Lomsadze A., Burns P. and  Borodovsky M.
#    "Integration of RNA-Seq Data into Eukaryotic Gene Finding Algorithm
#     with Semi-Supervised Training."
#    Nucleic Acids Research, 2014, July 2
#
# Gene prediction algorithm GeneMark.hmm ES BP version 2.0
#    Ter-Hovhannisyan V., Lomsadze A., Chernoff Y. and Borodovsky M.
#    "Gene prediction in novel fungal genomes using an ab initio
#     algorithm with unsupervised training."
#    Genome Research, 2008, Dec 18(12):1979-90
#
# Gene prediction algorithm GeneMark-ES version 1.0
#    Lomsadze A., Ter-Hovhannisyan V., Chernoff Y. and Borodovsky M.
#    "Gene identification in novel eukaryotic genomes by
#     self-training algorithm."
#    Nucleic Acids Research, 2005, Vol. 33, No. 20, 6494-6506
# ==============================================================
# Copyright:
#   Georgia Institute of Technology, Atlanta, Georgia, USA
#
# Please report problems to:
#   Alex Lomsadze alexl@gatech.edu
#   Mark Borodovsky borodovsky@gatech.edu
# ==============================================================

1. INSTALLATION

See file INSTALL

#------------------------------------
2. HOW TO RUN

To run GeneMark-ES

   gmes_petap.pl --sequence sequence.fna --ES
   gmes_petap.pl --sequence sequence.fna --ES --fungus

To run GeneMark-ET

   gmes_petap.pl --sequence sequence.fna --ET introns.gff --et_score 10
   gmes_petap.pl --sequence sequence.fna --ET introns.gff --et_score 10 --fungus

where file 'introns.gff' has intron coordinates from RNA-Seq read to genomic DNA splice alignment in GFF format.
Intron score should be set in score field of GFF file.
Depending on the type of RNA-Seq read alignment tool used, user should adjust command line parameter "--et_score".
In case of TopHat2, default value for --et score is '10'.
If UnSplicer or TrueSight are used then default value is '0.5'.
See section '4' for details about the 'intron.gff' file format.

To run GeneMark-EP

   gmes_petap.pl --sequence sequence.fna --EP hints.gff --ep_score 4,0.3
   gmes_petap.pl --sequence sequence.fna --EP hints.gff --ep_score 4,0.3 --fungus

where file 'hints.gff" is output of ProtHint pipeline in GFF format.

Detailed information about GeneMark-EP+ run mode can be found here:
    https://github.com/gatech-genemark/GeneMark-EP-plus

#------------------------------------
3. GENERAL INTRUCTIONS: USE OF PARAMETERS

Usage:  ./gmes_petap.pl  [options]  --sequence [filename]

# -------------------

WARNING: the algorithm is supposed to work best for genomes with uniform composition 
(with variance in GC content in 1000 nt long windows accross genome smaller than 20%) 

RUNNING TIME: On single 3 GHz CPU the program works for 2-3 hours on D. melanogaster genome (~100Mb).
Please use --cores or --pbs options for large genomes.

#------------------------------------
4. FORMAT OF INPUT DATA

For GeneMark-ET

Intron coordinates should be in GFF format.

Example line from GFF file:
"2L	TopHat2	intron	2740	2888	25	+	.	."

To convert intron predictions by TopHat2 from "bet" to "gff" format
use the following script from essuite distribution:

   path_to/bed_to_gff.pl  --bet path_to_tophat_out/junctions.bed   --gff introns.gff  --label TopHat2

To convert intron predictions by STAR algorithm to "gff" format
use the following script from essuite distribution:

   path_to/star_to_gff.pl --star path_to_star_out/SJ.out.tab  --gff introns.gff  --label STAR

Required values in the GFF format file:
see http://www.sanger.ac.uk/resources/software/gff/spec.html

Column <seqname>    value should match the corresponding definition line in the FASTA file with sequence
Column <source>     in this case TopHat2 (value in this column is not used currently)
Column <feature>    value "intron"
Column <start><end> intron coordinates, <start> points to first nucleotide of intron and <end> to the last one. 
                    Index starts from "1"
Column <score>      in case of TopHat2, score is the number of reads spanning this intron (reported by TopHat2)
                    in case of UnSplicer or TrueSight, score is the probability like estimate of intron quality, reported by these tools
Column <strand>     + or -
Values in other columns (frame and attribute) are not used in this program version.

FASTA format
https://www.ncbi.nlm.nih.gov/BLAST/blastcgihelp.shtml

In the definition lines of FASTA file shoudl be unique for each contig
">unique_contig_name"

IMPORTANT: the names of contigs in <seqname> column in GFF should be the same as in FASTA file 'unique_contig_name' definition fields  

#------------------------------------

