Linux Certif

Toute la documentation sur la certification Linux LPI

Bio::Tools::EUtilities.3pm

NAME

Bio::Tools::EUtilities - NCBI eutil XML parsers

SYNOPSIS

   # from file or fh
 
     my $parser = Bio::Tools::EUtilities->new(
                                        -eutil    => 'einfo',
                                        -file     => 'output.xml'
                                         );
 
   # or HTTP::Response object...
 
     my $parser = Bio::Tools::EUtilities->new(
                                        -eutil => 'esearch',
                                        -response => $response
                                         );
 
   # esearch, esummary, elink
 
     @ids = $parser->get_ids(); # returns array or array ref of IDs
 
   # egquery, espell
 
     $term = $parser->get_term(); # returns array or array ref of IDs
 
   # elink, einfo
 
     $db = $parser->get_database(); # returns database
 
   # Query-related methods (esearch, egquery, espell data)
   # eutil data centered on use of search terms
 
     my $ct = $parser->get_count; # uses optional database for egquery count
     my $translation = $parser->get_count;
 
     my $corrected = $parser->get_corrected_query; # espell
 
     while (my $gquery = $parser->next_GlobalQuery) {
        # iterates through egquery data
     }
 
   # Info-related methods (einfo data)
   # database-related information
 
     my $desc = $parser->get_description;
     my $update = $parser->get_last_update;
     my $nm = $parser->get_menu_name;
     my $ct = $parser->get_record_count;
 
     while (my $field = $parser->next_FieldInfo) {
         # ...
     }
     while (my $field = $parser->next_LinkInfo) {
         # ...
     }
 
   # History methods (epost data, some data returned from elink)
   # data which enables one to retrieve and query against user-stored
   # information on the NCBI server
 
     while (my $cookie = $parser->next_History) {
         # ...
     }
 
     my @hists = $parser->get_Histories;
 
   # Bio::Tools::EUtilities::Summary (esummary data)
   # information on a specific database record
 
     # retrieve nested docsum data
     while (my $docsum = $parser->next_DocSum) {
         print "ID:",$docsum->get_ids,"\n";
         while (my $item = $docsum->next_Item) {
             # do stuff here...
             while (my $listitem = $docsum->next_ListItem) {
                 # do stuff here...
                 while (my $listitem = $docsum->next_Structure) {
                     # do stuff here...
                 }
             }
         }
     }
 
     # retrieve flattened item list per DocSum
     while (my $docsum = $parser->next_DocSum) {
         my @items = $docsum->get_all_DocSum_Items;
     }
 
 

DESCRIPTION

Parses NCBI eutils XML output for retrieving IDs and other information. Part of the BioPerl EUtilities system.

This is a general parser for eutils XML; data from efetch is NOT parsed (this requires separate format-dependent parsers). All other XML for eutils is parsed. These modules can be used independently of Bio::DB::EUtilities and Bio::Tools::EUtilities::EUtilParameters; if used in this way, only data present in the XML will be parsed out (other bits are retrieved from a passed in Bio::Tools::EUtilities::EUtilParameters instance used while querying the database)

TODO

This module is largely complete. However there are a few holes which will eventually be filled in. TranslationSets from esearch are not currently parsed, for instance.

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 one of the Bioperl mailing lists. Your participation is much appreciated.

   bioperl-l@lists.open-bio.org               - General discussion
   http://www.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 the bugs and their resolution. Bug reports can be submitted via the web.

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

AUTHOR

Email cjfields at bioperl dot org

APPENDIX

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

Constructor methods

new

  Title    : new
  Usage    : my $parser = Bio::Tools::EUtilities->new(-file => 'my.xml',
                                                     -eutil => 'esearch');
  Function : create Bio::Tools::EUtilities instance
  Returns  : new Bio::Tools::EUtilities instance
  Args     : -file/-fh - File or filehandle
             -eutil    - eutil parser to use (supports all but efetch)
             -response - HTTP::Response object (optional)
 
 

