Bio::D...r::dbi(3pm)

📦

version 1.7.4 · 2 versions

1.7.4 · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble (latest)
1.7.4 · ubuntu resolute, ubuntu stonking

, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

💖 NAME 💖

Bio::DB::GFF::Adaptor::dbi — the Database adaptor for DBI (SQL) databases. It lives in the User Contributed Perl Documentation, bestie, and the manual page is Bio::DB::GFF::Adaptor::dbi(3pm). 🦋

✨ SYNOPSIS ✨

See Bio::DB::GFF. That's it. That's the synopsis. She's brief. 👑

🎀 DESCRIPTION 🎀

Okay so listen. This is the base class for all the DBI-based adaptors. She does literally everything the family needs — except writing the actual text of the queries. That part is somebody else's job. 🫶

If you wanna know which methods you absolutely have to implement yourself, scroll on down to the section QUERIES TO IMPLEMENT — that's the to-do list, and no cap, you can't skip it.

🌸 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 gets called automatically by Bio::DB::GFF->new, so you don't have to do anything, she just shows up. 💅

On top of the arguments that every adaptor shares, the following class-specific arguments are recognized:

-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 comes back is not really a DBI::db handle, it's a subclass of one. Which means you cannot mess with the handle's attributes directly. Instead, call the attribute method, like so:

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 does the low-level fetch of a DNA substring — you give it a name, a class and the range you want. Fr fr it's just a front end to the abstract method make_dna_query(), which it calls after doing a little argument consistency checking first. She's thorough like that. ✨

🌈 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 one does the low-level resolution of a landmark into a reference sequence and position. 🎀

The result is an array ref, and every element of it is a five-element list containing reference sequence name, class, start, stop and strand. Five things. Every time. Slay. 💅

🔥 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 gets called to pull GFF lines out of the database. She's the one responsible for retrieving features that satisfy your range and feature type criteria, and then handing the GFF fields over to a callback subroutine. 👑

For the interpretation of the arguments, and for how the info retrieved by get_features gets passed to the callback for processing, go read the manual page for Bio::DB::GFF.

Internally, get_features() is a front end for range_query(). That second method is the one that constructs the query and executes it. Then get_features() calls fetchrow_array() to recover the fields and passes them along to the callback. Teamwork, honestly. 🫶

🌸 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 aren't used by the database at all. Classes are distinct from types: they're essentially qualifiers on the reference namespaces. iykyk.

⚠️ NOTE: in the current mysql-based schema, this query takes a while to run because the classes are not normalized. Not me waiting on a query... 😭

🎀 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, so don't come for her. The callback arguments are the ones used by make_feature(). Internally, she 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

Also used internally. The $type selector is either "feature" or "group". The callback arguments are the ones used by make_feature(). Internally, she 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 in charge of fetching the list of feature type names out of the database. The query can be limited to a particular range, in which case the range is indicated by a landmark sequence name and class plus its subrange, if there is one. Any of these arguments can be undef if you want to retrieve all the feature types in the database — which, heads up, 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 then get combined like this:

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

⚠️ If any of the query fragments contain the ? bind variable, then you must provide the same number of bind arguments 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. She's the main character, honestly. 👑

The positional arguments are as follows:

$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 it works, this method returns a statement handle. That 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 gets constructed looks like this:

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

