Bio::DB::EUtilities(3pm)

Bio::DB::EUtilities3pm

Webagent which interacts with and retrieves data from ncbi's eutils.

Usage

  my $eutil = Bio::DB::EUtilities->new(
    -eutil      => 'esearch',
    -term       => 'BRCA1',
    -db         => 'pubmed',
    -retmax     => 10000,
    -email      => '[email protected]'); # please use your real email
  # eutil => any of esearch, esummary, elink
  @ids = $eutil->get_ids(); # returns array or array ref of IDs
  # eutil => any of egquery, espell
  $term = $eutil->get_term(); # returns array or array ref of IDs
  # eutil => any of elink, einfo
  $db = $eutil->get_database(); # returns database
  # Query-related methods (esearch, egquery, espell data)
  # eutil data centered on use of search terms
  my $ct = $eutil->get_count; # uses optional database for egquery count
  my $translation = $eutil->get_count;
  my $corrected = $eutil->get_corrected_query; # espell
  while (my $gquery = $eutil->next_GlobalQuery) {
     # iterates through egquery data
  }
  # Info-related methods (einfo data)
  # database-related information
  my $desc = $eutil->get_description;
  my $update = $eutil->get_last_update;
  my $nm = $eutil->get_menu_name;
  my $ct = $eutil->get_record_count;
  while (my $field = $eutil->next_FieldInfo) {
      # ...
  }
  while (my $field = $eutil->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 = $eutil->next_History) {
      # ...
  }
  my @hists = $eutil->get_Histories;
  # Bio::Tools::EUtilities::Summary (esummary data)
  # information on a specific database record
  # retrieve nested docsum data
  while (my $docsum = $eutil->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 = $eutil->next_DocSum) {
     my @items = $docsum->get_all_DocSum_Items;
  }

Version

version 1.77

Overview

This is a general webagent which posts and retrieves data to NCBI's eUtils service using their CGI interface. A separate project, currently present in BioPerl-Run, utilizes the SOAP-based interface for eUtils.

A full explanation of the eUtils interfaces are not possible within this short module; please see the BioPerl wiki HOWTO for more details.

Methods

Todo

•

Finish documentation

HOWTOs (both standard and Cookbook).

•

Cookbook tests

Set up dev-only tests for Cookbook examples to make sure they are consistently updated.

•

API

Mark Jensen has written up the SOAP-based eUtil modules, maybe we should coalesce around a consistent API between the two (they are close).

•

Carryover of parameters

Maybe add a default but configurable list of parameters that can be carried over between calls.

•

Make setting certain parameters consistent

Setting history is a bit inconsistent, so maybe use a common alias for this?

•

Moosify?

Not necessary, but it might make things easier and more maintainable in the long run.

Bio::DB::GenericWebAgent methods

GenericWebDBI methods

parameter_base

 Title   : parameter_base
 Usage   : $dbi->parameter_base($pobj);
 Function: Get/Set Bio::ParameterBaseI.
 Returns : Bio::ParameterBaseI object
 Args    : Bio::ParameterBaseI object

ua

 Title   : ua
 Usage   : $dbi->ua;
 Function: Get/Set LWP::UserAgent.
 Returns : LWP::UserAgent
 Args    : LWP::UserAgent

get_Response

 Title   : get_Response
 Usage   : $agent->get_Response;
 Function: Get the HTTP::Response object by passing it an HTTP::Request (generated from
           Bio::ParameterBaseI implementation).
 Returns : HTTP::Response object or data if callback is used
 Args    : (optional)
           -cache_response - flag to cache HTTP::Response object;
                             Default is 1 (TRUE, caching ON)
           These are passed on to LWP::UserAgent::request() if stipulated
           -cb     - use a LWP::UserAgent-compliant callback
           -file   - dumps the response to a file (handy for large responses)
                     Note: can't use file and callback at the same time
           -read_size_hint - bytes of content to read in at a time to pass to callback
 Note    : Caching and parameter checking are set

delay

 Title   : delay
 Usage   : $secs = $self->delay([$secs])
 Function: get/set number of seconds to delay between fetches
 Returns : number of seconds to delay
 Args    : new value

NOTE: the default is to use the value specified by delay_policy(). This can be overridden by calling this method.

Bio::Tools::EUtilities::EUtilParameters-delegating methods

This is only a subset of parameters available from Bio::Tools::EUtilities::EUtilParameters (the ones deemed absolutely necessary). All others are available by calling 'parameter_base->method' when needed.

set_parameters

 Title   : set_parameters
 Usage   : $pobj->set_parameters(@params);
 Function: sets the NCBI parameters listed in the hash or array
 Returns : None
 Args    : [optional] hash or array of parameter/values.
 Note    : This sets any parameter (i.e. doesn't screen them).  In addition to
           regular eutil-specific parameters, you can set the following:
           -eutil    - the eUtil to be used (default 'efetch')
           -history  - pass a HistoryI-implementing object, which
                       sets the WebEnv, query_key, and possibly db and linkname
                       (the latter two only for LinkSets)
           -correspondence - Boolean flag, set to TRUE or FALSE; indicates how
                       IDs are to be added together for elink request where
                       ID correspondence might be needed
                       (default 0)

reset_parameters

 Title   : reset_parameters
 Usage   : resets values
 Function: resets parameters to either undef or value in passed hash
 Returns : none
 Args    : [optional] hash of parameter-value pairs
 Note    : this also resets eutil(), correspondence(), and the history and request
           cache

available_parameters

 Title   : available_parameters
 Usage   : @params = $pobj->available_parameters()
 Function: Returns a list of the available parameters
 Returns : Array of available parameters (no values)
 Args    : [optional] A string; either eutil name (for returning eutil-specific
           parameters) or 'history' (for those parameters allowed when retrieving
           data stored on the remote server using a 'History' object).

get_parameters

 Title   : get_parameters
 Usage   : @params = $pobj->get_parameters;
           %params = $pobj->get_parameters;
 Function: Returns list of key/value pairs, parameter => value
 Returns : Flattened list of key-value pairs. All key-value pairs returned,
           though subsets can be returned based on the '-type' parameter.
           Data passed as an array ref are returned based on whether the
           '-join_id' flag is set (default is the same array ref).
 Args    : -type : the eutil name or 'history', for returning a subset of
                parameters (Default: returns all)
           -join_ids : Boolean; join IDs based on correspondence (Default: no join)

get_parameter_values

 Title   : get_parameter_values
 Usage   : @vals = $factory->get_parameter_value('id'); # always get array
 Function: Returns the specific parameter values.
 Returns : For consistency returns a list of values for this parameter.  If only
           one is expected, use:
           ($val) = $factory->get_parameter_value('id');
 Args    : parameter expected

Bio::Tools::EUtilities-delegating methods

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

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

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 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
            elink      : from parameter_base->dbfrom or undef
            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
            espell     : the queried database
            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 (Cookie or LinkSet)
 Args     : none

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.

  [email protected]               - General discussion
  https://bioperl.org/Support.html    - About the mailing lists

Support

Please direct usage questions or support issues to the mailing list: [email protected] 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

Releases

7 releases since Debian 5.0 (Lenny); the text changed 6 times.

  1. 5.0
  2. 6.0
  3. 7
  4. 10
  5. 11
  6. 12
  7. 13

Author

Chris Fields <[email protected]>

From libbio-eutilities-perl 1.77-3 in Debian 13 (Trixie). Parsed by carta from the page's man source.