Bio::Tools::EUtilities methods

cache_response

  Title    : cache_response
  Usage    : $parser->cache_response(1)
  Function : sets flag to cache response object (off by default)
  Returns  : value eval'ing to TRUE or FALSE
  Args     : value eval'ing to TRUE or FALSE
  Note     : must be set prior to any parsing run
 
 

response

  Title    : response
  Usage    : my $response = $parser->response;
  Function : Get/Set HTTP::Response object
  Returns  : HTTP::Response
  Args     : HTTP::Response
  Note     : to prevent object from destruction set cache_response() to TRUE
 
 

parameter_base

  Title    : parameter_base
  Usage    : my $response = $parser->parameter_base;
  Function : Get/Set Bio::ParameterBaseI object (should be Bio::Tools::EUtilities::EUtilParameters)
  Returns  : Bio::Tools::EUtilities::EUtilParameters || undef
  Args     : (optional) Bio::Tools::EUtilities::EUtilParameters
  Note     : If this object is present, it may be used as a last resort for
             some data values if parsed XML does not contain said values (for
             instance, database, term, IDs, etc).
 
 

data_parsed

  Title    : data_parsed
  Usage    : if ($parser->data_parsed) {...}
  Function : returns TRUE if data has been parsed
  Returns  : value eval'ing to TRUE or FALSE
  Args     : none (set within parser)
  Note     : mainly internal method (set in case user wants to check
             whether parser is exhausted).
 
 

is_lazy

  Title    : is_lazy
  Usage    : if ($parser->is_lazy) {...}
  Function : returns TRUE if parser is set to lazy parsing mode
             (only affects elink/esummary)
  Returns  : Boolean
  Args     : none
  Note     : Permanently set in constructor.  Still highly experimental.
             Don't stare directly at happy fun ball...
 
 

parse_data

  Title    : parse_data
  Usage    : $parser->parse_data
  Function : direct call to parse data; normally implicitly called
  Returns  : none
  Args     : none
 
 

to_string

  Title    : to_string
  Usage    : $foo->to_string()
  Function : converts current object to string
  Returns  : none
  Args     : (optional) simple data for text formatting
  Note     : Implemented in plugins
 
 

print_all

  Title    : print_all
  Usage    : $info->print_all();
             $info->print_all(-fh => $fh, -cb => $coderef);
  Function : prints (dumps) all data in parser.  Unless a coderef is supplied,
             this just dumps the parser-specific to_string method to either a
             file/fh or STDOUT
  Returns  : none
  Args     : [optional]
            -file : file to print to
            -fh   : filehandle to print to (cannot be used concurrently with file)
            -cb   : coderef to use in place of default print method.  This is
                    passed in the parser object 
            -wrap : number of columns to wrap default text output to (def = 80)
  Notes    : only applicable for einfo.  If -file or -fh are not defined,
             prints to STDOUT
 
 

Bio::Tools::EUtilities::EUtilDataI methods

eutil

  Title    : eutil
  Usage    : $eutil->$foo->eutil
  Function : Get/Set eutil
  Returns  : string
  Args     : string (eutil)
  Throws   : on invalid eutil
 
 

datatype

  Title    : datatype
  Usage    : $type = $foo->datatype;
  Function : Get/Set data object type
  Returns  : string
  Args     : string
 
 

Methods useful for multiple eutils

get_ids

  Title    : get_ids
  Usage    : my @ids = $parser->get_ids
  Function : returns array of requested IDs (see Notes for more specifics)
  Returns  : array
  Args     : [conditional] not required except when running elink queries against
             multiple databases. In case of the latter, the database name is
             optional but recommended when retrieving IDs as the ID list will
             be globbed together. In such cases, if a db name isn't provided a
             warning is issued as a reminder.
  Notes    : esearch    : returned ID list
             elink      : returned ID list (see Args above for caveats)
             all others : from parameter_base->id or undef
 
 

