Provided by: libbio-eutilities-perl_1.77-1_all 
NAME
Bio::Tools::EUtilities - NCBI eutil XML parsers.
VERSION
version 1.77
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.
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_terms
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
iterators (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
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
https://bioperl.org/Support.html - 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/bio-eutilities/issues
AUTHOR
Chris Fields <cjfields@bioperl.org>
COPYRIGHT
This software is copyright (c) 2006-2013 by Chris Fields.
This software is available under the same terms as the perl 5 programming language system
itself.