NAME

       Bio::Tools::GFF - A Bio::SeqAnalysisParserI compliant GFF format parser

SYNOPSIS

           use Bio::Tools::GFF;

           # specify input via -fh or -file
           my $gffio = Bio::Tools::GFF->new(-fh => \*STDIN, -gff_version => 2);
           my $feature;
           # loop over the input stream
           while($feature = $gffio->next_feature()) {
               # do something with feature
           }
           $gffio->close();

           # you can also obtain a GFF parser as a SeqAnalasisParserI in
           # HT analysis pipelines (see Bio::SeqAnalysisParserI and
           # Bio::Factory::SeqAnalysisParserFactory)
           my $factory = Bio::Factory::SeqAnalysisParserFactory->new();
           my $parser = $factory->get_parser(-input => \*STDIN, -method => "gff");
           while($feature = $parser->next_feature()) {
               # do something with feature
           }

DESCRIPTION

       This class provides a simple GFF parser and writer. In the sense of a SeqAnalysisParser,
       it parses an input file or stream into SeqFeatureI objects, but is not in any way specific
       to a particular analysis program and the output that program produces.

       That is, if you can get your analysis program spit out GFF, here is your result parser.

GFF3 AND SEQUENCE DATA

       GFF3 supports sequence data; see

       http://www.sequenceontology.org/gff3.shtml

       There are a number of ways to deal with this -

       If you call

         $gffio->ignore_sequence(1)

       prior to parsing the sequence data is ignored; this is useful if you just want the
       features. It avoids the memory overhead in building and caching sequences

       Alternatively, you can call either

         $gffio->get_seqs()

       Or

         $gffio->seq_id_by_h()

       At the end of parsing to get either a list or hashref of Bio::Seq objects (see the
       documentation for each of these methods)

       Note that these objects will not have the features attached - you have to do this
       yourself, OR call

         $gffio->features_attached_to_seqs(1)

       PRIOR to parsing; this will ensure that the Seqs have the features attached; ie you will
       then be able to call

         $seq->get_SeqFeatures();

       And use Bio::SeqIO methods

       Note that auto-attaching the features to seqs will incur a higher memory overhead as the
       features must be cached until the sequence data is found

TODO

       Make a Bio::SeqIO class specifically for GFF3 with sequence data

FEEDBACK

   Mailing Lists
       User feedback is an integral part of the evolution of this and other Bioperl modules. Send
       your comments and suggestions preferably to one of the Bioperl mailing lists.  Your
       participation is much appreciated.

         bioperl-l@bioperl.org                  - General discussion
         http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       rather than to the module maintainer directly. Many experienced and reponsive experts will
       be able look at the problem and quickly address it. Please include a thorough description
       of the problem with code and data examples if at all possible.

   Reporting Bugs
       Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their
       resolution.  Bug reports can be submitted the web:

         https://redmine.open-bio.org/projects/bioperl/

AUTHOR - Matthew Pocock

       Email mrp-at-sanger.ac.uk

CONTRIBUTORS

       Jason Stajich, jason-at-biperl-dot-org Chris Mungall, cjm-at-fruitfly-dot-org Steffen
       Grossmann [SG], grossman at molgen.mpg.de Malcolm Cook, mec-at-stowers-institute.org

