Queries#

easy_entrez.queries defines the supported queries as subclasses of EntrezQuery. You should not use this module directly, unless implementing support to a custom endpoint. The query objects created from EntrezQuery sub-classes can be executed with easy_entrez.api.EntrezAPI._request() (which is not a part of public API, because the preferred way of using the existing queries is by calling the appropriate methods of EntrezAPI).

class CitationQuery(database, citations, return_type='xml')#

Note: enforces xml as it is the only supported return_type for the citation endpoint.

Functionality:

  • Retrieves PubMed IDs (PMIDs) that correspond to a set of input citations

Parameters:

  • database (Literal['pubmed']) – Database to search. The only supported value is ‘pubmed’.

  • citations (List[Citation]) – Input citations (dictionaries complying the with the Citation interface).

Examples

Check PMIDs for two citations

>>> CitationQuery(database='pubmed', citations=[{'journal': 'proc natl acad sci u s a', 'year': 1991, 'volume': 88, 'first_page': 3248, 'author': 'mann bj', 'key': 'Art1'}, {'journal': 'science', 'year': 1987, 'volume': 235, 'first_page': 182, 'author': 'palmenberg ac', 'key': 'Art2'}], return_type='xml')
class EntrezQuery(database)#
Parameters:

database (EntrezDatabaseType) – The database to query. Value must be a valid E-utility database name.

abstract property endpoint#

The name of the endpoint.

class FetchQuery(database, ids, max_results, ignore_max_results_limit=False, return_type='xml')#

Note: FetchQuery enforces xml as a default return_type as JSON is not properly implemented by the eutilis server.

Functionality:

  • Returns formatted data records for a list of input UIDs

Parameters:

  • database (EntrezDatabaseType) – Database from which to retrieve records. Value must be a valid E-utility database name (default = 'pubmed'). Currently EFetch does not support all Entrez databases. Please see Table 1 for a list of available databases.

  • ids (List[Union[str, int]]) – UID list. Either a single UID or a comma-delimited list of UIDs may be provided. All of the UIDs must be from the database specified by database

  • max_results (int) – maximal number of results to return

class InfoQuery(database)#
Functionality:

  • Provides a list of the names of all valid Entrez databases

  • Provides statistics for a single database, including lists of indexing fields and available link names

Parameters:

database (EntrezDatabaseType) – if not provided, will return a list of the names of all valid Entrez databases.

class LinkQuery(database, ids, database_from, command='neighbor')#
Functionality:

  • Returns UIDs linked to an input set of UIDs in either the same or a different Entrez database

  • Returns UIDs linked to other UIDs in the same Entrez database that match an Entrez query

  • Checks for the existence of Entrez links for a set of UIDs within the same database

  • Lists the available links for a UID

  • Lists LinkOut URLs and attributes for a set of UIDs

  • Lists hyperlinks to primary LinkOut providers for a set of UIDs

  • Creates hyperlinks to the primary LinkOut provider for a single UID

Parameters:

  • database (EntrezDatabaseType) – Database to search. Value must be a valid E-utility database name (default = 'pubmed'). This is the destination database for the link operation.

  • database_from (EntrezDatabaseType) – Database to search. Value must be a valid E-utility database name (default = 'pubmed'). This is the origin database of the link operation. If database and database_from are set to the same database value, then ELink will return computational neighbors within that database. Please see the full list of Entrez links for available computational neighbors. Computational neighbors have linknames that begin with dbname_dbname (examples: protein_protein, pcassay_pcassay_activityneighbor).

  • ids (List[Union[str, int]]) – UID list. Either a single UID or a comma-delimited list of UIDs may be provided. All of the UIDs must be from the database specified by database_from

  • command (CommandType) – ELink command mode. The command mode specifies which function ELink will perform.

Examples

Link from protein to gene

>>> LinkQuery(database='gene', ids=[15718680, 157427902], database_from='protein', command='neighbor')

Find articles related to PMID 20210808

>>> LinkQuery(database='pubmed', ids=[20210808], database_from='pubmed', command='neighbor_score')

List all possible links from two protein GIs

>>> LinkQuery(database=None, ids=[15718680, 157427902], database_from='protein', command='acheck')

List all possible links from two protein GIs to PubMed

>>> LinkQuery(database='pubmed', ids=[15718680, 157427902], database_from='protein', command='acheck')
class SearchQuery(database, term, max_results, ignore_max_results_limit=False)#
Functionality:

  • Provides a list of UIDs matching a text query

  • Posts the results of a search on the History server

  • Downloads all UIDs from a dataset stored on the History server

  • Combines or limits UID datasets stored on the History server

  • Sorts sets of UIDs

Parameters:

  • database (EntrezDatabaseType) – Database to search. Value must be a valid E-utility database name (default = 'pubmed').

  • term (str) – Entrez text query

  • max_results (int) – Maximal number of results to return. Limited to 10’000, following the eUtils documentation.

  • ignore_max_results_limit (bool) – Ignore the upper limit placed on max_results. Experimentation has shown that some databases allow for higher limits, but as this is not documented, setting higher limits needs to be explicitly enabled here. Use at your own risk of hard to predict errors.

Examples

Find articles about human cancers

>>> SearchQuery(database='pubmed', term='cancer AND human[organism]', max_results=10000, ignore_max_results_limit=False)

Search PubMed Central for free full text articles containing the query stem cells

>>> SearchQuery(database='pmc', term='stem cells AND free fulltext[filter]', max_results=10000, ignore_max_results_limit=False)
class SummaryQuery(database, ids, max_results, ignore_max_results_limit=False)#
Functionality:

  • Returns document summaries (DocSums) for a list of input UIDs

Parameters:

  • database (EntrezDatabaseType) – Database from which to retrieve DocSums. Value must be a valid E-utility database name (default = 'pubmed').

  • ids (List[Union[str, int]]) – UID list. Either a single UID or a comma-delimited list of UIDs may be provided. All of the UIDs must be from the database specified by database. There is no set maximum for the number of UIDs that can be passed to ESummary. To comply with the recommendation of using HTTP POST method if lists of UIDs for ESummary is long, the method is by default set to post.

  • max_results (int) – Maximal number of results to return. Limited to 10’000, following the eUtils documentation.

  • ignore_max_results_limit (bool) – Ignore the upper limit placed on max_results. Experimentation has shown that some databases allow for higher limits, but as this is not documented, setting higher limits needs to be explicitly enabled here. Use at your own risk of hard to predict errors.

query_#

alias of SearchQuery