.\" Automatically generated by Pod::Man 4.09 (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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Bio::DB::HIV::HIVQueryHelper 3pm"
.TH Bio::DB::HIV::HIVQueryHelper 3pm "2018-10-27" "perl v5.26.2" "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::HIV::HIVQueryHelper \- Routines and packages used by Bio::DB::HIV and
Bio::DB::Query::HIVQuery
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  Used in Bio::DB::Query::HIVQuery. No need to use directly.
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Bio::DB::HIV::HIVQueryHelper\*(C'\fR contains a number of packages for use
by Bio::DB::Query::HIVQuery. Package \f(CW\*(C`HIVSchema\*(C'\fR parses the
\&\f(CW\*(C`lanl\-schema.xml\*(C'\fR file, and allows access to it in the context of the
relational database it represents (see \s-1APPENDIX\s0 for excruciating
detail). Packages \f(CW\*(C`QRY\*(C'\fR, \f(CW\*(C`R\*(C'\fR, and \f(CW\*(C`Q\*(C'\fR together create the query
string parser that enables NCBI-like queries to be understood by
\&\f(CW\*(C`Bio::DB::Query::HIVQuery\*(C'\fR. They provide objects and operators to
perform and simplify logical expressions involving \f(CW\*(C`AND\*(C'\fR, \f(CW\*(C`OR\*(C'\fR, and
\&\f(CW\*(C`()\*(C'\fR and return hash structures that can be handled by
\&\f(CW\*(C`Bio::DB::Query::HIVQuery\*(C'\fR routines.
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "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.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
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.
.SS "Reporting Bugs"
.IX Subsection "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:
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR \- Mark A. Jensen"
.IX Header "AUTHOR - Mark A. Jensen"
Email maj@fortinbras.us
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Mark A. Jensen
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the contained packages.
Internal methods are usually preceded with a _
.SS "HIVSchema \-  objects/methods to manipulate a version of the \s-1LANL HIV DB\s0 schema"
.IX Subsection "HIVSchema - objects/methods to manipulate a version of the LANL HIV DB schema"
\fIHIVSchema \s-1SYNOPSIS\s0\fR
.IX Subsection "HIVSchema SYNOPSIS"
.PP
.Vb 8
\&    $schema = new HIVSchema( \*(Aqlanl\-schema.xml\*(Aq );
\&    @tables = $schema\->tables;
\&    @validFields = $schema\->fields;
\&    @validAliases = $schema\->aliases;
\&    @query_aliases_for_coreceptor = $schema\->aliases( \*(AqSEQ_SAMple.SSAM_second_receptor\*(Aq );
\&    $pk_for_SequenceEntry = $schema\->primarykey(\*(AqSequenceEntry\*(Aq);    # returns \*(AqSequenceEntry.SE_id\*(Aq
\&    $fk_for_SEQ_SAMple_to_SequenceEntry =
\&              $schema\->foreignkey(\*(AqSEQ_SAMple\*(Aq, \*(AqSequenceEntry\*(Aq);    # returns \*(AqSEQ_SAMple.SSAM_SE_id\*(Aq
\&
\&    $table = $schema\->tablepart(\*(AqSEQ_SAMple.SSAM_badseq\*(Aq);           # returns \*(AqSEQ_SAMple\*(Aq
\&    $column = $schema\->columnpart(\*(AqSEQ_SAMple.SSAM_badseq\*(Aq);         # returns \*(AqSSAM_badseq\*(Aq
.Ve
.PP
\fIHIVSchema \s-1DESCRIPTION\s0\fR
.IX Subsection "HIVSchema DESCRIPTION"
.PP
HIVSchema methods are used in Bio::DB::Query::HIVQuery for table,
column, primary/foreign key manipulations based on the observed Los
Alamos \s-1HIV\s0 Sequence Database (\s-1LANL DB\s0) naming conventions for their
\&\s-1CGI\s0 parameters. The schema is contained in an \s-1XML\s0 file
(\f(CW\*(C`lanl\-schema.xml\*(C'\fR) 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.
.PP
\fIHIVSchema \s-1CONSTRUCTOR\s0\fR
.IX Subsection "HIVSchema CONSTRUCTOR"
.PP
HIVSchema::new
.IX Subsection "HIVSchema::new"
.PP
.Vb 6
\& Title   : new
\& Usage   : $schema = new HIVSchema( "lanl\-schema.xml ");
\& Function:
\& Example :
\& Returns : an HIVSchema object
\& Args    : XML filename
.Ve
.PP
\fIHIVSchema \s-1INSTANCE METHODS\s0\fR
.IX Subsection "HIVSchema INSTANCE METHODS"
.PP
HIVSchema tables
.IX Subsection "HIVSchema tables"
.PP
.Vb 6
\& Title   : tables
\& Usage   : $schema\->tables()
\& Function: get all table names in schema
\& Example :
\& Returns : array of table names
\& Args    : none
.Ve
.PP
HIVSchema columns
.IX Subsection "HIVSchema columns"
.PP
.Vb 7
\& 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
.Ve
.PP
HIVSchema fields
.IX Subsection "HIVSchema fields"
.PP
.Vb 6
\& 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
.Ve
.PP
HIVSchema options
.IX Subsection "HIVSchema options"
.PP
.Vb 7
\& 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
.Ve
.PP
HIVSchema aliases
.IX Subsection "HIVSchema aliases"
.PP
.Vb 6
\& 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\*(Aqd in XML file
\& Args    : [an array of] fieldname[s] in "table.column" format
.Ve
.PP
HIVSchema ankh
.IX Subsection "HIVSchema ankh"
.PP
.Vb 9
\& Title   : ankh (annotation key hash)
\& Usage   : $schema\->ankh(@fieldnames)
\& Function: return a hash translating fields to annotation keys for the
\&           spec\*(Aqd 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
.Ve
.PP
HIVSchema tablepart
.IX Subsection "HIVSchema tablepart"
.PP
.Vb 7
\& 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(\*(AqSequenceEntry.SE_id\*(Aq); # returns \*(AqSequenceEntry\*(Aq
\& Returns : table name as string
\& Args    : [an array of] fieldname[s] in "table.column" format
.Ve
.PP
HIVSchema columnpart
.IX Subsection "HIVSchema columnpart"
.PP
.Vb 7
\& 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(\*(AqSequenceEntry.SE_id\*(Aq); # returns \*(AqSE_id\*(Aq
\& Returns : column name as string
\& Args    : [an array of] fieldname[s] in "table.column" format
.Ve
.PP
HIVSchema primarykey
.IX Subsection "HIVSchema primarykey"
.PP
.Vb 8
\& 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\*(Aqs[s\*(Aq] fieldnames
\& Example : $schema\->pk(\*(AqSequenceEntry\*(Aq) # returns \*(AqSequenceEntry.SE_id\*(Aq
\& 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)
.Ve
.PP
HIVSchema foreignkey
.IX Subsection "HIVSchema foreignkey"
.PP
.Vb 9
\& 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\*(Aqd
\& Example : $schema\->fk(\*(AqAUthor\*(Aq, \*(AqSequenceEntry\*(Aq); # returns \*(AqAUthor_AU_SE_id\*(Aq
\& Returns : foreign key fieldname[s] in "table.column" format
\& Args    : tablename [, optional foreign table name] (fieldnames are ok,
\&           table part used)
.Ve
.PP
HIVSchema foreigntable
.IX Subsection "HIVSchema foreigntable"
.PP
.Vb 6
\& Title   : foreigntable [alias ftbl]
\& Usage   : $schema\->ftbl( @foreign_key_fieldnames );
\& Function: return tablename of table that foreign keys points to
\& Example : $schema\->ftbl( \*(AqAUthor.AU_SE_id\*(Aq ); # returns \*(AqSequenceEntry\*(Aq
\& Returns : tablename
\& Args    : [an array of] fieldname[s] in "table.column" format
.Ve
.PP
HIVSchema find_join
.IX Subsection "HIVSchema find_join"
.PP
.Vb 8
\& Title   : find_join
\& Usage   : $sch\->find_join(\*(AqTable1\*(Aq, \*(AqTable2\*(Aq)
\& 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
.Ve
.PP
HIVSchema _find_join_guts
.IX Subsection "HIVSchema _find_join_guts"
.PP
.Vb 10
\& Title   : _find_join_guts
\& Usage   : $sch\->_find_join_guts($table1, $table2, $stackref, \e$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
\&           \e$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
.Ve
.PP
HIVSchema loadSchema
.IX Subsection "HIVSchema loadSchema"
.PP
.Vb 10
\& Title   : loadHIVSchema [alias: loadSchema]
\& Usage   : $schema\->loadSchema( $XMLfilename )
\& Function: read (LANL DB) schema spec from XML
\& Example : $schema\->loadSchema(\*(Aqlanl\-schema.xml\*(Aq);
\& Returns : hashref to schema data
\&           Keys are fieldnames in "table.column" format.
\&           Each value is a hashref with the following properties:
\&           {name}    : HIVWEB \*(Aqtable.column\*(Aq 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    :
.Ve
.PP
HIVSchema _sfieldh
.IX Subsection "HIVSchema _sfieldh"
.PP
.Vb 6
\& Title   : _sfieldh
\& Usage   : $schema\->_sfieldh($fieldname)
\& Function: get hashref to the specified field hash
\& Example :
\& Returns : hashref
\& Args    : fieldname in "table.column" format
.Ve
.SS "Class \s-1QRY\s0 \-  a query algebra for HIVQuery"
.IX Subsection "Class QRY - a query algebra for HIVQuery"
\fI\s-1QRY SYNOPSIS\s0\fR
.IX Subsection "QRY SYNOPSIS"
.PP
.Vb 10
\&  $Q = new QRY(
\&               new R(
\&                      new Q(\*(Aqcoreceptor\*(Aq, \*(AqCXCR4\*(Aq),
\&                      new Q(\*(Aqcountry\*(Aq, \*(AqZA\*(Aq)
\&                     )
\&               );
\&  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( \*(Aqcoreceptor\*(Aq, \*(AqCCR5\*(Aq ),
\&                       new Q( \*(Aqcountry\*(Aq, \*(AqZA\*(Aq)
\&                      )
\&               );
\&  (QRY::And($Q, $Q2))\->isnull;                       # returns 1
\&  $Q3 = QRY::Or($Q, $Q2);
\&  print $Q3\->A;                                      # prints \*(Aq(CCR5 CXCR4)[coreceptor] (ZA)[country]\*(Aq
.Ve
.PP
\fI\s-1QRY DESCRIPTION\s0\fR
.IX Subsection "QRY DESCRIPTION"
.PP
The \s-1QRY\s0 package provides a query parser for
Bio::DB::Query::HIVQuery. Currently, the parser supports \s-1AND, OR,\s0
and () operations. The structure of the \s-1LANL\s0 cgi makes it tricky to
perform NOTs, though this could be implemented if the desire were
great.
.PP
Two class methods do the work. \f(CW\*(C`QRY::_parse_q\*(C'\fR does a first-pass
parse of the query string. \f(CW\*(C`QRY::_make_q\*(C'\fR interprets the parse tree
as returned by \f(CW\*(C`QRY::_parse_q\*(C'\fR and produces an array of hash
structures that can be used directly by \f(CW\*(C`Bio::DB::Query::HIVQuery\*(C'\fR
query execution methods. Validation of query fields and options is
performed at the \f(CW\*(C`Bio::DB::Query::HIVQuery\*(C'\fR level, not here.
.PP
\&\f(CW\*(C`QRY\*(C'\fR objects are collections of \f(CW\*(C`R\*(C'\fR (or request) objects, which are
in turn collections of \f(CW\*(C`Q\*(C'\fR (or atomic query) objects. \f(CW\*(C`Q\*(C'\fR objects
represent a query on a single field, with match data options \f(CW\*(C`OR\*(C'\fRed
together, e.g. \f(CW\*(C`(A B)[subtype]\*(C'\fR. \f(CW\*(C`R\*(C'\fR objects collect \f(CW\*(C`Q\*(C'\fR objects
that could be processed in a single \s-1HTTP\s0 request; i.e., a set of
atomic queries each having different fields \f(CW\*(C`AND\*(C'\fRed together, such as
.PP
.Vb 1
\&  (A B)[subtype] AND (\*(AqCCR5\*(Aq)[coreceptor] AND (US CA)[country]
.Ve
.PP
The \f(CW\*(C`QRY\*(C'\fR object collects \f(CW\*(C`R\*(C'\fRs that cannot be reduced (through
logical operations) to a single \s-1HTTP\s0 request, e.g.
.PP
.Vb 1
\&  ((C)[subtype] AND (SI)[phenotype]) OR ( (D)[subtype] AND (NSI)[phenotype] ),
.Ve
.PP
which cannot be got in one go through the current \s-1LANL\s0 cgi
implementation (as far as I can tell). The parser will simplify
something like
.PP
.Vb 1
\&  ((C)[subtype] AND (SI)[phenotype]) OR ((C)[subtype] AND (NSI)[phenotype])
.Ve
.PP
to the single request
.PP
.Vb 1
\&  (C)[subtype] AND (NSI SI)[phenotype]
.Ve
.PP
however.
.PP
The operators \f(CW\*(C`&\*(C'\fR and \f(CW\*(C`|\*(C'\fR are overloaded to \f(CW\*(C`QRY::And\*(C'\fR and
\&\f(CW\*(C`QRY::Or\*(C'\fR, to get Perl precedence and grouping for free. \f(CW\*(C`bool\*(C'\fR is
overloaded to get symbolic tests such as \f(CW\*(C`if ($QRY) {stuff}\*(C'\fR. \f(CW\*(C`==\*(C'\fR
is overloaded with \f(CW\*(C`QRY::Eq\*(C'\fR for convenience. No overloading is done
for \f(CW\*(C`R\*(C'\fR or \f(CW\*(C`Q\*(C'\fR.
.PP
\s-1QRY\s0 _make_q
.IX Subsection "QRY _make_q"
.PP
.Vb 7
\& 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
.Ve
.PP
\s-1QRY\s0 _make_q_guts
.IX Subsection "QRY _make_q_guts"
.PP
.Vb 10
\& 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)
.Ve
.PP
\s-1QRY\s0 _parse_q
.IX Subsection "QRY _parse_q"
.PP
.Vb 7
\& 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
.Ve
.PP
\fI\s-1QRY CONSTRUCTOR\s0\fR
.IX Subsection "QRY CONSTRUCTOR"
.PP
\s-1QRY\s0 Constructor
.IX Subsection "QRY Constructor"
.PP
.Vb 6
\& Title   : QRY constructor
\& Usage   : $QRY = new QRY()
\& Function:
\& Example :
\& Returns :
\& Args    : array of R objects, optional
.Ve
.PP
\fI\s-1QRY INSTANCE METHODS\s0\fR
.IX Subsection "QRY INSTANCE METHODS"
.PP
\s-1QRY\s0 requests
.IX Subsection "QRY requests"
.PP
.Vb 6
\& Title   : requests
\& Usage   : $QRY\->requests
\& Function: get/set array of requests comprising this QRY object
\& Example :
\& Returns :
\& Args    : array of class R objects
.Ve
.PP
\s-1QRY\s0 put_requests
.IX Subsection "QRY put_requests"
.PP
.Vb 6
\& 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]
.Ve
.PP
\s-1QRY\s0 isnull
.IX Subsection "QRY isnull"
.PP
.Vb 6
\& Title   : isnull
\& Usage   : $QRY\->isnull
\& Function: test if QRY object is null
\& Example :
\& Returns : 1 if null, 0 otherwise
\& Args    :
.Ve
.PP
\s-1QRY A\s0
.IX Subsection "QRY A"
.PP
.Vb 6
\& Title   : A
\& Usage   : print $QRY\->A
\& Function: get a string representation of QRY object
\& Example :
\& Returns : string scalar
\& Args    :
.Ve
.PP
\s-1QRY\s0 len
.IX Subsection "QRY len"
.PP
.Vb 6
\& Title   : len
\& Usage   : $QRY\->len
\& Function: get number of class R objects contained by QRY object
\& Example :
\& Returns : scalar
\& Args    :
.Ve
.PP
\s-1QRY\s0 clone
.IX Subsection "QRY clone"
.PP
.Vb 6
\& Title   : clone
\& Usage   : $QRY2 = $QRY1\->clone;
\& Function: create and return a clone of the object
\& Example :
\& Returns : object of class QRY
\& Args    :
.Ve
.PP
\fI\s-1QRY CLASS METHODS\s0\fR
.IX Subsection "QRY CLASS METHODS"
.PP
\s-1QRY\s0 Or
.IX Subsection "QRY Or"
.PP
.Vb 6
\& Title   : Or
\& Usage   : $QRY3 = QRY::Or($QRY1, $QRY2)
\& Function: logical OR for QRY objects
\& Example :
\& Returns : a QRY object
\& Args    : two class QRY objects
.Ve
.PP
\s-1QRY\s0 And
.IX Subsection "QRY And"
.PP
.Vb 6
\& Title   : And
\& Usage   : $QRY3 = QRY::And($QRY1, $QRY2)
\& Function: logical AND for QRY objects
\& Example :
\& Returns : a QRY object
\& Args    : two class QRY objects
.Ve
.PP
\s-1QRY\s0 Bool
.IX Subsection "QRY Bool"
.PP
.Vb 6
\& 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
.Ve
.PP
\s-1QRY\s0 Eq
.IX Subsection "QRY Eq"
.PP
.Vb 7
\& 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
.Ve
.SS "Class R \- request objects for \s-1QRY\s0 algebra"
.IX Subsection "Class R - request objects for QRY algebra"
\fIR \s-1SYNOPSIS\s0\fR
.IX Subsection "R SYNOPSIS"
.PP
.Vb 12
\&  $R = new R( $q1, $q2 );
\&  $R\->put_atoms($q3);
\&  $R\->del_atoms(\*(Aqcoreceptor\*(Aq, \*(Aqphenotype\*(Aq);
\&  return $R\->clone;
\&  $R1 = new R( new Q(\*(Aqsubtype\*(Aq, \*(AqB\*(Aq) );
\&  $R2 = new R( new Q(\*(Aqsubtype\*(Aq, \*(AqB C\*(Aq),
\&               new Q(\*(Aqcountry\*(Aq, \*(AqUS\*(Aq) );
\&  R::Eq( (R::And($R1, $R2))[0],
\&         new R( new Q(\*(Aqsubtype\*(Aq, \*(AqB\*(Aq ),
\&                new Q(\*(Aqcountry\*(Aq, \*(AqUS\*(Aq) ));                 # 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
.Ve
.PP
\fIR \s-1DESCRIPTION\s0\fR
.IX Subsection "R DESCRIPTION"
.PP
Class R objects contain a list of atomic queries (class Q
objects). Each class R object represents a single \s-1HTTP\s0 request to the
\&\s-1LANL DB.\s0 When converted to a \s-1DB\s0 query, the class Q objects contained
by an R object are effectively \f(CW\*(C`AND\*(C'\fRed.
.PP
\fIR \s-1CONSTRUCTOR\s0\fR
.IX Subsection "R CONSTRUCTOR"
.PP
R constructor
.IX Subsection "R constructor"
.PP
.Vb 6
\& 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
.Ve
.PP
\fIR \s-1INSTANCE METHODS\s0\fR
.IX Subsection "R INSTANCE METHODS"
.PP
R len
.IX Subsection "R len"
.PP
.Vb 6
\& Title   : len
\& Usage   : $R\->len
\& Function: get number of class Q objects contained in R object
\& Example :
\& Returns : scalar
\& Args    :
.Ve
.PP
R atoms
.IX Subsection "R atoms"
.PP
.Vb 7
\& 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(\*(Aqcoreceptor\*(Aq)
\& Returns : array of class Q objects (all Qs or those corresponding to $field
\&           if present)
\& Args    : optional, scalar string
.Ve
.PP
R fields
.IX Subsection "R fields"
.PP
.Vb 6
\& Title   : fields
\& Usage   : $R\->fields
\& Function: get array of fields of all Q objects contained in $R
\& Example :
\& Returns : array of scalars
\& Args    :
.Ve
.PP
R put_atoms
.IX Subsection "R put_atoms"
.PP
.Vb 6
\& Title   : put_atoms
\& Usage   : $R\->put_atoms( @q )
\& Function: AND an atomic query (class Q object) to the class R object\*(Aqs list
\& Example :
\& Returns : void
\& Args    : an [array of] class Q object[s]
.Ve
.PP
R del_atoms
.IX Subsection "R del_atoms"
.PP
.Vb 7
\& Title   : del_atoms
\& Usage   : $R\->del_atoms( @qfields )
\& Function: removes class Q objects from R object\*(Aqs list according to the
\&           field names given in arguments
\& Example :
\& Returns : the class Q objects deleted
\& Args    : scalar array of field names
.Ve
.PP
R isnull
.IX Subsection "R isnull"
.PP
.Vb 6
\& Title   : isnull
\& Usage   : $R\->isnull
\& Function: test if class R object is null
\& Example :
\& Returns : 1 if null, 0 otherwise
\& Args    :
.Ve
.PP
R A
.IX Subsection "R A"
.PP
.Vb 6
\& Title   : A
\& Usage   : print $R\->A
\& Function: get a string representation of class R object
\& Example :
\& Returns : string scalar
\& Args    :
.Ve
.PP
R clone
.IX Subsection "R clone"
.PP
.Vb 6
\& Title   : clone
\& Usage   : $R2 = $R1\->clone;
\& Function: create and return a clone of the object
\& Example :
\& Returns : object of class R
\& Args    :
.Ve
.PP
\fIR \s-1CLASS METHODS\s0\fR
.IX Subsection "R CLASS METHODS"
.PP
R In
.IX Subsection "R In"
.PP
.Vb 7
\& 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
.Ve
.PP
R And
.IX Subsection "R And"
.PP
.Vb 6
\& 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
.Ve
.PP
R Or
.IX Subsection "R Or"
.PP
.Vb 6
\& 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
.Ve
.PP
R Eq
.IX Subsection "R Eq"
.PP
.Vb 7
\& 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
.Ve
.SS "Class Q \-  atomic query objects for \s-1QRY\s0 algebra"
.IX Subsection "Class Q - atomic query objects for QRY algebra"
\fIQ \s-1SYNOPSIS\s0\fR
.IX Subsection "Q SYNOPSIS"
.PP
.Vb 9
\&    $q = new Q(\*(Aqcoreceptor\*(Aq, \*(AqCXCR4 CCR5\*(Aq);
\&    $u = new Q(\*(Aqcoreceptor\*(Aq, \*(AqCXCR4\*(Aq);
\&    $q\->fld;                                 # returns \*(Aqcoreceptor\*(Aq
\&    $q\->dta;                                 # returns \*(AqCXCR4 CCR5\*(Aq
\&    print $q\->A;                             # prints \*(Aq(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
.Ve
.PP
\fIQ \s-1DESCRIPTION\s0\fR
.IX Subsection "Q DESCRIPTION"
.PP
Class Q objects represent atomic queries, that can be described by a
single \s-1LANL\s0 cgi parameter=value pair. Class R objects (requests) are
built from class Qs. The logical operations at the higher levels
(\f(CW\*(C`QRY, R\*(C'\fR) ultimately depend on the lower level operations on Qs:
\&\f(CW\*(C`qeq, qin, qand, qor\*(C'\fR.
.PP
\fIQ \s-1CONSTRUCTOR\s0\fR
.IX Subsection "Q CONSTRUCTOR"
.PP
Q constructor
.IX Subsection "Q constructor"
.PP
.Vb 6
\& 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
.Ve
.PP
\fIQ \s-1INSTANCE METHODS\s0\fR
.IX Subsection "Q INSTANCE METHODS"
.PP
Q isnull
.IX Subsection "Q isnull"
.PP
.Vb 6
\& Title   : isnull
\& Usage   : $q\->isnull
\& Function: test if class Q object is null
\& Example :
\& Returns : 1 if null, 0 otherwise
\& Args    :
.Ve
.PP
Q fld
.IX Subsection "Q fld"
.PP
.Vb 6
\& Title   : fld
\& Usage   : $q\->fld($field)
\& Function: get/set fld (field name) property
\& Example :
\& Returns : scalar
\& Args    : scalar
.Ve
.PP
Q dta
.IX Subsection "Q dta"
.PP
.Vb 6
\& Title   : dta
\& Usage   : $q\->dta($data)
\& Function: get/set dta (whsp\-separated data string) property
\& Example :
\& Returns : scalar
\& Args    : scalar
.Ve
.PP
Q A
.IX Subsection "Q A"
.PP
.Vb 6
\& Title   : A
\& Usage   : print $q\->A
\& Function: get a string representation of class Q object
\& Example :
\& Returns : string scalar
\& Args    :
.Ve
.PP
Q clone
.IX Subsection "Q clone"
.PP
.Vb 6
\& Title   : clone
\& Usage   : $q2 = $q1\->clone;
\& Function: create and return a clone of the object
\& Example :
\& Returns : object of class Q
\& Args    :
.Ve
.PP
\fIQ \s-1CLASS METHODS\s0\fR
.IX Subsection "Q CLASS METHODS"
.PP
Q qin
.IX Subsection "Q qin"
.PP
.Vb 7
\& 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
.Ve
.PP
Q qeq
.IX Subsection "Q qeq"
.PP
.Vb 7
\& 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
.Ve
.PP
Q qor
.IX Subsection "Q qor"
.PP
.Vb 6
\& 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
.Ve
.PP
Q qand
.IX Subsection "Q qand"
.PP
.Vb 6
\& 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
.Ve
.PP
\fIQ \s-1INTERNALS\s0\fR
.IX Subsection "Q INTERNALS"
.PP
Q unique
.IX Subsection "Q unique"
.PP
.Vb 6
\& Title   : unique
\& Usage   : @ua = unique(@a)
\& Function: return contents of @a with duplicates removed
\& Example :
\& Returns :
\& Args    : an array
.Ve
.SS "Additional tools for Bio::AnnotationCollectionI"
.IX Subsection "Additional tools for Bio::AnnotationCollectionI"
\fIBio::AnnotationCollectionI \s-1SYNOPSIS\s0 (additional methods)\fR
.IX Subsection "Bio::AnnotationCollectionI SYNOPSIS (additional methods)"
.PP
.Vb 8
\&    $seq\->annotation\->put_value(\*(Aqpatient_id\*(Aq, 1401)
\&    $seq\->annotation\->get_value(\*(Aqpatient_ids\*(Aq)                   # returns 1401
\&    $seq\->annotation\->put_value(\*(Aqpatient_group\*(Aq, \*(AqMassGenH\*(Aq)
\&    $seq\->annotation\->put_value([\*(Aqclinical\*(Aq, \*(Aqcd4count\*(Aq], 503);
\&    $seq\->annotation\->put_value([\*(Aqclinical\*(Aq, \*(Aqvirus_load\*(Aq], 150805);
\&    foreach ( qw( cd4count virus_load ) ) {
\&        $blood_readings{$_} = $seq\->annonation\->get_value([\*(Aqclinical\*(Aq, $_]);
\&    }
.Ve
.PP
\fIBio::AnnotationCollectionI \s-1DESCRIPTION\s0 (additional methods)\fR
.IX Subsection "Bio::AnnotationCollectionI DESCRIPTION (additional methods)"
.PP
\&\f(CW\*(C`get_value()\*(C'\fR and \f(CW\*(C`put_value\*(C'\fR 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.
.SS "get_value"
.IX Subsection "get_value"
.Vb 7
\& Title   : get_value
\& Usage   : $ac\->get_value($tagname) \-or\-
\&           $ac\->get_value( $tag_level1, $tag_level2,... )
\& Function: access the annotation value associated with the given tags
\& Example :
\& Returns : a scalar
\& Args    : an array of tagnames that descend into the annotation tree
.Ve
.SS "put_value"
.IX Subsection "put_value"
.Vb 10
\& 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\-
\&           \e@tagnames, $value (or as \-KEYS=>\e@tagnames, \-VALUE=>$value )
\& Note    : If intervening nodes do not exist, put_value creates them, replacing
\&           existing nodes. So if $ac\->put_value(\*(Aqx\*(Aq, 10) was done, then later,
\&           $ac\->put_value([\*(Aqx\*(Aq, \*(Aqy\*(Aq], 20), the original value of \*(Aqx\*(Aq is trashed,
\&           and $ac\->get_value(\*(Aqx\*(Aq) will now return the annotation collection
\&           with tagname \*(Aqy\*(Aq.
.Ve
.SS "get_keys"
.IX Subsection "get_keys"
.Vb 7
\& 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(\*(AqCategory 1\*(Aq) ;
\& Returns : array of tagnames or empty list if the arguments represent a leaf
\& Args    : [array of] tagname[s]
.Ve