APPENDIX

       The rest of the documentation details each of the object methods. Internal methods are
       usually preceded with a _

   new
        Title   : new
        Usage   : my $parser = Bio::Tools::GFF->new(-gff_version => 2,
                                                    -file        => "filename.gff");
                  or
                  my $writer = Bio::Tools::GFF->new(-gff_version => 3,
                                                    -file        => ">filename.gff3");
        Function: Creates a new instance. Recognized named parameters are -file, -fh,
                  and -gff_version.
        Returns : a new object
        Args    : named parameters
                  -gff_version => [1,2,3]

   _parse_header
        Title   : _parse_header
        Usage   : $gffio->_parse_header()
        Function: used to turn parse GFF header lines.  currently
                  produces Bio::LocatableSeq objects from ##sequence-region
                  lines
        Returns : 1 on success
        Args    : none

   next_segment
        Title   : next_segment
        Usage   : my $seq = $gffio->next_segment;
        Function: Returns a Bio::LocatableSeq object corresponding to a
                  GFF "##sequence-region" header line.
        Example :
        Returns : A Bio::LocatableSeq object, or undef if
                  there are no more sequences.
        Args    : none

   next_feature
        Title   : next_feature
        Usage   : $seqfeature = $gffio->next_feature();
        Function: Returns the next feature available in the input file or stream, or
                  undef if there are no more features.
        Example :
        Returns : A Bio::SeqFeatureI implementing object, or undef if there are no
                  more features.
        Args    : none

   from_gff_string
        Title   : from_gff_string
        Usage   : $gff->from_gff_string($feature, $gff_string);
        Function: Sets properties of a SeqFeatureI object from a GFF-formatted
                  string. Interpretation of the string depends on the version
                  that has been specified at initialization.

                  This method is used by next_feature(). It actually dispatches to
                  one of the version-specific (private) methods.
        Example :
        Returns : void
        Args    : A Bio::SeqFeatureI implementing object to be initialized
                  The GFF-formatted string to initialize it from

   _from_gff1_string
        Title   : _from_gff1_string
        Usage   :
        Function:
        Example :
        Returns : void
        Args    : A Bio::SeqFeatureI implementing object to be initialized
                  The GFF-formatted string to initialize it from

   _from_gff2_string
        Title   : _from_gff2_string
        Usage   :
        Function:
        Example :
        Returns : void
        Args    : A Bio::SeqFeatureI implementing object to be initialized
                  The GFF2-formatted string to initialize it from

   write_feature
        Title   : write_feature
        Usage   : $gffio->write_feature($feature);
        Function: Writes the specified SeqFeatureI object in GFF format to the stream
                  associated with this instance.
        Returns : none
        Args    : An array of Bio::SeqFeatureI implementing objects to be serialized

   gff_string
        Title   : gff_string
        Usage   : $gffstr = $gffio->gff_string($feature);
        Function: Obtain the GFF-formatted representation of a SeqFeatureI object.
                  The formatting depends on the version specified at initialization.

                  This method is used by write_feature(). It actually dispatches to
                  one of the version-specific (private) methods.
        Example :
        Returns : A GFF-formatted string representation of the SeqFeature
        Args    : A Bio::SeqFeatureI implementing object to be GFF-stringified

   _gff1_string
        Title   : _gff1_string
        Usage   : $gffstr = $gffio->_gff1_string
        Function:
        Example :
        Returns : A GFF1-formatted string representation of the SeqFeature
        Args    : A Bio::SeqFeatureI implementing object to be GFF-stringified

   _gff2_string
        Title   : _gff2_string
        Usage   : $gffstr = $gffio->_gff2_string
        Function:
        Example :
        Returns : A GFF2-formatted string representation of the SeqFeature
        Args    : A Bio::SeqFeatureI implementing object to be GFF2-stringified

   _gff25_string
        Title   : _gff25_string
        Usage   : $gffstr = $gffio->_gff2_string
        Function: To get a format of GFF that is peculiar to Gbrowse/Bio::DB::GFF
        Example :
        Returns : A GFF2.5-formatted string representation of the SeqFeature
        Args    : A Bio::SeqFeatureI implementing object to be GFF2.5-stringified

   _gff3_string
         Title   : _gff3_string
         Usage   : $gffstr = $gffio->_gff3_string
         Function:
         Example :
         Returns : A GFF3-formatted string representation of the SeqFeature
         Args    : A Bio::SeqFeatureI implementing object to be GFF3-stringified

   gff_version
         Title   : _gff_version
         Usage   : $gffversion = $gffio->gff_version
         Function:
         Example :
         Returns : The GFF version this parser will accept and emit.
         Args    : none

   newFh
        Title   : newFh
        Usage   : $fh = Bio::Tools::GFF->newFh(-file=>$filename,-format=>'Format')
        Function: does a new() followed by an fh()
        Example : $fh = Bio::Tools::GFF->newFh(-file=>$filename,-format=>'Format')
                  $feature = <$fh>;            # read a feature object
                  print $fh $feature;          # write a feature object
        Returns : filehandle tied to the Bio::Tools::GFF class
        Args    :

   fh
        Title   : fh
        Usage   : $obj->fh
        Function:
        Example : $fh = $obj->fh;      # make a tied filehandle
                  $feature = <$fh>;    # read a feature object
                  print $fh $feature;  # write a feature object
        Returns : filehandle tied to Bio::Tools::GFF class
        Args    : none

   get_seqs
        Title   : get_seqs
        Usage   :
        Function: Returns all Bio::Seq objects populated by GFF3 file
        Example :
        Returns :
        Args    :

   features_attached_to_seqs
        Title   : features_attached_to_seqs
        Usage   : $obj->features_attached_to_seqs(1);
        Function: For use with GFF3 containg sequence only

           Setting this B<before> parsing ensures that all Bio::Seq object
           created will have the appropriate features added to them

           defaults to false (off)

           Note that this mode will incur higher memory usage because features
           will have to be cached until the relevant feature comes along

        Example :
        Returns : value of features_attached_to_seqs (a boolean)
        Args    : on set, new value (a boolean, optional)

   ignore_sequence
        Title   : ignore_sequence
        Usage   : $obj->ignore_sequence(1);
        Function: For use with GFF3 containg sequence only

           Setting this B<before> parsing means that all sequence data will be
           ignored

        Example :
        Returns : value of ignore_sequence (a boolean)
        Args    : on set, new value (a boolean, optional)