.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Bio::DB::GFF::Adaptor::dbi 3pm" .TH Bio::DB::GFF::Adaptor::dbi 3pm "2020-01-13" "perl v5.30.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Bio::DB::GFF::Adaptor::dbi \-\- Database adaptor for DBI (SQL) databases .SH "SYNOPSIS" .IX Header "SYNOPSIS" See Bio::DB::GFF .SH "DESCRIPTION" .IX Header "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 \&\s-1QUERIES TO IMPLEMENT\s0 for the list of methods that must be implemented. .SS "new" .IX Subsection "new" .Vb 6 \& 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 .Ve .PP 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: .PP .Vb 2 \& Argument Description \& \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- \& \& \-dsn the DBI data source, e.g. \*(Aqdbi:mysql:ens0040\*(Aq \& \& \-user username for authentication \& \& \-pass the password for authentication .Ve .SS "features_db" .IX Subsection "features_db" .Vb 6 \& 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\*(Aqs attributes directly. Instead call the attribute \& method: \& \& my $dbh = $db\->features_db; \& $dbh\->attribute(AutoCommit=>0); .Ve .SS "get_dna" .IX Subsection "get_dna" .Vb 6 \& 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 .Ve .PP This method performs the low-level fetch of a \s-1DNA\s0 substring given its name, class and the desired range. It is actually a front end to the abstract method \fBmake_dna_query()\fR, which it calls after some argument consistency checking. .SS "get_abscoords" .IX Subsection "get_abscoords" .Vb 6 \& 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 .Ve .PP This method performs the low-level resolution of a landmark into a reference sequence and position. .PP The result is an array ref, each element of which is a five-element list containing reference sequence name, class, start, stop and strand. .SS "get_features" .IX Subsection "get_features" .Vb 6 \& 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 .Ve .PP This is the low-level method that is called to retrieve \s-1GFF\s0 lines from the database. It is responsible for retrieving features that satisfy range and feature type criteria, and passing the \s-1GFF\s0 fields to a callback subroutine. .PP 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. .PP Internally, \fBget_features()\fR is a front end for \fBrange_query()\fR. The latter method constructs the query and executes it. \fBget_features()\fR calls \fBfetchrow_array()\fR to recover the fields and passes them to the callback. .SS "classes" .IX Subsection "classes" .Vb 6 \& Title : classes \& Usage : $db\->classes \& Function: return list of landmark classes in database \& Returns : a list of classes \& Args : none \& Status : public .Ve .PP 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. .PP \&\s-1NOTE:\s0 In the current mysql-based schema, this query takes a while to run due to the classes not being normalized. .SS "make_classes_query" .IX Subsection "make_classes_query" .Vb 6 \& 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 .Ve .SS "_feature_by_name" .IX Subsection "_feature_by_name" .Vb 6 \& 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 .Ve .PP This method is used internally. The callback arguments are those used by \fBmake_feature()\fR. Internally, it invokes the following abstract procedures: .PP .Vb 5 \& 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 .Ve .SS "_feature_by_id" .IX Subsection "_feature_by_id" .Vb 6 \& 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 .Ve .PP This method is used internally. The \f(CW$type\fR selector is one of \&\*(L"feature\*(R" or \*(L"group\*(R". The callback arguments are those used by \&\fBmake_feature()\fR. Internally, it invokes the following abstract procedures: .PP .Vb 4 \& make_features_select_part \& make_features_from_part \& make_features_by_id_where_part \& make_features_join_part .Ve .SS "get_types" .IX Subsection "get_types" .Vb 6 \& 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 .Ve .PP 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). .PP If the \f(CW$count\fR flag is false, the method returns a simple list of vBio::DB::GFF::Typename objects. If \f(CW$count\fR is true, the method returns a list of \f(CW$name\fR=>$count pairs, where \f(CW$count\fR indicates the number of times this feature occurs in the range. .PP Internally, this method calls upon the following functions to generate the \s-1SQL\s0 and its bind variables: .PP .Vb 5 \& ($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); .Ve .PP The components are then combined as follows: .PP .Vb 1 \& $query = "SELECT $q1 FROM $q2 WHERE $q3 AND $q4 GROUP BY $q5"; .Ve .PP If any of the query fragments contain the ? bind variable, then the same number of bind arguments must be provided in \f(CW@args\fR. The fragment-generating functions are described below. .SS "range_query" .IX Subsection "range_query" .Vb 6 \& 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 .Ve .PP This method constructs the statement handle for this module's central query: given a range and/or a list of feature types, fetch their \s-1GFF\s0 records. .PP The positional arguments are as follows: .PP .Vb 1 \& 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. .Ve .PP If successful, this method returns a statement handle. The handle is expected to return the fields described for \fBget_features()\fR. .PP Internally, \fBrange_query()\fR makes calls to the following methods, each of which is expected to be overridden in subclasses: .PP .Vb 5 \& $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); .Ve .PP The query that is constructed looks like this: .PP .Vb 1 \& SELECT $select FROM $from WHERE $join AND $where .Ve .PP The arguments that are returned from \fBmake_features_by_range_where_part()\fR are passed to the statement handler's \fBexecute()\fR method. .PP \&\fBrange_query()\fR also calls a \fBdo_straight_join()\fR method, described below. If this method returns true, then the keyword \*(L"straight_join\*(R" is inserted right after \s-1SELECT.\s0 .SS "make_features_by_range_where_part" .IX Subsection "make_features_by_range_where_part" .Vb 7 \& 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 .Ve .PP This method creates the part of the features query that immediately follows the \s-1WHERE\s0 keyword and is ANDed with the string returned by \&\fBmake_features_join_part()\fR. .PP 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. .PP The method result is a multi-element list containing the query string and the list of runtime arguments to bind to it with the \fBexecute()\fR method. .PP This method's job is to clean up arguments and perform consistency checking. The real work is done by the following abstract methods: .PP .Vb 1 \& 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. .Ve .PP See Bio::DB::Adaptor::dbi::mysql for an example of how this works. .SS "do_straight_join" .IX Subsection "do_straight_join" .Vb 6 \& 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 .Ve .PP This subroutine, called by \fBrange_query()\fR returns a boolean flag. If true, \fBrange_query()\fR will perform a straight join, which can be used to optimize certain \s-1SQL\s0 queries. The four arguments correspond to similarly-named arguments passed to \fBrange_query()\fR. .SS "string_match" .IX Subsection "string_match" .Vb 6 \& 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 .Ve .PP This method examines the passed value for meta characters. If so it produces a \s-1SQL\s0 fragment that performs a regular expression match. Otherwise, it produces a fragment that performs an exact string match. .PP This method is not used in the module, but is available for use by subclasses. .SS "exact_match" .IX Subsection "exact_match" .Vb 6 \& 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 .Ve .PP This method produces the \s-1SQL\s0 fragment for matching a field name to a constant string value. .SS "search_notes" .IX Subsection "search_notes" .Vb 6 \& 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 .Ve .PP 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: .PP .Vb 4 \& 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 .Ve .SS "meta" .IX Subsection "meta" .Vb 6 \& 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 .Ve .PP 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: .PP .Vb 5 \& 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 .Ve .PP Don't make changes unless you know what you're doing! It will affect the persistent database. .SS "make_meta_get_query" .IX Subsection "make_meta_get_query" .Vb 6 \& 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 .Ve .PP By default this does nothing; meta parameters are not stored or retrieved. .SS "make_meta_set_query" .IX Subsection "make_meta_set_query" .Vb 6 \& 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 .Ve .PP By default this does nothing; meta parameters are not stored or retrieved. .SS "default_meta_values" .IX Subsection "default_meta_values" .Vb 6 \& 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 .Ve .PP This method returns a list of tag=>value pairs that contain default meta information about the database. It is invoked by \fBinitialize()\fR to write out the default meta values. The base class version returns an empty list. .PP For things to work properly, meta value names must be \s-1UPPERCASE.\s0 .SS "get_features_iterator" .IX Subsection "get_features_iterator" .Vb 6 \& 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 .Ve .PP This method is similar to \fBget_features()\fR, except that it returns an iterator across the query. See Bio::DB::GFF::Adaptor::dbi::iterator. .SS "do_initialize" .IX Subsection "do_initialize" .Vb 6 \& 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 .Ve .PP This method will load the schema into the database. If \f(CW$drop_all\fR is true, then any existing data in the tables known to the schema will be deleted. .PP Internally, this method calls \fBschema()\fR to get the schema data. .SS "finish_load" .IX Subsection "finish_load" .Vb 6 \& Title : finish_load \& Usage : $db\->finish_load \& Function: called after load_gff_line() \& Returns : number of records loaded \& Args : none \& Status : protected .Ve .PP This method performs schema-specific cleanup after loading a set of \&\s-1GFF\s0 records. It finishes each of the statement handlers prepared by \&\fBsetup_load()\fR. .SS "create_other_schema_objects" .IX Subsection "create_other_schema_objects" .Vb 6 \& 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 .Ve .SS "drop_all" .IX Subsection "drop_all" .Vb 6 \& Title : drop_all \& Usage : $db\->drop_all \& Function: empty the database \& Returns : void \& Args : none \& Status : protected .Ve .PP This method drops the tables known to this module. Internally it calls the abstract \fBtables()\fR method. .SS "clone" .IX Subsection "clone" The \fBclone()\fR method should be used when you want to pass the Bio::DB::GFF object to a child process across a \fBfork()\fR. The child must call \fBclone()\fR before making any queries. .PP 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\->\fBclone()\fR, so that we now have an independent handle. .SH "QUERIES TO IMPLEMENT" .IX Header "QUERIES TO IMPLEMENT" The following astract methods either return \s-1DBI\s0 statement handles or fragments of \s-1SQL.\s0 They must be implemented by subclasses of this module. See Bio::DB::GFF::Adaptor::dbi::mysql for examples. .SS "drop_other_schema_objects" .IX Subsection "drop_other_schema_objects" .Vb 6 \& 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 .Ve .SS "make_features_select_part" .IX Subsection "make_features_select_part" .Vb 6 \& 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 .Ve .PP This abstract method creates the part of the features query that immediately follows the \s-1SELECT\s0 keyword. .SS "tables" .IX Subsection "tables" .Vb 6 \& Title : tables \& Usage : @tables = $db\->tables \& Function: return list of tables that belong to this module \& Returns : list of tables \& Args : none \& Status : protected .Ve .PP This method lists the tables known to the module. .SS "schema" .IX Subsection "schema" .Vb 6 \& Title : schema \& Usage : $schema = $db\->schema \& Function: return the CREATE script for the schema \& Returns : a hashref \& Args : none \& Status : abstract .Ve .PP This method returns an array ref containing the various \s-1CREATE\s0 statements needed to initialize the database tables. The keys are the table names, and the values are strings containing the appropriate \&\s-1CREATE\s0 statement. .SS "\s-1DESTROY\s0" .IX Subsection "DESTROY" .Vb 6 \& Title : DESTROY \& Usage : $db\->DESTROY \& Function: disconnect database at destruct time \& Returns : void \& Args : none \& Status : protected .Ve .PP This is the destructor for the class. .SS "make_features_by_name_where_part" .IX Subsection "make_features_by_name_where_part" .Vb 6 \& 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 .Ve .SS "make_features_by_id_where_part" .IX Subsection "make_features_by_id_where_part" .Vb 6 \& 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 .Ve .SS "make_features_by_gid_where_part" .IX Subsection "make_features_by_gid_where_part" .Vb 6 \& 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 .Ve .SS "make_features_from_part" .IX Subsection "make_features_from_part" .Vb 6 \& 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 .Ve .PP This method creates the part of the features query that immediately follows the \s-1FROM\s0 keyword. .SS "make_features_join_part" .IX Subsection "make_features_join_part" .Vb 6 \& 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 .Ve .PP This method creates the part of the features query that immediately follows the \s-1WHERE\s0 keyword. .SS "make_features_order_by_part" .IX Subsection "make_features_order_by_part" .Vb 6 \& 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 .Ve .PP This method creates the part of the features query that immediately follows the \s-1ORDER BY\s0 part of the query issued by \fBfeatures()\fR and related methods. .SS "make_features_group_by_part" .IX Subsection "make_features_group_by_part" .Vb 6 \& 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 .Ve .PP This method creates the part of the features query that immediately follows the \s-1GROUP BY\s0 part of the query issued by \fBfeatures()\fR and related methods. .SS "refseq_query" .IX Subsection "refseq_query" .Vb 6 \& 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 .Ve .PP This method is called by \fBmake_features_by_range_where_part()\fR to construct the part of the select \s-1WHERE\s0 section that selects a particular reference sequence. It returns a mult-element list in which the first element is the \s-1SQL\s0 fragment and subsequent elements are bind values. .PP For example: .PP .Vb 5 \& sub refseq_query { \& my ($name,$class) = @_; \& return (\*(Aqgff.refseq=? AND gff.refclass=?\*(Aq, \& $name,$class); \& } .Ve .PP The current schema does not distinguish among different classes of reference sequence. .SS "attributes" .IX Subsection "attributes" .Vb 6 \& 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 .Ve .PP Some \s-1GFF\s0 version 2 files use the groups column to store a series of attribute/value pairs. In this interpretation of \s-1GFF,\s0 the first such pair is treated as the primary group for the feature; subsequent pairs are treated as attributes. Two attributes have special meaning: \&\*(L"Note\*(R" is for backward compatibility and is used for unstructured text remarks. \*(L"Alias\*(R" is considered as a synonym for the feature name. .PP If no name is provided, then \fBattributes()\fR returns a flattened hash, of attribute=>value pairs. This lets you do: .PP .Vb 1 \& %attributes = $db\->attributes($id); .Ve .PP Normally, \fBattributes()\fR will be called by the feature: .PP .Vb 1 \& @notes = $feature\->attributes(\*(AqNote\*(Aq); .Ve .SS "overlap_query_nobin" .IX Subsection "overlap_query_nobin" .Vb 6 \& 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 .Ve .PP This method is called by \fBmake_features_byrange_where_part()\fR to construct the part of the select \s-1WHERE\s0 section that selects a set of features that overlap a range. It returns a multi-element list in which the first element is the \s-1SQL\s0 fragment and subsequent elements are bind values. .PP sub overlap_query_nobin { my ($start,$stop) = \f(CW@_\fR; return ('gff.stop>=? \s-1AND\s0 gff.start<=?', \f(CW$start\fR,$stop); .SS "contains_query_nobin" .IX Subsection "contains_query_nobin" .Vb 6 \& 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 .Ve .PP This method is called by \fBmake_features_byrange_where_part()\fR to construct the part of the select \s-1WHERE\s0 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 \s-1SQL\s0 fragment and subsequent elements are bind values. For example: .PP .Vb 4 \& sub contains_query_nobin { \& my ($start,$stop) = @_; \& return (\*(Aqgff.start>=? AND gff.stop<=?\*(Aq, \& $start,$stop); .Ve .SS "contained_in_query_nobin" .IX Subsection "contained_in_query_nobin" .Vb 6 \& 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 .Ve .PP This method is called by \fBmake_features_byrange_where_part()\fR to construct the part of the select \s-1WHERE\s0 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 \s-1SQL\s0 fragment and subsequent elements are bind values.For example: .PP .Vb 5 \& sub contained_in_query_nobin { \& my ($start,$stop) = @_; \& return (\*(Aqgff.start<=? AND gff.stop>=?\*(Aq, \& $start,$stop); \& } .Ve .SS "types_query" .IX Subsection "types_query" .Vb 6 \& 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 .Ve .PP This method is called by \fBmake_features_byrange_where_part()\fR to construct the part of the select \s-1WHERE\s0 section that selects a set of features based on their type. It returns a multi-element list in which the first element is the \s-1SQL\s0 fragment and subsequent elements are bind values. The argument is an array reference containing zero or more [$method,$source] pairs. .SS "make_types_select_part" .IX Subsection "make_types_select_part" .Vb 6 \& 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 .Ve .PP This method is called by \fBget_types()\fR to generate the query fragment and bind arguments for the \s-1SELECT\s0 part of the query that retrieves lists of feature types. The four positional arguments are as follows: .PP .Vb 4 \& $refseq reference sequence name \& $start start of region \& $stop end of region \& $want_count true to return the count of this feature type .Ve .PP If \f(CW$want_count\fR is false, the \s-1SQL\s0 fragment returned must produce a list of feature types in the format (method, source). .PP If \f(CW$want_count\fR is true, the returned fragment must produce a list of feature types in the format (method, source, count). .SS "make_types_from_part" .IX Subsection "make_types_from_part" .Vb 6 \& 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 .Ve .PP This method is called by \fBget_types()\fR to generate the query fragment and bind arguments for the \s-1FROM\s0 part of the query that retrieves lists of feature types. The four positional arguments are as follows: .PP .Vb 4 \& $refseq reference sequence name \& $start start of region \& $stop end of region \& $want_count true to return the count of this feature type .Ve .PP If \f(CW$want_count\fR is false, the \s-1SQL\s0 fragment returned must produce a list of feature types in the format (method, source). .PP If \f(CW$want_count\fR is true, the returned fragment must produce a list of feature types in the format (method, source, count). .SS "make_types_join_part" .IX Subsection "make_types_join_part" .Vb 6 \& 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 .Ve .PP This method is called by \fBget_types()\fR to generate the query fragment and bind arguments for the \s-1JOIN\s0 part of the query that retrieves lists of feature types. The four positional arguments are as follows: .PP .Vb 4 \& $refseq reference sequence name \& $start start of region \& $stop end of region \& $want_count true to return the count of this feature type .Ve .SS "make_types_where_part" .IX Subsection "make_types_where_part" .Vb 6 \& 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 .Ve .PP This method is called by \fBget_types()\fR to generate the query fragment and bind arguments for the \s-1WHERE\s0 part of the query that retrieves lists of feature types. The four positional arguments are as follows: .PP .Vb 4 \& $refseq reference sequence name \& $start start of region \& $stop end of region \& $want_count true to return the count of this feature type .Ve .SS "make_types_group_part" .IX Subsection "make_types_group_part" .Vb 6 \& 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 .Ve .PP This method is called by \fBget_types()\fR to generate the query fragment and bind arguments for the \s-1GROUP BY\s0 part of the query that retrieves lists of feature types. The four positional arguments are as follows: .PP .Vb 4 \& $refseq reference sequence name \& $start start of region \& $stop end of region \& $want_count true to return the count of this feature type .Ve .SS "get_feature_id" .IX Subsection "get_feature_id" .Vb 6 \& 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 .Ve .PP This internal method is called by load_gff_line to look up the integer \&\s-1ID\s0 of an existing feature. It is ony needed when replacing a feature with new information. .SS "make_abscoord_query" .IX Subsection "make_abscoord_query" .Vb 6 \& 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 .Ve .PP The statement handler should return rows containing five fields: .PP .Vb 5 \& 1. reference sequence name \& 2. reference sequence class \& 3. start position \& 4. stop position \& 5. strand ("+" or "\-") .Ve .PP This query always returns \*(L"Sequence\*(R" as the class of the reference sequence. .SS "feature_summary" .IX Subsection "feature_summary" .Vb 6 \& 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 .Ve .PP 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 \&\*(L"coverage\*(R" that will return an array ref of \*(L"bins\*(R" length. Each element of the array describes the number of features that overlap the bin at this position. .PP Arguments: .PP .Vb 2 \& 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 .Ve .PP 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. .PP Although an \-iterator option is provided, the method only ever returns a single feature, so this is fairly useless. .SS "coverage_array" .IX Subsection "coverage_array" .Vb 6 \& 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 .Ve .PP 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. .PP Arguments: .PP .Vb 2 \& 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. .Ve .PP 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. .SS "build_summary_statistics" .IX Subsection "build_summary_statistics" .Vb 6 \& Title : build_summary_statistics \& Usage : $db\->build_summary_statistics \& Function: prepares the table needed to call feature_summary() \& Returns : nothing \& Args : none \& Status : public .Ve .PP This method is used to build the summary statistics table that is used by the \fBfeature_summary()\fR and \fBcoverage_array()\fR methods. It needs to be called whenever the database is updated. .SH "BUGS" .IX Header "BUGS" Schemas need work to support multiple hierarchical groups. .SH "SEE ALSO" .IX Header "SEE ALSO" Bio::DB::GFF, bioperl .SH "AUTHOR" .IX Header "AUTHOR" Lincoln Stein . .PP Copyright (c) 2001 Cold Spring Harbor Laboratory. .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.