get_database

  Title    : get_database
  Usage    : my $db = $info->get_database;
  Function : returns single database name (eutil-compatible).  This is the
             queried database. For most eutils this is straightforward. For
             elinks (which have 'db' and 'dbfrom') this is db/dbto, for egquery,
             it is the first db in the list (you probably want get_databases
             instead)
  Returns  : string
  Args     : none
  Notes    : egquery    : first db in the query (you probably want get_databases)
             einfo      : the queried database
             espell     : the queried database
             all others : from parameter_base->db or undef
 
 

get_db (alias for get_database)

get_databases

  Title    : get_databases
  Usage    : my @dbs = $parser->get_databases
  Function : returns list of databases 
  Returns  : array of strings
  Args     : none
  Notes    : This is guaranteed to return a list of databases. For a single
             database use the convenience method get_db/get_database
             
             egquery    : list of all databases in the query
             einfo      : the queried database, or the available databases
             espell     : the queried database
             elink      : collected from each LinkSet
             all others : from parameter_base->db or undef
 
 

get_dbs (alias for get_databases)

next_History

  Title    : next_History
  Usage    : while (my $hist=$parser->next_History) {...}
  Function : returns next HistoryI (if present).
  Returns  : Bio::Tools::EUtilities::HistoryI (Cookie or LinkSet)
  Args     : none
  Note     : esearch, epost, and elink are all capable of returning data which
             indicates search results (in the form of UIDs) is stored on the
             remote server. Access to this data is wrapped up in simple interface
             (HistoryI), which is implemented in two classes:
             Bio::DB::EUtilities::History (the simplest) and
             Bio::DB::EUtilities::LinkSet. In general, calls to epost and esearch
             will only return a single HistoryI object (formerly known as a
             Cookie), but calls to elink can generate many depending on the
             number of IDs, the correspondence, etc. Hence this iterator, which
             allows one to retrieve said data one piece at a time.
 
 

next_cookie (alias for next_History)

get_Histories

  Title    : get_Histories
  Usage    : my @hists = $parser->get_Histories
  Function : returns list of HistoryI objects.
  Returns  : list of Bio::Tools::EUtilities::HistoryI (History or LinkSet)
  Args     : none
 
 

Query-related methods

get_count

  Title    : get_count
  Usage    : my $ct = $parser->get_count
  Function : returns the count (hits for a search)
  Returns  : integer
  Args     : [CONDITIONAL] string with database name - used to retrieve
             count from specific database when using egquery
  Notes    : egquery    : count for specified database (specified above)
             esearch    : count for last search
             all others : undef
 
 

get_term

  Title    : get_term
  Usage    : $st = $qd->get_term;
  Function : retrieve the term for the global search
  Returns  : string
  Args     : none
  Notes    : egquery    : search term
             espell     : search term
             esearch    : from parameter_base->term or undef
             all others : undef
 
 

get_translation_from

  Title   : get_translation_from
  Usage   : $string = $qd->get_translation_from();
  Function: portion of the original query replaced with translated_to()
  Returns : string
  Args    : none
  Note    : only applicable for esearch
 
 

get_translation_to

  Title   : get_translation_to
  Usage   : $string = $qd->get_translation_to();
  Function: replaced string used in place of the original query term in translation_from()
  Returns : string
  Args    : none
  Note    : only applicable for esearch
 
 

get_retstart

  Title    : get_retstart
  Usage    : $start = $qd->get_retstart();
  Function : retstart setting for the query (either set or NCBI default)
  Returns  : Integer
  Args     : none
  Notes    : esearch    : retstart
             esummary   : retstart
             all others : from parameter_base->retstart or undef
 
 

get_retmax

  Title    : get_retmax
  Usage    : $max = $qd->get_retmax();
  Function : retmax setting for the query (either set or NCBI default)
  Returns  : Integer
  Args     : none
  Notes    : esearch    : retmax
             esummary   : retmax
             all others : from parameter_base->retmax or undef
 
 

