Bio::T...lities(3pm)

📦
version 1.77 · 4 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

🌸 Bio::Tools::EUtilities 💅

okay bestie, welcome to the Bio::Tools::EUtilities page from the User Contributed Perl Documentation section — it's a 3pm manual, it's giving NCBI eutil XML parsers, and honestly? she's iconic.

VERSION — version 1.77 ✨

🦋 SYNOPSIS

no cap, here's the whole vibe in code:

  # 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 ✨

She parses NCBI eutils XML output so you can pull out IDs and other info. Part of the BioPerl EUtilities system, obvi. 💖

So like, this is a general parser for eutils XML. But heads up bestie: data from efetch is NOT parsed — that one needs its own separate format-dependent parsers, no shortcuts. Every other eutils XML? Parsed, slay. 🌈

These modules can absolutely be used independently of Bio::DB::EUtilities and Bio::Tools::EUtilities::EUtilParameters. And if you do run them solo, then only the data that's actually present in the XML gets parsed out — the other bits come from a passed-in Bio::Tools::EUtilities::EUtilParameters instance that was used while querying the database. iykyk 🫶

💀 TODO

ngl, this module is largely complete, but there are a few holes that'll eventually get filled in. TranslationSets from esearch aren't currently parsed, for instance. that's the tea 🍓

🎀 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
bestie, listen: this has to be set before any parsing run. no setting it after, that's not the move. 💅

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...
not me warning you: "Still highly experimental. Don't stare directly at happy fun ball..." 😭 that's literally a quote, respect it.

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
 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
lowkey important: the Args here are conditional. Only elink queries against multiple databases need a db name, and even then it's optional-but-recommended, because otherwise the ID list gets globbed together. No db name = a warning gets issued as a lil reminder. 💜

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)

that's it, that's the whole subsection. an alias. she's a shortcut, and we respect her. 🎀

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)

another alias, another slay. ✨

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.

yes bestie, the old name lives on. 💅

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

🌸 okay that's part one, more is coming — don't go anywhere 💖

okay these are all the little getters that pull info out of your query object, bestie. each one tells you which eutil it actually works for, so read the Notes, fr fr.

🌸 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
  • 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

this is where esummary stops being mysterious and starts handing you whole objects, periodt.

💜 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
  • 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

einfo girlies rise up, this is your moment 💅. all of these are only applicable for einfo, every single one, no cap.

⭐ 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.
  • 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
  • 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

🔗 next_LinkSet

  • Title: next_LinkSet
  • Usage: while (my $ls = $eutil->next_LinkSet {...}
  • Function: iterates through LinkSet objects, one at a time, bestie
  • Returns: a LinkSet object
  • Args: none
  • Notes: only applicable for elink. Uses callback() for filtering if one is defined for 'linksets'

🔗 get_LinkSets

  • Title: get_LinkSets
  • Usage: my @links = $info->get_LinkSets;
  • Function: returns a list of LinkSets objects
  • Returns: array (of LinkSet objects)
  • Args: none
  • Notes: only applicable for elink.
  • 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 a list of databases linked to in linksets
  • Returns: array of databases
  • Args: none
  • Notes: only applicable for elink. Now defers to get_databases.

🌸 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 a string describing the specific main object iterator to reset. The following are recognized (case-insensitive):
    • 'all' — rewinds 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 (a 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 a 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 a 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>

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.

okay bestie that's a wrap, fr fr 💖 this page is from perl v5.40.0, dated 2025-01-27, and it's the Bio::T...lities(3pm) manual you just devoured like the icon you are ✨ go forth and iterate, periodt 🦋

📦 where this page comes from