Linux Certif

Toute la documentation sur la certification Linux LPI

Bio::DB::EUtilities::elink.3pm

NAME

Bio::DB::EUtilities::elink - check for and retrieve external or related ID's from a list of one or more primary ID's, including relevancy scores.

SYNOPSIS

Do not use this module directly. Use it via the Bio::DB::EUtilities class.

   # chain EUtilities for complex queries
 
   use Bio::DB::EUtilities;
 
   my $esearch = Bio::DB::EUtilities->new(-eutil      => 'esearch',
                                          -db         => 'pubmed',
                                          -term       => 'hutP',
                                          -usehistory => 'y');
 
   $esearch->get_response; # parse the response, fetch a cookie
 
   my $elink = Bio::DB::EUtilities->new(-eutil        => 'elink',
                                        -db           => 'protein,taxonomy',
                                        -dbfrom       => 'pubmed',
                                        -cookie       => $esearch->next_cookie,
                                        -cmd          => 'neighbor');
 
   # this retrieves the Bio::DB::EUtilities::ElinkData object
 
   my ($linkset) = $elink->next_linkset;
   my @ids;
 
   # step through IDs for each linked database in the ElinkData object
 
   for my $db ($linkset->get_databases) {   
     @ids = $linkset->get_LinkIds_by_db($db); #returns primary ID's
     # do something here
   }
 
   # multiple ID groups (for one-to-one-correspondence of IDs)
 
   my $elink = Bio::DB::EUtilities->new(-eutil        => 'elink',
                                        -db           => 'all',
                                        -dbfrom       => 'protein',
                                        -id           => [\@id1, @ids2],
                                        -multi_id     => 1,
                                        -cmd          => 'neighbor');
 
   while (my $linkset = $elink->next_linkset) {
     for my $db ($linkset->get_databases) {
       my @ids = $linkset->get_LinkIds_by_db($db); #returns primary ID's
       # do something here
     }
   }
 
   # to retrieve scores for a linkset
 
   while (my $linkset = $elink->next_linkset) {
     my @score_dbs = $linkset->has_scores; # retrieve databases with score values
     for my $db (@score_dbs) {
       my @ids = $linkset->get_LinkIds_by_db($db); #returns primary ID's
       $linkset->set_score_db($db);  # to current database containing scores
       for my $id (@ids) {
          my $score = get_score($id);  
          # do something here, like screen for IDs based on score
       }
     }
   }
 
   # or just receive a hash containing ID-score key-value pairs
 
   while (my $linkset = $elink->next_linkset) {
     my @score_dbs = $linkset->has_scores; 
     for my $db (@score_dbs) {
       $linkset->set_score_db($db);
       %scores = $linkset->get_score_hash;
     }
   }
 
 

DESCRIPTION

WARNING: Please do NOT spam the Entrez web server with multiple requests.

The EUtility Elink is used to check for and retrieve external or related ID's from a list of one or more primary ID's. Using the "cmd" parameter, one can vary the returned data. See the below command options for explanations on returned XML output. For certain command options one can retrieve one or more Bio::DB::EUtilities::Cookie objects to be used in other EUtility searches or efetch primary IDs. Other will return the ID information and relevancy scores in one or more Bio::DB::EUtilities::ElinkData objects.

NCBI ELink Parameters

The following are a general list of parameters that can be used to take advantage of ELink. Up-to-date help for ELink is available at this URL (the information below is a summary of the options found there):

   http://eutils.ncbi.nlm.nih.gov/entrez/query/static/elink_help.html
 
 

"db"