get_query_translation

  Title   : get_query_translation
  Usage   : $string = $qd->get_query_translation();
  Function: returns the translated query used for the search (if any)
  Returns : string
  Args    : none
  Notes   : only applicable for esearch.  This is the actual term used for
            esearch.
 
 

get_corrected_query

  Title    : get_corrected_query
  Usage    : my $cor = $eutil->get_corrected_query;
  Function : retrieves the corrected query when using espell
  Returns  : string
  Args     : none
  Notes    : only applicable for espell.
 
 

get_replaced_terms

  Title    : get_replaced_terms
  Usage    : my $term = $eutil->get_replaced_term
  Function : returns array of strings replaced in the query
  Returns  : string 
  Args     : none
  Notes    : only applicable for espell
 
 

next_GlobalQuery

  Title    : next_GlobalQuery
  Usage    : while (my $query = $eutil->next_GlobalQuery) {...}
  Function : iterates through the queries returned from an egquery search
  Returns  : GlobalQuery object
  Args     : none
  Notes    : only applicable for egquery
 
 

get_GlobalQueries

  Title    : get_GlobalQueries
  Usage    : @queries = $eutil->get_GlobalQueries
  Function : returns list of GlobalQuery objects
  Returns  : array of GlobalQuery objects
  Args     : none
  Notes    : only applicable for egquery
 
 

print_GlobalQueries

  Title    : print_GlobalQueries
  Usage    : $docsum->print_GlobalQueries();
             $docsum->print_GlobalQueries(-fh => $fh, -callback => $coderef);
  Function : prints item data for all global queries.  The default printing
             method is each item per DocSum is printed with relevant values if
             present in a simple table using Text::Wrap. 
  Returns  : none
  Args     : [optional]
            -file : file to print to
            -fh   : filehandle to print to (cannot be used concurrently with file)
            -cb   : coderef to use in place of default print method.  This is passed
                    in a GlobalQuery object;
            -wrap : number of columns to wrap default text output to (def = 80)
  Notes    : only applicable for esummary.  If -file or -fh are not defined,
             prints to STDOUT
 
 

Summary-related methods

next_DocSum

  Title    : next_DocSum
  Usage    : while (my $ds = $esum->next_DocSum) {...}
  Function : iterate through DocSum instances
  Returns  : single Bio::Tools::EUtilities::Summary::DocSum
  Args     : none yet
  Notes    : only applicable for esummary
 
 

get_DocSums

  Title    : get_DocSums
  Usage    : my @docsums = $esum->get_DocSums
  Function : retrieve a list of DocSum instances
  Returns  : array of Bio::Tools::EUtilities::Summary::DocSum
  Args     : none
  Notes    : only applicable for esummary
 
 

print_DocSums

  Title    : print_DocSums
  Usage    : $docsum->print_DocSums();
             $docsum->print_DocSums(-fh => $fh, -cb => $coderef);
  Function : prints item data for all docsums.  The default data is generated
             via DocSum::to_string
  Returns  : none
  Args     : [optional]
            -file : file to print to
            -fh   : filehandle to print to (cannot be used concurrently with file)
            -cb   : coderef to use in place of default print method.  This is passed
                    in a DocSum object
            -wrap : number of columns to wrap default text output to (def = 80)
  Notes    : only applicable for esummary.  If -file or -fh are not defined,
             prints to STDOUT
 
 

Info-related methods

get_available_databases

  Title    : get_available_databases
  Usage    : my @dbs = $info->get_available_databases
  Function : returns list of available eutil-compatible database names
  Returns  : Array of strings 
  Args     : none
  Notes    : only applicable for einfo.
 
 

get_record_count

  Title    : get_record_count
  Usage    : my $ct = $eutil->get_record_count;
  Function : returns database record count
  Returns  : integer
  Args     : none
  Notes    : only applicable for einfo.
 
 

