Provided by: libbio-db-gff-perl_1.7.4-1_all bug

NAME

       Bio::DB::GFF -- Storage and retrieval of sequence annotation data

SYNOPSIS

         use Bio::DB::GFF;

         # Open the sequence database
         my $db      = Bio::DB::GFF->new( -adaptor => 'dbi::mysqlopt',
                                          -dsn     => 'dbi:mysql:elegans');

         # fetch a 1 megabase segment of sequence starting at landmark "ZK909"
         my $segment = $db->segment('ZK909', 1 => 1000000);

         # pull out all transcript features
         my @transcripts = $segment->features('transcript');

         # for each transcript, total the length of the introns
         my %totals;
         for my $t (@transcripts) {
           my @introns = $t->Intron;
           $totals{$t->name} += $_->length foreach @introns;
         }

         # Sort the exons of the first transcript by position
         my @exons = sort {$a->start <=> $b->start} $transcripts[0]->Exon;

         # Get a region 1000 bp upstream of first exon
         my $upstream = $exons[0]->subseq(-1000,0);

         # get its DNA
         my $dna = $upstream->seq;

         # and get all curated polymorphisms inside it
         @polymorphisms = $upstream->contained_features('polymorphism:curated');

         # get all feature types in the database
         my @types = $db->types;

         # count all feature types in the segment
         my %type_counts = $segment->types(-enumerate=>1);

         # get an iterator on all curated features of type 'exon' or 'intron'
         my $iterator = $db->get_seq_stream(-type     => ['exon:curated','intron:curated']);

         while (my $s = $iterator->next_seq) {
             print $s,"\n";
         }

         # find all transcripts annotated as having function 'kinase'
         my $iterator = $db->get_seq_stream(-type=>'transcript',
                                            -attributes=>{Function=>'kinase'});
         while (my $s = $iterator->next_seq) {
             print $s,"\n";
         }