The arguments that come back 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 that 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 comes immediately after the WHERE keyword, and it gets 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 of [$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.

Her job is to clean up arguments and do consistency checking. The real work is done by the following abstract methods:

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

So this little guy gets called by range_query() and hands back a boolean flag. If it's true, range_query() is gonna do a straight join, which is a whole optimization move for certain SQL queries. The four arguments line up with the same-named arguments you'd pass into range_query(). Slay, matching energy. ✨

`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 one eyeballs the value you passed in, looking for meta characters. Found some? It builds you a SQL fragment that does a regular expression match. Found none? Then it hands back a fragment that does an exact string match. 💅

Heads up bestie: this method isn't used anywhere in the module itself — it's just sitting there, available for subclasses to use. 🫶

`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 one produces the SQL fragment for matching a field name against a constant string value. No regexp drama here, just straight-up exact matching. 🎀

`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, so don't go expecting it to work everywhere, okay?

Give it a search string and it does a full-text search of the notes table, then returns an array of results. Each row of that returned array is an arrayref containing these 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 are for database-specific settings, iykyk. This method calls two class-specific methods that you have to implement yourself:

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. Like, permanently. No take-backs, no undo, fr fr. 😭

`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 absolutely nothing — meta parameters are not stored or retrieved. Empty. Void. A lil ghost method. 👻

`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

Same situation here, bestie: by default this does nothing, and 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 one returns a list of tag=>value pairs holding default meta info about the database. initialize() calls it to write out those default meta values. The base class version? Returns an empty list. Nada. 🫠

💖 For things to work properly, meta value names must be UPPERCASE. Not lowercase, not mixed case. UPPERCASE. Periodt.

`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

Basically get_features() but it returns an iterator across the query instead. So instead of the whole thing at once, you get to walk through it. Go check out Bio::DB::GFF::Adaptor::dbi::iterator for the deets. 🦋

`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 loads the schema into the database. And if $drop_all is true? Then any existing data in the tables that the schema knows about gets deleted. Gone. Poof. 👑

Internally it calls schema() to grab 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 performs schema-specific cleanup after a set of GFF records gets loaded. It finishes each of the statement handlers that were prepared by setup_load(). Closing time, besties. ✨

`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

Drops the tables that this module knows about. Internally it calls the abstract tables() method. Bye bye tables 💅

`clone`

The clone() method is the one you reach for when you wanna pass the Bio::DB::GFF object to a child process across a fork(). The child must call clone() before making any queries. No exceptions.

This method does two things:

It sets the underlying database handle's InactiveDestroy parameter to 1, which stops the database connection from being destroyed in the parent when the dbh's destructor gets called.
It replaces the dbh with the result of dbh->clone(), so now we have an independent handle. 🌈

🎀 QUERIES TO IMPLEMENT 🎀

Okay so the following abstract methods either return DBI statement handles or fragments of SQL. They must be implemented by subclasses of this module. Peep Bio::DB::GFF::Adaptor::dbi::mysql for examples, bestie. 💖

`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 comes immediately after the SELECT keyword. So like, right after SELECT. 👑

`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

Lists out the tables known to the module. That's it, that's the job. 🌸

`schema`

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

This returns an array ref containing all the various CREATE statements you need to initialize the database tables. The keys are the table names, and the values are strings holding 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. It does the disconnecting at destruct time. 💀

`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

Creates the part of the features query that comes immediately after 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

Creates the part of the features query that comes immediately after the WHERE keyword. (Yes, it's called the join part and it lives after WHERE. That's just how it is here, bestie, I don't make the rules. 🙈)

`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

Creates the part of the features query that comes immediately after the ORDER BY part of the query issued by features() and its 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

And this one creates the part of the features query that comes immediately after the GROUP BY part of the query issued by features() and its related methods. Grouping era. 👑✨

🌸 `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

okay so this one is called by make_features_by_range_where_part() — she's the girl who builds the WHERE chunk of the select that picks out one specific reference sequence. What she hands back is a multi-element list where element number one is the SQL fragment and everything after that is bind values. no cap.

For example, bestie:

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

and here's the lil plot twist: the current schema does not distinguish among different classes of reference sequence. so the $class is just kind of... there. 💀

🌸 `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 are extra and use the groups column to stash a whole series of attribute/value pairs. In this interpretation of GFF, the very first pair is treated as the primary group for the feature, and every pair after that is an attribute. it's giving nested energy fr fr.

Two attributes have special meaning and you should know them:

"Note" — this one is for backward compatibility, and it's used for unstructured text remarks.
"Alias" — this one is considered a synonym for the feature name.

If you don't pass a name, then attributes() returns a flattened hash, of attribute=>value pairs. Which lets you do this iconic move:

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

Normally though, attributes() gets called by the feature herself:

@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

She's called by make_features_byrange_where_part() to construct the part of the select WHERE section that selects a set of features overlapping a range. returns a multi-element list, first element = the SQL fragment, everything after = bind values.

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

(yeah the closing brace is missing up there, that's just how the page is, we don't fix it, we respect it 🫶)

🌸 `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

Called by make_features_byrange_where_part() to build the bit of the select WHERE that selects a set of features entirely enclosed by a range. multi-element list, first element is the SQL fragment, the rest 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

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. Returns a multi-element list, first element is the SQL fragment, subsequent elements are bind values.For example:

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

(yes, "values.For" with no space is literally what it says, we're keeping her exactly as she is 💅)

🌸 `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

Called by make_features_byrange_where_part() to construct the part of the select WHERE that selects features based on their type. Returns a multi-element list: first element = SQL fragment, rest = bind values. The argument is an array reference containing zero or more [$method,$source] pairs. zero. or more. she's flexible like that. ✨

🌸 `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

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 go like this:

$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

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. Same four positional arguments, bestie:

$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

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. And the four positional arguments, one more time:

$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

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:

$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

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, for the last time in this lil squad:

$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 gets called by load_gff_line to look up the integer ID of an existing feature. She's only needed when you're replacing a feature with new information. so like, a glow-up for a feature. 💅 (also: Args : none while the Usage clearly passes five things, we are simply not going to talk about it 🙈)

🌸 `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, and they come in this order:

reference sequence name
reference sequence class
start position
stop position
strand ("+" or "-")

and heads up: this query always returns "Sequence" as the class of the reference sequence. always. periodt.

🌸 `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 how you get coverage density information across a region of interest. You give her a region of interest, optionally a list of feature types, and a count of the number of bins over which you want the coverage density calculated. What comes back is an object corresponding to the requested region, and it carries a tag called "coverage" that returns an array ref of "bins" length. Every element of that array describes the number of features that overlap the bin at that position. it's giving histogram but make it bioinformatics. 📊✨

Arguments:

-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

okay so real talk bestie — this method runs on an approximate algorithm that's only accurate down to 500 bp. so when you're dealing with bins smaller than 1000 bp, you might see some shifting of counts between adjacent bins. it's giving ✨approximation✨, not precision. just know that going in. 🫶

and also? even though an -iterator option is provided, the method only ever returns a single feature, so honestly that option is fairly useless. not me exposing the API like this but okay 💀

✨ 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

so this one is your go-to for getting coverage density info across a region of interest 🧚. the args are identical to feature_summary, EXCEPT that instead of handing you back a Bio::SeqFeatureI object, it gives you an array reference with however many bins you asked for. each element in that array = the number of features sitting in that bin. slay. 👑

Arguments:

-seq_id — the sequence ID for the region 💖
-start — where the region starts
-end — where the region ends
-type / -types — the feature type you want, or an array ref of types if you're feeling extra
-bins — how many bins across the region. defaults to 1000.

heads up again bestie: this method also uses an approximate algorithm that's only accurate to 500 bp. so when bins are smaller than 1000 bp, you may see some shifting of counts between adjacent bins. it's the same vibe as feature_summary, no cap 😭

✨ 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 builds the summary statistics table that feature_summary() and coverage_array() depend on 🎀. so basically, it's the backstage crew for those two methods' main character moment.

💀 IMPORTANT: you need to call this whenever the database is updated. otherwise your summaries are stale and that's not the vibe.

💀 BUGS

Schemas need work to support multiple hierarchical groups. that's it, that's the bug. fr fr 🙈

🌈 SEE ALSO

Bio::DB::GFF
bioperl

👑 AUTHOR

Lincoln Stein <lstein@cshl.org>.

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

and that's a wrap on the whole page bestie!! 💅 this was documented for perl v5.30.0, dated 2020-01-13, and it's the user-contributed Perl documentation for Bio::DB::GFF::dbi(3pm). you read the whole thing, you ate, you slayed, you understood your database interface. obsessed with you fr fr 🦋✨💖

📦 where this page comes from

debian bookworm: libbio-db-gff-perl 1.7.4-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
debian trixie: libbio-db-gff-perl 1.7.4-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu jammy: libbio-db-gff-perl 1.7.4-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu noble: libbio-db-gff-perl 1.7.4-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Bio::D...r::dbi(3pm)

💖 NAME 💖

✨ SYNOPSIS ✨

🎀 DESCRIPTION 🎀

🌸 new 🌸

🦋 features_db 🦋

💜 get_dna 💜

🌈 get_abscoords 🌈

🔥 get_features 🔥

🌸 classes 🌸

🎀 make_classes_query 🎀

🦋 _feature_by_name 🦋

💜 _feature_by_id 💜

✨ get_types ✨

🔥 range_query 🔥

💜 make_features_by_range_where_part 💜

do_straight_join

string_match

exact_match

search_notes

meta

make_meta_get_query

make_meta_set_query

default_meta_values

get_features_iterator

do_initialize

finish_load

create_other_schema_objects

drop_all

clone

🎀 QUERIES TO IMPLEMENT 🎀

drop_other_schema_objects

make_features_select_part

tables

schema

DESTROY

make_features_by_name_where_part

make_features_by_id_where_part

make_features_by_gid_where_part

make_features_from_part

make_features_join_part

make_features_order_by_part

make_features_group_by_part

🌸 refseq_query 🌸

🌸 attributes 🌸

🌸 overlap_query_nobin 🌸

🌸 contains_query_nobin 🌸

🌸 contained_in_query_nobin 🌸

🌸 types_query 🌸

🌸 make_types_select_part 🌸

🌸 make_types_from_part 🌸

🌸 make_types_join_part 🌸

🌸 make_types_where_part 🌸

🌸 make_types_group_part 🌸

🌸 get_feature_id 🌸

🌸 make_abscoord_query 🌸

🌸 feature_summary 🌸