Bio::DB::HIV::HIVQueryHelper - Routines and packages used by Bio::DB::HIV and Bio::DB::Query::HIVQuery
Used in Bio::DB::Query::HIVQuery. No need to use directly.
Bio::DB::HIV::HIVQueryHelper contains a number of packages for use by Bio::DB::Query::HIVQuery. Package HIVSchema parses the lanl-schema.xml file, and allows access to it in the context of the relational database it represents (see APPENDIX for excruciating detail). Packages QRY, R, and Q together create the query string parser that enables NCBI-like queries to be understood by Bio::DB::Query::HIVQuery. They provide objects and operators to perform and simplify logical expressions involving AND, OR, and () and return hash structures that can be handled by Bio::DB::Query::HIVQuery routines.
Bio::DB::HIV::HIVQueryHelper
HIVSchema
lanl-schema.xml
QRY
R
Q
Bio::DB::Query::HIVQuery
AND
OR
()
User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to the Bioperl mailing list. Your participation is much appreciated.
bioperl-l@bioperl.org - General discussion http://bioperl.org/wiki/Mailing_lists - About the mailing lists
Please direct usage questions or support issues to the mailing list:
bioperl-l@bioperl.org
rather than to the module maintainer directly. Many experienced and reponsive experts will be able look at the problem and quickly address it. Please include a thorough description of the problem with code and data examples if at all possible.
Report bugs to the Bioperl bug tracking system to help us keep track of the bugs and their resolution. Bug reports can be submitted via the web:
https://redmine.open-bio.org/projects/bioperl/
Email maj@fortinbras.us
Mark A. Jensen
The rest of the documentation details each of the contained packages. Internal methods are usually preceded with a _
$schema = new HIVSchema( 'lanl-schema.xml' ); @tables = $schema->tables; @validFields = $schema->fields; @validAliases = $schema->aliases; @query_aliases_for_coreceptor = $schema->aliases( 'SEQ_SAMple.SSAM_second_receptor' ); $pk_for_SequenceEntry = $schema->primarykey('SequenceEntry'); # returns 'SequenceEntry.SE_id' $fk_for_SEQ_SAMple_to_SequenceEntry = $schema->foreignkey('SEQ_SAMple', 'SequenceEntry'); # returns 'SEQ_SAMple.SSAM_SE_id' $table = $schema->tablepart('SEQ_SAMple.SSAM_badseq'); # returns 'SEQ_SAMple' $column = $schema->columnpart('SEQ_SAMple.SSAM_badseq'); # returns 'SSAM_badseq'
HIVSchema methods are used in Bio::DB::Query::HIVQuery for table, column, primary/foreign key manipulations based on the observed Los Alamos HIV Sequence Database (LANL DB) naming conventions for their CGI parameters. The schema is contained in an XML file (lanl-schema.xml) which is read into an HIVSchema object, in turn a property of the HIVQuery object. HIVSchema methods are used to build correct cgi queries in a way that attempts to preserve the context of the relational database the query parameters represent.
Title : new Usage : $schema = new HIVSchema( "lanl-schema.xml "); Function: Example : Returns : an HIVSchema object Args : XML filename
Title : tables Usage : $schema->tables() Function: get all table names in schema Example : Returns : array of table names Args : none
Title : columns Usage : $schema->columns( [$tablename] ); Function: return array of columns for specified table, or all columns in schema, if called w/o args Example : Returns : Args : tablename or fieldname string
Title : fields Usage : $schema->fields(); Function: return array of all fields in schema, in format "table.column" Example : Returns : array of all fields Args : none
Title : options Usage : $schema->options(@fieldnames) Function: get array of options (i.e., valid match data strings) available to specified field Example : Returns : array of match data strings Args : [array of] fieldname string[s] in "table.column" format
Title : aliases Usage : $schema->aliases(@fieldnames) Function: get array of aliases to specified field[s] Example : Returns : array of valid query aliases for fields as spec'd in XML file Args : [an array of] fieldname[s] in "table.column" format
Title : ankh (annotation key hash) Usage : $schema->ankh(@fieldnames) Function: return a hash translating fields to annotation keys for the spec'd fields. (Annotation keys are used for parsing the tab-delimited response to Bio::DB::Query::HIVQuery::_do_lanl_request.) Example : Returns : hash ref Args : [an array of] fieldname[s] in "table.column" format
Title : tablepart (alias: tbl) Usage : $schema->tbl(@fieldnames) Function: return the portion of the fieldname[s] that refer to the db table Example : $schema->tbl('SequenceEntry.SE_id'); # returns 'SequenceEntry' Returns : table name as string Args : [an array of] fieldname[s] in "table.column" format
Title : columnpart (alias: col) Usage : $schema->col(@fieldnames) Function: return the portion of the fieldname[s] that refer to the db column Example : $schema->col('SequenceEntry.SE_id'); # returns 'SE_id' Returns : column name as string Args : [an array of] fieldname[s] in "table.column" format
Title : primarykey [alias: pk] Usage : $schema->pk(@tablenames); Function: return the primary key of the specified table[s], as judged by the syntax of the table's[s'] fieldnames Example : $schema->pk('SequenceEntry') # returns 'SequenceEntry.SE_id' Returns : primary key fieldname[s] in "table.column" format, or null if no pk exists Args : [an array of] table name[s] (fieldnames are ok, table part used)
Title : foreignkey [alias: fk] Usage : $schema->fk($intable [, $totable]) Function: return foreign key fieldname in table $intable referring to table $totable, or all foreign keys in $intable if $totable unspec'd Example : $schema->fk('AUthor', 'SequenceEntry'); # returns 'AUthor_AU_SE_id' Returns : foreign key fieldname[s] in "table.column" format Args : tablename [, optional foreign table name] (fieldnames are ok, table part used)
Title : foreigntable [alias ftbl] Usage : $schema->ftbl( @foreign_key_fieldnames ); Function: return tablename of table that foreign keys points to Example : $schema->ftbl( 'AUthor.AU_SE_id' ); # returns 'SequenceEntry' Returns : tablename Args : [an array of] fieldname[s] in "table.column" format
Title : find_join Usage : $sch->find_join('Table1', 'Table2') Function: Retrieves a set of foreign and primary keys (in table.column format) that represents a join path from Table1 to Table2 Example : Returns : an array of keys (as table.column strings) -or- an empty array if Table1 == Table2 -or- undef if no path exists Args : two table names as strings
Title : _find_join_guts Usage : $sch->_find_join_guts($table1, $table2, $stackref, \$found, $reverse) (call with $stackref = [], $found=0) Function: recursive guts of find_join Example : Returns : if a path is found, $found==1 and @$stackref contains the keys in table.column format representing the path; if a path is not found, $found == 0 and @$stackref contains garbage Args : $table1, $table2 : table names as strings $stackref : an arrayref to an empty array \$found : a scalar ref to the value 0 $rev : if $rev==1, the arrays of table names will be reversed; this can give a shorter path if cycles exist in the schema graph
Title : loadHIVSchema [alias: loadSchema] Usage : $schema->loadSchema( $XMLfilename ) Function: read (LANL DB) schema spec from XML Example : $schema->loadSchema('lanl-schema.xml'); Returns : hashref to schema data Keys are fieldnames in "table.column" format. Each value is a hashref with the following properties: {name} : HIVWEB 'table.column' format fieldname, can be used directly in the cgi query {aliases} : ref to array containing valid aliases/shortcuts for {name}; can be used in routines creating the HTML query {options} : ref to array containing valid matchdata for this field can be used directly in the HTML query {ankey} : contains the annotation key for this field used with Bioperl annotation objects {..attr..}: ..value_of_attr.. for this field (app-specific metadata) Args :
Title : _sfieldh Usage : $schema->_sfieldh($fieldname) Function: get hashref to the specified field hash Example : Returns : hashref Args : fieldname in "table.column" format
$Q = new QRY( new R( new Q('coreceptor', 'CXCR4'), new Q('country', 'ZA') ) ); QRY::Eq(QRY::And($Q, $Q), $Q); # returns 1 QRY::Eq(QRY::Or($Q, $Q), $Q); # returns 1 $Q2 = $Q1->clone; $Q2 = new QRY( new R( new Q( 'coreceptor', 'CCR5' ), new Q( 'country', 'ZA') ) ); (QRY::And($Q, $Q2))->isnull; # returns 1 $Q3 = QRY::Or($Q, $Q2); print $Q3->A; # prints '(CCR5 CXCR4)[coreceptor] (ZA)[country]'
The QRY package provides a query parser for Bio::DB::Query::HIVQuery. Currently, the parser supports AND, OR, and () operations. The structure of the LANL cgi makes it tricky to perform NOTs, though this could be implemented if the desire were great.
Two class methods do the work. QRY::_parse_q does a first-pass parse of the query string. QRY::_make_q interprets the parse tree as returned by QRY::_parse_q and produces an array of hash structures that can be used directly by Bio::DB::Query::HIVQuery query execution methods. Validation of query fields and options is performed at the Bio::DB::Query::HIVQuery level, not here.
QRY::_parse_q
QRY::_make_q
QRY objects are collections of R (or request) objects, which are in turn collections of Q (or atomic query) objects. Q objects represent a query on a single field, with match data options ORed together, e.g. (A B)[subtype]. R objects collect Q objects that could be processed in a single HTTP request; i.e., a set of atomic queries each having different fields ANDed together, such as
(A B)[subtype]
(A B)[subtype] AND ('CCR5')[coreceptor] AND (US CA)[country]
The QRY object collects Rs that cannot be reduced (through logical operations) to a single HTTP request, e.g.
((C)[subtype] AND (SI)[phenotype]) OR ( (D)[subtype] AND (NSI)[phenotype] ),
which cannot be got in one go through the current LANL cgi implementation (as far as I can tell). The parser will simplify something like
((C)[subtype] AND (SI)[phenotype]) OR ((C)[subtype] AND (NSI)[phenotype])
to the single request
(C)[subtype] AND (NSI SI)[phenotype]
however.
The operators & and | are overloaded to QRY::And and QRY::Or, to get Perl precedence and grouping for free. bool is overloaded to get symbolic tests such as if ($QRY) {stuff}. == is overloaded with QRY::Eq for convenience. No overloading is done for R or Q.
&
|
QRY::And
QRY::Or
bool
if ($QRY) {stuff}
==
QRY::Eq
Title : _make_q Usage : QRY::_make_q($parsetree) Function: creates hash structures suitable for HIVQuery from parse tree returned by QRY::_parse_q Example : Returns : array of hashrefs of query specs Args : a hashref
Title : _make_q_guts (Internal class method) Usage : _make_q_guts($ptree, $q_expr, $qarry, $anarry) Function: traverses the parse tree returned from QRY::_parse_q, checking syntax and creating HIVQuery-compliant query structures Example : Returns : Args : $parse_tree (hashref), $query_expression (scalar string ref), $query_array (array ref : stack for returning query structures), $annotation_array (array ref : stack for returning annotation fields)
Title : _parse_q Usage : QRY::_parse_q($query_string) Function: perform first pass parse of a query string with some syntax checking, return a parse tree suitable for QRY::_make_q Example : QRY::_parse_q(" to[be] OR (not to)[be] "); Returns : hashref Args : query string
Title : QRY constructor Usage : $QRY = new QRY() Function: Example : Returns : Args : array of R objects, optional
Title : requests Usage : $QRY->requests Function: get/set array of requests comprising this QRY object Example : Returns : Args : array of class R objects
Title : put_requests Usage : $QRY->put_request(@R) Function: add object of class R to $QRY Example : Returns : Args : [an array of] of class R object[s]
Title : isnull Usage : $QRY->isnull Function: test if QRY object is null Example : Returns : 1 if null, 0 otherwise Args :
Title : A Usage : print $QRY->A Function: get a string representation of QRY object Example : Returns : string scalar Args :
Title : len Usage : $QRY->len Function: get number of class R objects contained by QRY object Example : Returns : scalar Args :
Title : clone Usage : $QRY2 = $QRY1->clone; Function: create and return a clone of the object Example : Returns : object of class QRY Args :
Title : Or Usage : $QRY3 = QRY::Or($QRY1, $QRY2) Function: logical OR for QRY objects Example : Returns : a QRY object Args : two class QRY objects
Title : And Usage : $QRY3 = QRY::And($QRY1, $QRY2) Function: logical AND for QRY objects Example : Returns : a QRY object Args : two class QRY objects
Title : Bool Usage : QRY::Bool($QRY1) Function: allows symbolic testing of QRY object when bool overloaded Example : do {stuff} if $QRY1 *same as* do {stuff} if !$QRY1->isnull Returns : Args : a class QRY object
Title : Eq Usage : QRY::Eq($QRY1, $QRY2) Function: test if R objects in two QRY objects are the same (irrespective of order) Example : Returns : 1 if equal, 0 otherwise Args : two class QRY objects
$R = new R( $q1, $q2 ); $R->put_atoms($q3); $R->del_atoms('coreceptor', 'phenotype'); return $R->clone; $R1 = new R( new Q('subtype', 'B') ); $R2 = new R( new Q('subtype', 'B C'), new Q('country', 'US') ); R::Eq( (R::And($R1, $R2))[0], new R( new Q('subtype', 'B' ), new Q('country', 'US') )); # returns 1 QRY::Eq( new QRY(R::Or($R1, $R2)), new QRY($R1, $R2) ); # returns 1 R::In( (R::And($R1, $R2))[0], $R1 ); # returns 1
Class R objects contain a list of atomic queries (class Q objects). Each class R object represents a single HTTP request to the LANL DB. When converted to a DB query, the class Q objects contained by an R object are effectively ANDed.
Title : R constructor Usage : $R = new R() Function: create a new R (request) object Example : Returns : class R (request) object Args : optional, array of class Q objects
Title : len Usage : $R->len Function: get number of class Q objects contained in R object Example : Returns : scalar Args :
Title : atoms Usage : $R->atoms( [optional $field]) Function: get array of class Q (atomic query) objects in class R object Example : $R->atoms(); $R->atoms('coreceptor') Returns : array of class Q objects (all Qs or those corresponding to $field if present) Args : optional, scalar string
Title : fields Usage : $R->fields Function: get array of fields of all Q objects contained in $R Example : Returns : array of scalars Args :
Title : put_atoms Usage : $R->put_atoms( @q ) Function: AND an atomic query (class Q object) to the class R object's list Example : Returns : void Args : an [array of] class Q object[s]
Title : del_atoms Usage : $R->del_atoms( @qfields ) Function: removes class Q objects from R object's list according to the field names given in arguments Example : Returns : the class Q objects deleted Args : scalar array of field names
Title : isnull Usage : $R->isnull Function: test if class R object is null Example : Returns : 1 if null, 0 otherwise Args :
Title : A Usage : print $R->A Function: get a string representation of class R object Example : Returns : string scalar Args :
Title : clone Usage : $R2 = $R1->clone; Function: create and return a clone of the object Example : Returns : object of class R Args :
Title : In Usage : R::In($R1, $R2) Function: tests whether the query represented by $R1 would return a subset of items returned by the query represented by $R2 Example : print "R2 gets those and more" if R::In($R1, $R2); Returns : 1 if R1 is subset of R2, 0 otherwise Args : two class R objects
Title : And Usage : @Rresult = R::And($R1, $R2) Function: logical AND for R objects Example : Returns : an array containing class R objects Args : two class R objects
Title : Or Usage : @Rresult = R::Or($R1, $R2) Function: logical OR for R objects Example : Returns : an array containing class R objects Args : two class R objects
Title : Eq Usage : R::Eq($R1, $R2) Function: test if class Q objects in two R objects are the same (irrespective of order) Example : Returns : 1 if equal, 0 otherwise Args : two class R objects
$q = new Q('coreceptor', 'CXCR4 CCR5'); $u = new Q('coreceptor', 'CXCR4'); $q->fld; # returns 'coreceptor' $q->dta; # returns 'CXCR4 CCR5' print $q->A; # prints '(CXCR4 CCR5)[coreceptor] Q::qeq($q, $u); # returns 0 Q::qeq( Q::qor($q, $q), $q ); # returns 1 Q::qin($u, $q) # returns 1 Q::qeq(Q::qand($u, $q), $u ); # returns 1
Class Q objects represent atomic queries, that can be described by a single LANL cgi parameter=value pair. Class R objects (requests) are built from class Qs. The logical operations at the higher levels (QRY, R) ultimately depend on the lower level operations on Qs: qeq, qin, qand, qor.
QRY, R
qeq, qin, qand, qor
Title : Q constructor Usage : $q = new Q($field, $data) Function: create a new Q (atomic query) object Example : Returns : class Q object Args : optional $field, $data strings
Title : isnull Usage : $q->isnull Function: test if class Q object is null Example : Returns : 1 if null, 0 otherwise Args :
Title : fld Usage : $q->fld($field) Function: get/set fld (field name) property Example : Returns : scalar Args : scalar
Title : dta Usage : $q->dta($data) Function: get/set dta (whsp-separated data string) property Example : Returns : scalar Args : scalar
Title : A Usage : print $q->A Function: get a string representation of class Q object Example : Returns : string scalar Args :
Title : clone Usage : $q2 = $q1->clone; Function: create and return a clone of the object Example : Returns : object of class Q Args :
Title : qin Usage : Q::qin($q1, $q2) Function: tests whether the query represented by $q1 would return a subset of items returned by the query represented by $q2 Example : print "q2 gets those and more" if Q::qin($q1, $q2); Returns : 1 if q1 is subset of q2, 0 otherwise Args : two class Q objects
Title : qeq Usage : Q::qeq($q1, $q2) Function: test if fld and dta properties in two class Q objects are the same (irrespective of order) Example : Returns : 1 if equal, 0 otherwise Args : two class Q objects
Title : qor Usage : @qresult = Q::qor($q1, $q2) Function: logical OR for Q objects Example : Returns : an array of class Q objects Args : two class Q objects
Title : qand Usage : @qresult = Q::And($q1, $q2) Function: logical AND for R objects Example : Returns : an array of class Q objects Args : two class Q objects
Title : unique Usage : @ua = unique(@a) Function: return contents of @a with duplicates removed Example : Returns : Args : an array
$seq->annotation->put_value('patient_id', 1401) $seq->annotation->get_value('patient_ids') # returns 1401 $seq->annotation->put_value('patient_group', 'MassGenH') $seq->annotation->put_value(['clinical', 'cd4count'], 503); $seq->annotation->put_value(['clinical', 'virus_load'], 150805); foreach ( qw( cd4count virus_load ) ) { $blood_readings{$_} = $seq->annonation->get_value(['clinical', $_]); }
get_value() and put_value allow easy creation of and access to an annotation collection tree with nodes of Bio::Annotation::SimpleValue. These methods obiviate direct accession of the SimpleValue objects.
get_value()
put_value
Title : get_value Usage : $ac->get_value($tagname) -or- $ac->get_value( $tag_level1, $tag_level2,... ) Function: access the annotation value assocated with the given tags Example : Returns : a scalar Args : an array of tagnames that descend into the annotation tree
Title : put_value Usage : $ac->put_value($tagname, $value) -or- $ac->put_value([$tag_level1, $tag_level2, ...], $value) -or- $ac->put_value( [$tag_level1, $tag_level2, ...] ) Function: create a node in an annotation tree, and assign a scalar value to it if a value is specified Example : Returns : scalar or a Bio::AnnotationCollection object Args : $tagname, $value scalars (can be specified as -KEYS=>$tagname, -VALUE=>$value) -or- \@tagnames, $value (or as -KEYS=>\@tagnames, -VALUE=>$value ) Note : If intervening nodes do not exist, put_value creates them, replacing existing nodes. So if $ac->put_value('x', 10) was done, then later, $ac->put_value(['x', 'y'], 20), the original value of 'x' is trashed, and $ac->get_value('x') will now return the annotation collection with tagname 'y'.
Title : get_keys Usage : $ac->get_keys($tagname_level_1, $tagname_level_2,...) Function: Get an array of tagnames underneath the named tag nodes Example : # prints the values of the members of Category 1... print map { $ac->get_value($_) } $ac->get_keys('Category 1') ; Returns : array of tagnames or empty list if the arguments represent a leaf Args : [array of] tagname[s]
To install Bio::Seq, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Bio::Seq
CPAN shell
perl -MCPAN -e shell install Bio::Seq
For more information on module installation, please visit the detailed CPAN module installation guide.