DESCRIPTION

       Bio::DB::GFF provides fast indexed access to a sequence annotation database.  It supports
       multiple database types (ACeDB, relational), and multiple schemas through a system of
       adaptors and aggregators.

       The following operations are supported by this module:

         - retrieving a segment of sequence based on the ID of a landmark
         - retrieving the DNA from that segment
         - finding all annotations that overlap with the segment
         - finding all annotations that are completely contained within the
           segment
         - retrieving all annotations of a particular type, either within a
           segment, or globally
         - conversion from absolute to relative coordinates and back again,
           using any arbitrary landmark for the relative coordinates
         - using a sequence segment to create new segments based on relative
           offsets

       The data model used by Bio::DB::GFF is compatible with the GFF flat file format
       (<http://www.sequenceontology.org/gff3.shtml>). The module can load a set of GFF files
       into the database, and serves objects that have methods corresponding to GFF fields.

       The objects returned by Bio::DB::GFF are compatible with the SeqFeatureI interface,
       allowing their use by the Bio::Graphics and Bio::DAS modules.

   Auxiliary Scripts
       The bioperl distribution includes several scripts that make it easier to work with
       Bio::DB::GFF databases.  They are located in the scripts directory under a subdirectory
       named Bio::DB::GFF:

       •   bp_load_gff.pl

           This script will load a Bio::DB::GFF database from a flat GFF file of sequence
           annotations.  Only the relational database version of Bio::DB::GFF is supported.  It
           can be used to create the database from scratch, as well as to incrementally load new
           data.

           This script takes a --fasta argument to load raw DNA into the database as well.
           However, GFF databases do not require access to the raw DNA for most of their
           functionality.

           load_gff.pl also has a --upgrade option, which will perform a non-destructive upgrade
           of older schemas to newer ones.

       •   bp_bulk_load_gff.pl

           This script will populate a Bio::DB::GFF database from a flat GFF file of sequence
           annotations.  Only the MySQL database version of Bio::DB::GFF is supported.  It uses
           the "LOAD DATA INFILE" query in order to accelerate loading considerably; however, it
           can only be used for the initial load, and not for updates.

           This script takes a --fasta argument to load raw DNA into the database as well.
           However, GFF databases do not require access to the raw DNA for most of their
           functionality.

       •   bp_fast_load_gff.pl

           This script is as fast as bp_bulk_load_gff.pl but uses Unix pipe tricks to allow for
           incremental updates.  It only supports the MySQL database version of Bio::DB::GFF and
           is guaranteed not to work on non-Unix platforms.

           Arguments are the same as bp_load_gff.pl

       •   gadfly_to_gff.pl

           This script will convert the GFF-like format used by the Berkeley Drosophila
           Sequencing project into a format suitable for use with this module.

       •   sgd_to_gff.pl

           This script will convert the tab-delimited feature files used by the Saccharomyces
           Genome Database into a format suitable for use with this module.

   GFF Fundamentals
       The GFF format is a flat tab-delimited file, each line of which corresponds to an
       annotation, or feature.  Each line has nine columns and looks like this:

        Chr1  curated  CDS 365647  365963  .  +  1  Transcript "R119.7"

       The 9 columns are as follows:

       1.  reference sequence

           This is the ID of the sequence that is used to establish the coordinate system of the
           annotation.  In the example above, the reference sequence is "Chr1".

       2.  source

           The source of the annotation.  This field describes how the annotation was derived.
           In the example above, the source is "curated" to indicate that the feature is the
           result of human curation.  The names and versions of software programs are often used
           for the source field, as in "tRNAScan-SE/1.2".

       3.  method

           The annotation method.  This field describes the type of the annotation, such as
           "CDS".  Together the method and source describe the annotation type.

       4.  start position

           The start of the annotation relative to the reference sequence.

       5.  stop position

           The stop of the annotation relative to the reference sequence.  Start is always less
           than or equal to stop.

       6.  score

           For annotations that are associated with a numeric score (for example, a sequence
           similarity), this field describes the score.  The score units are completely
           unspecified, but for sequence similarities, it is typically percent identity.
           Annotations that don't have a score can use "."

       7.  strand

           For those annotations which are strand-specific, this field is the strand on which the
           annotation resides.  It is "+" for the forward strand, "-" for the reverse strand, or
           "." for annotations that are not stranded.

       8.  phase

           For annotations that are linked to proteins, this field describes the phase of the
           annotation on the codons.  It is a number from 0 to 2, or "." for features that have
           no phase.

       9.  group

           GFF provides a simple way of generating annotation hierarchies ("is composed of"
           relationships) by providing a group field.  The group field contains the class and ID
           of an annotation which is the logical parent of the current one.  In the example given
           above, the group is the Transcript named "R119.7".

           The group field is also used to store information about the target of sequence
           similarity hits, and miscellaneous notes.  See the next section for a description of
           how to describe similarity targets.

           The format of the group fields is "Class ID" with a single space (not a tab)
           separating the class from the ID. It is VERY IMPORTANT to follow this format, or
           grouping will not work properly.

       The sequences used to establish the coordinate system for annotations can correspond to
       sequenced clones, clone fragments, contigs or super-contigs.  Thus, this module can be
       used throughout the lifecycle of a sequencing project.

       In addition to a group ID, the GFF format allows annotations to have a group class.  For
       example, in the ACeDB representation, RNA interference experiments have a class of "RNAi"
       and an ID that is unique among the RNAi experiments.  Since not all databases support this
       notion, the class is optional in all calls to this module, and defaults to "Sequence" when
       not provided.

       Double-quotes are sometimes used in GFF files around components of the group field.
       Strictly, this is only necessary if the group name or class contains whitespace.

   Making GFF files work with this module
       Some annotations do not need to be individually named.  For example, it is probably not
       useful to assign a unique name to each ALU repeat in a vertebrate genome.  Others, such as
       predicted genes, correspond to named biological objects; you probably want to be able to
       fetch the positions of these objects by referring to them by name.

       To accommodate named annotations, the GFF format places the object class and name in the
       group field.  The name identifies the object, and the class prevents similarly-named
       objects, for example clones and sequences, from collding.

       A named object is shown in the following excerpt from a GFF file:

        Chr1  curated transcript  939627 942410 . +  . Transcript Y95B8A.2

       This object is a predicted transcript named Y95BA.2.  In this case, the group field is
       used to identify the class and name of the object, even though no other annotation belongs
       to that group.

       It now becomes possible to retrieve the region of the genome covered by transcript
       Y95B8A.2 using the segment() method:

         $segment = $db->segment(-class=>'Transcript',-name=>'Y95B8A.2');

       It is not necessary for the annotation's method to correspond to the object class,
       although this is commonly the case.

       As explained above, each annotation in a GFF file refers to a reference sequence.  It is
       important that each reference sequence also be identified by a line in the GFF file.  This
       allows the Bio::DB::GFF module to determine the length and class of the reference
       sequence, and makes it possible to do relative arithmetic.

       For example, if "Chr1" is used as a reference sequence, then it should have an entry in
       the GFF file similar to this one:

        Chr1 assembly chromosome 1 14972282 . + . Sequence Chr1

       This indicates that the reference sequence named "Chr1" has length 14972282 bp, method
       "chromosome" and source "assembly".  In addition, as indicated by the group field, Chr1
       has class "Sequence" and name "Chr1".

       The object class "Sequence" is used by default when the class is not specified in the
       segment() call.  This allows you to use a shortcut form of the segment() method:

        $segment = $db->segment('Chr1');          # whole chromosome
        $segment = $db->segment('Chr1',1=>1000);  # first 1000 bp

       For your convenience, if, during loading a GFF file, Bio::DB::GFF encounters a line like
       the following:

         ##sequence-region Chr1 1 14972282

       It will automatically generate the following entry:

        Chr1 reference Component 1 14972282 . + . Sequence Chr1

       This is sufficient to use Chr1 as a reference point.  The ##sequence-region line is
       frequently found in the GFF files distributed by annotation groups.

   Specifying the group tag
       A frequent problem with GFF files is the problem distinguishing which of the several
       tag/value pairs in the 9th column is the grouping pair.  Ordinarily the first tag will be
       used for grouping, but some GFF manipulating tools do not preserve the order of
       attributes.  To eliminate this ambiguity, this module provides two ways of explicitly
       specifying which tag to group on:

       •   Using -preferred_groups

           When you create a Bio::DB::GFF object, pass it a -preferred_groups=> argument.  This
           specifies a tag that will be used for grouping.  You can pass an array reference to
           specify a list of such tags.

       •   In the GFF header

           The GFF file itself can specify which tags are to be used for grouping.  Insert a
           comment like the following:

            ##group-tags Accession Locus

           This says to use the Accession tag for grouping.  If it is not available, use the
           Locus tag.  If neither tag is available, use the first pair to appear.

       These options only apply when loading a GFF file into the database, and have no effect on
       existing databases.

       The group-tags comment in the GFF file will *override* the preferred groups set when you
       create the Bio::DB::GFF object.

       For backward compatibility, the tags Sequence and Transcript are always treated as
       grouping tags unless preferred_tags are specified.  The "Target" tag is always used for
       grouping regardless of the preferred_groups() setting, and the tags "tstart", "tend" and
       "Note" cannot be used for grouping.  These are historical artefacts coming from various
       interpretations of GFF2, and cannot be changed.

   Sequence alignments
       There are two cases in which an annotation indicates the relationship between two
       sequences.  The first case is a similarity hit, where the annotation indicates an
       alignment.  The second case is a map assembly, in which the annotation indicates that a
       portion of a larger sequence is built up from one or more smaller ones.

       Both cases are indicated by using the Target tag in the group field.  For example, a
       typical similarity hit will look like this:

        Chr1 BLASTX similarity 76953 77108 132 + 0 Target Protein:SW:ABL_DROME 493 544

       The group field contains the Target tag, followed by an identifier for the biological
       object referred to.  The GFF format uses the notation Class:Name for the biological
       object, and even though this is stylistically inconsistent, that's the way it's done.  The
       object identifier is followed by two integers indicating the start and stop of the
       alignment on the target sequence.

       Unlike the main start and stop columns, it is possible for the target start to be greater
       than the target end.  The previous example indicates that the the section of Chr1 from
       76,953 to 77,108 aligns to the protein SW:ABL_DROME starting at position 493 and extending
       to position 544.

       A similar notation is used for sequence assembly information as shown in this example:

        Chr1        assembly Link   10922906 11177731 . . . Target Sequence:LINK_H06O01 1 254826
        LINK_H06O01 assembly Cosmid 32386    64122    . . . Target Sequence:F49B2       6 31742

       This indicates that the region between bases 10922906 and 11177731 of Chr1 are composed of
       LINK_H06O01 from bp 1 to bp 254826.  The region of LINK_H0601 between 32386 and 64122 is,
       in turn, composed of the bases 5 to 31742 of cosmid F49B2.

   Attributes
       While not intended to serve as a general-purpose sequence database (see bioperl-db for
       that), GFF allows you to tag features with arbitrary attributes.  Attributes appear in the
       Group field following the initial class/name pair.  For example:

        Chr1  cur trans  939 942 . +  . Transcript Y95B8A.2 ; Gene sma-3 ; Alias sma3

       This line tags the feature named Transcript Y95B8A.2 as being "Gene" named sma-3 and
       having the Alias "sma3".  Features having these attributes can be looked up using the
       fetch_feature_by_attribute() method.

       Two attributes have special meaning: "Note" is for backward compatibility and is used for
       unstructured text remarks.  "Alias" is considered as a synonym for the feature name and
       will be consulted when looking up a feature by its name.

   Adaptors and Aggregators
       This module uses a system of adaptors and aggregators in order to make it adaptable to use
       with a variety of databases.

       •   Adaptors

           The core of the module handles the user API, annotation coordinate arithmetic, and
           other common issues.  The details of fetching information from databases is handled by
           an adaptor, which is specified during Bio::DB::GFF construction.  The adaptor
           encapsulates database-specific information such as the schema, user authentication and
           access methods.

           There are currently five adaptors recommended for general use:

             Adaptor Name             Description
             ------------             -----------

             memory                   A simple in-memory database suitable for testing
                                       and small data sets.

             berkeleydb               An indexed file database based on the DB_File module,
                                       suitable for medium-sized read-only data sets.

             dbi::mysql               An interface to a schema implemented in the Mysql
                                       relational database management system.

             dbi::oracle              An interface to a schema implemented in the Oracle
                                       relational database management system.

             dbi::pg                  An interface to a schema implemented in the PostgreSQL
                                       relational database management system.

           Check the Bio/DB/GFF/Adaptor directory and subdirectories for other, more specialized
           adaptors, as well as experimental ones.

       •   Aggregators

           The GFF format uses a "group" field to indicate aggregation properties of individual
           features.  For example, a set of exons and introns may share a common transcript
           group, and multiple transcripts may share the same gene group.

           Aggregators are small modules that use the group information to rebuild the hierarchy.
           When a Bio::DB::GFF object is created, you indicate that it use a set of one or more
           aggregators.  Each aggregator provides a new composite annotation type.  Before the
           database query is generated each aggregator is called to "disaggregate" its annotation
           type into list of component types contained in the database.  After the query is
           generated, each aggregator is called again in order to build composite annotations
           from the returned components.

           For example, during disaggregation, the standard "processed_transcript" aggregator
           generates a list of component feature types including "UTR", "CDS", and "polyA_site".
           Later, it aggregates these features into a set of annotations of type
           "processed_transcript".

           During aggregation, the list of aggregators is called in reverse order.  This allows
           aggregators to collaborate to create multi-level structures: the transcript aggregator
           assembles transcripts from introns and exons; the gene aggregator then assembles genes
           from sets of transcripts.

           Three default aggregators are provided:

                 transcript   assembles transcripts from features of type
                              exon, CDS, 5'UTR, 3'UTR, TSS, and PolyA
                 clone        assembles clones from Clone_left_end, Clone_right_end
                              and Sequence features.
                 alignment    assembles gapped alignments from features of type
                              "similarity".

           In addition, this module provides the optional "wormbase_gene" aggregator, which
           accommodates the WormBase representation of genes.  This aggregator aggregates
           features of method "exon", "CDS", "5'UTR", "3'UTR", "polyA" and "TSS" into a single
           object.  It also expects to find a single feature of type "Sequence" that spans the
           entire gene.

           The existing aggregators are easily customized.

           Note that aggregation will not occur unless you specifically request the aggregation
           type.  For example, this call:

             @features = $segment->features('alignment');

           will generate an array of aggregated alignment features.  However, this call:

             @features = $segment->features();

           will return a list of unaggregated similarity segments.

           For more informnation, see the manual pages for
           Bio::DB::GFF::Aggregator::processed_transcript, Bio::DB::GFF::Aggregator::clone, etc.

   Loading GFF3 Files
       This module will accept GFF3 files, as described at
       http://song.sourceforge.net/gff3.shtml. However, the implementation has some limitations.

       GFF version string is required
           The GFF file must contain the version comment:

            ##gff-version 3

           Unless this version string is present at the top of the GFF file, the loader will
           attempt to parse the file in GFF2 format, with less-than-desirable results.

       Only one level of nesting allowed
           A major restriction is that Bio::DB::GFF only allows one level of nesting of features.
           For nesting, the Target tag will be used preferentially followed by the ID tag,
           followed by the Parent tag.  This means that if genes are represented like this:

             XXXX XXXX gene XXXX XXXX XXXX ID=myGene
             XXXX XXXX mRNA XXXX XXXX XXXX ID=myTranscript;Parent=myGene
             XXXX XXXX exon XXXX XXXX XXXX Parent=myTranscript
             XXXX XXXX exon XXXX XXXX XXXX Parent=myTranscript

           Then there will be one group called myGene containing the "gene" feature and one group
           called myTranscript containing the mRNA, and two exons.

           You can work around this restriction to some extent by using the Alias attribute
           literally:

             XXXX XXXX gene XXXX XXXX XXXX ID=myGene
             XXXX XXXX mRNA XXXX XXXX XXXX ID=myTranscript;Parent=myGene;Alias=myGene
             XXXX XXXX exon XXXX XXXX XXXX Parent=myTranscript;Alias=myGene
             XXXX XXXX exon XXXX XXXX XXXX Parent=myTranscript;Alias=myGene

           This limitation will be corrected in the next version of Bio::DB::GFF.

API

       The following is the API for Bio::DB::GFF.

Querying GFF Databases

   new
        Title   : new
        Usage   : my $db = Bio::DB::GFF->new(@args);
        Function: create a new Bio::DB::GFF object
        Returns : new Bio::DB::GFF object
        Args    : lists of adaptors and aggregators
        Status  : Public

       These are the arguments:

        -adaptor      Name of the adaptor module to use.  If none
                      provided, defaults to "dbi::mysqlopt".

        -aggregator   Array reference to a list of aggregators
                      to apply to the database.  If none provided,
                      defaults to ['processed_transcript','alignment'].

         -preferred_groups  When interpreteting the 9th column of a GFF2 file,
                        the indicated group names will have preference over
                        other attributes, even if they do not come first in
                        the list of attributes.  This can be a scalar value
                        or an array reference.

         <other>      Any other named argument pairs are passed to
                      the adaptor for processing.

       The adaptor argument must correspond to a module contained within the
       Bio::DB::GFF::Adaptor namespace.  For example, the Bio::DB::GFF::Adaptor::dbi::mysql
       adaptor is loaded by specifying 'dbi::mysql'.  By Perl convention, the adaptors names are
       lower case because they are loaded at run time.

       The aggregator array may contain a list of aggregator names, a list of initialized
       aggregator objects, or a string in the form
       "aggregator_name{subpart1,subpart2,subpart3/main_method}" (the "/main_method" part is
       optional, but if present a feature with the main_method must be present in order for
       aggregation to occur).  For example, if you wish to change the components aggregated by
       the transcript aggregator, you could pass it to the GFF constructor this way:

         my $transcript =
            Bio::DB::Aggregator::transcript->new(-sub_parts=>[qw(exon intron utr
                                                                 polyA spliced_leader)]);

         my $db = Bio::DB::GFF->new(-aggregator=>[$transcript,'clone','alignment],
                                    -adaptor   => 'dbi::mysql',
                                    -dsn      => 'dbi:mysql:elegans42');

       Alternatively, you could create an entirely new transcript aggregator this way:

         my $new_agg = 'transcript{exon,intron,utr,polyA,spliced_leader}';
         my $db      = Bio::DB::GFF->new(-aggregator=>[$new_agg,'clone','alignment],
                                         -adaptor   => 'dbi::mysql',
                                         -dsn       => 'dbi:mysql:elegans42');

       See Bio::DB::GFF::Aggregator for more details.

       The -preferred_groups argument is used to change the default processing of the 9th column
       of GFF version 2 files.  By default, the first tag/value pair is used to establish the
       group class and name.  If you pass -preferred_groups a scalar, the parser will look for a
       tag of the indicated type and use it as the group even if it is not first in the file.  If
       you pass this argument a list of group classes as an array ref, then the list will
       establish the precedence for searching.

       The commonly used 'dbi::mysql' adaptor recognizes the following adaptor-specific
       arguments:

         Argument       Description
         --------       -----------

         -dsn           the DBI data source, e.g. 'dbi:mysql:ens0040'
                        If a partial name is given, such as "ens0040", the
                        "dbi:mysql:" prefix will be added automatically.

         -user          username for authentication

         -pass          the password for authentication

         -refclass      landmark Class; defaults to "Sequence"

       The commonly used 'dbi::mysqlopt' adaptor also recognizes the following arguments.

         Argument       Description
         --------       -----------

         -fasta         path to a directory containing FASTA files for the DNA
                        contained in this database (e.g. "/usr/local/share/fasta")

         -acedb         an acedb URL to use when converting features into ACEDB
                           objects (e.g. sace://localhost:2005)

   types
        Title   : types
        Usage   : $db->types(@args)
        Function: return list of feature types in range or database
        Returns : a list of Bio::DB::GFF::Typename objects
        Args    : see below
        Status  : public

       This routine returns a list of feature types known to the database.  The list can be
       database-wide or restricted to a region.  It is also possible to find out how many times
       each feature occurs.

       For range queries, it is usually more convenient to create a Bio::DB::GFF::Segment object,
       and then invoke it's types() method.

       Arguments are as follows:

         -ref        ID of reference sequence
         -class      class of reference sequence
         -start      start of segment
         -stop       stop of segment
         -enumerate  if true, count the features

       The returned value will be a list of Bio::DB::GFF::Typename objects, which if evaluated in
       a string context will return the feature type in "method:source" format.  This object
       class also has method() and source() methods for retrieving the like-named fields.

       If -enumerate is true, then the function returns a hash (not a hash reference) in which
       the keys are type names in "method:source" format and the values are the number of times
       each feature appears in the database or segment.

       The argument -end is a synonum for -stop, and -count is a synonym for -enumerate.

   classes
        Title   : classes
        Usage   : $db->classes
        Function: return list of landmark classes in database
        Returns : a list of classes
        Args    : none
        Status  : public

       This routine returns the list of reference classes known to the database, or empty if
       classes are not used by the database.  Classes are distinct from types, being essentially
       qualifiers on the reference namespaces.

   segment
        Title   : segment
        Usage   : $db->segment(@args);
        Function: create a segment object
        Returns : segment object(s)
        Args    : numerous, see below
        Status  : public

       This method generates a segment object, which is a Perl object subclassed from
       Bio::DB::GFF::Segment.  The segment can be used to find overlapping features and the raw
       DNA.

       When making the segment() call, you specify the ID of a sequence landmark (e.g. an
       accession number, a clone or contig), and a positional range relative to the landmark.  If
       no range is specified, then the entire extent of the landmark is used to generate the
       segment.

       You may also provide the ID of a "reference" sequence, which will set the coordinate
       system and orientation used for all features contained within the segment.  The reference
       sequence can be changed later.  If no reference sequence is provided, then the coordinate
       system is based on the landmark.

       Arguments:

        -name         ID of the landmark sequence.

        -class        Database object class for the landmark sequence.
                      "Sequence" assumed if not specified.  This is
                      irrelevant for databases which do not recognize
                      object classes.

        -start        Start of the segment relative to landmark.  Positions
                      follow standard 1-based sequence rules.  If not specified,
                      defaults to the beginning of the landmark.

        -end          Stop of the segment relative to the landmark.  If not specified,
                      defaults to the end of the landmark.

        -stop         Same as -end.

        -offset       For those who prefer 0-based indexing, the offset specifies the
                      position of the new segment relative to the start of the landmark.

        -length       For those who prefer 0-based indexing, the length specifies the
                      length of the new segment.

        -refseq       Specifies the ID of the reference landmark used to establish the
                      coordinate system for the newly-created segment.

        -refclass     Specifies the class of the reference landmark, for those databases
                      that distinguish different object classes.  Defaults to "Sequence".

        -absolute
                      Return features in absolute coordinates rather than relative to the
                      parent segment.

        -nocheck      Don't check the database for the coordinates and length of this
                      feature.  Construct a segment using the indicated name as the
                      reference, a start coordinate of 1, an undefined end coordinate,
                      and a strand of +1.

        -force        Same as -nocheck.

        -seq,-sequence,-sourceseq   Aliases for -name.

        -begin,-end   Aliases for -start and -stop

        -off,-len     Aliases for -offset and -length

        -seqclass     Alias for -class

       Here's an example to explain how this works:

         my $db = Bio::DB::GFF->new(-dsn => 'dbi:mysql:human',-adaptor=>'dbi::mysql');

       If successful, $db will now hold the database accessor object.  We now try to fetch the
       fragment of sequence whose ID is A0000182 and class is "Accession."

         my $segment = $db->segment(-name=>'A0000182',-class=>'Accession');

       If successful, $segment now holds the entire segment corresponding to this accession
       number.  By default, the sequence is used as its own reference sequence, so its first base
       will be 1 and its last base will be the length of the accession.

       Assuming that this sequence belongs to a longer stretch of DNA, say a contig, we can fetch
       this information like so:

         my $sourceseq = $segment->sourceseq;

       and find the start and stop on the source like this:

         my $start = $segment->abs_start;
         my $stop = $segment->abs_stop;

       If we had another segment, say $s2, which is on the same contiguous piece of DNA, we can
       pass that to the refseq() method in order to establish it as the coordinate reference
       point:

         $segment->refseq($s2);

       Now calling start() will return the start of the segment relative to the beginning of $s2,
       accounting for differences in strandedness:

         my $rel_start = $segment->start;

       IMPORTANT NOTE: This method can be used to return the segment spanned by an arbitrary
       named annotation.  However, if the annotation appears at multiple locations on the genome,
       for example an EST that maps to multiple locations, then, provided that all locations
       reside on the same physical segment, the method will return a segment that spans the
       minimum and maximum positions.  If the reference sequence occupies ranges on different
       physical segments, then it returns them all in an array context, and raises a "multiple
       segment exception" exception in a scalar context.

   features
        Title   : features
        Usage   : $db->features(@args)
        Function: get all features, possibly filtered by type
        Returns : a list of Bio::DB::GFF::Feature objects
        Args    : see below
        Status  : public

       This routine will retrieve features in the database regardless of position.  It can be
       used to return all features, or a subset based on their method and source.

       Arguments are as follows:

         -types     List of feature types to return.  Argument is an array
                    reference containing strings of the format "method:source"

         -merge     Whether to apply aggregators to the generated features.

         -rare      Turn on optimizations suitable for a relatively rare feature type,
                    where it makes more sense to filter by feature type first,
                    and then by position.

         -attributes A hash reference containing attributes to match.

         -iterator  Whether to return an iterator across the features.

         -binsize   A true value will create a set of artificial features whose
                    start and stop positions indicate bins of the given size, and
                    whose scores are the number of features in the bin.  The
                    class and method of the feature will be set to "bin",
                    its source to "method:source", and its group to "bin:method:source".
                    This is a handy way of generating histograms of feature density.

       If -iterator is true, then the method returns a single scalar value consisting of a
       Bio::SeqIO object.  You can call next_seq() repeatedly on this object to fetch each of the
       features in turn.  If iterator is false or absent, then all the features are returned as a
       list.

       Currently aggregation is disabled when iterating over a series of features.

       Types are indicated using the nomenclature "method:source".  Either of these fields can be
       omitted, in which case a wildcard is used for the missing field.  Type names without the
       colon (e.g. "exon") are interpreted as the method name and a source wild card.  Regular
       expressions are allowed in either field, as in: "similarity:BLAST.*".

       The -attributes argument is a hashref containing one or more attributes to match against:

         -attributes => { Gene => 'abc-1',
                          Note => 'confirmed' }

       Attribute matching is simple string matching, and multiple attributes are ANDed together.

   get_seq_stream
        Title   : get_seq_stream
        Usage   : my $seqio = $self->get_seq_sream(@args)
        Function: Performs a query and returns an iterator over it
        Returns : a Bio::SeqIO stream capable of producing sequence
        Args    : As in features()
        Status  : public

       This routine takes the same arguments as features(), but returns a
       Bio::SeqIO::Stream-compliant object.  Use it like this:

         $stream = $db->get_seq_stream('exon');
         while (my $exon = $stream->next_seq) {
            print $exon,"\n";
         }

       NOTE: This is also called get_feature_stream(), since that's what it really does.

   get_feature_by_name
        Title   : get_feature_by_name
        Usage   : $db->get_feature_by_name($class => $name)
        Function: fetch features by their name
        Returns : a list of Bio::DB::GFF::Feature objects
        Args    : the class and name of the desired feature
        Status  : public

       This method can be used to fetch a named feature from the database.  GFF annotations are
       named using the group class and name fields, so for features that belong to a group of
       size one, this method can be used to retrieve that group (and is equivalent to the
       segment() method).  Any Alias attributes are also searched for matching names.

       An alternative syntax allows you to search for features by name within a circumscribed
       region:

         @f = $db->get_feature_by_name(-class => $class,-name=>$name,
                                       -ref   => $sequence_name,
                                       -start => $start,
                                       -end   => $end);

       This method may return zero, one, or several Bio::DB::GFF::Feature objects.

       Aggregation is performed on features as usual.

       NOTE: At various times, this function was called fetch_group(), fetch_feature(),
       fetch_feature_by_name() and segments().  These names are preserved for backward
       compatibility.

   get_feature_by_target
        Title   : get_feature_by_target
        Usage   : $db->get_feature_by_target($class => $name)
        Function: fetch features by their similarity target
        Returns : a list of Bio::DB::GFF::Feature objects
        Args    : the class and name of the desired feature
        Status  : public

       This method can be used to fetch a named feature from the database based on its similarity
       hit.

   get_feature_by_attribute
        Title   : get_feature_by_attribute
        Usage   : $db->get_feature_by_attribute(attribute1=>value1,attribute2=>value2)
        Function: fetch segments by combinations of attribute values
        Returns : a list of Bio::DB::GFF::Feature objects
        Args    : the class and name of the desired feature
        Status  : public

       This method can be used to fetch a set of features from the database.  Attributes are a
       list of name=>value pairs.  They will be logically ANDED together.

   get_feature_by_id
        Title   : get_feature_by_id
        Usage   : $db->get_feature_by_id($id)
        Function: fetch segments by feature ID
        Returns : a Bio::DB::GFF::Feature object
        Args    : the feature ID
        Status  : public

       This method can be used to fetch a feature from the database using its ID.  Not all GFF
       databases support IDs, so be careful with this.

   get_feature_by_gid
        Title   : get_feature_by_gid
        Usage   : $db->get_feature_by_gid($id)
        Function: fetch segments by feature ID
        Returns : a Bio::DB::GFF::Feature object
        Args    : the feature ID
        Status  : public

       This method can be used to fetch a feature from the database using its group ID.  Not all
       GFF databases support IDs, so be careful with this.

       The group ID is often more interesting than the feature ID, since groups can be complex
       objects containing subobjects.

   delete_fattribute_to_features
        Title   : delete_fattribute_to_features
        Usage   : $db->delete_fattribute_to_features(@ids_or_features)
        Function: delete one or more fattribute_to_features
        Returns : count of fattribute_to_features deleted
        Args    : list of features or feature ids
        Status  : public

       Pass this method a list of numeric feature ids or a set of features.  It will attempt to
       remove the fattribute_to_features rows of those features from the database and return a
       count of the rows removed.

       NOTE: This method is also called delete_fattribute_to_feature().  Also see delete_groups()
       and delete_features().

   delete_features
        Title   : delete_features
        Usage   : $db->delete_features(@ids_or_features)
        Function: delete one or more features
        Returns : count of features deleted
        Args    : list of features or feature ids
        Status  : public

       Pass this method a list of numeric feature ids or a set of features.  It will attempt to
       remove the features from the database and return a count of the features removed.

       NOTE: This method is also called delete_feature().  Also see delete_groups().

   delete_groups
        Title   : delete_groups
        Usage   : $db->delete_groups(@ids_or_features)
        Function: delete one or more feature groups
        Returns : count of features deleted
        Args    : list of features or feature group ids
        Status  : public

       Pass this method a list of numeric group ids or a set of features.  It will attempt to
       recursively remove the features and ALL members of their group from the database.  It
       returns a count of the number of features (not groups) returned.

       NOTE: This method is also called delete_group().  Also see delete_features().

   delete
        Title   : delete
        Usage   : $db->delete(@args)
        Function: delete features
        Returns : count of features deleted -- if available
        Args    : numerous, see below
        Status  : public

       This method deletes all features that overlap the specified region or are of a particular
       type.  If no arguments are provided and the -force argument is true, then deletes ALL
       features.

       Arguments:

        -name         ID of the landmark sequence.

        -ref          ID of the landmark sequence (synonym for -name).

        -class        Database object class for the landmark sequence.
                      "Sequence" assumed if not specified.  This is
                      irrelevant for databases which do not recognize
                      object classes.

        -start        Start of the segment relative to landmark.  Positions
                      follow standard 1-based sequence rules.  If not specified,
                      defaults to the beginning of the landmark.

        -end          Stop of the segment relative to the landmark.  If not specified,
                      defaults to the end of the landmark.

        -offset       Zero-based addressing

        -length       Length of region

        -type,-types  Either a single scalar type to be deleted, or an
                      reference to an array of types.

        -force        Force operation to be performed even if it would delete
                      entire feature table.

        -range_type   Control the range type of the deletion.  One of "overlaps" (default)
                      "contains" or "contained_in"

       Examples:

         $db->delete(-type=>['intron','repeat:repeatMasker']);  # remove all introns & repeats
         $db->delete(-name=>'chr3',-start=>1,-end=>1000);       # remove annotations on chr3 from 1 to 1000
         $db->delete(-name=>'chr3',-type=>'exon');              # remove all exons on chr3

       The short form of this call, as described in segment() is also allowed:

         $db->delete("chr3",1=>1000);
         $db->delete("chr3");

       IMPORTANT NOTE: This method only deletes features.  It does *NOT* delete the names of
       groups that contain the deleted features.  Group IDs will be reused if you later load a
       feature with the same group name as one that was previously deleted.

       NOTE ON FEATURE COUNTS: The DBI-based versions of this call return the result code from
       the SQL DELETE operation.  Some dbd drivers return the count of rows deleted, while others
       return 0E0.  Caveat emptor.

   absolute
        Title   : absolute
        Usage   : $abs = $db->absolute([$abs]);
        Function: gets/sets absolute mode
        Returns : current setting of absolute mode boolean
        Args    : new setting for absolute mode boolean
        Status  : public

       $db->absolute(1) will turn on absolute mode for the entire database.  All segments
       retrieved will use absolute coordinates by default, rather than relative coordinates.  You
       can still set them to use relative coordinates by calling $segment->absolute(0).

       Note that this is not the same as calling abs_segment(); it continues to allow you to look
       up groups that are not used directly as reference sequences.

   strict_bounds_checking
        Title   : strict_bounds_checking
        Usage   : $flag = $db->strict_bounds_checking([$flag])
        Function: gets/sets strict bounds checking
        Returns : current setting of bounds checking flag
        Args    : new setting for bounds checking flag
        Status  : public

       This flag enables extra checks for segment requests that go beyond the ends of their
       reference sequences.  If bounds checking is enabled, then retrieved segments will be
       truncated to their physical length, and their truncated() methods will return true.

       If the flag is off (the default), then the module will return segments that appear to
       extend beyond their physical boundaries.  Requests for features beyond the end of the
       segment will, however, return empty.

   get_Seq_by_id
        Title   : get_Seq_by_id
        Usage   : $seq = $db->get_Seq_by_id('ROA1_HUMAN')
        Function: Gets a Bio::Seq object by its name
        Returns : a Bio::Seq object
        Args    : the id (as a string) of a sequence
        Throws  : "id does not exist" exception

       NOTE: Bio::DB::RandomAccessI compliant method

   get_Seq_by_accession
        Title   : get_Seq_by_accession
        Usage   : $seq = $db->get_Seq_by_accession('AL12234')
        Function: Gets a Bio::Seq object by its accession
        Returns : a Bio::Seq object
        Args    : the id (as a string) of a sequence
        Throws  : "id does not exist" exception

       NOTE: Bio::DB::RandomAccessI compliant method

   get_Seq_by_acc
        Title   : get_Seq_by_acc
        Usage   : $seq = $db->get_Seq_by_acc('X77802');
        Function: Gets a Bio::Seq object by accession number
        Returns : A Bio::Seq object
        Args    : accession number (as a string)
        Throws  : "acc does not exist" exception

       NOTE: Bio::DB::RandomAccessI compliant method

   get_Stream_by_name
         Title   : get_Stream_by_name
         Usage   : $seq = $db->get_Stream_by_name(@ids);
         Function: Retrieves a stream of Seq objects given their names
         Returns : a Bio::SeqIO stream object
         Args    : an array of unique ids/accession numbers, or
                   an array reference

       NOTE: This is also called get_Stream_by_batch()

   get_Stream_by_id
         Title   : get_Stream_by_id
         Usage   : $seq = $db->get_Stream_by_id(@ids);
         Function: Retrieves a stream of Seq objects given their ids
         Returns : a Bio::SeqIO stream object
         Args    : an array of unique ids/accession numbers, or
                   an array reference

       NOTE: This is also called get_Stream_by_batch()

   get_Stream_by_batch ()
         Title   : get_Stream_by_batch
         Usage   : $seq = $db->get_Stream_by_batch(@ids);
         Function: Retrieves a stream of Seq objects given their ids
         Returns : a Bio::SeqIO stream object
         Args    : an array of unique ids/accession numbers, or
                   an array reference

       NOTE: This is the same as get_Stream_by_id().

   get_Stream_by_group ()
       Bioperl compatibility.

   all_seqfeatures
        Title   : all_seqfeatures
        Usage   : @features = $db->all_seqfeatures(@args)
        Function: fetch all the features in the database
        Returns : an array of features, or an iterator
        Args    : See below
        Status  : public

       This is equivalent to calling $db->features() without any types, and will return all the
       features in the database.  The -merge and -iterator arguments are recognized, and behave
       the same as described for features().

Creating and Loading GFF Databases

   initialize
        Title   : initialize
        Usage   : $db->initialize(-erase=>$erase,-option1=>value1,-option2=>value2);
        Function: initialize a GFF database
        Returns : true if initialization successful
        Args    : a set of named parameters
        Status  : Public

       This method can be used to initialize an empty database.  It takes the following named
       arguments:

         -erase     A boolean value.  If true the database will be wiped clean if it
                    already contains data.

       Other named arguments may be recognized by subclasses.  They become database meta values
       that control various settable options.

       As a shortcut (and for backward compatibility) a single true argument is the same as
       initialize(-erase=>1).

   load_gff
        Title   : load_gff
        Usage   : $db->load_gff($file|$directory|$filehandle [,$verbose]);
        Function: load GFF data into database
        Returns : count of records loaded
        Args    : a directory, a file, a list of files,
                  or a filehandle
        Status  : Public

       This method takes a single overloaded argument, which can be any of:

       •   a scalar corresponding to a GFF file on the system

           A pathname to a local GFF file.  Any files ending with the .gz, .Z, or .bz2 suffixes
           will be transparently decompressed with the appropriate command-line utility.

       •   an array reference containing a list of GFF files on the system

           For example ['/home/gff/gff1.gz','/home/gff/gff2.gz']

       •   directory path

           The indicated directory will be searched for all files ending in the suffixes .gff,
           .gff.gz, .gff.Z or .gff.bz2.

       •   filehandle

           An open filehandle from which to read the GFF data.  Tied filehandles now work as
           well.

       •   a pipe expression

           A pipe expression will also work. For example, a GFF file on a remote web server can
           be loaded with an expression like this:

             $db->load_gff("lynx -dump -source http://stein.cshl.org/gff_test |");

       The optional second argument, if true, will turn on verbose status reports that indicate
       the progress.

       If successful, the method will return the number of GFF lines successfully loaded.

       NOTE:this method used to be called load(), but has been changed.  The old method name is
       also recognized.

   load_gff_file
        Title   : load_gff_file
        Usage   : $db->load_gff_file($file [,$verbose]);
        Function: load GFF data into database
        Returns : count of records loaded
        Args    : a path to a file
        Status  : Public

       This is provided as an alternative to load_gff_file. It doesn't munge STDIN or play tricks
       with ARGV.

   load_fasta
        Title   : load_fasta
        Usage   : $db->load_fasta($file|$directory|$filehandle);
        Function: load FASTA data into database
        Returns : count of records loaded
        Args    : a directory, a file, a list of files,
                  or a filehandle
        Status  : Public

       This method takes a single overloaded argument, which can be any of:

       •   scalar corresponding to a FASTA file on the system

           A pathname to a local FASTA file.  Any files ending with the .gz, .Z, or .bz2 suffixes
           will be transparently decompressed with the appropriate command-line utility.

       •   array reference containing a list of FASTA files on the system

           For example ['/home/fasta/genomic.fa.gz','/home/fasta/genomic.fa.gz']

       •   path to a directory

           The indicated directory will be searched for all files ending in the suffixes .fa,
           .fa.gz, .fa.Z or .fa.bz2.

       •   filehandle

           An open filehandle from which to read the FASTA data.

       •   pipe expression

           A pipe expression will also work. For example, a FASTA file on a remote web server can
           be loaded with an expression like this:

             $db->load_gff("lynx -dump -source http://stein.cshl.org/fasta_test.fa |");

   load_fasta_file
        Title   : load_fasta_file
        Usage   : $db->load_fasta_file($file [,$verbose]);
        Function: load FASTA data into database
        Returns : count of records loaded
        Args    : a path to a file
        Status  : Public

       This is provided as an alternative to load_fasta. It doesn't munge STDIN or play tricks
       with ARGV.

   load_sequence_string
        Title   : load_sequence_string
        Usage   : $db->load_sequence_string($id,$dna)
        Function: load a single DNA entry
        Returns : true if successfully loaded
        Args    : a raw sequence string (DNA, RNA, protein)
        Status  : Public

   lock_on_load
        Title   : lock_on_load
        Usage   : $lock = $db->lock_on_load([$lock])
        Function: set write locking during load
        Returns : current value of lock-on-load flag
        Args    : new value of lock-on-load-flag
        Status  : Public

       This method is honored by some of the adaptors.  If the value is true, the tables used by
       the GFF modules will be locked for writing during loads and inaccessible to other
       processes.

   meta
        Title   : meta
        Usage   : $value = $db->meta($name [,$newval])
        Function: get or set a meta variable
        Returns : a string
        Args    : meta variable name and optionally value
        Status  : abstract

       Get or set a named metavalues for the database.  Metavalues can be used for database-
       specific settings.

       By default, this method does nothing!

   default_meta_values
        Title   : default_meta_values
        Usage   : %values = $db->default_meta_values
        Function: empty the database
        Returns : a list of tag=>value pairs
        Args    : none
        Status  : protected

       This method returns a list of tag=>value pairs that contain default meta information about
       the database.  It is invoked by initialize() to write out the default meta values.  The
       base class version returns an empty list.

       For things to work properly, meta value names must be UPPERCASE.

   error
        Title   : error
        Usage   : $db->error( [$new error] );
        Function: read or set error message
        Returns : error message
        Args    : an optional argument to set the error message
        Status  : Public

       This method can be used to retrieve the last error message.  Errors are not reset to empty
       by successful calls, so contents are only valid immediately after an error condition has
       been detected.

   debug
        Title   : debug
        Usage   : $db->debug( [$flag] );
        Function: read or set debug flag
        Returns : current value of debug flag
        Args    : new debug flag (optional)
        Status  : Public

       This method can be used to turn on debug messages.  The exact nature of those messages
       depends on the adaptor in use.

   automerge
        Title   : automerge
        Usage   : $db->automerge( [$new automerge] );
        Function: get or set automerge value
        Returns : current value (boolean)
        Args    : an optional argument to set the automerge value
        Status  : Public

       By default, this module will use the aggregators to merge groups into single composite
       objects.  This default can be changed to false by calling automerge(0).

   attributes
        Title   : attributes
        Usage   : @attributes = $db->attributes($id,$name)
        Function: get the "attributes" on a particular feature
        Returns : an array of string
        Args    : feature ID
        Status  : public

       Some GFF version 2 files use the groups column to store a series of attribute/value pairs.
       In this interpretation of GFF, the first such pair is treated as the primary group for the
       feature; subsequent pairs are treated as attributes.  Two attributes have special meaning:
       "Note" is for backward compatibility and is used for unstructured text remarks.  "Alias"
       is considered as a synonym for the feature name.

       If no name is provided, then attributes() returns a flattened hash, of attribute=>value
       pairs.  This lets you do:

         %attributes = $db->attributes($id);

       If no arguments are provided, attributes() will return the list of all attribute names:

         @attribute_names = $db->attributes();

       Normally, however, attributes() will be called by the feature:

         @notes = $feature->attributes('Note');

       In a scalar context, attributes() returns the first value of the attribute if a tag is
       present, otherwise a hash reference in which the keys are attribute names and the values
       are anonymous arrays containing the values.

   fast_queries
        Title   : fast_queries
        Usage   : $flag = $db->fast_queries([$flag])
        Function: turn on and off the "fast queries" option
        Returns : a boolean
        Args    : a boolean flag (optional)
        Status  : public

       The mysql database driver (and possibly others) support a "fast" query mode that caches
       results on the server side.  This makes queries come back faster, particularly when
       creating iterators.  The downside is that while iterating, new queries will die with a
       "command synch" error.  This method turns the feature on and off.

       For databases that do not support a fast query, this method has no effect.

   add_aggregator
        Title   : add_aggregator
        Usage   : $db->add_aggregator($aggregator)
        Function: add an aggregator to the list
        Returns : nothing
        Args    : an aggregator
        Status  : public

       This method will append an aggregator to the end of the list of registered aggregators.
       Three different argument types are accepted:

         1) a Bio::DB::GFF::Aggregator object -- will be added
         2) a string in the form "aggregator_name{subpart1,subpart2,subpart3/main_method}"
                -- will be turned into a Bio::DB::GFF::Aggregator object (the /main_method
               part is optional).
         3) a valid Perl token -- will be turned into a Bio::DB::GFF::Aggregator
               subclass, where the token corresponds to the subclass name.

   aggregators
        Title   : aggregators
        Usage   : $db->aggregators([@new_aggregators]);
        Function: retrieve list of aggregators
        Returns : list of aggregators
        Args    : a list of aggregators to set (optional)
        Status  : public

       This method will get or set the list of aggregators assigned to the database.  If 1 or
       more arguments are passed, the existing set will be cleared.

   clear_aggregators
        Title   : clear_aggregators
        Usage   : $db->clear_aggregators
        Function: clears list of aggregators
        Returns : nothing
        Args    : none
        Status  : public

       This method will clear the aggregators stored in the database object.  Use aggregators()
       or add_aggregator() to add some back.

   preferred_groups
        Title   : preferred_groups
        Usage   : $db->preferred_groups([$group_name_or_arrayref])
        Function: get/set list of groups for altering GFF2 parsing
        Returns : a list of classes
        Args    : new list (scalar or array ref)
        Status  : public

Methods for use by Subclasses

       The following methods are chiefly of interest to subclasses and are not intended for use
       by end programmers.

   abscoords
        Title   : abscoords
        Usage   : $db->abscoords($name,$class,$refseq)
        Function: finds position of a landmark in reference coordinates
        Returns : ($ref,$class,$start,$stop,$strand)
        Args    : name and class of landmark
        Status  : public

       This method is called by Bio::DB::GFF::RelSegment to obtain the absolute coordinates of a
       sequence landmark.  The arguments are the name and class of the landmark.  If successful,
       abscoords() returns the ID of the reference sequence, its class, its start and stop
       positions, and the orientation of the reference sequence's coordinate system ("+" for
       forward strand, "-" for reverse strand).

       If $refseq is present in the argument list, it forces the query to search for the landmark
       in a particular reference sequence.