One or more database available through EUtilities. If set to 'all', will retrieve all relevant information from each database based on the "cmd" parameter (the default setting is to retrieve related primary ID's). One interesting behaviour is when "db" and "dbfrom" are set to the same database; related IDs from database are retrieved along with a relevancy score. This score differs from database to database; if protein-protein elinks are sought, the scores are generated from BLASTP

"dbfrom"

originating database; useful only if using directly when querying with ID's

"id"

a list of primary ID's

Below are a list of IDs which can be used with ELink:

PMID (pubmed), MIM number (omim), GI number (nucleotide, protein), Genome ID (genome), Popset ID (popset), SNP cluster ID (snp), UniSTS ID (unists), UniGene cluster ID (unigene), MMDB-ID (structure), PSSM-ID (cdd), 3D SDI (domains), TAXID (taxonomy), GEO ID (geo)

"reldate"

limits results to the number of days preceding today's date

"mindate", "maxdate"

limits results by dates ("yyyy/mm/dd" format, or by year)

"term"

limits results by Entrez query (only valid when "cmd=neighbor" within a single database)

"retmode"

set to XML, but can be changed to ref when needed

"cmd"

command values (see below)

"holding"

list LinkOut URLs for specified holding provider; used with "cmd=llinks" or "cmd=llinkslib" (rarely used)

Additional (Bioperl-related) Parameters

The following are a general list of parameters that can be used to take advantage of ELink. Up-to-date help for ELink is available at this URL (the information below is a summary of the options found there):

   http://eutils.ncbi.nlm.nih.gov/entrez/query/static/elink_help.html
 
 

"eutil"

The relevant EUtility to be used (elink).

"cookie"

Uses a Cookie-based search (see below)

"multi_id"

Sets a flag to treat the ID data ("id" parameter) as multiple ID groups (see below).

"keep_cookies"

Sets a flag to retain the cookie queue (this is normally cleared before

Command Values

Command values are set using the "cmd" parameter.

"prlinks"

List the hyperlink to the primary LinkOut provider for multiple IDs and database. Each ID is processed separately.

"prlinks&retmode=ref"

Create a hyperlink to the primary LinkOut provider for a single ID and database.

"llinks"

List LinkOut URLs and Attributes, except PubMed libraries, for multiple IDs and database. Each ID is processed separately.

"llinkslib"

List LinkOut URLs and Attributes for multiple IDs and database. Each ID is processed separately.

"lcheck"

Check for the existence (Y or N) of an external link in for multiple IDs and database.

"ncheck"

Check for the existence of a neighbor link for each ID within a database, e.g., Related Articles in PubMed.

"neighbor"

The default setting. Display neighbors and their scores within a database. This module will parse XML output from an ELink query and will return a Bio::DB::EUtilities::ElinkData object, which contains IDs for every database liked to using "db" (see "id" and "db" for more details).

"neighbor_history"

Create history (WebEnv & query_key) for use in other EUtilities.

"acheck"

Lists Entrez databases links for multiple IDs from a single database.

Cookies

Some EUtilities ("epost", "esearch", or "elink") are able to retain information on the NCBI server under certain settings. This information can be retrieved by using a cookie. Here, the idea of the 'cookie' is similar to the 'cookie' set on a user's computer when browsing the Web. XML data returned by these EUtilities, when applicable, is parsed for the cookie information (the 'WebEnv' and 'query_key' tags to be specific) The information along with other identifying data, such as the calling eutility, description of query, etc.) is stored as a Bio::DB::EUtilities::Cookie object in an internal queue. These can be retrieved one at a time by using the next_cookie method or all at once in an array using get_all_cookies. Each cookie can then be 'fed', one at a time, to another EUtility object, thus enabling chained queries as demonstrated in the synopsis.

For more information, see the POD documentation for Bio::DB::EUtilities::Cookie.

ElinkData Objects

Due to the diversity of information that can be returned via elink, a special object (ElinkData) has been created to hold data parsed from the XML output. This object holds returned IDs, scores, and potentially additional data as the need arises. ElinkData objects are stored in an internal queue much like for Cookie objects; similarly, they can be accessed using next_linkset and get_all_linksets. If a simple search is initiated, where one database is queried using one set of IDs, the default EUtilities method "get_ids" can be used to retrieve the IDs. If more than one database is specified for a single set of IDs, (such as when "db" is set to 'all' or a comma-separated list, like 'protein,taxonomy'), the database must be passed explicitly to "get_ids" as an argument to retrieve the relevant IDs.

The most complicated sitation comes when using multiple ID groups (see below). This requires that each ID group have a separate set of data (a linkset), each with potential multiple databases, multiple IDs, and so on. Linkset data is stored in a special object (Bio::DB::EUtilities::ElinkData).

For more information, see the POD documentation for Bio::DB::EUtilities::ElinkData.

CURRENT USES

Complex queries

Chaining queries for retrieving related data using elink and other EUtilities is now possible (see the ``SYNOPSIS'' for an example). For instance, one can grab a large number of taxon IDs using protein/nucleotide IDs; these can be retrieved directly or saved on the server (setting "cmd" to 'neighbor_history'), and the cookie passed on to efetch.

Retrieving relevancy scores

When the "db" and "dbfrom" parameters are set to the same database, one can retrieve relevancy scores for a single ID. These are based on several different factors. For proteins, they are precomputed BLASTP scores, so this is actually a quick way to get the best hits without having to run BLASTP directly! Similarly, scores returned for nucleotide-nucleotide are based on BLASTN scores.

Multiple ID groups

When "multi_id" flag is set to a TRUE value, the id list is built based on different set of factors. The default method for submitting an ID list for a query request for any EUtility is by having the "id" parameter set to an array reference (multiple IDs) or pass a single ID as a scalar, like this:

   -id  => \@ids,
   -id  => '1621261',
 
 

Bio::DB::EUtilities::elink has the additional capability to submit ID groups where searches are performed on each ID group independently. This is accomplished by setting the "multi_id" flag to true, which indicates that the ID list will be evaluated as an array reference, with each ID group represented by another array reference or a single ID. So, with "multi_id" set to TRUE:

   -id  => \@ids,  # evaluates each ID in the array independently
   ...
   -id  => [@ids], # same as above
   ...
   -id  => [\@ids, $id], # IDs in @ids are grouped together for one search
                         # while single ID in scalar is searched independently
 
 

It can get tricky:

   -id  => [\@ids, $id1, @ids2], # @ids ID grouped together; IDs in $id1 and @id2
                                 # are flattened and evaluated independently
 
 

This enables one-to-one correspondence with the returned data, so that one can determine, per ID, what the matching ELink ID is. The default is to return them all as a group (no one-to-one correspondence). Using a small ID array, "multi_id" set to TRUE, '-id => \@ids', and this loop:

   while (my $linkset = $elink->next_linkset) {
     print "Query ID : ",join q(,), $linkset->query_id,"\n";
     print "\tTax ID : ",join q(,), $linkset->get_LinkIds_by_db('taxonomy'),"\n";
   }
 
 

gets this result:

     Query ID : 1621261,
             Tax ID : 83332,
     Query ID : 31618162,
             Tax ID : 233413,
     Query ID : 31792573,
             Tax ID : 233413,
 
 

Setting "multi_id" to FALSE or not setting, using all other conditions above, gets this result:

Query ID : 31792573,31618162,1621261,
        Tax ID : 233413,83332,

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
 
 

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 uiuc dot edu

APPENDIX

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

parse_response

  Title   : parse_response
  Usage   : $elink->parse_response($content)
  Function: parse out response for cookie and/or id's
  Returns : none
  Args    : HTTP::Response object
  Throws  : 'NCBI elink nonrecoverable error'
            'No links' error
 
 

multi_id

  Title   : multi_id
  Usage   : $elink->multi_id(1);
  Function: gets/sets value (switch for using multiple ids)
  Returns : Boolean (value evaluating to true or false)
  Args    : Boolean (value evaluating to true or false)
 
 

next_linkset

  Title   : next_linkset
  Usage   : $ls = $elink->next_linkset;
  Function: returns next linkset in internal cache of 
          : Bio::DB::EUtilities::ElinkData objects
  Returns : Boolean (value evaluating to true or false)
  Args    : Boolean (value evaluating to true or false)
 
 

get_all_linksets

  Title   : get_all_linksets
  Usage   : @ls = $elink->get_all_linksets;
  Function: returns array of Bio::DB::EUtilities::ElinkData objects
  Returns : array or array ref of Bio::DB::EUtilities::ElinkData objects
            based on wantarray
  Args    : None
 
 

reset_linksets

  Title   : reset_linksets
  Usage   : $elink->reset_linksets;
  Function: resets (empties) internal cache of Linkset objects
  Returns : None
  Args    : None
 
 

rewind_linksets

  Title   : rewind_linksets
  Usage   : $elink->rewind_linksets;
  Function: resets linkset index to 0 (starts over)
  Returns : None
  Args    : None
 
 

get_linkset_count

  Title   : get_linkset_count
  Usage   : $ct = $elink->get_linkset_count;
  Function: returns total # of linksets in Elink object
  Returns : Integer (# linksets)
  Args    : None