NAME

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

SYNOPSIS

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_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.

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.

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($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

  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.

BUGS

Schemas need work to support multiple hierarchical groups.

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.

To install LocalConfig, copy and paste the appropriate command in to your terminal.

cpanm

cpanm LocalConfig

CPAN shell

perl -MCPAN -e shell
install LocalConfig

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

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

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

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

BUGS

SEE ALSO

AUTHOR

Module Install Instructions