get_last_update

  Title    : get_last_update
  Usage    : my $time = $info->get_last_update;
  Function : returns string containing time/date stamp for last database update
  Returns  : integer
  Args     : none
  Notes    : only applicable for einfo.
 
 

get_menu_name

  Title    : get_menu_name
  Usage    : my $nm = $info->get_menu_name;
  Function : returns string of database menu name
  Returns  : string
  Args     : none
  Notes    : only applicable for einfo.
 
 

get_description

  Title    : get_description
  Usage    : my $desc = $info->get_description;
  Function : returns database description
  Returns  : string
  Args     : none
  Notes    : only applicable for einfo.
 
 

next_FieldInfo

  Title    : next_FieldInfo
  Usage    : while (my $field = $info->next_FieldInfo) {...}
  Function : iterate through FieldInfo objects
  Returns  : Field object
  Args     : none
  Notes    : only applicable for einfo. Uses callback() for filtering if defined
             for 'fields'
 
 

get_FieldInfo

  Title    : get_FieldInfo
  Usage    : my @fields = $info->get_FieldInfo;
  Function : returns list of FieldInfo objects
  Returns  : array (FieldInfo objects)
  Args     : none
  Notes    : only applicable for einfo.
 
 

next_LinkInfo

  Title    : next_LinkInfo
  Usage    : while (my $link = $info->next_LinkInfo) {...}
  Function : iterate through LinkInfo objects
  Returns  : LinkInfo object
  Args     : none
  Notes    : only applicable for einfo.  Uses callback() for filtering if defined
             for 'linkinfo'
 
 

get_LinkInfo

  Title    : get_LinkInfo
  Usage    : my @links = $info->get_LinkInfo;
  Function : returns list of LinkInfo objects
  Returns  : array (LinkInfo objects)
  Args     : none
  Notes    : only applicable for einfo.
 
 

print_FieldInfo

  Title    : print_FieldInfo
  Usage    : $info->print_FieldInfo();
             $info->print_FieldInfo(-fh => $fh, -cb => $coderef);
  Function : prints link data for each FieldInfo object. The default is generated
             via FieldInfo::to_string
  Returns  : none
  Args     : [optional]
            -file : file to print to
            -fh   : filehandle to print to (cannot be used concurrently with file)
            -cb   : coderef to use in place of default print method.  This is
                    passed in a FieldInfo object
            -wrap : number of columns to wrap default text output to (def = 80)
  Notes    : only applicable for einfo.  If -file or -fh are not defined,
             prints to STDOUT
 
 

print_LinkInfo

  Title    : print_LinkInfo
  Usage    : $info->print_LinkInfo();
             $info->print_LinkInfo(-fh => $fh, -cb => $coderef);
  Function : prints link data for each LinkInfo object. The default is generated
             via LinkInfo::to_string
  Returns  : none
  Args     : [optional]
            -file : file to print to
            -fh   : filehandle to print to (cannot be used concurrently with file)
            -cb   : coderef to use in place of default print method.  This is passed
                    in a LinkInfo object
            -wrap : number of columns to wrap default text output to (def = 80)
  Notes    : only applicable for einfo.  If -file or -fh are not defined,
             prints to STDOUT
 
 

Bio::Tools::EUtilities::Link-related methods

