esearch {reutils}

esearch - searching an Entrez database

Description

esearch performs searches using the the NCBI ESearch utility to retrieve primary UIDs matching a text query. These UIDs can be used in subsequent calls to esummary, efetch, or elink.

Usage

esearch(term, db = "nuccore", rettype = "uilist", retmode = "xml",
  retstart = 0, retmax = 100, usehistory = FALSE, webenv = NULL,
  querykey = NULL, sort = NULL, field = NULL, datetype = NULL,
  reldate = NULL, mindate = NULL, maxdate = NULL)

Arguments

term

A valid Entrez text query.

db

Database to search (default: nuccore).

rettype

Retrieval type. (default: 'uilist', alternative: 'count')

retmode

Retrieval mode. (default: 'xml', alternative: 'json')

retstart

Numeric index of the first UID in the retrieved set to be shown in the XML output (default: 0).

retmax

Total number of UIDs to be retrieved (default: 100).

usehistory

If TRUE, search results are posted directly to the Entrez History Server so that they can be used in subsequent calls to esummary, efetch, or elink. Also, usehistory must be set to TRUE for esearch to interpret query key values included in term or to accept a webenv as input.

webenv

Web environment string returned by a previous call to esearch, epost or elink. When provided, esearch will append the results of the search to the pre-existing Web environment. Providing webenv also allows query keys to be used in term so that previous search sets can be combined or limited.

querykey

query key returned by a previous call to esearch, epost or elink. When provided, esearch will find the intersection of the set specified by querykey and the set retrieved by the query in term (i.e. joins the two with AND).

sort

Method used to sort UIDs in the ESearch output. The available values vary by database. Example values are ‘relevance’ and ‘name’ for Gene and ‘first author’ and ‘pub date’ for PubMed.

field

Optional. Search field used to limit the entire search term.

datetype

Optional. Type of date to limit the search. One of "mdat" (modification date), "pdat" (publication date) or "edat" (Entrez date)

reldate

Optional. Number of days back for which search items are returned.

mindate

Optional. Minimum date of search range. Format YYYY/MM/DD, YYYY/MM, or YYYY.

maxdate

Optional. Maximum date of search range. Format YYYY/MM/DD, YYYY/MM, or YYYY.

Details

See the official online documentation for NCBI's EUtilities for additional information on this EUtility.

Value

An esearch object.

See Also

Combine calls to ESearch with other EUtils: esummary, efetch, elink.

Accessor methods: content, getUrl, getError, database, uid, webenv, querykey.

Examples

## Search PubMed for articles with the term "Chlamydia psittaci" in the
## title that were published in 2013.
pmid <- esearch("Chlamydia psittaci[titl] and 2013[pdat]", "pubmed")
pmid

## Not run: 
## Extract the query results either as an XML tree or parsed into
## a character vector
xml <- content(pmid, "xml")
uids <- uid(pmid)

## Alternatively post the UIDs to the History Server.
pmid <- esearch("Chlamydia psittaci[titl] and 2013[pdat]", "pubmed",
                usehistory = TRUE)
pmid

## Associate new search results with the existing search results.
pmid2 <- esearch("Chlamydia psittaci[titl] and 2012[pdat]", "pubmed",
                 usehistory = TRUE, webenv = webenv(pmid))
pmid2

## Sort results by author
pmid3 <- esearch("Chlamydia psittaci[titl] and 2013[pdat]", "pubmed",
                 sort = "first author")
pmid3

## End(Not run)