Protected API

       The following methods are not intended for public consumption, but are intended to be
       overridden/implemented by adaptors.

   default_aggregators
        Title   : default_aggregators
        Usage   : $db->default_aggregators;
        Function: retrieve list of aggregators
        Returns : array reference containing list of aggregator names
        Args    : none
        Status  : protected

       This method (which is intended to be overridden by adaptors) returns a list of standard
       aggregators to be applied when no aggregators are specified in the constructor.

   do_load_gff
        Title   : do_load_gff
        Usage   : $db->do_load_gff($handle)
        Function: load a GFF input stream
        Returns : number of features loaded
        Args    : A filehandle.
        Status  : protected

       This method is called to load a GFF data stream.  The method will read GFF features from
       <> and load them into the database.  On exit the method must return the number of features
       loaded.

       Note that the method is responsible for parsing the GFF lines.  This is to allow for
       differences in the interpretation of the "group" field, which are legion.

       You probably want to use load_gff() instead.  It is more flexible about the arguments it
       accepts.

   load_sequence
        Title   : load_sequence
        Usage   : $db->load_sequence($handle)
        Function: load a FASTA data stream
        Returns : number of sequences
        Args    : a filehandle to the FASTA file
        Status  : protected

       You probably want to use load_fasta() instead.

   setup_load
        Title   : setup_load
        Usage   : $db->setup_load
        Function: called before load_gff_line()
        Returns : void
        Args    : none
        Status  : abstract

       This abstract method gives subclasses a chance to do any schema-specific initialization
       prior to loading a set of GFF records.  It must be implemented by a subclass.

   finish_load
        Title   : finish_load
        Usage   : $db->finish_load
        Function: called after load_gff_line()
        Returns : number of records loaded
        Args    : none
        Status  :abstract

       This method gives subclasses a chance to do any schema-specific cleanup after loading a
       set of GFF records.

   load_gff_line
        Title   : load_gff_line
        Usage   : $db->load_gff_line(@args)
        Function: called to load one parsed line of GFF
        Returns : true if successfully inserted
        Args    : see below
        Status  : abstract

       This abstract method is called once per line of the GFF and passed a hashref containing
       parsed GFF fields.  The fields are:

        {ref    => $ref,
         class  => $class,
         source => $source,
         method => $method,
         start  => $start,
         stop   => $stop,
         score  => $score,
         strand => $strand,
         phase  => $phase,
         gclass => $gclass,
         gname  => $gname,
         tstart => $tstart,
         tstop  => $tstop,
         attributes  => $attributes}

   do_initialize
        Title   : do_initialize
        Usage   : $db->do_initialize([$erase])
        Function: initialize and possibly erase database
        Returns : true if successful
        Args    : optional erase flag
        Status  : protected

       This method implements the initialize() method described above, and takes the same
       arguments.

   dna
        Title   : dna
        Usage   : $db->dna($id,$start,$stop,$class)
        Function: return the raw DNA string for a segment
        Returns : a raw DNA string
        Args    : id of the sequence, its class, start and stop positions
        Status  : public

       This method is invoked by Bio::DB::GFF::Segment to fetch the raw DNA sequence.

       Arguments: -name          sequence name
                  -start         start position
                  -stop          stop position
                  -class         sequence class

       If start and stop are both undef, then the entire DNA is retrieved.  So to fetch the whole
       dna, call like this:

         $db->dna($name_of_sequence);

       or like this:

          $db->dna(-name=>$name_of_sequence,-class=>$class_of_sequence);

       NOTE: you will probably prefer to create a Segment and then invoke its dna() method.

   get_dna
        Title   : get_dna
        Usage   : $db->get_dna($id,$start,$stop,$class)
        Function: get DNA for indicated segment
        Returns : the dna string
        Args    : sequence ID, start, stop and class
        Status  : protected

       If start > stop and the sequence is nucleotide, then this method should return the reverse
       complement.  The sequence class may be ignored by those databases that do not recognize
       different object types.

   get_features
        Title   : get_features
        Usage   : $db->get_features($search,$options,$callback)
        Function: get list of features for a region
        Returns : count of number of features retrieved
        Args    : see below
        Status  : protected

       The first argument is a hash reference containing search criteria for retrieving features.
       It contains the following keys:

          rangetype One of "overlaps", "contains" or "contained_in".  Indicates
                     the type of range query requested.

          refseq    ID of the landmark that establishes the absolute
                     coordinate system.

          refclass  Class of this landmark.  Can be ignored by implementations
                     that don't recognize such distinctions.

          start     Start of the range, inclusive.

          stop      Stop of the range, inclusive.

          types     Array reference containing the list of annotation types
                     to fetch from the database.  Each annotation type is an
                     array reference consisting of [source,method].

       The second argument is a hash reference containing certain options that affect the way
       information is retrieved:

          sort_by_group
                    A flag.  If true, means that the returned features should be
                    sorted by the group that they're in.

          sparse    A flag.  If true, means that the expected density of the
                    features is such that it will be more efficient to search
                    by type rather than by range.  If it is taking a long
                    time to fetch features, give this a try.

          binsize   A true value will create a set of artificial features whose
                    start and stop positions indicate bins of the given size, and
                    whose scores are the number of features in the bin.  The
                    class of the feature will be set to "bin", and its name to
                    "method:source".  This is a handy way of generating histograms
                    of feature density.

       The third argument, the $callback, is a code reference to which retrieved features are
       passed.  It is described in more detail below.

       This routine is responsible for getting arrays of GFF data out of the database and passing
       them to the callback subroutine.  The callback does the work of constructing a
       Bio::DB::GFF::Feature object out of that data.  The callback expects a list of 13 fields:

         $refseq      The reference sequence
         $start       feature start
         $stop        feature stop
         $source      feature source
         $method      feature method
         $score       feature score
         $strand      feature strand
         $phase       feature phase
         $groupclass  group class (may be undef)
         $groupname   group ID (may be undef)
         $tstart      target start for similarity hits (may be undef)
         $tstop       target stop for similarity hits (may be undef)
         $feature_id  A unique feature ID (may be undef)

       These fields are in the same order as the raw GFF file, with the exception that the group
       column has been parsed into group class and group name fields.

       The feature ID, if provided, is a unique identifier of the feature line.  The module does
       not depend on this ID in any way, but it is available via Bio::DB::GFF->id() if wanted.
       In the dbi::mysql and dbi::mysqlopt adaptor, the ID is a unique row ID.  In the acedb
       adaptor it is not used.

   feature_summary(), coverage_array()
       The DBI adaptors provide methods for rapidly fetching coverage statistics across a region
       of interest. Please see Bio::DB::GFF::Adaptor::dbi for more information about these
       methods.

   _feature_by_name
        Title   : _feature_by_name
        Usage   : $db->_feature_by_name($class,$name,$location,$callback)
        Function: get a list of features by name and class
        Returns : count of number of features retrieved
        Args    : name of feature, class of feature, and a callback
        Status  : abstract

       This method is used internally.  The callback arguments are the same as those used by
       make_feature().  This method must be overridden by subclasses.

   _feature_by_id
        Title   : _feature_by_id
        Usage   : $db->_feature_by_id($ids,$type,$callback)
        Function: get a feature based
        Returns : count of number of features retrieved
        Args    : arrayref to feature IDs to fetch
        Status  : abstract

       This method is used internally to fetch features either by their ID or their group ID.
       $ids is a arrayref containing a list of IDs, $type is one of "feature" or "group", and
       $callback is a callback.  The callback arguments are the same as those used by
       make_feature().  This method must be overridden by subclasses.

   overlapping_features
        Title   : overlapping_features
        Usage   : $db->overlapping_features(@args)
        Function: get features that overlap the indicated range
        Returns : a list of Bio::DB::GFF::Feature objects
        Args    : see below
        Status  : public

       This method is invoked by Bio::DB::GFF::Segment->features() to find the list of features
       that overlap a given range.  It is generally preferable to create the Segment first, and
       then fetch the features.

       This method takes set of named arguments:

         -refseq    ID of the reference sequence
         -class     Class of the reference sequence
         -start     Start of the desired range in refseq coordinates
         -stop      Stop of the desired range in refseq coordinates
         -types     List of feature types to return.  Argument is an array
                    reference containing strings of the format "method:source"
         -parent    A parent Bio::DB::GFF::Segment object, used to create
                    relative coordinates in the generated features.
         -rare      Turn on an optimization suitable for a relatively rare feature type,
                    where it will be faster to filter by feature type first
                    and then by position, rather than vice versa.
         -merge     Whether to apply aggregators to the generated features.
         -iterator  Whether to return an iterator across the features.

       If -iterator is true, then the method returns a single scalar value consisting of a
       Bio::SeqIO object.  You can call next_seq() repeatedly on this object to fetch each of the
       features in turn.  If iterator is false or absent, then all the features are returned as a
       list.

       Currently aggregation is disabled when iterating over a series of features.

       Types are indicated using the nomenclature "method:source".  Either of these fields can be
       omitted, in which case a wildcard is used for the missing field.  Type names without the
       colon (e.g. "exon") are interpreted as the method name and a source wild card.  Regular
       expressions are allowed in either field, as in: "similarity:BLAST.*".

   contained_features
        Title   : contained_features
        Usage   : $db->contained_features(@args)
        Function: get features that are contained within the indicated range
        Returns : a list of Bio::DB::GFF::Feature objects
        Args    : see overlapping_features()
        Status  : public

       This call is similar to overlapping_features(), except that it only retrieves features
       whose end points are completely contained within the specified range.

       Generally you will want to fetch a Bio::DB::GFF::Segment object and call its
       contained_features() method rather than call this directly.

   contained_in
        Title   : contained_in
        Usage   : @features = $s->contained_in(@args)
        Function: get features that contain this segment
        Returns : a list of Bio::DB::GFF::Feature objects
        Args    : see features()
        Status  : Public

       This is identical in behavior to features() except that it returns only those features
       that completely contain the segment.

   get_abscoords
        Title   : get_abscoords
        Usage   : $db->get_abscoords($name,$class,$refseq)
        Function: get the absolute coordinates of sequence with name & class
        Returns : ($absref,$absstart,$absstop,$absstrand)
        Args    : name and class of the landmark
        Status  : protected

       Given the name and class of a genomic landmark, this function returns a four-element array
       consisting of:

         $absref      the ID of the reference sequence that contains this landmark
         $absstart    the position at which the landmark starts
         $absstop     the position at which the landmark stops
         $absstrand   the strand of the landmark, relative to the reference sequence

       If $refseq is provided, the function searches only within the specified reference
       sequence.

   get_types
        Title   : get_types
        Usage   : $db->get_types($absref,$class,$start,$stop,$count)
        Function: get list of all feature types on the indicated segment
        Returns : list or hash of Bio::DB::GFF::Typename objects
        Args    : see below
        Status  : protected

       Arguments are:

         $absref      the ID of the reference sequence
         $class       the class of the reference sequence
         $start       the position to start counting
         $stop        the position to end counting
         $count       a boolean indicating whether to count the number
                      of occurrences of each feature type

       If $count is true, then a hash is returned.  The keys of the hash are feature type names
       in the format "method:source" and the values are the number of times a feature of this
       type overlaps the indicated segment.  Otherwise, the call returns a set of
       Bio::DB::GFF::Typename objects.  If $start or $stop are undef, then all features on the
       indicated segment are enumerated.  If $absref is undef, then the call returns all feature
       types in the database.

   make_feature
        Title   : make_feature
        Usage   : $db->make_feature(@args)
        Function: Create a Bio::DB::GFF::Feature object from string data
        Returns : a Bio::DB::GFF::Feature object
        Args    : see below
        Status  : internal

        This takes 14 arguments (really!):

         $parent                A Bio::DB::GFF::RelSegment object
         $group_hash            A hashref containing unique list of GFF groups
         $refname               The name of the reference sequence for this feature
         $refclass              The class of the reference sequence for this feature
         $start                 Start of feature
         $stop                  Stop of feature
         $source                Feature source field
         $method                Feature method field
         $score                 Feature score field
         $strand                Feature strand
         $phase                 Feature phase
         $group_class           Class of feature group
         $group_name            Name of feature group
         $tstart                For homologies, start of hit on target
         $tstop                 Stop of hit on target

       The $parent argument, if present, is used to establish relative coordinates in the
       resulting Bio::DB::Feature object.  This allows one feature to generate a list of other
       features that are relative to its coordinate system (for example, finding the coordinates
       of the second exon relative to the coordinates of the first).

       The $group_hash allows the group_class/group_name strings to be turned into rich database
       objects via the make_obect() method (see above).  Because these objects may be expensive
       to create, $group_hash is used to uniquefy them.  The index of this hash is the composite
       key {$group_class,$group_name,$tstart,$tstop}.  Values are whatever object is returned by
       the make_object() method.

       The remainder of the fields are taken from the GFF line, with the exception that "Target"
       features, which contain information about the target of a homology search, are parsed into
       their components.

   make_match_sub
        Title   : make_match_sub
        Usage   : $db->make_match_sub($types)
        Function: creates a subroutine used for filtering features
        Returns : a code reference
        Args    : a list of parsed type names
        Status  : protected

       This method is used internally to generate a code subroutine that will accept or reject a
       feature based on its method and source.  It takes an array of parsed type names in the
       format returned by parse_types(), and generates an anonymous subroutine.  The subroutine
       takes a single Bio::DB::GFF::Feature object and returns true if the feature matches one of
       the desired feature types, and false otherwise.

   make_object
        Title   : make_object
        Usage   : $db->make_object($class,$name,$start,$stop)
        Function: creates a feature object
        Returns : a feature object
        Args    : see below
        Status  : protected

       This method is called to make an object from the GFF "group" field.  By default, all
       Target groups are turned into Bio::DB::GFF::Homol objects, and everything else becomes a
       Bio::DB::GFF::Featname.  However, adaptors are free to override this method to generate
       more interesting objects, such as true BioPerl objects, or Acedb objects.

       Arguments are:

         $name      database ID for object
         $class     class of object
         $start     for similarities, start of match inside object
         $stop      for similarities, stop of match inside object

   do_attributes
        Title   : do_attributes
        Usage   : $db->do_attributes($id [,$tag]);
        Function: internal method to retrieve attributes given an id and tag
        Returns : a list of Bio::DB::GFF::Feature objects
        Args    : a feature id and a attribute tag (optional)
        Status  : protected

       This method is overridden by subclasses in order to return a list of attributes.  If
       called with a tag, returns the value of attributes of that tag type.  If called without a
       tag, returns a flattened array of (tag=>value) pairs.  A particular tag can be present
       multiple times.

   clone
       The clone() method should be used when you want to pass the Bio::DB::GFF object to a child
       process across a fork(). The child must call clone() before making any queries.

       The default behavior is to do nothing, but adaptors that use the DBI interface may need to
       implement this in order to avoid database handle errors. See the dbi adaptor for an
       example.

