.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::Tools::GFF 3pm"
.TH Bio::Tools::GFF 3pm "2020-10-28" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::Tools::GFF \- A Bio::SeqAnalysisParserI compliant GFF format parser
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Bio::Tools::GFF;
\&
\&    # specify input via \-fh or \-file
\&    my $gffio = Bio::Tools::GFF\->new(\-fh => \e*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 => \e*STDIN, \-method => "gff");
\&    while($feature = $parser\->next_feature()) {
\&        # do something with feature
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class provides a simple \s-1GFF\s0 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.
.PP
That is, if you can get your analysis program spit out \s-1GFF,\s0 here is
your result parser.
.SH "GFF3 AND SEQUENCE DATA"
.IX Header "GFF3 AND SEQUENCE DATA"
\&\s-1GFF3\s0 supports sequence data; see
.PP
http://www.sequenceontology.org/gff3.shtml
.PP
There are a number of ways to deal with this \-
.PP
If you call
.PP
.Vb 1
\&  $gffio\->ignore_sequence(1)
.Ve
.PP
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
.PP
Alternatively, you can call either
.PP
.Vb 1
\&  $gffio\->get_seqs()
.Ve
.PP
Or
.PP
.Vb 1
\&  $gffio\->seq_id_by_h()
.Ve
.PP
At the \fBend\fR of parsing to get either a list or hashref of Bio::Seq
objects (see the documentation for each of these methods)
.PP
Note that these objects will not have the features attached \- you have
to do this yourself, \s-1OR\s0 call
.PP
.Vb 1
\&  $gffio\->features_attached_to_seqs(1)
.Ve
.PP
\&\s-1PRIOR\s0 to parsing; this will ensure that the Seqs have the features
attached; ie you will then be able to call
.PP
.Vb 1
\&  $seq\->get_SeqFeatures();
.Ve
.PP
And use Bio::SeqIO methods
.PP
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
.SH "TODO"
.IX Header "TODO"
Make a Bio::SeqIO class specifically for \s-1GFF3\s0 with sequence data
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "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.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
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.
.SS "Reporting Bugs"
.IX Subsection "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:
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR \- Matthew Pocock"
.IX Header "AUTHOR - Matthew Pocock"
Email mrp\-at\-sanger.ac.uk
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Jason Stajich, jason-at-biperl-dot-org
Chris Mungall, cjm-at-fruitfly-dot-org
Steffen Grossmann [\s-1SG\s0], grossman at molgen.mpg.de
Malcolm Cook, mec\-at\-stowers\-institute.org
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _
.SS "new"
.IX Subsection "new"
.Vb 11
\& 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]
.Ve
.SS "_parse_header"
.IX Subsection "_parse_header"
.Vb 7
\& 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
.Ve
.SS "next_segment"
.IX Subsection "next_segment"
.Vb 8
\& 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
.Ve
.SS "next_feature"
.IX Subsection "next_feature"
.Vb 8
\& 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
.Ve
.SS "from_gff_string"
.IX Subsection "from_gff_string"
.Vb 5
\& 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
.Ve
.SS "_from_gff1_string"
.IX Subsection "_from_gff1_string"
.Vb 7
\& 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
.Ve
.SS "_from_gff2_string"
.IX Subsection "_from_gff2_string"
.Vb 7
\& 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
.Ve
.SS "write_feature"
.IX Subsection "write_feature"
.Vb 6
\& 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
.Ve
.SS "gff_string"
.IX Subsection "gff_string"
.Vb 4
\& 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
.Ve
.SS "_gff1_string"
.IX Subsection "_gff1_string"
.Vb 6
\& 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
.Ve
.SS "_gff2_string"
.IX Subsection "_gff2_string"
.Vb 6
\& 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
.Ve
.SS "_gff25_string"
.IX Subsection "_gff25_string"
.Vb 6
\& 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
.Ve
.SS "_gff3_string"
.IX Subsection "_gff3_string"
.Vb 6
\&  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
.Ve
.SS "gff_version"
.IX Subsection "gff_version"
.Vb 6
\&  Title   : _gff_version
\&  Usage   : $gffversion = $gffio\->gff_version
\&  Function:
\&  Example :
\&  Returns : The GFF version this parser will accept and emit.
\&  Args    : none
.Ve
.SS "newFh"
.IX Subsection "newFh"
.Vb 8
\& Title   : newFh
\& Usage   : $fh = Bio::Tools::GFF\->newFh(\-file=>$filename,\-format=>\*(AqFormat\*(Aq)
\& Function: does a new() followed by an fh()
\& Example : $fh = Bio::Tools::GFF\->newFh(\-file=>$filename,\-format=>\*(AqFormat\*(Aq)
\&           $feature = <$fh>;            # read a feature object
\&           print $fh $feature;          # write a feature object
\& Returns : filehandle tied to the Bio::Tools::GFF class
\& Args    :
.Ve
.SS "fh"
.IX Subsection "fh"
.Vb 8
\& 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
.Ve
.SS "get_seqs"
.IX Subsection "get_seqs"
.Vb 6
\& Title   : get_seqs
\& Usage   :
\& Function: Returns all Bio::Seq objects populated by GFF3 file
\& Example :
\& Returns :
\& Args    :
.Ve
.SS "features_attached_to_seqs"
.IX Subsection "features_attached_to_seqs"
.Vb 3
\& Title   : features_attached_to_seqs
\& Usage   : $obj\->features_attached_to_seqs(1);
\& Function: For use with GFF3 containing 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)
.Ve
.SS "ignore_sequence"
.IX Subsection "ignore_sequence"
.Vb 3
\& Title   : ignore_sequence
\& Usage   : $obj\->ignore_sequence(1);
\& Function: For use with GFF3 containing 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)
.Ve