/ 
BioPerl-1.6.0
River stage two • 61 direct dependents • 66 total dependents
/ Bio::DB::HIV::HIVQueryHelper

NAME

Bio::DB::HIV::HIVQueryHelper - Routines and packages used by Bio::DB::HIV and Bio::DB::Query::HIVQuery

SYNOPSIS

Used in Bio::DB::Query::HIVQuery. No need to use directly.

DESCRIPTION

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.

FEEDBACK

Mailing Lists

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

Reporting Bugs

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:

http://bugzilla.open-bio.org/

AUTHOR - Mark A. Jensen

Email maj@fortinbras.us

CONTRIBUTORS

APPENDIX

The rest of the documentation details each of the contained packages. Internal methods are usually preceded with a _

HIVSchema - objects/methods to manipulate a version of the LANL HIV DB schema

SYNOPSIS

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

DESCRIPTION

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.

CONSTRUCTOR

new

Title   : new
Usage   : $schema = new HIVSchema( "lanl-schema.xml ");
Function: 
Example :
Returns : an HIVSchema object
Args    : XML filename

INSTANCE METHODS

tables

Title   : tables
Usage   : $schema->tables()
Function: get all table names in schema
Example :
Returns : array of table names
Args    : none

columns

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

fields

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

options

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

aliases

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

ankh

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

tablepart

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

columnpart

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

primarykey

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)

foreignkey

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)

foreigntable

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

find_join

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

_find_join_guts

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

loadSchema

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    :

_sfieldh

Title   : _sfieldh
Usage   : $schema->_sfieldh($fieldname)
Function: get hashref to the specified field hash
Example :
Returns : hashref
Args    : fieldname in "table.column" format

Class QRY - a query algebra for HIVQuery

SYNOPSIS

$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]'

DESCRIPTION

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

CLASS METHODS

_make_q

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

_make_q_guts

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)

_parse_q

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

CONSTRUCTOR

QRY Constructor

Title   : QRY constructor
Usage   : $QRY = new QRY()
Function:
Example :
Returns : 
Args    : array of R objects, optional

INSTANCE METHODS

requests

Title   : requests
Usage   : $QRY->requests
Function: get/set array of requests comprising this QRY object
Example :
Returns : 
Args    : array of class R objects

put_requests

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]

isnull

Title   : isnull
Usage   : $QRY->isnull
Function: test if QRY object is null
Example :
Returns : 1 if null, 0 otherwise
Args    :

A

Title   : A
Usage   : print $QRY->A
Function: get a string representation of QRY object
Example :
Returns : string scalar
Args    :

len

Title   : len
Usage   : $QRY->len
Function: get number of class R objects contained by QRY object
Example :
Returns : scalar
Args    :

clone

Title   : clone
Usage   : $QRY2 = $QRY1->clone;
Function: create and return a clone of the object
Example :
Returns : object of class QRY
Args    :

CLASS METHODS

Or

Title   : Or 
Usage   : $QRY3 = QRY::Or($QRY1, $QRY2)
Function: logical OR for QRY objects
Example :
Returns : a QRY object
Args    : two class QRY objects

And

Title   : And 
Usage   : $QRY3 = QRY::And($QRY1, $QRY2)
Function: logical AND for QRY objects
Example :
Returns : a QRY object
Args    : two class QRY objects

Bool

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

Eq

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

Class R - request objects for QRY algebra

SYNOPSIS

$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

DESCRIPTION

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.

CONSTRUCTOR

R constructor

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

INSTANCE METHODS

len

Title   : len
Usage   : $R->len
Function: get number of class Q objects contained in R object
Example :
Returns : scalar
Args    :

atoms

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

fields

Title   : fields
Usage   : $R->fields
Function: get array of fields of all Q objects contained in $R
Example :
Returns : array of scalars
Args    :

put_atoms

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]

del_atoms

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

isnull

Title   : isnull
Usage   : $R->isnull
Function: test if class R object is null
Example :
Returns : 1 if null, 0 otherwise
Args    :

A

Title   : A
Usage   : print $R->A
Function: get a string representation of class R object
Example :
Returns : string scalar
Args    :

clone

Title   : clone
Usage   : $R2 = $R1->clone;
Function: create and return a clone of the object
Example :
Returns : object of class R
Args    :

CLASS METHODS

In

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

And

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

Or

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

Eq

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

Class Q - atomic query objects for QRY algebra

SYNOPSIS

$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

DESCRIPTION

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.

CONSTRUCTOR

Q constructor

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

INSTANCE METHODS

isnull

Title   : isnull
Usage   : $q->isnull
Function: test if class Q object is null
Example :
Returns : 1 if null, 0 otherwise
Args    :

fld

Title   : fld
Usage   : $q->fld($field)
Function: get/set fld (field name) property
Example :
Returns : scalar 
Args    : scalar

dta

Title   : dta
Usage   : $q->dta($data)
Function: get/set dta (whsp-separated data string) property
Example :
Returns : scalar 
Args    : scalar

A

Title   : A
Usage   : print $q->A
Function: get a string representation of class Q object
Example :
Returns : string scalar
Args    :

clone

Title   : clone
Usage   : $q2 = $q1->clone;
Function: create and return a clone of the object
Example :
Returns : object of class Q
Args    :

CLASS METHODS

qin

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

qeq

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

qor

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

qand

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

INTERNALS

unique

Title   : unique
Usage   : @ua = unique(@a)
Function: return contents of @a with duplicates removed
Example :
Returns : 
Args    : an array

Additional tools for Bio::AnnotationCollectionI

SYNOPSIS

$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', $_]);
}

DESCRIPTION

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

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

put_value

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

get_keys

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]