tools/GFF/gtf2gff3.README

   1 https://github.com/GMOD/GBrowse/blob/master/bin/gtf2gff3.pl
   2 http://www.sequenceontology.org/resources/gtf2gff3.cfg
   3 http://song.cvs.sourceforge.net/viewvc/song/software/scripts/gtf2gff3/README
   4
   5 NAME
   6
   7 gtf2gff3
   8
   9 VERSION
  10
  11 This document describes version 0.1
  12
  13 SYNOPSIS
  14
  15 gtf2gff3 --cfg gtf2gff3_MY_CONFIG.cfg gtf_file > gff3_file
  16
  17 DESCRIPTION
  18
  19 This script will convert GTF formatted files to valid GFF3 formatted
  20 files.  It will map the value in column 3 (\"type\" column) to valid
  21 SO, however because many non standard terms may appear in that column
  22 in GTF files, you may edit the config file to provide your own GTF
  23 feature to SO mapping.  The script will also build gene models from
  24 exons, CDSs and other features given in the GTF file.  It is currently
  25 tested on Ensemble and Twinscan GTF, and it should work on any other
  26 files that follow those same specifications.  It does not work on GTF
  27 from the UCSC table browser because those files use the same ID for
  28 gene and transcript, so it is impossible to group multiple transcripts
  29 to a gene.
  30
  31 OPTIONS:
  32
  33 --cfg   Provide the filename for a config file.  See the configuration file
  34         provided with this script for format details.  Use this configuration
  35         file to modify the behavior of the script. If no config file is given
  36         it looks for ./gtf2gff3.cfg, ~/gtf2gff3.cfg or /etc/gtf2gff3.cfg in
  37         that order.
  38
  39
  40 --help  Provide a detailed man page style help message and then exit.
  41
  42
  43 INSTALLATION
  44
  45 This script requires the following perl packages that are available
  46 from CPAN (www.cpan.org): Getopt::Long, use Config::Std.  If these are not
  47 already installed try:
  48
  49 perl -MCPAN -e shell
  50 install Getopt::Long
  51 install Config::Std
  52 quit
  53
  54 After that the script is ready to run.
  55
  56 DESCRIPTION OF THE ALGORITHM
  57
  58 This script was designed to convert GTF formatted files to GFF3
  59 format.  It reads input from a GTF file and prints it's GFF3 output to
  60 STDOUT.  It was written based on and has been tested on GTF files from
  61 Ensembl and Twinscan.  It should work on similarly formatted GTF
  62 files.  It was also written to the extent possible to be robust about
  63 missing features and will try to infer those features where
  64 appropriate.
  65
  66 The first step is of course to parse the incoming GTF file.  The
  67 script requires the standard 9-column format, but two configuration
  68 variables ATTRB_DELIMITER and ATTRB_REGEX allow flexibility in the 9th
  69 (attributes) column.  ATTRB_DELIMETER will determine the delimiter
  70 between attributes, and ATTRB_REGEX will determine the regular
  71 expression that will split the key value pairs.  Both variables take
  72 any valid perl regular expression.
  73
  74 The features present in a GTF file can vary quite a bit.  Some have
  75 exons, start codons, CDSs, stop codons and UTRs.  Others have some
  76 subset of those.  This script will take those features and try to
  77 build a valid gene model infering any missing features where
  78 appropriate.  You must have as a minimum at least exons or CDSs for
  79 the script to infer a gene model.  For example the script would throw
  80 an error if it encountered an orphaned stop codon for instance.  Gene
  81 features in a GTF file have a gene_id and a transcript_id in the
  82 attributes.  The key terms that identify those IDs can be set in the
  83 configuration file.  However, if those IDs are not present then that
  84 feature can not be associated with any gene or transcript.  The script
  85 does not try to do any unflattening of gene features based on
  86 coordinates.  For example if you have features that have transcript
  87 IDs but no gene IDs, then no attempt will be made to cluster those
  88 transcripts into genes and in fact no gene models would be built.
  89
  90 With regards to gene models the script limits itself to the features,
  91 exon, CDS, start codon, stop codon, 5' UTR and 3' UTR.  Those feature
  92 may be named anything you want in your input GTF file as long as the
  93 appropriate mappings are set up in the config file.
  94
  95 As a first step in constructing gene models the script checks for
  96 start and stop codons.  If they don't exist it tries to infer them
  97 from the exons, CDSs and/or UTRs.  It currently will assume a start or
  98 stop codon from the appropriate end of a terminal CDS if an exon or
  99 UTR is periferal to that CDS.  It does not check coordinates to see if
 100 those features are contiguous.
 101
 102 GFF3 requires start and stop codons to be part of the CDS.  Many GTF
 103 files do not include one or both (often the stop is excluded) within
 104 the CDS.  Two configuration variables can be used to direct the script
 105 about whether or not terminal codons are included in the CDS within
 106 your GTF file.  These variables are START_IN_CDS and STOP_IN_CDS
 107 respectively.  A value of 1 indicates that your GTF file includes the
 108 codon within the coordinates of the annotated CDSs.  A value of 0
 109 indicates that is does not.  Defaults assume that start codons are
 110 part of the CDS and stop codons are not within your GTF file.
 111
 112 The next step is to infer CDSs and UTRs from any appropriate
 113 combination of exons, start codon, stop codon, CDSs and/or UTRs.  If
 114 exons are unavailable the script will try to infer them from any
 115 combination of CDSs, start codon, stop codon and/or UTRs.  In both
 116 cases coordinates are consulted to be sure we're "doing the right
 117 thing".
 118
 119 If CDS phase is annotated it is not validated, however if CDSs are
 120 infered and a start codon is annoated or infered then CDSs phase is
 121 set.
 122
 123 As a final step in building a gene model, the script checks all
 124 features within each transcript and feature to be sure that each feild
 125 is filled and is consistent with other features associated with the
 126 same transcript and gene.  Since genes and transcripts are not
 127 annotated in GTF these features are constructed for the GFF3 output.
 128 Gene and transcript boundaries are simply assumed to be the minimum
 129 and maximum coordiantes of all contained features.
 130
 131
 132 EXAMPLE USAGE
 133
 134 Consider the following GTF
 135
 136 chr1       protein_coding  exon    28163331        28164986        .       +       .        gene="gene_2" | mRNA="trnsc_5"
 137 chr1       protein_coding  CDS     28163331        28164986        .       +       0        gene="gene_2" | mRNA="trnsc_5"
 138 chr1       protein_coding  exon    28165075        28165231        .       +       .        gene="gene_2" | mRNA="trnsc_5"
 139 chr1       protein_coding  CDS     28165075        28165231        .       +       0        gene="gene_2" | mRNA="trnsc_5"
 140 chr1       protein_coding  exon    28173088        28173224        .       +       .        gene="gene_2" | mRNA="trnsc_5"
 141 chr1       protein_coding  CDS     28173088        28173224        .       +       2        gene="gene_2" | mRNA="trnsc_5"
 142 chr1       protein_coding  exon    28176514        28176665        .       +       .        gene="gene_2" | mRNA="trnsc_5"
 143 chr1       protein_coding  CDS     28176514        28176665        .       +       0        gene="gene_2" | mRNA="trnsc_5"
 144 chr1       protein_coding  exon    28176847        28176950        .       +       .        gene="gene_2" | mRNA="trnsc_5"
 145 chr1       protein_coding  CDS     28176847        28176950        .       +       1        gene="gene_2" | mRNA="trnsc_5"
 146 chr1       protein_coding  exon    28181630        28181713        .       +       .        gene="gene_2" | mRNA="trnsc_5"
 147 chr1       protein_coding  CDS     28181630        28181713        .       +       2        gene="gene_2" | mRNA="trnsc_5"
 148 chr1       protein_coding  exon    28187071        28187711        .       +       .        gene="gene_2" | mRNA="trnsc_5"
 149 chr1       protein_coding  CDS     28187071        28187381        .       +       2        gene="gene_2" | mRNA="trnsc_5"
 150
 151 Let's assume that the start codon coordinates are included within the
 152 CDS, but that the stop codon is not.  We make the following settings
 153 in the configuration file to account for that:
 154
 155 START_IN_CDS = 1
 156 STOP_IN_CDS  = 0
 157
 158 We see that the gene ID is annotated as gene="gene_2" and the
 159 transcript ID is annotated as mRNA="trnsc_5" and that attributes are
 160 seperated by a vertical bar "|".  We adjust the configuration file as follows:
 161
 162 ATTRB_DELIMITER = \s*|\s*
 163 ATTRB_REGEX     = ^\s*(\S+)=(\"[^\"]+\")\s*$
 164
 165 [GTF_ATTRB_MAP]
 166 #Code Tag    #GTF Tag
 167 gene_id    = gene
 168 trnsc_id   = mRNA
 169
 170 The above input would provide the following GFF3 output:
 171
 172 chr1    protein_coding  gene    28163331        28187711        .       +       .       ID=gene_2;
 173 chr1    protein_coding  mRNA    28163331        28187711        .       +       .       ID=trnsc_5; PARENT=gene_2;
 174 chr1    protein_coding  exon    28163331        28164986        .       +       .       ID=exon:trnsc_5:1; PARENT=trnsc_5;
 175 chr1    protein_coding  exon    28165075        28165231        .       +       .       ID=exon:trnsc_5:2; PARENT=trnsc_5;
 176 chr1    protein_coding  exon    28173088        28173224        .       +       .       ID=exon:trnsc_5:3; PARENT=trnsc_5;
 177 chr1    protein_coding  exon    28176514        28176665        .       +       .       ID=exon:trnsc_5:4; PARENT=trnsc_5;
 178 chr1    protein_coding  exon    28176847        28176950        .       +       .       ID=exon:trnsc_5:5; PARENT=trnsc_5;
 179 chr1    protein_coding  exon    28181630        28181713        .       +       .       ID=exon:trnsc_5:6; PARENT=trnsc_5;
 180 chr1    protein_coding  exon    28187071        28187711        .       +       .       ID=exon:trnsc_5:7; PARENT=trnsc_5;
 181 chr1    protein_coding  CDS     28163331        28164986        .       +       0       ID=CDS:trnsc_5:1; PARENT=trnsc_5;
 182 chr1    protein_coding  CDS     28165075        28165231        .       +       0       ID=CDS:trnsc_5:2; PARENT=trnsc_5;
 183 chr1    protein_coding  CDS     28173088        28173224        .       +       2       ID=CDS:trnsc_5:3; PARENT=trnsc_5;
 184 chr1    protein_coding  CDS     28176514        28176665        .       +       0       ID=CDS:trnsc_5:4; PARENT=trnsc_5;
 185 chr1    protein_coding  CDS     28176847        28176950        .       +       1       ID=CDS:trnsc_5:5; PARENT=trnsc_5;
 186 chr1    protein_coding  CDS     28181630        28181713        .       +       2       ID=CDS:trnsc_5:6; PARENT=trnsc_5;
 187 chr1    protein_coding  CDS     28187071        28187381        .       +       2       ID=CDS:trnsc_5:7; PARENT=trnsc_5;
 188
 189 CONFIGURATION AND ENVIRONMENT
 190
 191 A configuration file is provided with this script.  The script will
 192 look for that configuration file in ./gtf2gff3.cfg, ~/gtf2gff3.cfg
 193 or /etc/gtf2gff3.cfg in that order.  If the configuration file is not
 194 found in one of those locations and one is not provided via the --cfg
 195 flag it will try to choose some sane defaults, but you really should
 196 provide the configuration file.  See the supplied configuration file
 197 itself as well as the README that came with this package for format
 198 and details about the configuration file.
 199
 200 DEPENDENCIES
 201
 202 This script requires the following perl packages that are available
 203 from CPAN (www.cpan.org).
 204
 205 Getopt::Long
 206 use Config::Std
 207
 208 INCOMPATIBILITIES
 209
 210 None reported.
 211
 212 BUGS AND LIMITATIONS
 213
 214 No bugs have been reported.
 215
 216 Please report any bugs or feature requests to:
 217 barry dot moore at genetics dot utah dot edu
 218
 219 AUTHOR
 220
 221 Barry Moore
 222 barry dot moore at genetics dot utah dot edu
 223
 224 LICENCE AND COPYRIGHT
 225
 226 Copyright (c) 2007, University of Utah
 227
 228     This module is free software; you can redistribute it and/or
 229     modify it under the same terms as Perl itself.
 230
 231 DISCLAIMER OF WARRANTY
 232
 233 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
 234 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
 235 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
 236 PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
 237 EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 238 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
 239 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
 240 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
 241 NECESSARY SERVICING, REPAIR, OR CORRECTION.
 242
 243 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
 244 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
 245 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
 246 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
 247 OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
 248 THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
 249 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
 250 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
 251 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
 252 SUCH DAMAGES.
 253