next_LinkSet

  Title    : next_LinkSet
  Usage    : while (my $ls = $eutil->next_LinkSet {...}
  Function : iterate through LinkSet objects
  Returns  : LinkSet object
  Args     : none
  Notes    : only applicable for elink.  Uses callback() for filtering if defined
             for 'linksets'
 
 

get_LinkSets

  Title    : get_LinkSets
  Usage    : my @links = $info->get_LinkSets;
  Function : returns list of LinkSets objects
  Returns  : array (LinkSet objects)
  Args     : none
  Notes    : only applicable for elink.
 
 

print_LinkSets

  Title    : print_LinkSets
  Usage    : $info->print_LinkSets();
             $info->print_LinkSets(-fh => $fh, -cb => $coderef);
  Function : prints link data for each LinkSet object. The default is generated
             via LinkSet::to_string
  Returns  : none
  Args     : [optional]
            -file : file to print to
            -fh   : filehandle to print to (cannot be used concurrently with file)
            -cb   : coderef to use in place of default print method.  This is passed
                    in a LinkSet object
            -wrap : number of columns to wrap default text output to (def = 80)
  Notes    : only applicable for einfo.  If -file or -fh are not defined,
             prints to STDOUT
 
 

get_linked_databases

  Title    : get_linked_databases
  Usage    : my @dbs = $eutil->get_linked_databases
  Function : returns list of databases linked to in linksets
  Returns  : array of databases
  Args     : none
  Notes    : only applicable for elink.  Now defers to get_databases.
 
 

Iterator- and callback-related methods

rewind

  Title    : rewind
  Usage    : $esum->rewind()
             $esum->rewind('recursive')
  Function : retrieve a list of DocSum instances
  Returns  : array of Bio::Tools::EUtilities::Summary::DocSum
  Args     : [optional] Scalar; string ('all') to reset all iterators, or string
             describing the specific main object iterator to reset. The following
             are recognized (case-insensitive):
 
             'all' - rewind all objects and also recursively resets nested object interators
                     (such as LinkSets and DocSums).
             'globalqueries' - GlobalQuery objects
             'fieldinfo' or 'fieldinfos' - FieldInfo objects
             'linkinfo' or 'linkinfos' - LinkInfo objects in this layer
             'linksets' - LinkSet objects
             'docsums' - DocSum objects
             'histories' - HistoryI objects (Cookies, LinkSets)
 
 

generate_iterator

  Title    : generate_iterator
  Usage    : my $coderef = $esum->generate_iterator('linkinfo')
  Function : generates an iterator (code reference) which iterates through
             the relevant object indicated by the args
  Returns  : code reference
  Args     : [REQUIRED] Scalar; string describing the specific object to iterate.
             The following are currently recognized (case-insensitive):
 
             'globalqueries'
             'fieldinfo' or 'fieldinfos' (the latter sounds clumsy, but I alias it JIC)
             'linkinfo' or 'linkinfos' (the latter sounds clumsy, but I alias it JIC)
             'linksets'
             'docsums'
             'histories'
 
  Note     : This function generates a simple coderef that one can use
             independently of the various next_* functions (in fact, the next_*
             functions use lazily created iterators generated via this method,
             while rewind() merely deletes them so they can be regenerated on the
             next call).
 
             A callback specified using callback() will be used to filter objects
             for any generated iterator. This behaviour is implemented for both
             normal and lazy iterator types and is the default. If you don't want
             this, make sure to reset any previously set callbacks via
             reset_callback() (which just deletes the code ref).  Note that setting
             callback() also changes the behavior of the next_* functions as the
             iterators are generated here (as described above); this is a feature
             and not a bug.
 
             'Lazy' iterators are considered an experimental feature and may be
             modified in the future. A 'lazy' iterator, which loops through and
             returns objects as they are created (instead of creating all data
             instances up front, then iterating through) is returned if the
             parser is set to 'lazy' mode. This mode is only present for elink
             and esummary output as they are the two formats parsed which can
             generate potentially thousands of individual objects (note efetch
             isn't parsed, so isn't counted). Use of rewind() with these
             iterators is not supported for the time being as we can't guarantee
             you can rewind(), as this depends on whether the data source is
             seek()able and thus 'rewindable'. We will add rewind() support at a
             later time which will work for 'seekable' data or possibly cached
             objects via Storable or BDB.
 
 

callback

  Title    : callback
  Usage    : $parser->callback(sub {$_[0]->get_database eq 'protein'});
  Function : Get/set callback code ref used to filter returned data objects
  Returns  : code ref if previously set
  Args     : single argument:
             code ref - evaluates a passed object and returns true or false value
                        (used in iterators)
             'reset' - string, resets the iterator.
             returns upon any other args