validate_gff3.pod

   1 =head1 NAME
   2
   3 validate_gff3.pod
   4
   5 =head1 SYNOPSIS
   6
   7 GFF3 Validation Tutorial
   8
   9 =head1 DESCRIPTION
  10
  11 This package contains code for validating a GFF3 file. Validation can be performed using the command-line script or
  12 the web script.
  13
  14 In either case, analysis is performed using the GFF3::Validator module.
  15
  16 This module, parses the GFF3 file, loads data into a MySQL/SQLite database, performs a number of analysis steps and produces a report file.
  17
  18 This document details the analysis steps performed. The command-line script and the web script generate a Validator object,
  19 managing I/O and run Validator object methods, and provide the results to the user.
  20
  21 =head2 Analysis and Validation Steps
  22
  23 =head3 Parsing and Format Validation
  24
  25 In this step, the GFF3 file is read from beginning to end, lines are parsed and formatting errors are recorded.
  26 Feature lines and directives are stored in two separate tables for further processing. Malformed directives, comments
  27 and FASTA lines are not loaded into the database. Parseable parts of feature lines are loaded into the database.
  28 The implication of this is that, if a line is not parseable, it will be disregarded in further analysis. For example,
  29 (i) if feature A has a parent feature A and (ii) feature A cannot be parsed and loaded, (iii) in downstream analysis,
  30 since feature A points to an invalid feature, this will be raised as an error.
  31
  32 The following points are validated at this step:
  33
  34  - spaces at the end of lines are allowed and disregarded
  35  - empty lines, comments (starting with a single #) are disregarded
  36  - '>' implies a '##FASTA' directive, following lines that follow are disegarded
  37
  38  - the following directives are recognized and checked for format
  39    multiple spaces in the format are treated as single space
  40
  41     - ##gff-version version
  42       - must be "##gff-version 3"
  43       - must be present and be the first line
  44
  45     - ##sequence-region seqid end
  46       - must have the format "##sequence-region \S+ \d+ \d+"
  47
  48     - ##feature-ontology URI
  49
  50     - ##attribute-ontology URI
  51       - cannot be used now, reserved for future use
  52
  53     - ##source-ontology URI
  54       - cannot be used now, reserved for future use
  55
  56     - ###
  57
  58     - ##FASTA
  59       - lines following this directive are disregarded
  60
  61  - the following checks are performed on feature lines:
  62
  63     - must be exactly 9 fields
  64     - fields are split on single tabs
  65     - empty fields must have a dot
  66
  67     - individual fields are processed as follows:
  68
  69       - field 1: seqid
  70         - only following characters are allowed [a-zA-Z0-9\.\:\^\*\$\@\!\+\_\?\-\|\%]
  71         - cannot be empty (dot)
  72
  73       - field 2: source
  74         - only following characters are allowed [a-zA-Z0-9\.\: \^\*\$\@\!\+\_\?\-\%]
  75         - can be empty (dot)
  76
  77       - field 3: type
  78         - only following characters are allowed [a-zA-Z0-9\.\: \^\*\$\@\!\+\_\?\-]
  79         - cannot be empty (dot)
  80
  81       - fields 4 and 5: start and end
  82         - must be integers
  83         - must be in 1-based coordinate system
  84         - end must be greater than or equal to start
  85         - cannot be empty (dot)
  86
  87       - field 6: score
  88         - must be a floating number (e.g. "1.2", "5", "1e-10", "-1e+10")
  89           (for scientific notation: /^[\+\-]{0,1}\d+(e|E)[\+\-]\d+$/ is used)
  90         - can be empty (dot)
  91
  92       - field 7: strand
  93         - must be + or -
  94         - can be empty (dot)
  95
  96       - field 8: phase
  97         - must be 0 or 1 or 2
  98         - can be empty (dot)
  99         - must be 0, 1 or 2 for CDS features
 100
 101       - field 9: attributes
 102         - can be empty (dot)
 103         - attributes are in tag=value format, separated by semicolon (tag=value pairs split on semicolon)
 104         - tag=value pairs are parsed based on first equals sign
 105         - value cannot contain an unescaped equals sign
 106         - each tag should must appear only once, multiple values can be provided to a tag
 107           separated by comma
 108         - tag cannot have a preceding or leading space and cannot be empty
 109         - value cannot be empty
 110         - first-upprcase tags are reserved, only the following are recognized and checked as follows
 111
 112           - tag: ID
 113             - there can be only one ID in a single line
 114
 115           - tag: Name
 116
 117           - tag: Alias
 118
 119           - tag: Parent
 120             - parents are captured for further analysis
 121
 122           - tag: Target
 123             - format must be target_id start end [strand]
 124             - multiple spaces can be used
 125
 126           - tag: Gap
 127             - format checked, e.g. Gap=M8 D3 M6 I1 M6
 128             - the following operations are allowed: [MIDFRmidfr]
 129             - multiple spaces can be used
 130
 131           - tag: Derives_from
 132             - derives_from parents are captured for further analysis
 133           - tag: Note
 134
 135           - tag: Dbxref
 136             - format checked for DBTAG:ID (split on first colon)
 137
 138           - tag: Ontology_term
 139             - format checked for DBTAG:ID (split on first colon)
 140
 141 =head3 Unique ID Validation
 142
 143 ID attributes provided for features must be unique throughout the gff3 file. These ID's are used to
 144 make "part_of" (Parent) associations between features. Each line, if contains an ID, must be unique.
 145 For multi-feature features, such as alignments, multiple lines can share the same ID. If this is the case,
 146 the seqid, source, type (method), strand, target name and all other attributes other than target must be the same.
 147
 148 This step goes through the features that have an ID and checks for uniqueness, taking into account
 149 multi-feature cases.
 150
 151 Unique features are marked as unique. Features that illegally share the same ID are marked as non-unique.
 152 This information is later used for further processing.
 153
 154 =head3 Loading Ontology
 155
 156 GFF3 requires types of features to be coming from an ontology and Parent relationships to be valid "part_of" relationships
 157 based on the ontology. In this step, the ontology that will be used as the basis of this analysis is loaded.
 158
 159 GFF3 specs allow the ontology to be loaded by the ##feature-ontology directive. Multiple ontologies can be loaded,
 160 in which case, they need to be merged and used for the analysis. If they are not provided, the ontology defaults to SOFA.
 161
 162 In this validation implementation, the following rule is used:
 163
 164  - Ontology files provided in the command line and ##feature-ontology directives are
 165    retrieved. If at least one of these files are retrieved, that ontology file is loaded in memory
 166    and used for the analysis.
 167
 168  - If no ontology files are provided in the command-line and ##feature-ontology directives, or
 169    if they are provided but none of them are accesible, default ontology file provided in the
 170    configuration file is retrieved and used for the analysis. If it is not accessible either,
 171    an error is recorded and loading ontology, type field validation, parent and derives_from
 172    validation steps are skipped.
 173
 174 For retrieval of ontologies, the following rule is used:
 175
 176  - the URIs that begin with http:, ftp:, file: are retrieved
 177    by LWP
 178  - the URIs that begin with other <protocol>: are not retrieved
 179  - other URIs are treated as local file names and ther existence is checked
 180
 181 =head3 "type" Field Validation
 182
 183 GFF3 file type fields must be valid ontology terms (names or accession numbers). In this step, the type fields are
 184 validated against the ontology, as loaded in the previous step. This step is skipped if no ontology can be loaded.
 185
 186 Features are marked as valid or invalid. This information is later used for further processing.
 187
 188 =head3 "part_of" Relationship Validation
 189
 190 For features in a GFF3 file, Parent attribute, if provided, indicates that the feature is "part_of" the feature,
 191 assigned as Parent. The feature type of the parent and the feature type of the child must be terms that
 192 can have a part_of relationship based on the ontology. Circular assignments are checked at this step as well
 193 (e.g. if C is parent of B, B is parent of A, then A cannot be parent of B or C).
 194 or the parent have in-valid types, or parent has a non-unique ID.
 195
 196 These checks are not performed if either the child or the parent have invalid types, or parent has a non-unique
 197 ID or does not exist (These cases are recorded separately as erros).
 198
 199 This step is skipped if no ontology can be loaded.
 200
 201 =head3 "derives_from" Relationship Validation
 202
 203 Similar to Parent attribute, Derives_from attribute, if provided, indicates that the feature "derives_from" the feature,
 204 assigned as Derives_from. The feature type of the parent and the feature type of the child must be terms that
 205 can have a derives_from relationship based on the ontology.
 206
 207 Unlike Parent assignments, Derives_from assignments are checked for one level only.
 208
 209 *** Currently type validation for Derives_from assignments is disabled. ***
 210
 211 These checks are not performed if either the child or the parent have invalid types, or parent has a non-unique
 212 ID or does not exist (These cases are recorded separately as erros).
 213
 214 This step is skipped if no ontology can be loaded.
 215
 216 =head2 Report Generation
 217
 218 At the end of analysis, errors and warnings are compiled into a single list, sorted by their line numbers.
 219
 220 =head2 Installation
 221
 222 =head3 Command-line tool
 223
 224 - Copy over lib/GFF3/Validator.pm. Adjust your Perl library paths to make it accesible.
 225
 226 - Create a writable temporary directory and include path to it in the configuration file.
 227
 228 - Use validate_gff3.pl validation script with its configuration file, validate_gff3.cfg.
 229
 230 - For usage information on validate_gff3.pl, use:
 231
 232   perldoc validate_gff3.pl
 233
 234 - For configuration information, check documentation embedded in validate_gff3.cfg .
 235
 236 =head3 Online tool
 237
 238 - Copy over lib/GFF3/Validator.pm and lib/GFF3/Online.pm. Adjust your Perl library paths to make them accesible.
 239
 240 - In your web site's document root, create the following directory (you can use another web accesible directory,
 241 if this is the case configure the paths in the configuration files accordingly):
 242
 243   validate_gff3_online
 244
 245 Copy over contents of html directory (images, documentation, stylesheet) into this directory, adjust permissions.
 246
 247 - Copy over validate_gff3_online (CGI script) into a CGI-executable directory, adjust permissions.
 248
 249 - Create a writable temporary directory and include path to it in the configuration files (see configuration files).
 250
 251 - Copy over validate_gff3.cfg and validate_gff3_online.cfg (configuration files) into $ENV{DOCUMENT_ROOT}/../conf
 252 directory. Configure the application using these files (files contain embedded documentation). Start with
 253 validate_gff3.cfg. Note: If you want to place validate_gff3_online.cfg in a different directory, modify the
 254 location of this file in validate_gff3_online script. The location of validate_gff3.cfg
 255 can be set in the validate_gff3_online.cfg file.
 256
 257 =head3 Notes
 258
 259 - The default source for an ontology file is to retrieve it from the Sequence Ontology site. However, if you
 260 intend to make many runs locally, or if you install an online version, please download the ontology file
 261 and change the configuration to point to the local file.
 262
 263 =cut
 264
 265 =head1 SEE ALSO
 266
 267 =head1 AUTHOR
 268
 269 Payan Canaran <canaran@cshl.edu>
 270
 271 =head1 VERSION
 272
 273 $Id: validate_gff3.pod,v 1.1 2007/12/03 14:20:23 canaran Exp $
 274
 275 =head1 CREDITS
 276
 277 - SQLite support adapted from patch contributed by Robert Buels <rmb32@cornell.edu>.
 278
 279 =head1 COPYRIGHT AND LICENSE
 280
 281 Copyright (c) 2006-2007 Cold Spring Harbor Laboratory
 282
 283 This program is free software; you can redistribute it and/or modify it
 284 under the same terms as Perl itself. See DISCLAIMER.txt for
 285 disclaimers of warranty.
 286
 287 =cut
 288
 289 1;