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

NAME

       Bio::DB::GFF::Adaptor::dbi -- Database adaptor for DBI (SQL) databases

SYNOPSIS

       See Bio::DB::GFF

DESCRIPTION

       This is the base class for DBI-based adaptors.  It does everything except generating the
       text of the queries to be used.  See the section QUERIES TO IMPLEMENT for the list of
       methods that must be implemented.

   new
        Title   : new
        Usage   : $db = Bio::DB::GFF->new(@args)
        Function: create a new adaptor
        Returns : a Bio::DB::GFF object
        Args    : see below
        Status  : Public

       This is the constructor for the adaptor.  It is called automatically by Bio::DB::GFF->new.
       In addition to arguments that are common among all adaptors, the following class-specific
       arguments are recgonized:

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

         -dsn           the DBI data source, e.g. 'dbi:mysql:ens0040'

         -user          username for authentication

         -pass          the password for authentication

   features_db
        Title   : features_db
        Usage   : $dbh = $db->features_db
        Function: get database handle
        Returns : a DBI handle
        Args    : none
        Status  : Public

        Note: what is returned is not really a DBI::db handle, but a
        subclass of one.  This means that you cannot manipulate the
        handle's attributes directly.  Instead call the attribute
        method:

        my $dbh = $db->features_db;
        $dbh->attribute(AutoCommit=>0);

   get_dna
        Title   : get_dna
        Usage   : $string = $db->get_dna($name,$start,$stop,$class)
        Function: get DNA string
        Returns : a string
        Args    : name, class, start and stop of desired segment
        Status  : Public

       This method performs the low-level fetch of a DNA substring given its name, class and the
       desired range.  It is actually a front end to the abstract method make_dna_query(), which
       it calls after some argument consistency checking.

   get_abscoords
        Title   : get_abscoords
        Usage   : ($refseq,$refclass,$start,$stop,$strand) = $db->get_abscoords($name,$class)
        Function: get absolute coordinates for landmark
        Returns : an array ref -- see below
        Args    : name and class of desired landmark
        Status  : Public

       This method performs the low-level resolution of a landmark into a reference sequence and
       position.

       The result is an array ref, each element of which is a five-element list containing
       reference sequence name, class, start, stop and strand.

   get_features
        Title   : get_features
        Usage   : $db->get_features($search,$options,$callback)
        Function: retrieve features from the database
        Returns : number of features retrieved
        Args    : see below
        Status  : Public

       This is the low-level method that is called to retrieve GFF lines from the database.  It
       is responsible for retrieving features that satisfy range and feature type criteria, and
       passing the GFF fields to a callback subroutine.

       See the manual page for Bio::DB::GFF for the interpretation of the arguments and how the
       information retrieved by get_features is passed to the callback for processing.

       Internally, get_features() is a front end for range_query().  The latter method constructs
       the query and executes it.  get_features() calls fetchrow_array() to recover the fields
       and passes them to the callback.

   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.

       NOTE: In the current mysql-based schema, this query takes a while to run due to the
       classes not being normalized.

   make_classes_query
        Title   : make_classes_query
        Usage   : ($query,@args) = $db->make_classes_query
        Function: return query fragment for generating list of reference classes
        Returns : a query and args
        Args    : none
        Status  : public

   _feature_by_name
        Title   : _feature_by_name
        Usage   : $db->get_features_by_name($name,$class,$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  : protected

       This method is used internally.  The callback arguments are those used by make_feature().
       Internally, it invokes the following abstract procedures:

        make_features_select_part
        make_features_from_part
        make_features_by_name_where_part
        make_features_by_alias_where_part  (for aliases)
        make_features_join_part

   _feature_by_id
        Title   : _feature_by_id
        Usage   : $db->_feature_by_id($ids,$type,$callback)
        Function: get a list of features by ID
        Returns : count of number of features retrieved
        Args    : arrayref containing list of IDs to fetch and a callback
        Status  : protected

       This method is used internally.  The $type selector is one of "feature" or "group".  The
       callback arguments are those used by make_feature().  Internally, it invokes the following
       abstract procedures:

        make_features_select_part
        make_features_from_part
        make_features_by_id_where_part
        make_features_join_part

   get_types
        Title   : get_types
        Usage   : $db->get_types($refseq,$refclass,$start,$stop,$count)
        Function: get list of types
        Returns : a list of Bio::DB::GFF::Typename objects
        Args    : see below
        Status  : Public

       This method is responsible for fetching the list of feature type names from the database.
       The query may be limited to a particular range, in which case the range is indicated by a
       landmark sequence name and class and its subrange, if any.  These arguments may be undef
       if it is desired to retrieve all feature types in the database (which may be a slow
       operation in some implementations).

       If the $count flag is false, the method returns a simple list of vBio::DB::GFF::Typename
       objects.  If $count is true, the method returns a list of $name=>$count pairs, where
       $count indicates the number of times this feature occurs in the range.

       Internally, this method calls upon the following functions to generate the SQL and its
       bind variables:

         ($q1,@args) = make_types_select_part(@args);
         ($q2,@args) = make_types_from_part(@args);
         ($q3,@args) = make_types_where_part(@args);
         ($q4,@args) = make_types_join_part(@args);
         ($q5,@args) = make_types_group_part(@args);

       The components are then combined as follows:

         $query = "SELECT $q1 FROM $q2 WHERE $q3 AND $q4 GROUP BY $q5";

       If any of the query fragments contain the ? bind variable, then the same number of bind
       arguments must be provided in @args.  The fragment-generating functions are described
       below.

   range_query
        Title   : range_query
        Usage   : $db->range_query($range_type,$refseq,$refclass,$start,$stop,$types,$order_by_group,$attributes,$binsize)
        Function: create statement handle for range/overlap queries
        Returns : a DBI statement handle
        Args    : see below
        Status  : Protected

       This method constructs the statement handle for this module's central query: given a range
       and/or a list of feature types, fetch their GFF records.

       The positional arguments are as follows:

         Argument               Description

         $isrange               A flag indicating that this is a range.
                                query.  Otherwise an overlap query is
                                assumed.

         $refseq                The reference sequence name (undef if no range).

         $refclass              The reference sequence class (undef if no range).

         $start                 The start of the range (undef if none).

         $stop                  The stop of the range (undef if none).

         $types                 Array ref containing zero or feature types in the
                                format [method,source].

         $order_by_group        A flag indicating that statement handler should group
                                the features by group id (handy for iterative fetches)

         $attributes            A hash containing select attributes.

         $binsize               A bin size for generating tables of feature density.

       If successful, this method returns a statement handle.  The handle is expected to return
       the fields described for get_features().

       Internally, range_query() makes calls to the following methods, each of which is expected
       to be overridden in subclasses:

         $select        = $self->make_features_select_part;
         $from          = $self->make_features_from_part;
         $join          = $self->make_features_join_part;
         ($where,@args) = $self->make_features_by_range_where_part($isrange,$srcseq,$class,
                                                                  $start,$stop,$types,$class);

       The query that is constructed looks like this:

         SELECT $select FROM $from WHERE $join AND $where

       The arguments that are returned from make_features_by_range_where_part() are passed to the
       statement handler's execute() method.

       range_query() also calls a do_straight_join() method, described below.  If this method
       returns true, then the keyword "straight_join" is inserted right after SELECT.

   make_features_by_range_where_part
        Title   : make_features_by_range_where_part
        Usage   : ($string,@args) =
            $db->make_features_select_part($isrange,$refseq,$class,$start,$stop,$types)
        Function: make where part of the features query
        Returns : the list ($query,@bind_args)
        Args    : see below
        Status  : Protected

       This method creates the part of the features query that immediately follows the WHERE
       keyword and is ANDed with the string returned by make_features_join_part().

       The six positional arguments are a flag indicating whether to perform a range search or an
       overlap search, the reference sequence, class, start and stop, all of which define an
       optional range to search in, and an array reference containing a list [$method,$souce]
       pairs.

       The method result is a multi-element list containing the query string and the list of
       runtime arguments to bind to it with the execute() method.

       This method's job is to clean up arguments and perform consistency checking.  The real
       work is done by the following abstract methods:

         Method             Description

         refseq_query()     Return the query string needed to match the reference
                            sequence.

         range_query()      Return the query string needed to find all features contained
                            within a range.

         overlap_query()    Return the query string needed to find all features that overlap
                            a range.

       See Bio::DB::Adaptor::dbi::mysql for an example of how this works.

   do_straight_join
        Title   : do_straight_join
        Usage   : $boolean = $db->do_straight_join($refseq,$class,$start,$stop,$types)
        Function: optimization flag
        Returns : a flag
        Args    : see range_query()
        Status  : Protected

       This subroutine, called by range_query() returns a boolean flag.  If true, range_query()
       will perform a straight join, which can be used to optimize certain SQL queries.  The four
       arguments correspond to similarly-named arguments passed to range_query().

   string_match
        Title   : string_match
        Usage   : $string = $db->string_match($field,$value)
        Function: create a SQL fragment for performing exact or regexp string matching
        Returns : query string
        Args    : the table field and match value
        Status  : public

       This method examines the passed value for meta characters.  If so it produces a SQL
       fragment that performs a regular expression match.  Otherwise, it produces a fragment that
       performs an exact string match.

       This method is not used in the module, but is available for use by subclasses.

   exact_match
        Title   : exact_match
        Usage   : $string = $db->exact_match($field,$value)
        Function: create a SQL fragment for performing exact string matching
        Returns : query string
        Args    : the table field and match value
        Status  : public

       This method produces the SQL fragment for matching a field name to a constant string
       value.

   search_notes
        Title   : search_notes
        Usage   : @search_results = $db->search_notes("full text search string",$limit)
        Function: Search the notes for a text string, using mysql full-text search
        Returns : array of results
        Args    : full text search string, and an optional row limit
        Status  : public

       This is a mysql-specific method.  Given a search string, it performs a full-text search of
       the notes table and returns an array of results.  Each row of the returned array is a
       arrayref containing the following fields:

         column 1     A Bio::DB::GFF::Featname object, suitable for passing to segment()
         column 2     The text of the note
         column 3     A relevance score.
         column 4     A Bio::DB::GFF::Typename object

   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  : public

       Get or set a named metavariable for the database.  Metavariables can be used for database-
       specific settings.  This method calls two class-specific methods which must be
       implemented:

         make_meta_get_query()   Returns a sql fragment which given a meta
                                 parameter name, returns its value.  One bind
                                 variable.
         make_meta_set_query()   Returns a sql fragment which takes two bind
                                 arguments, the parameter name and its value

       Don't make changes unless you know what you're doing!  It will affect the persistent
       database.

   make_meta_get_query
        Title   : make_meta_get_query
        Usage   : $sql = $db->make_meta_get_query
        Function: return SQL fragment for getting a meta parameter
        Returns : SQL fragment
        Args    : none
        Status  : public

       By default this does nothing; meta parameters are not stored or retrieved.

   make_meta_set_query
        Title   : make_meta_set_query
        Usage   : $sql = $db->make_meta_set_query
        Function: return SQL fragment for setting a meta parameter
        Returns : SQL fragment
        Args    : none
        Status  : public

       By default this does nothing; meta parameters are not stored or retrieved.

   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.

   get_features_iterator
        Title   : get_features_iterator
        Usage   : $iterator = $db->get_features_iterator($search,$options,$callback)
        Function: create an iterator on a features() query
        Returns : A Bio::DB::GFF::Adaptor::dbi::iterator object
        Args    : see get_features()
        Status  : public

       This method is similar to get_features(), except that it returns an iterator across the
       query.  See Bio::DB::GFF::Adaptor::dbi::iterator.

   do_initialize
        Title   : do_initialize
        Usage   : $success = $db->do_initialize($drop_all)
        Function: initialize the database
        Returns : a boolean indicating the success of the operation
        Args    : a boolean indicating whether to delete existing data
        Status  : protected

       This method will load the schema into the database.  If $drop_all is true, then any
       existing data in the tables known to the schema will be deleted.

       Internally, this method calls schema() to get the schema data.

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

       This method performs schema-specific cleanup after loading a set of GFF records.  It
       finishes each of the statement handlers prepared by setup_load().

   create_other_schema_objects
        Title   : create_other_schema_objects
        Usage   : $self->create_other_schema_objects($table_name)
        Function: create other schema objects like : indexes, sequences, triggers
        Returns :
        Args    :
        Status  : Abstract

   drop_all
        Title   : drop_all
        Usage   : $db->drop_all
        Function: empty the database
        Returns : void
        Args    : none
        Status  : protected

       This method drops the tables known to this module.  Internally it calls the abstract
       tables() method.

   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.

       This method does two things: (1) it sets the underlying database handle's InactiveDestroy
       parameter to 1, thereby preventing the database connection from being destroyed in the
       parent when the dbh's destructor is called; (2) it replaces the dbh with the result of
       dbh->clone(), so that we now have an independent handle.

QUERIES TO IMPLEMENT

       The following astract methods either return DBI statement handles or fragments of SQL.
       They must be implemented by subclasses of this module.  See
       Bio::DB::GFF::Adaptor::dbi::mysql for examples.

   drop_other_schema_objects
        Title   : drop_other_schema_objects
        Usage   : $self->create_other_schema_objects($table_name)
        Function: create other schema objects like : indexes, sequences, triggers
        Returns :
        Args    :
        Status  : Abstract

   make_features_select_part
        Title   : make_features_select_part
        Usage   : $string = $db->make_features_select_part()
        Function: make select part of the features query
        Returns : a string
        Args    : none
        Status  : Abstract

       This abstract method creates the part of the features query that immediately follows the
       SELECT keyword.

   tables
        Title   : tables
        Usage   : @tables = $db->tables
        Function: return list of tables that belong to this module
        Returns : list of tables
        Args    : none
        Status  : protected

       This method lists the tables known to the module.

   schema
        Title   : schema
        Usage   : $schema = $db->schema
        Function: return the CREATE script for the schema
        Returns : a hashref
        Args    : none
        Status  : abstract

       This method returns an array ref containing the various CREATE statements needed to
       initialize the database tables.  The keys are the table names, and the values are strings
       containing the appropriate CREATE statement.

   DESTROY
        Title   : DESTROY
        Usage   : $db->DESTROY
        Function: disconnect database at destruct time
        Returns : void
        Args    : none
        Status  : protected

       This is the destructor for the class.

   make_features_by_name_where_part
        Title   : make_features_by_name_where_part
        Usage   : $db->make_features_by_name_where_part
        Function: create the SQL fragment needed to select a feature by its group name & class
        Returns : a SQL fragment and bind arguments
        Args    : see below
        Status  : Protected

   make_features_by_id_where_part
        Title   : make_features_by_id_where_part
        Usage   : $db->make_features_by_id_where_part($ids)
        Function: create the SQL fragment needed to select a set of features by their ids
        Returns : a SQL fragment and bind arguments
        Args    : arrayref of IDs
        Status  : Protected

   make_features_by_gid_where_part
        Title   : make_features_by_id_where_part
        Usage   : $db->make_features_by_gid_where_part($ids)
        Function: create the SQL fragment needed to select a set of features by their ids
        Returns : a SQL fragment and bind arguments
        Args    : arrayref of IDs
        Status  : Protected

   make_features_from_part
        Title   : make_features_from_part
        Usage   : $string = $db->make_features_from_part()
        Function: make from part of the features query
        Returns : a string
        Args    : none
        Status  : protected

       This method creates the part of the features query that immediately follows the FROM
       keyword.

   make_features_join_part
        Title   : make_features_join_part
        Usage   : $string = $db->make_features_join_part()
        Function: make join part of the features query
        Returns : a string
        Args    : none
        Status  : protected

       This method creates the part of the features query that immediately follows the WHERE
       keyword.

   make_features_order_by_part
        Title   : make_features_order_by_part
        Usage   : ($query,@args) = $db->make_features_order_by_part()
        Function: make the ORDER BY part of the features() query
        Returns : a SQL fragment and bind arguments, if any
        Args    : none
        Status  : protected

       This method creates the part of the features query that immediately follows the ORDER BY
       part of the query issued by features() and related methods.

   make_features_group_by_part
        Title   : make_features_group_by_part
        Usage   : ($query,@args) = $db->make_features_group_by_part()
        Function: make the GROUP BY part of the features() query
        Returns : a SQL fragment and bind arguments, if any
        Args    : none
        Status  : protected

       This method creates the part of the features query that immediately follows the GROUP BY
       part of the query issued by features() and related methods.

   refseq_query
        Title   : refseq_query
        Usage   : ($query,@args) = $db->refseq_query($name,$class)
        Function: create SQL fragment that selects the desired reference sequence
        Returns : a list containing the query and bind arguments
        Args    : reference sequence name and class
        Status  : protected

       This method is called by make_features_by_range_where_part() to construct the part of the
       select WHERE section that selects a particular reference sequence.  It returns a mult-
       element list in which the first element is the SQL fragment and subsequent elements are
       bind values.

       For example:

         sub refseq_query {
            my ($name,$class) = @_;
            return ('gff.refseq=? AND gff.refclass=?',
                    $name,$class);
         }

       The current schema does not distinguish among different classes of reference sequence.

   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);

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

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

   overlap_query_nobin
        Title   : overlap_query
        Usage   : ($query,@args) = $db->overlap_query($start,$stop)
        Function: create SQL fragment that selects the desired features by range
        Returns : a list containing the query and bind arguments
        Args    : the start and stop of a range, inclusive
        Status  : protected

       This method is called by make_features_byrange_where_part() to construct the part of the
       select WHERE section that selects a set of features that overlap a range. It returns a
       multi-element list in which the first element is the SQL fragment and subsequent elements
       are bind values.

       sub overlap_query_nobin {
            my ($start,$stop) = @_;
            return ('gff.stop>=? AND gff.start<=?',           $start,$stop);

   contains_query_nobin
        Title   : contains_query
        Usage   : ($query,@args) = $db->contains_query_nobin($start,$stop)
        Function: create SQL fragment that selects the desired features by range
        Returns : a list containing the query and bind arguments
        Args    : the start and stop of a range, inclusive
        Status  : protected

       This method is called by make_features_byrange_where_part() to construct the part of the
       select WHERE section that selects a set of features entirely enclosed by a range. It
       returns a multi-element list in which the first element is the SQL fragment and subsequent
       elements are bind values. For example:

         sub contains_query_nobin {
            my ($start,$stop) = @_;
            return ('gff.start>=? AND gff.stop<=?',
                    $start,$stop);

   contained_in_query_nobin
        Title   : contained_in_query_nobin
        Usage   : ($query,@args) = $db->contained_in_query($start,$stop)
        Function: create SQL fragment that selects the desired features by range
        Returns : a list containing the query and bind arguments
        Args    : the start and stop of a range, inclusive
        Status  : protected

       This method is called by make_features_byrange_where_part() to construct the part of the
       select WHERE section that selects a set of features entirely enclosed by a range. It
       returns a multi-element list in which the first element is the SQL fragment and subsequent
       elements are bind values.For example:

         sub contained_in_query_nobin {
            my ($start,$stop) = @_;
            return ('gff.start<=? AND gff.stop>=?',
                    $start,$stop);
         }

   types_query
        Title   : types_query
        Usage   : ($query,@args) = $db->types_query($types)
        Function: create SQL fragment that selects the desired features by type
        Returns : a list containing the query and bind arguments
        Args    : an array reference containing the types
        Status  : protected

       This method is called by make_features_byrange_where_part() to construct the part of the
       select WHERE section that selects a set of features based on their type. It returns a
       multi-element list in which the first element is the SQL fragment and subsequent elements
       are bind values.  The argument is an array reference containing zero or more
       [$method,$source] pairs.

   make_types_select_part
        Title   : make_types_select_part
        Usage   : ($string,@args) = $db->make_types_select_part(@args)
        Function: create the select portion of the SQL for fetching features type list
        Returns : query string and bind arguments
        Args    : see below
        Status  : protected

       This method is called by get_types() to generate the query fragment and bind arguments for
       the SELECT part of the query that retrieves lists of feature types.  The four positional
       arguments are as follows:

        $refseq      reference sequence name
        $start       start of region
        $stop        end of region
        $want_count  true to return the count of this feature type

       If $want_count is false, the SQL fragment returned must produce a list of feature types in
       the format (method, source).

       If $want_count is true, the returned fragment must produce a list of feature types in the
       format (method, source, count).

   make_types_from_part
        Title   : make_types_from_part
        Usage   : ($string,@args) = $db->make_types_from_part(@args)
        Function: create the FROM portion of the SQL for fetching features type lists
        Returns : query string and bind arguments
        Args    : see below
        Status  : protected

       This method is called by get_types() to generate the query fragment and bind arguments for
       the FROM part of the query that retrieves lists of feature types.  The four positional
       arguments are as follows:

        $refseq      reference sequence name
        $start       start of region
        $stop        end of region
        $want_count  true to return the count of this feature type

       If $want_count is false, the SQL fragment returned must produce a list of feature types in
       the format (method, source).

       If $want_count is true, the returned fragment must produce a list of feature types in the
       format (method, source, count).

   make_types_join_part
        Title   : make_types_join_part
        Usage   : ($string,@args) = $db->make_types_join_part(@args)
        Function: create the JOIN portion of the SQL for fetching features type lists
        Returns : query string and bind arguments
        Args    : see below
        Status  : protected

       This method is called by get_types() to generate the query fragment and bind arguments for
       the JOIN part of the query that retrieves lists of feature types.  The four positional
       arguments are as follows:

        $refseq      reference sequence name
        $start       start of region
        $stop        end of region
        $want_count  true to return the count of this feature type

   make_types_where_part
        Title   : make_types_where_part
        Usage   : ($string,@args) = $db->make_types_where_part(@args)
        Function: create the WHERE portion of the SQL for fetching features type lists
        Returns : query string and bind arguments
        Args    : see below
        Status  : protected

       This method is called by get_types() to generate the query fragment and bind arguments for
       the WHERE part of the query that retrieves lists of feature types.  The four positional
       arguments are as follows:

        $refseq      reference sequence name
        $start       start of region
        $stop        end of region
        $want_count  true to return the count of this feature type

   make_types_group_part
        Title   : make_types_group_part
        Usage   : ($string,@args) = $db->make_types_group_part(@args)
        Function: create the GROUP BY portion of the SQL for fetching features type lists
        Returns : query string and bind arguments
        Args    : see below
        Status  : protected

       This method is called by get_types() to generate the query fragment and bind arguments for
       the GROUP BY part of the query that retrieves lists of feature types.  The four positional
       arguments are as follows:

        $refseq      reference sequence name
        $start       start of region
        $stop        end of region
        $want_count  true to return the count of this feature type

   get_feature_id
        Title   : get_feature_id
        Usage   : $integer = $db->get_feature_id($ref,$start,$stop,$typeid,$groupid)
        Function: get the ID of a feature
        Returns : an integer ID or undef
        Args    : none
        Status  : private

       This internal method is called by load_gff_line to look up the integer ID of an existing
       feature.  It is ony needed when replacing a feature with new information.

   make_abscoord_query
        Title   : make_abscoord_query
        Usage   : $sth = $db->make_abscoord_query($name,$class);
        Function: create query that finds the reference sequence coordinates given a landmark & classa
        Returns : a DBI statement handle
        Args    : name and class of landmark
        Status  : protected

       The statement handler should return rows containing five fields:

         1. reference sequence name
         2. reference sequence class
         3. start position
         4. stop position
         5. strand ("+" or "-")

       This query always returns "Sequence" as the class of the reference sequence.

   feature_summary
        Title   : feature_summary
        Usage   : $summary = $db->feature_summary(@args)
        Function: returns a coverage summary across indicated region/type
        Returns : a Bio::SeqFeatureI object containing the "coverage" tag
        Args    : see below
        Status  : public

       This method is used to get coverage density information across a region of interest. You
       provide it with a region of interest, optional a list of feature types, and a count of the
       number of bins over which you want to calculate the coverage density. An object is
       returned corresponding to the requested region. It contains a tag called "coverage" that
       will return an array ref of "bins" length. Each element of the array describes the number
       of features that overlap the bin at this position.

       Arguments:

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

         -seq_id        Sequence ID for the region
         -start         Start of region
         -end           End of region
         -type/-types   Feature type of interest or array ref of types
         -bins          Number of bins across region. Defaults to 1000.
         -iterator      Return an iterator across the region

       Note that this method uses an approximate algorithm that is only accurate to 500 bp, so
       when dealing with bins that are smaller than 1000 bp, you may see some shifting of counts
       between adjacent bins.

       Although an -iterator option is provided, the method only ever returns a single feature,
       so this is fairly useless.

   coverage_array
        Title   : coverage_array
        Usage   : $arrayref = $db->coverage_array(@args)
        Function: returns a coverage summary across indicated region/type
        Returns : an array reference
        Args    : see below
        Status  : public

       This method is used to get coverage density information across a region of interest. The
       arguments are identical to feature_summary, except that instead of returning a
       Bio::SeqFeatureI object, it returns an array reference of the desired number of bins. The
       value of each element corresponds to the number of features in the bin.

       Arguments:

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

         -seq_id        Sequence ID for the region
         -start         Start of region
         -end           End of region
         -type/-types   Feature type of interest or array ref of types
         -bins          Number of bins across region. Defaults to 1000.

       Note that this method uses an approximate algorithm that is only accurate to 500 bp, so
       when dealing with bins that are smaller than 1000 bp, you may see some shifting of counts
       between adjacent bins.

   build_summary_statistics
        Title   : build_summary_statistics
        Usage   : $db->build_summary_statistics
        Function: prepares the table needed to call feature_summary()
        Returns : nothing
        Args    : none
        Status  : public

       This method is used to build the summary statistics table that is used by the
       feature_summary() and coverage_array() methods. It needs to be called whenever the
       database is updated.

BUGS

       Schemas need work to support multiple hierarchical groups.

SEE ALSO

       Bio::DB::GFF, bioperl

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.