GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  BIO::DB::QUERY::HIVQUERY (3)

.ds Aq ’

NAME

Bio::DB::Query::HIVQuery - Query interface to the Los Alamos HIV Sequence Database

CONTENTS

SYNOPSIS



    $q = new Bio::DB::Query::HIVQuery(" C[subtype] ZA[country] CXCR4[coreceptor] ");
    $q = new Bio::DB::Query::HIVQuery(
         -query=>{subtype=>C,
                  country=>ZA,
                  coreceptor=>CXCR4});

    $ac = $q->get_annotations_by_id(($q->ids)[0]);
    $ac->get_value(Geo, country)                    # returns SOUTH AFRICA

    $db = new Bio::DB::HIV();
    $seqio = $db->get_Stream_by_query($q);              # returns annotated Bio::Seqs

    # get subtype C sequences from South Africa and Brazil,
    # with associated info on patient health, coreceptor use, and
    # infection period:

    $q = new Bio::DB::Query::HIVQuery(
         -query => {
                    query => {subtype=>C,
                    country=>[ZA, BR]},
                    annot => [patient_health,
                                coreceptor,
                                days_post_infection]
                    });



DESCRIPTION

Bio::DB::Query::HIVQuery provides a query-like interface to the cgi-based Los Alamos National Laboratory (LANL) HIV Sequence Database. It uses Bioperl facilities to capture both sequences and annotations in batch in an automated and computable way. Use with Bio::DB::HIV to create Bio::Seq objects and annotated Bio::SeqIO streams.

    Query format

The interface implements a simple query language emulation that understands AND, OR, and parenthetical nesting. The basic query unit is



 (match1 match2 ...)[fieldname]



Sequences are returned for which fieldname equals match1 OR match2 OR .... These units can be combined with AND, OR and parentheses. For example:



 (B, C)[subtype] AND (2000, 2001, 2002, 2003)[year] AND ((CN)[country] OR (ZA)[country])



which can be shortened to



 (B C)[subtype] (2000 2001 2002 2003)[year] (CN ZA)[country]



The user can specify annotation fields, that do not restrict the query, but arrange for the return of the associated field data for each sequence returned. Specify annotation fields between curly braces, as in:



 (B C)[subtype] 2000[year] {country cd4_count cd8_count}



Annotations can be accessed off the query using methods described in APPENDIX.

    Hash specifications for query construction

Single query specifications can be made as hash references provided to the -query argument of the constructor. There are two forms:



 -query => { country=>BR, phenotype=>NSI, cd4_count=>Any }



equivalent to



 -query => [ country=>BR, phenotype=>NSI, cd4_count=>Any ]



or



 -query => { query => {country=>BR, phenotype=>NSI},
             annot => [cd4_count] }



In both cases, the CD4 count is included in the annotations returned, but does not restrict the rest of the query.

To ’OR’ multiple values of a field, use an anonymous array ref:



 -query => { country=>[ZA,BR,NL], subtype=>[A, C, D] }



    Valid query field names

An attempt was made to make the query field names natural and easy to remember. Aliases are specified in an XML file (lanl-schema.xml) that is part of the distribution. Custom field aliases can be set up by modifying this file.

An HTML cheatsheet with valid field names, aliases, and match data can be generated from the XML by using hiv_object->help(help.html). A query can also be validated locally before it is unleashed on the server; see below.

    Annotations

LANL DB annotations have been organized into a number of natural groupings, tagged Geo, Patient, Virus, and StdMap. After a successful query, each id is associated with a tree of Bio::Annotation::SimpleValue objects. These can be accessed with methods get_value and put_value described in APPENDIX.

    Delayed/partial query runs

Accessing the LANL DB involves multiple HTTP requests. The query can be instructed to proceed through all (the default) or only some of them, using the named parameter RUN_OPTION.

To validate a query locally, use



 $q = new Bio::DB::Query::HIVQuery( -query => {...}, -RUN_OPTION=>0 )



which will throw an exception if a field name or option is invalid.

To get a query count only, you can save a server hit by using



 $q = new Bio::DB::Query::HIVQuery( -query => {...}, -RUN_OPTION=>1 )



and asking for $q->count. To finish the query, do



 $q->_do_query(2)



which picks up where you left off.

-RUN_OPTION=>2, the default, runs the full query, returning ids and annotations.

    Query re-use

You can clear the query results, retaining the same LANL session and query spec, by doing $q->_reset. Change the query, and rerun with $q->_do_query($YOUR_RUN_OPTION).

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



    Support

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.

    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:



  https://github.com/bioperl/bioperl-live/issues



AUTHOR - Mark A. Jensen

Email maj@fortinbras.us

CONTRIBUTORS

Mark A. Jensen

APPENDIX

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