Internal Methods

       The following methods are internal to Bio::DB::GFF and are not guaranteed to remain the
       same.

   _features
        Title   : _features
        Usage   : $db->_features($search,$options,$parent)
        Function: internal method
        Returns : a list of Bio::DB::GFF::Feature objects
        Args    : see below
        Status  : internal

       This is an internal method that is called by overlapping_features(), contained_features()
       and features() to create features based on a parent segment's coordinate system.  It takes
       three arguments, a search options hashref, an options hashref, and a parent segment.

       The search hashref contains the following keys:

         rangetype     One of "overlaps", "contains" or "contained_in".  Indicates
                       the type of range query requested.
         refseq        reference sequence ID
         refclass      reference sequence class
         start         start of range
         stop          stop of range
         types         arrayref containing list of types in "method:source" form

       The options hashref contains zero or more of the following keys:

         sparse        turn on optimizations for a rare feature
         automerge     if true, invoke aggregators to merge features
         iterator      if true, return an iterator

       The $parent argument is a scalar object containing a Bio::DB::GFF::RelSegment object or
       descendent.

   get_features_iterator
        Title   : get_features_iterator
        Usage   : $db->get_features_iterator($search,$options,$callback)
        Function: get an iterator on a features query
        Returns : a Bio::SeqIO object
        Args    : as per get_features()
        Status  : Public

       This method takes the same arguments as get_features(), but returns an iterator that can
       be used to fetch features sequentially, as per Bio::SeqIO.

       Internally, this method is simply a front end to range_query().  The latter method
       constructs and executes the query, returning a statement handle. This routine passes the
       statement handle to the constructor for the iterator, along with the callback.

   split_group
        Title   : split_group
        Usage   : $db->split_group($group_field,$gff3_flag)
        Function: parse GFF group field
        Returns : ($gclass,$gname,$tstart,$tstop,$attributes)
        Args    : the gff group column and a flag indicating gff3 compatibility
        Status  : internal

       This is a method that is called by load_gff_line to parse out the contents of one or more
       group fields.  It returns the class of the group, its name, the start and stop of the
       target, if any, and an array reference containing any attributes that were stuck into the
       group field, in [attribute_name,attribute_value] format.

   _split_gff2_group
       This is an internal method called by split_group().

   gff3_name_munging
        Title   : gff3_name_munging
        Usage   : $db->gff3_name_munging($boolean)
        Function: get/set gff3_name_munging flag
        Returns : $current value of flag
        Args    : new value of flag (optional)
        Status  : utility

       If this is set to true (default false), then features identified in gff3 files with an ID
       in the format foo:bar will be parsed so that "foo" is the class and "bar" is the name.
       This is mostly for backward compatibility with GFF2.

   _split_gff3_group
       This is called internally from split_group().

   _delete_features(), _delete_groups(),_delete(),_delete_fattribute_to_features()
        Title   : _delete_features(), _delete_groups(),_delete(),_delete_fattribute_to_features()
        Usage   : $count = $db->_delete_features(@feature_ids)
                  $count = $db->_delete_groups(@group_ids)
                  $count = $db->_delete(\%delete_spec)
                  $count = $db->_delete_fattribute_to_features(@feature_ids)
        Function: low-level feature/group deleter
        Returns : count of groups removed
        Args    : list of feature or group ids removed
        Status  : for implementation by subclasses

       These methods need to be implemented in adaptors.  For _delete_features, _delete_groups
       and _delete_fattribute_to_features, the arguments are a list of feature or group IDs to
       remove.  For _delete(), the argument is a hashref with the three keys 'segments', 'types'
       and 'force'.  The first contains an arrayref of Bio::DB::GFF::RelSegment objects to delete
       (all FEATURES within the segment are deleted).  The second contains an arrayref of
       [method,source] feature types to delete.  The two are ANDed together.  If 'force' has a
       true value, this forces the operation to continue even if it would delete all features.

BUGS

       Features can only belong to a single group at a time.  This must be addressed soon.

       Start coordinate can be greater than stop coordinate for relative addressing.  This breaks
       strict BioPerl compatibility and must be fixed.

SEE ALSO

       Bio::DB::GFF::RelSegment, Bio::DB::GFF::Aggregator, Bio::DB::GFF::Feature,
       Bio::DB::GFF::Adaptor::dbi::mysqlopt, Bio::DB::GFF::Adaptor::dbi::oracle,
       Bio::DB::GFF::Adaptor::memory Bio::DB::GFF::Adaptor::berkeleydb

AUTHOR

       Lincoln Stein <lstein@cshl.org>.

       Copyright (c) 2001 Cold Spring Harbor Laboratory.

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.