tutor/ncbi

National Center for Biotechnology Information (NCBI) E-Utils Guzzle Client

NCBI E-Utils Guzzle Client

Provides an implementation of the Guzzle library to query NCBI E-Utils service., _(*1)

The Entrez Programming Utilities (E-utilities) are a set of nine server-side programs that provide a stable interface into the Entrez query and database system at the National Center for Biotechnology Information (NCBI)., _(*2)

The E-utilities use a fixed URL syntax that translates a standard set of input parameters into the values necessary for various NCBI software components to search for and retrieve the requested data. The E-utilities are therefore the structured interface to the Entrez system, which currently includes 38 databases covering a variety of biomedical data, including nucleotide and protein sequences, gene records, three-dimensional molecular structures, and the biomedical literature., _(*3)

• https://www.ncbi.nlm.nih.gov/books/NBK25497/

The Nine E-utilities in Brief

EInfo (database statistics)

https://eutils.ncbi.nlm.nih.gov/entrez/eutils/einfo.fcgi, _(*4)

Provides the number of records indexed in each field of a given database, the date of the last update of the database, and the available links from the database to other Entrez databases., _(*5)

ESearch (text searches)

https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi, _(*6)

Responds to a text query with the list of matching UIDs in a given database (for later use in ESummary, EFetch or ELink), along with the term translations of the query., _(*7)

EPost (UID uploads)

https://eutils.ncbi.nlm.nih.gov/entrez/eutils/epost.fcgi, _(*8)

Accepts a list of UIDs from a given database, stores the set on the History Server, and responds with a query key and web environment for the uploaded dataset., _(*9)

ESummary (document summary downloads)

https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi, _(*10)

Responds to a list of UIDs from a given database with the corresponding document summaries., _(*11)

EFetch (data record downloads)

https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi, _(*12)

Responds to a list of UIDs in a given database with the corresponding data records in a specified format., _(*13)

ELink (Entrez links)

https://eutils.ncbi.nlm.nih.gov/entrez/eutils/elink.fcgi, _(*14)

Responds to a list of UIDs in a given database with either a list of related UIDs (and relevancy scores) in the same database or a list of linked UIDs in another Entrez database; checks for the existence of a specified link from a list of one or more UIDs; creates a hyperlink to the primary LinkOut provider for a specific UID and database, or lists LinkOut URLs and attributes for multiple UIDs., _(*15)

EGQuery (global query)

https://eutils.ncbi.nlm.nih.gov/entrez/eutils/egquery.fcgi, _(*16)

Responds to a text query with the number of records matching the query in each Entrez database., _(*17)

ESpell (spelling suggestions)

https://eutils.ncbi.nlm.nih.gov/entrez/eutils/espell.fcgi, _(*18)

Retrieves spelling suggestions for a text query in a given database., _(*19)

ECitMatch (batch citation searching in PubMed)

https://eutils.ncbi.nlm.nih.gov/entrez/eutils/ecitmatch.cgi, _(*20)

Retrieves PubMed IDs (PMIDs) corresponding to a set of input citation strings., _(*21)

Usage

To use the NCBI API Client simply instantiate the client., _(*22)

<?php

require dirname(__FILE__).'/../vendor/autoload.php';

use Tutor\NCBI\EUtilsClient;
$client = EUtilsClient::factory();

// if you want to see what is happening, add debug => true to the factory call
$client = EUtilsClient::factory(['debug' => true]);

Invoke Commands using the __call method (auto-complete phpDocs are included), _(*23)

<?php

$client = EUtilsClient::factory();
$response = $client->eFetch([
  'db' => 'protein',
  'id' => '194680922,50978626,28558982,9507199,6678417',
]);

Or Use the getCommand method (in this case you need to work with the $response['data'] array:, _(*24)

<?php

$client = EUtilsClient::factory();

//Retrieve the Command from Guzzle
$command = $client->getCommand('EFetch', [
  'db' => 'protein',
  'id' => '194680922,50978626,28558982,9507199,6678417',
]);
$command->prepare();

$response = $command->execute();

$data = $response['data'];

Examples

You can execute the examples in the examples directory., _(*25)

You can look at the services.json for details on what methods are available and what parameters are available to call them., _(*26)

TODO

• [ ] Add some more examples
• [ ] Add tests
• [ ] Add some Response models
• [ ] Integrate with api token
• [ ] EPost
• [ ] EGQuery
• [ ] ESpell
• [ ] ESummary
• [ ] ELink
• [ ] ECitMatch

Contributions welcome

Found a bug, open an issue, preferably with the debug output and what you did. Bugfix? Open a Pull Request and I'll look into it., _(*27)

License

The use NCBI\EUtilsClient API client is available under an MIT License., _(*28)