Constructor

    new



 Title   : new
 Usage   : my $hiv_query = new Bio::DB::Query::HIVQuery();
 Function: Builds a new Bio::DB::Query::HIVQuery object,
           running a sequence query against the Los Alamos
           HIV sequence database
 Returns : an instance of Bio::DB::Query::HIVQuery
 Args    :



QueryI compliance

    count



 Title   : count
 Usage   : $hiv_query->count($newval)
 Function: return number of sequences found
 Example :
 Returns : value of count (a scalar)
 Args    : on set, new value (a scalar or undef, optional)
 Note    : count warns if it is accessed for reading before query
           has been executed to at least level 1



    ids



 Title   : ids
 Usage   : $hiv_query->ids($newval)
 Function: LANL ids of returned sequences
 Example :
 Returns : value of ids (an arrayref of sequence accessions/ids)
 Args    : on set, new value (an arrayref or undef, optional)



    query



 Title   : query
 Usage   : $hiv_query->query
 Function: Get/set the submitted query hash or string
 Example :
 Returns : hashref or string
 Args    : query in hash or string form (see DESCRIPTION)



Bio::DB::Query::HIVQuery specific methods

    help



 Title   : help
 Usage   : $hiv_query->help("help.html")
 Function: get html-formatted listing of valid fields/aliases/options
           based on current schema xml
 Example : perl -MBio::DB::Query::HIVQuery -e "new Bio::DB::Query::HIVQuery()->help" | lynx -stdin
 Returns : HTML
 Args    : optional filename; otherwise prints to stdout



Annotation manipulation methods

    get_annotations_by_ids



 Title   : get_annotations_by_ids (or ..._by_id)
 Usage   : $ac = $hiv_query->get_annotations_by_ids(@ids)
 Function: Get the Bio::Annotation::Collection for these sequence ids
 Example :
 Returns : A Bio::Annotation::Collection object
 Args    : an array of sequence ids



    add_annotations_for_id



 Title   : add_annotations_for_id
 Usage   : $hiv_query->add_annotations_for_id( $id ) to create a new
            empty collection for $id
           $hiv_query->add_annotations_for_id( $id, $ac ) to associate
           $ac with $id
 Function: Associate a Bio::Annotation::Collection with this sequence id
 Example :
 Returns : a Bio::Annotation::Collection object
 Args    : sequence id [, Bio::Annotation::Collection object]



    remove_annotations_for_ids



 Title   : remove_annotations_for_ids (or ..._for_id)
 Usage   : $hiv_query->remove_annotations_for_ids( @ids)
 Function: Remove annotation collection for this sequence id
 Example :
 Returns : An array of the previous annotation collections for these ids
 Args    : an array of sequence ids



    remove_annotations



 Title   : remove_annotations
 Usage   : $hiv_query->remove_annotations()
 Function: Remove all annotation collections for this object
 Example :
 Returns : The previous annotation collection hash for this object
 Args    : none



    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
 Note    : this is a L<Bio::AnnotationCollectionI> method added in
           L<Bio::DB::HIV::HIVQueryHelper>



    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 )
 Notes   : This is a L<Bio::AnnotationCollectionI> method added in
           L<Bio::DB::HIV::HIVQueryHelper>.
           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]



GenBank accession manipulation methods

    get_accessions



 Title   : get_accessions
 Usage   : $hiv_query->get_accessions()
 Function: Return an array of GenBank accessions associated with these
           sequences (available only after a query is subjected to a
           full run (i.e., when $RUN_OPTION == 2)
 Example :
 Returns : array of gb accession numbers, or () if none found for this query
 Args    : none



    get_accessions_by_ids



 Title   : get_accessions_by_ids (or ..._by_id)
 Usage   : $hiv_query->get_accessions_by_ids(@ids)
 Function: Return an array of GenBank accessions associated with these
           LANL ids (available only after a query is subjected to a
           full run (i.e., when $RUN_OPTION == 2)
 Example :
 Returns : array of gb accession numbers, or () if none found for this query
 Args    : none



Query control methods

    _do_query



 Title   : _do_query
 Usage   : $hiv_query->_do_query or $hiv_query->_do_query($run_level)
 Function: Execute the query according to argument or $RUN_OPTION
           and set _RUN_LEVEL
           extent of query reflects the value of argument
            0 : validate only (no HTTP action)
            1 : return sequence count only
            2 : return sequence ids (full query, returns with annotations)
           noop if current _RUN_LEVEL of query is >= argument or $RUN_OPTION,
 Example :
 Returns : actual _RUN_LEVEL (0, 1, or 2) achieved
 Args    : desired run level (optional, global $RUN_OPTION is default)



    _reset



 Title   : _reset
 Usage   : $hiv_query->_reset
 Function: Resets query storage, count, and ids, while retaining session id,
           original query string, and db schema
 Example :
 Returns : void
 Args    : none



    _session_id



 Title   : _session_id
 Usage   : $hiv_query->_session_id($newval)
 Function: Get/set HIV db session id (initialized in _do_lanl_request)
 Example :
 Returns : value of _session_id (a scalar)
 Args    : on set, new value (a scalar or undef, optional)



    _run_level



 Title   : _run_level
 Usage   : $obj->_run_level($newval)
 Function: returns the level at which the query has so far been run
 Example :
 Returns : value of _run_level (a scalar)
 Args    : on set, new value (a scalar or undef, optional)



    _run_option



 Title   : _run_option
 Usage   : $hiv_query->_run_option($newval)
 Function: Get/set HIV db query run option (see _do_query for values)
 Example :
 Returns : value of _run_option (a scalar)
 Args    : on set, new value (a scalar or undef, optional)



    _ua_hash



 Title   : _ua_hash
 Usage   : $obj->_ua_hash($newval)
 Function:
 Example :
 Returns : value of _ua_hash (a scalar)
 Args    : on set, new value (a scalar or undef, optional)



Internals

    add_id



 Title   : add_id
 Usage   : $hiv_query->add_id($id)
 Function: Add new id to ids
 Example :
 Returns : the new id
 Args    : a sequence id



    map_db



 Title   : map_db
 Usage   : $obj->map_db($newval)
 Function:
 Example :
 Returns : value of map_db (a scalar)
 Args    : on set, new value (a scalar or undef, optional)



    make_search_if



 Title   : make_search_if
 Usage   : $obj->make_search_if($newval)
 Function:
 Example :
 Returns : value of make_search_if (a scalar)
 Args    : on set, new value (a scalar or undef, optional)



    search_



 Title   : search_
 Usage   : $obj->search_($newval)
 Function:
 Example :
 Returns : value of search_ (a scalar)
 Args    : on set, new value (a scalar or undef, optional)



    _map_db_uri



 Title   : _map_db_uri
 Usage   :
 Function: return the full map_db uri ("Database Map")
 Example :
 Returns : scalar string
 Args    : none



    _make_search_if_uri



 Title   : _make_search_if_uri
 Usage   :
 Function: return the full make_search_if uri ("Make Search Interface")
 Example :
 Returns : scalar string
 Args    : none



    _search_uri



 Title   : _search_uri
 Usage   :
 Function: return the full search cgi uri ("Search Database")
 Example :
 Returns : scalar string
 Args    : none



    _schema_file



 Title   : _schema_file
 Usage   : $hiv_query->_schema_file($newval)
 Function:
 Example :
 Returns : value of _schema_file (an XML string or filename)
 Args    : on set, new value (an XML string or filename, or undef, optional)



    _schema



 Title   : _schema
 Usage   : $hiv_query->_schema($newVal)
 Function:
 Example :
 Returns : value of _schema (an HIVSchema object in package
           L<Bio::DB::HIV::HIVQueryHelper>)
 Args    : none (field set directly in new())



    _lanl_query



 Title   : _lanl_query
 Usage   : $hiv_query->_lanl_query(\@query_parms)
 Function: pushes \@query_parms onto @{$self->{_lanl_query}
 Example :
 Returns : value of _lanl_query (an arrayref)
 Args    : on set, new value (an arrayref or undef, optional)



    _lanl_response



 Title   : _lanl_response
 Usage   : $hiv_query->_lanl_response($response)
 Function: pushes $response onto @{$hiv_query->{_lanl_response}}
 Example :
 Returns : value of _lanl_response (an arrayref of HTTP::Response objects)
 Args    : on set, new value (an HTTP::Response object or undef, optional)



    _create_lanl_query



 Title   : _create_lanl_query
 Usage   : $hiv_query->_create_lanl_query()
 Function: validate query hash or string, prepare for _do_lanl_request
 Example :
 Returns : 1 if successful; throws exception on invalid query
 Args    :



    _do_lanl_request



 Title   : _do_lanl_request
 Usage   : $hiv_query->_do_lanl_request()
 Function: Perform search request on _create_lanl_query-validated query
 Example :
 Returns : 1 if successful
 Args    :



    _parse_lanl_response



 Title   : _parse_lanl_response
 Usage   : $hiv_query->_parse_lanl_response()
 Function: Parse the tab-separated-value response obtained by _do_lanl_request
           for sequence ids, accessions, and annotations
 Example :
 Returns : 1 if successful
 Args    :



    _parse_query_string



 Title   : _parse_query_string
 Usage   : $hiv_query->_parse_query_string($str)
 Function: Parses a query string using query language emulator QRY
         : in L<Bio::DB::Query::HIVQueryHelper>
 Example :
 Returns : arrayref of hash structures suitable for passing to _create_lanl_query
 Args    : a string scalar



Dude, sorry-

    _sorry



 Title   : _sorry
 Usage   : $hiv_query->_sorry("-president=>Powell")
 Function: Throws an exception for unsupported option or parameter
 Example :
 Returns :
 Args    : scalar string



Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 BIO::DB::QUERY::HIVQUERY (3) 2016-04-05

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.