Package 'reutils'

Title:	Talk to the NCBI EUtils
Description:	An interface to NCBI databases such as PubMed, GenBank, or GEO powered by the Entrez Programming Utilities (EUtils). The nine EUtils provide programmatic access to the NCBI Entrez query and database system for searching and retrieving biological data.
Authors:	Gerhard Schöfl <[email protected]>
Maintainer:	Gerhard Schöfl <[email protected]>
License:	MIT + file LICENSE
Version:	0.2.5
Built:	2024-09-06 03:52:52 UTC
Source:	https://github.com/gschofl/reutils

Help Index

reutils: Talk to the NCBI EUtils

Description

An interface to NCBI databases such as PubMed, GenBank, or GEO powered by the Entrez Programming Utilities (EUtils). The nine EUtils provide programmatic access to the NCBI Entrez query and database system for searching and retrieving biological data.

Details

With nine Entrez Progamming Utilities, NCBI provides a programmatical interface to the Entrez query and database system for searching and retrieving requested data

Each of these tools corresponds to an R function in the reutils package described below.

The output returned by the EUtils is typically in XML format. To gain access to this output you have several options:

Use the content(as = "xml") method to extract the output as an XMLInternalDocument object and process it further using the facilities provided by the XML package.
Use the content(as = "parsed") method to extract the output into data.frames. Note that this is currently only implemented for docsums returned by esummary, uilists returned by esearch, and the output returned by einfo.
Access specific nodes in the XML tree using XPath expressions with the reference class methods #xmlValue, #xmlAttr, or #xmlName built into eutil objects.

The Entrez Programming Utilities can also generate output in other formats, such as plain-text Fasta or GenBank files for sequence databases, or the MedLine format for the literature database. The type of output is generally controlled by setting the retmode and rettype arguments when calling a EUtil. Please check the relevant usage guidelines when using these services. Note that Entrez server requests are subject to frequency limits.

Main functions

esearch: Search and retrieve primary UIDs for use with esummary, elink, or efetch. esearch additionally returns term translations and optionally stores results for future use in the user's Web Environment.
esummary: Retrieve document summaries from a list of primary UIDs (Provided as a character vector or as an esearch object).
egquery: Provides Entrez database counts in XML for a single search term using a Global Query.
einfo: Retrieve field names, term counts, last update, and available updates for each database.
efetch: Retrieve data records in a specified format corresponding to a list of primary UIDs or from the user's Web Environment in the Entrez History server.
elink: Returns a list of UIDs (and relevancy scores) from a target database that are related to a list of UIDs in the same database or in another Entrez database.
epost: Uploads primary UIDs to the users's Web Environment on the Entrez history server for subsequent use with esummary, elink, or efetch.
espell: Provide spelling suggestions.
ecitmatch: Retrieves PubMed IDs (PMIDs) that correspond to a set of input citation strings
content: Extract the content of a request from the eutil object returned by any of the above functions.

Package options

reutils uses five options to configure behaviour:

reutils.api.key: Starting May 2018, NCBI limits eutils queries to 3 per second. This limit is increased to 10 per second with an API key. If you are going to perform a lot of queries consider registering an NCBI account to obtain a key. You can then set the reutils.api.key option to your API key in your .Rprofile file.
reutils.show.headlines: By default efetch objects containing text data show only the first 12 lines. This is quite handy if you have downloaded a fairly large genome in Genbank file format. This can be changed by setting the global option reutils.show.headlines to another numeric value or NULL.
reutils.verbose.queries: If you perform many queries interactively you might want to get messages announcing the queries you run. You can do so by setting the option reutils.verbose.queries to TRUE.
reutils.test.remote: Unit tests that require online access to NCBI services are disabled by default, as they cannot be garanteed to be available/working under all circumstances. Set the option codereutils.test.remote to TRUE to run the full suite of tests.
reutils.rcurl.connecttimeout: Set the connection timeout (Default: 10).

Author(s)

Gerhard Schöfl [email protected]

Examples

#
# combine esearch and efetch
#
# Download PubMed records that are indexed in MeSH for both 'Chlamydia' and 
# 'genome' and were published in 2013.
query <- "Chlamydia[mesh] and genome[mesh] and 2013[pdat]"

# Upload the PMIDs for this search to the History server
pmids <- esearch(query, "pubmed", usehistory = TRUE)
pmids

## Not run: 
# Fetch the records
articles <- efetch(pmids)

# Use XPath expressions with the #xmlValue() or #xmlAttr() methods to directly
# extract specific data from the XML records stored in the 'efetch' object.
titles <- articles$xmlValue("//ArticleTitle")
abstracts <- articles$xmlValue("//AbstractText")

#
# combine epost with esummary/efetch
#
# Download protein records corresponding to a list of GI numbers.
uid <- c("194680922", "50978626", "28558982", "9507199", "6678417")

# post the GI numbers to the Entrez history server
p <- epost(uid, "protein")

# retrieve docsums with esummary
docsum <- content(esummary(p, version = "1.0"), "parsed")
docsum

# download FASTAs as 'text' with efetch
prot <- efetch(p, retmode = "text", rettype = "fasta")
prot

# retrieve the content from the efetch object
fasta <- content(prot)

## End(Not run)
#
# combine esearch and efetch
#
# Download PubMed records that are indexed in MeSH for both 'Chlamydia' and 
# 'genome' and were published in 2013.
query <- "Chlamydia[mesh] and genome[mesh] and 2013[pdat]"

# Upload the PMIDs for this search to the History server
pmids <- esearch(query, "pubmed", usehistory = TRUE)
pmids

## Not run: 
# Fetch the records
articles <- efetch(pmids)

# Use XPath expressions with the #xmlValue() or #xmlAttr() methods to directly
# extract specific data from the XML records stored in the 'efetch' object.
titles <- articles$xmlValue("//ArticleTitle")
abstracts <- articles$xmlValue("//AbstractText")

#
# combine epost with esummary/efetch
#
# Download protein records corresponding to a list of GI numbers.
uid <- c("194680922", "50978626", "28558982", "9507199", "6678417")

# post the GI numbers to the Entrez history server
p <- epost(uid, "protein")

# retrieve docsums with esummary
docsum <- content(esummary(p, version = "1.0"), "parsed")
docsum

# download FASTAs as 'text' with efetch
prot <- efetch(p, retmode = "text", rettype = "fasta")
prot

# retrieve the content from the efetch object
fasta <- content(prot)

## End(Not run)

EFetch accessors

Description

Extract XML nodes from an efetch object.

Usage

## S4 method for signature 'efetch,character,missing'
x[i, j]

## S4 method for signature 'efetch,character'
x[[i]]
## S4 method for signature 'efetch,character,missing'
x[i, j]

## S4 method for signature 'efetch,character'
x[[i]]

Arguments

`x`	An `efetch` object containing XML data.
`i`	An XPath expression specifying the XML nodes to extract.
`j`	Ignored.

Value

An XML node set.

Examples

## Not run: 
p <- efetch("195055", "protein", "gp", "xml")
p['//GBFeature[GBFeature_key="mat_peptide"]//GBQualifier_value']

## End(Not run)
## Not run: 
p <- efetch("195055", "protein", "gp", "xml")
p['//GBFeature[GBFeature_key="mat_peptide"]//GBQualifier_value']

## End(Not run)

EInfo accessors

Description

Extract parts of a parsed einfo object.

Usage

## S4 method for signature 'einfo,ANY,missing'
x[i, j]

## S4 method for signature 'einfo,ANY'
x[[i]]
## S4 method for signature 'einfo,ANY,missing'
x[i, j]

## S4 method for signature 'einfo,ANY'
x[[i]]

Arguments

`x`	An `einfo` object.
`i`	Numeric or character indices specifying the elements to extract.
`j`	Ignored.

Value

A list.

Examples

## Not run: 
e <- einfo("pubmed")
e[1:5]
e["Description"]
e[["Links"]]

e2 <- einfo("pubmed", retmode = 'json')
e2[["header"]]
e2[["einforesult"]][["dbinfo"]][["description"]]

## End(Not run)
## Not run: 
e <- einfo("pubmed")
e[1:5]
e["Description"]
e[["Links"]]

e2 <- einfo("pubmed", retmode = 'json')
e2[["header"]]
e2[["einforesult"]][["dbinfo"]][["description"]]

## End(Not run)

ELink Accessors

Description

Extract UIDs from an elink object.

Usage

## S4 method for signature 'elink,ANY,missing'
x[i, j]

## S4 method for signature 'elink,character,ANY'
x[i]
## S4 method for signature 'elink,ANY,missing'
x[i, j]

## S4 method for signature 'elink,character,ANY'
x[i]

Arguments

`x`	An `elink` object.
`i`	Numeric or character indices.
`j`	Ignored.

Value

A entrez_linkset object.

Examples

## Not run: 
e <- elink(c("34577062", "24475906"), dbFrom = "nuccore")
e[1]

## End(Not run)
## Not run: 
e <- elink(c("34577062", "24475906"), dbFrom = "nuccore")
e[1]

## End(Not run)

ESearch Accessors

Description

Extract UIDs from an esearch object.

Usage

## S4 method for signature 'esearch,numeric,missing'
x[i, j]
## S4 method for signature 'esearch,numeric,missing'
x[i, j]

Arguments

`x`	An `esearch` object.
`i`	Numeric indices.
`j`	Ignored.

Value

A entrez_uid object.

Examples

## Not run: 
e <- esearch("Mus musculus", "protein", retmax = 20)
e[1:5]
## pass the subset directly on to esummary or efetch
content(esummary(e[1:5]), "parsed")

## End(Not run)
## Not run: 
e <- esearch("Mus musculus", "protein", retmax = 20)
e[1:5]
## pass the subset directly on to esummary or efetch
content(esummary(e[1:5]), "parsed")

## End(Not run)

ESummary accessors

Description

Extract XML nodes from an esummary object.

Usage

## S4 method for signature 'esummary,character,ANY'
x[i]

## S4 method for signature 'esummary,character'
x[[i]]
## S4 method for signature 'esummary,character,ANY'
x[i]

## S4 method for signature 'esummary,character'
x[[i]]

Arguments

`x`	An `esummary` object.
`i`	An XPath expression.

Value

An XML node set.

Examples

## Not run: 
ds <- esummary("470338", "protein")
ds["//Slen/node()"]

as.numeric(XML::xmlValue(ds[["//Slen"]]))

## End(Not run)
## Not run: 
ds <- esummary("470338", "protein")
ds["//Slen/node()"]

as.numeric(XML::xmlValue(ds[["//Slen"]]))

## End(Not run)

Extract the data content from an Entrez request

Description

There are five ways to access data returned by an Entrez request: as a character string (as = "text"), as a textConnection (as = "textConnection"), as an XMLInternalDocument (as = "xml") or json object (as = "json") (depending on the retmode with which the request was performed), or parsed into a native R object, e.g. a list or a data.frame (as = "parsed").

Usage

content(x, ...)

## S4 method for signature 'eutil'
content(x, ...)

## S4 method for signature 'ecitmatch'
content(x, as = "text")

## S4 method for signature 'efetch'
content(x, as = NULL)

## S4 method for signature 'egquery'
content(x, as = NULL)

## S4 method for signature 'einfo'
content(x, as = NULL)

## S4 method for signature 'elink'
content(x, as = NULL)

## S4 method for signature 'epost'
content(x, as = NULL)

## S4 method for signature 'esearch'
content(x, as = NULL)

## S4 method for signature 'espell'
content(x, as = NULL)

## S4 method for signature 'esummary'
content(x, as = NULL)
content(x, ...)

## S4 method for signature 'eutil'
content(x, ...)

## S4 method for signature 'ecitmatch'
content(x, as = "text")

## S4 method for signature 'efetch'
content(x, as = NULL)

## S4 method for signature 'egquery'
content(x, as = NULL)

## S4 method for signature 'einfo'
content(x, as = NULL)

## S4 method for signature 'elink'
content(x, as = NULL)

## S4 method for signature 'epost'
content(x, as = NULL)

## S4 method for signature 'esearch'
content(x, as = NULL)

## S4 method for signature 'espell'
content(x, as = NULL)

## S4 method for signature 'esummary'
content(x, as = NULL)

Arguments

`x`	An `eutil` object.
`...`	Further arguments passed on to methods.
`as`	Type of output: `"text"`, `"xml"`, `"json"`, `"textConnection"`, or `"parsed"`. `content` attempts to figure out the most appropriate output type, based on the `retmode` of the object.

Methods (by class)

eutil: Access the data content from an eutil object.
ecitmatch: Return PubMed IDs if as = "parsed".
efetch: Access the data content from an efetch request.
egquery: Access the data content from an egquery request.
einfo: Access the data content from an einfo request.
elink: Access the data content from an elink request.
epost: Access the data content from an epost request.
esearch: Access the data content from an esearch request.
espell: Access the data content from an espell request.
esummary: Access the data content from an esummary request.

Examples

## Not run: 
## einfo() defaults to retmode 'xml'
e <- einfo()

## automatically return data as an 'XMLInternalDocument'.
if (e$no_errors()) {
  content(e)

  ## return the XML data as character string.
  cat(content(e, "text"))

  ## return DbNames parsed into a character vector.
  content(e, "parsed")
}

## return data as a JSON object
e2 <- einfo(db = "gene", retmode = "json")
if (e2$no_errors()) {
  content(e2)
}

## return a textConnection to allow linewise reading of the data.
x <- efetch("CP000828", "nuccore", rettype = "gbwithparts", retmode = "text")
con <- content(x, as = "textConnection")
readLines(con, 2)
close(con)

## End(Not run)
## Not run: 
## einfo() defaults to retmode 'xml'
e <- einfo()

## automatically return data as an 'XMLInternalDocument'.
if (e$no_errors()) {
  content(e)

  ## return the XML data as character string.
  cat(content(e, "text"))

  ## return DbNames parsed into a character vector.
  content(e, "parsed")
}

## return data as a JSON object
e2 <- einfo(db = "gene", retmode = "json")
if (e2$no_errors()) {
  content(e2)
}

## return a textConnection to allow linewise reading of the data.
x <- efetch("CP000828", "nuccore", rettype = "gbwithparts", retmode = "text")
con <- content(x, as = "textConnection")
readLines(con, 2)
close(con)

## End(Not run)

database

Description

Retrieve the target database name from an eutil object.

Usage

database(x, ...)

## S4 method for signature 'eutil'
database(x, ...)

## S4 method for signature 'entrez_linkset'
database(x, ...)

## S4 method for signature 'entrez_uid'
database(x, ...)
database(x, ...)

## S4 method for signature 'eutil'
database(x, ...)

## S4 method for signature 'entrez_linkset'
database(x, ...)

## S4 method for signature 'entrez_uid'
database(x, ...)

Arguments

`x`	An `eutil` object.
`...`	Further arguments passed on to methods.

Value

A character string.

Methods (by class)

eutil: Retrieve the target database name from an eutil object.
entrez_linkset: Retrieve the target database name from an entrez_linkset object.
entrez_uid: Retrieve the target database name from an entrez_uid object.

Examples

## Not run: 
e <- esearch("Mus musculus", "taxonomy")
database(e)

## End(Not run)
## Not run: 
e <- esearch("Mus musculus", "taxonomy")
database(e)

## End(Not run)

ecitmatch - searching PubMed with citation data

Description

ecitmatch serves as an API to the PubMed batch citation matcher. It retrieves PubMed IDs (PMIDs) that correspond to a set of input citation strings.

Usage

ecitmatch(bdata, db = "pubmed", retmode = "xml")
ecitmatch(bdata, db = "pubmed", retmode = "xml")

Arguments

`bdata`	Citation strings. Each input citation must be represented by a citation string in the following format: journal_title\|year\|volume\|first_page\|author_name\|your_key\|
`db`	Database to search. The only supported value is ‘pubmed’.
`retmode`	Retrieval mode. The only supported value is ‘xml’.

Value

An ecitmatch object.

Examples

citstrings <- c("proc natl acad sci u s a|1991|88|3248|mann bj|Art1|",
                "science|1987|235|182|palmenber ac|Art2|")
x <- ecitmatch(citstrings)
x
if (x$no_errors()) {
  content(x, "parsed")
}

citstrings <- c("proc natl acad sci u s a|1991|88|3248|mann bj|Art1|",
                "science|1987|235|182|palmenber ac|Art2|")
x <- ecitmatch(citstrings)
x
if (x$no_errors()) {
  content(x, "parsed")
}

efetch - downloading full records

Description

efetch performs calls to the NCBI EFetch utility to retrieve data records in the requested format for an NCBI Accession Number, one or more primary UIDs, or for a set of UIDs stored in the user's web environment.

Usage

efetch(
  uid,
  db = NULL,
  rettype = NULL,
  retmode = NULL,
  outfile = NULL,
  retstart = NULL,
  retmax = NULL,
  querykey = NULL,
  webenv = NULL,
  strand = NULL,
  seqstart = NULL,
  seqstop = NULL,
  complexity = NULL
)
efetch(
  uid,
  db = NULL,
  rettype = NULL,
  retmode = NULL,
  outfile = NULL,
  retstart = NULL,
  retmax = NULL,
  querykey = NULL,
  webenv = NULL,
  strand = NULL,
  seqstart = NULL,
  seqstop = NULL,
  complexity = NULL
)

Arguments

`uid`	(Required) A list of UIDs provided either as a character vector, as an `esearch` object, or by reference to a Web Environment and a query key obtained directly from previous calls to `esearch` (if `usehistory = TRUE`), `epost` or `elink`. If UIDs are provided as a plain character vector, `db` must be specified explicitly, and all of the UIDs must be from the database specified by `db`.
`db`	(Required if `uid` is a character vector of UIDs) Database from which to retrieve records. See here for the supported databases.
`rettype`	A character string specifying the retrieval type, such as 'abstract' or 'medline' for PubMed, 'gp' or 'fasta' for Protein, or 'gb', or 'fasta' for Nuccore. See here for the available values for each database.
`retmode`	A character string specifying the data mode of the records returned, such as 'text' or 'xml'. See here for the available values for each database.
`outfile`	A character string naming a file for writing the data to. Required if more than 500 UIDs are retrieved at once. In this case UIDs have to be provided by reference to a Web Environment and a query key obtained directly from previous calls to `esearch` (if `usehistory = TRUE`), `epost` or `elink`.
`retstart`	Numeric index of the first record to be retrieved.
`retmax`	Total number of records from the input set to be retrieved.
`querykey`	An integer specifying which of the UID lists attached to a user's Web Environment will be used as input to `efetch`. (Usually obtained drectely from objects returned by a previous call to `esearch`, `epost` or `elink`.)
`webenv`	A character string specifying the Web Environment that contains the UID list. (Usually obtained directely from objects returned by a previous call to `esearch`, `epost` or `elink`.)
`strand`	Strand of DNA to retrieve. (1: plus strand, 2: minus strand)
`seqstart`	First sequence base to retrieve.
`seqstop`	Last sequence base to retrieve.
`complexity`	Data content to return. (0: entire data structure, 1: bioseq, 2: minimal bioseq-set, 3: minimal nuc-prot, 4: minimal pub-set)

Details

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

See here for the default values for rettype and retmode, as well as a list of the available databases for the EFetch utility.

Value

An efetch object.

Note

If you are going to retrieve more than 500 UIDs at once, you will have to provide the UIDs by reference to a Web Environment and a query key obtained from previous calls to esearch (if usehistory = TRUE), epost or elink and you will have to specify an outfile to write the data to, rather than collecting the data into an R object.

Examples

## Not run: 
## From Protein, retrieve a raw GenPept record and write it to a file.
p <- efetch("195055", "protein", "gp")
p

write(content(p, "text"), file = "~/AAD15290.gp")

## Get accessions for a list of GenBank IDs (GIs)
acc <- efetch(c("1621261", "89318838", "68536103", "20807972", "730439"),
              "protein", rettype = "acc")
acc
acc <- strsplit(content(acc), "\n")[[1]]
acc

## Get GIs from a list of accession numbers
gi <- efetch(c("CAB02640.1", "EAS10332.1", "YP_250808.1", "NP_623143.1", "P41007.1"),
             "protein", "uilist")
gi

## we can conveniently extract the UIDs using the eutil method #xmlValue(xpath)
gi$xmlValue("/IdList/Id")

## or we can extract the contents of the efetch query using the fuction content()
## and use the XML package to retrieve the UIDs
doc <- content(gi)
XML::xpathSApply(doc, "/IdList/Id", XML::xmlValue)

## Get the scientific name for an organism starting with the NCBI taxon id.
tx <- efetch("527031", "taxonomy")
tx
 
## Convenience accessor for XML nodes of interest using XPath
## Extract the TaxIds of the Lineage
tx["//LineageEx/Taxon/TaxId"]

## Use an XPath expession to extract the scientific name.
tx$xmlValue("/TaxaSet/Taxon/ScientificName")

## Iteratively retrieve a large number of records
# First store approx. 8400 UIDs on the History server.
uid <- esearch(term = "hexokinase", db = 'protein', usehistory = TRUE)
# Fetch the records and write to file in batches of 500.
efetch(uid, rettype = "fasta", retmode = "text", outfile = "~/tmp/hexokinases.fna")


## End(Not run)
## Not run: 
## From Protein, retrieve a raw GenPept record and write it to a file.
p <- efetch("195055", "protein", "gp")
p

write(content(p, "text"), file = "~/AAD15290.gp")

## Get accessions for a list of GenBank IDs (GIs)
acc <- efetch(c("1621261", "89318838", "68536103", "20807972", "730439"),
              "protein", rettype = "acc")
acc
acc <- strsplit(content(acc), "\n")[[1]]
acc

## Get GIs from a list of accession numbers
gi <- efetch(c("CAB02640.1", "EAS10332.1", "YP_250808.1", "NP_623143.1", "P41007.1"),
             "protein", "uilist")
gi

## we can conveniently extract the UIDs using the eutil method #xmlValue(xpath)
gi$xmlValue("/IdList/Id")

## or we can extract the contents of the efetch query using the fuction content()
## and use the XML package to retrieve the UIDs
doc <- content(gi)
XML::xpathSApply(doc, "/IdList/Id", XML::xmlValue)

## Get the scientific name for an organism starting with the NCBI taxon id.
tx <- efetch("527031", "taxonomy")
tx
 
## Convenience accessor for XML nodes of interest using XPath
## Extract the TaxIds of the Lineage
tx["//LineageEx/Taxon/TaxId"]

## Use an XPath expession to extract the scientific name.
tx$xmlValue("/TaxaSet/Taxon/ScientificName")

## Iteratively retrieve a large number of records
# First store approx. 8400 UIDs on the History server.
uid <- esearch(term = "hexokinase", db = 'protein', usehistory = TRUE)
# Fetch the records and write to file in batches of 500.
efetch(uid, rettype = "fasta", retmode = "text", outfile = "~/tmp/hexokinases.fna")


## End(Not run)

egquery - performing a global Entrez search

Description

egquery retrieves the number of records in all Entrez databases for a single text query.

Usage

egquery(term)
egquery(term)

Arguments

term

A valid Entrez text query.

Details

See the official online documentation for NCBIs EUtilities for additional information.

Value

An egquery object.

Examples

## Determine the number of records for mouse in Entrez.
e <- egquery("mouse[orgn]")
e
## Determine the number of records for mouse in Entrez.
e <- egquery("mouse[orgn]")
e

einfo - getting database statistics and search fields

Description

einfo queries the NCBI EInfo utility to retrieve the names of all valid Entrez databases, or, if db is provided, to retrieve statistics for a single database, including lists of indexing fields and available link names. Version 2.0 data is requested by default.

Usage

einfo(db = NULL, version = "2.0", retmode = "xml")
einfo(db = NULL, version = "2.0", retmode = "xml")

Arguments

`db`	A valid NCBI database name. If `NULL`, a list of all current NCBI databases is returned.
`version`	Specifies version 2.0 EInfo XML. Set to `NULL` for the older version.
`retmode`	'xml' (default) or 'json'.

Details

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

Value

An einfo object.

Examples

## Not run: 
## Fetch a list of all current Entrez database names
einfo()

## Fetch statistics for an Entrez database and parse
## the data into a data.frame
x <- einfo("gene")
if (x$no_errors()) {
  content(x, "parsed")
}



## Fetch statistics for an Entrez database in JSON format
## and parse the data into a list
x <- einfo("pubmed", retmode = "json")
if (x$no_errors()) {
  content(x, "parsed")
}

## End(Not run)
## Not run: 
## Fetch a list of all current Entrez database names
einfo()

## Fetch statistics for an Entrez database and parse
## the data into a data.frame
x <- einfo("gene")
if (x$no_errors()) {
  content(x, "parsed")
}



## Fetch statistics for an Entrez database in JSON format
## and parse the data into a list
x <- einfo("pubmed", retmode = "json")
if (x$no_errors()) {
  content(x, "parsed")
}

## End(Not run)

elink - finding related data through Entrez links

Description

elink generates a list of UIDs in a specified Entrez database that are linked to a set of input UIDs in either the same or another database. For instance, the ELink utility can find Entrez gene records linked to records in Entrez Protein.

Usage

elink(
  uid,
  dbFrom = NULL,
  dbTo = NULL,
  linkname = NULL,
  usehistory = FALSE,
  cmd = "neighbor",
  correspondence = FALSE,
  querykey = NULL,
  webenv = NULL,
  term = NULL,
  holding = NULL,
  datetype = NULL,
  reldate = NULL,
  mindate = NULL,
  maxdate = NULL
)
elink(
  uid,
  dbFrom = NULL,
  dbTo = NULL,
  linkname = NULL,
  usehistory = FALSE,
  cmd = "neighbor",
  correspondence = FALSE,
  querykey = NULL,
  webenv = NULL,
  term = NULL,
  holding = NULL,
  datetype = NULL,
  reldate = NULL,
  mindate = NULL,
  maxdate = NULL
)

Arguments

`uid`	(Required) A character vector of UIDs.
`dbFrom`	Initial database containing the UIDs in the input list.
`dbTo`	Destination database from which to retrieve linked UIDs. If not provided links will be sought in the database containing the input UIDs.
`linkname`	Name of the Entrez link to retrieve. Every link in Entrez is given a name of the form dbFrom_dbTo_subset.
`usehistory`	If `TRUE` search results are stored directly in the user's Web environment so that they can be used in subsequents calls to `esummary` or `efetch`.
`cmd`	ELink command mode (default: 'neighbor'). See Details.
`correspondence`	if `TRUE` correspondence between query UIDs and destination UIDs is preserved.
`querykey`	Query key.
`webenv`	Web Environment.
`term`	Search query to limit the output set of linked UIDs.
`holding`	Name of LinkOut provider.
`datetype`	Type of date to limit the search. One of 'mdat' (modification date), 'pdat' (publication date) or 'edat' (Entrez date).
`reldate`	umber of days back for which search items are returned.
`mindate`	Minimum date of search range. Format YYYY/MM/DD.
`maxdate`	Maximum date of search range. Format YYYY/MM/DD.

Details

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

If dbTo and dbFrom are set to the same database, ELink will return neighbors within that database.

Elink commands (cmd) specify the function that elink will perform. Available commands are:

"neighbor" (Default) ELink returns a set of UIDs in dbTo linked to the input UIDs in dbFrom.
"neighbor_score" ELink returns a set of UIDs within the same database as the input UIDs along with similarity scores.
"neighbor_history" ELink posts the output UIDs to the Entrez History server and returns a query_key and WebEnv parameter. Alternatively this is achieved by setting usehistory=TRUE

Value

An elink object.

Examples

## Find one set of Gene IDs linked to nuccore GIs 34577062 and 24475906
e <- elink(c("927442695", "312836839"), dbFrom = "nuccore", dbTo = "gene")
e

## Not run: 
## Find related articles to PMID 20210808
p <- elink("20210808", dbFrom = "pubmed", dbTo = "pubmed")
p

## Extract linked UIDs from the "pubmed" to "pubmed_reviews" link
linkset(p, "pubmed_pubmed_reviews")

## or
p["pubmed_pubmed_reviews"]

## retrive the abstracts for the first five linked reviews
abstracts <- efetch(p["pubmed_pubmed_reviews"][1:5], rettype = "abstract")

## End(Not run)
## Find one set of Gene IDs linked to nuccore GIs 34577062 and 24475906
e <- elink(c("927442695", "312836839"), dbFrom = "nuccore", dbTo = "gene")
e

## Not run: 
## Find related articles to PMID 20210808
p <- elink("20210808", dbFrom = "pubmed", dbTo = "pubmed")
p

## Extract linked UIDs from the "pubmed" to "pubmed_reviews" link
linkset(p, "pubmed_pubmed_reviews")

## or
p["pubmed_pubmed_reviews"]

## retrive the abstracts for the first five linked reviews
abstracts <- efetch(p["pubmed_pubmed_reviews"][1:5], rettype = "abstract")

## End(Not run)

epost - uploading UIDs to Entrez

Description

epost uses the Entrez EPost utility to upload primary UIDs to the Entrez History server or append a list of UIDs to an existing set of UIDs attached to a Web Environment.

Usage

epost(uid, db = NULL, webenv = NULL)
epost(uid, db = NULL, webenv = NULL)

Arguments

`uid`	(Required) List of UIDs provided as a character or as an `esearch` object.
`db`	(Required if `uid` is a character vector) Database containing the UIDs in the input list.
`webenv`	(Optional) Web Environment. If provided, this parameter specifies the Web Environment that will receive the UIDs sent by `epost`. `epost` will create a new query key associated with that Web Environment. The `webenv` value is usually returned by a previous call to `esearch`, `epost` or `elink`. If no `webenv` parameter is provided, the EPost utility will create a new Web Environment and post the UIDs to query key 1.

Details

epost returns an integer label called a query key and an encoded cookie string called a Web environment. epost objects can then be used instead of a UID list in subsequent calls to esummary, efetch, or elink.

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

Value

An epost object.

Examples

## post a list of protein GIs to the Entrez History server
gi <- c("194680922", "50978626", "28558982", "9507199", "6678417")
p <- epost(gi, "protein")
p
## post a list of protein GIs to the Entrez History server
gi <- c("194680922", "50978626", "28558982", "9507199", "6678417")
p <- epost(gi, "protein")
p

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

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

espell - retrieving spelling suggestions

Description

For a text query retrieve an XML containing the original query and spelling suggestions.

Usage

espell(term, db = "pubmed")
espell(term, db = "pubmed")

Arguments

`term`	An Entrez text query.
`db`	An Entrez database.

Value

An espell object.

Examples

e <- espell("Chlamidia")
e
e <- espell("Chlamidia")
e

esummary - downloading Document Summaries

Description

esummary performs calls to the NCBI ESummary utility to retrieve document summaries (DocSums) for a list of primary UIDs or for a set of UIDs stored in the user's web environment (using the Entrez History server).

Usage

esummary(
  uid,
  db = NULL,
  retstart = 1,
  retmax = 10000,
  querykey = NULL,
  webenv = NULL,
  retmode = "xml",
  version = "2.0"
)
esummary(
  uid,
  db = NULL,
  retstart = 1,
  retmax = 10000,
  querykey = NULL,
  webenv = NULL,
  retmode = "xml",
  version = "2.0"
)

Arguments

`uid`	(Required) List of UIDs provided either as a character vector, as an `esearch` or `elink` object, or by reference to a Web Environment and a query key obtained directly from objects returned by previous calls to `esearch`, `epost` or `elink`. If UIDs are provided as a plain character vector, `db` must be specified explicitly, and all of the UIDs must be from the database specified by `db`.
`db`	(Required only when `id` is a character vector of UIDs) Database from which to retrieve DocSums.
`retstart`	Numeric index of the first DocSum to be retrieved (default: 1).
`retmax`	Total number of DocSums from the input set to be retrieved (maximum: 10,000).
`querykey`	An integer specifying which of the UID lists attached to a user's Web Environment will be used as input to `efetch`. (Usually obtained drectely from objects returned by previous `esearch`, `epost` or `elink` calls.)
`webenv`	A character string specifying the Web Environment that contains the UID list. (Usually obtained directely from objects returned by previous `esearch`, `epost` or `elink` calls.)
`retmode`	Retrieval mode. (default: 'xml', alternative: 'json')
`version`	If "2.0" `esummary` will retrieve version 2.0 ESummary XML output.

Details

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

Value

An esummary object.

Examples

## Retrieve the Document Summary information for a set of
## UIDs frome the Nuccore datanase.
ds <- esummary(c("1060721643", "1060721620", "1060721618"), "nuccore")
ds

## Not run: 
## parse the XML into a data frame
df <- content(ds, "parsed")
df

## use XPath expressions to extract nodes of interest
ds['//TaxId/text()']

## End(Not run)
## Retrieve the Document Summary information for a set of
## UIDs frome the Nuccore datanase.
ds <- esummary(c("1060721643", "1060721620", "1060721618"), "nuccore")
ds

## Not run: 
## parse the XML into a data frame
df <- content(ds, "parsed")
df

## use XPath expressions to extract nodes of interest
ds['//TaxId/text()']

## End(Not run)

getError

Description

Retrieve a http or XML parsing error from an eutil object.

Usage

getError(x, ...)

## S4 method for signature 'eutil'
getError(x, ...)
getError(x, ...)

## S4 method for signature 'eutil'
getError(x, ...)

Arguments

`x`	An `eutil` object.
`...`	Further arguments passed on to methods.

Value

An eutil_error object.

Methods (by class)

eutil: a http or XML parsing error from an eutil object.

Examples

## Not run: 
e <- efetch("Nonsensical_accession_nr", "protein", rettype = "fasta")
getError(e)

## End(Not run)
## Not run: 
e <- efetch("Nonsensical_accession_nr", "protein", rettype = "fasta")
getError(e)

## End(Not run)

getUrl

Description

Retrieve the URL used to perform an Entrez E-Utilities query.

Usage

getUrl(x, ...)

## S4 method for signature 'eutil'
getUrl(x, ...)
getUrl(x, ...)

## S4 method for signature 'eutil'
getUrl(x, ...)

Arguments

`x`	An `eutil` object.
`...`	Further arguments passed on to methods.

Value

A character string.

Methods (by class)

eutil: etrieve the URL used to perform an Entrez E-Utilities query from an eutil object.

Examples

## Not run: 
e <- efetch("AV333213.1", "protein", rettype = "fasta")
getUrl(e)

## End(Not run)
## Not run: 
e <- efetch("AV333213.1", "protein", rettype = "fasta")
getUrl(e)

## End(Not run)

linkset

Description

Retrieve a linkset from an elink object.

Usage

linkset(x, linkname = NULL, ...)

## S4 method for signature 'entrez_linkset'
linkset(x, linkname = NULL, ...)

## S4 method for signature 'elink'
linkset(x, linkname = NULL, ...)
linkset(x, linkname = NULL, ...)

## S4 method for signature 'entrez_linkset'
linkset(x, linkname = NULL, ...)

## S4 method for signature 'elink'
linkset(x, linkname = NULL, ...)

Arguments

`x`	An `elink` object.
`linkname`	(optional) Name of the Entrez link to retrieve. Every link in Entrez is given a name of the form dbFrom_dbTo_subset. If `NULL`, all available links are retrieved from the object.
`...`	Further arguments passed on to methods.

Value

A list.

Methods (by class)

entrez_linkset: Retrieve a linkset from an elink object.
elink: Retrieve a linkset from an elink object.

Examples

## Not run: 
## Find related articles to PMID 20210808 and xtract linked UIDs from the
## "pubmed" to "pubmed_reviews" link
x <- elink("20210808", dbFrom = "pubmed", dbTo = "pubmed", cmd = "neighbor_score")
linkset(x, "pubmed_pubmed_reviews")

## End(Not run)
## Not run: 
## Find related articles to PMID 20210808 and xtract linked UIDs from the
## "pubmed" to "pubmed_reviews" link
x <- elink("20210808", dbFrom = "pubmed", dbTo = "pubmed", cmd = "neighbor_score")
linkset(x, "pubmed_pubmed_reviews")

## End(Not run)

querykey

Description

An integer query key returned by an ESearch, EPost or ELink call if the History server was used. Otherwise NA.

Usage

querykey(x, ...)

## S4 method for signature 'epost'
querykey(x, ...)

## S4 method for signature 'entrez_uid'
querykey(x, ...)

## S4 method for signature 'esearch'
querykey(x, ...)
querykey(x, ...)

## S4 method for signature 'epost'
querykey(x, ...)

## S4 method for signature 'entrez_uid'
querykey(x, ...)

## S4 method for signature 'esearch'
querykey(x, ...)

Arguments

`x`	An `eutil` object.
`...`	Further arguments passed on to methods.

Value

An integer or NA.

Methods (by class)

epost: Retrieve the querykey from an epost object.
entrez_uid: Retrieve the querykey from an entrez_uid object.
esearch: Retrieve the querykey from an esearch object.

Examples

## Not run: 
e <- esearch("Mus musculus", "taxonomy", usehistory = TRUE)
querykey(e)

## End(Not run)
## Not run: 
e <- esearch("Mus musculus", "taxonomy", usehistory = TRUE)
querykey(e)

## End(Not run)

retmode

Description

Get the “retrieval mode” of an eutil object. It is usually one of xml, json, text, or asn.1. It is set to NULL if “retrieval mode” is not supported by an E-Utility.

Usage

retmode(x, ...)

## S4 method for signature 'eutil'
retmode(x, ...)
retmode(x, ...)

## S4 method for signature 'eutil'
retmode(x, ...)

Arguments

`x`	An `eutil` object.
`...`	Further arguments passed on to methods.

Value

A character string or NULL.

Methods (by class)

eutil: Access the “retrieval mode” of an eutil object.

Examples

## Not run: 
e <- efetch("10090", "taxonomy")
retmode(e)

## End(Not run)
## Not run: 
e <- efetch("10090", "taxonomy")
retmode(e)

## End(Not run)

rettype

Description

Get the “retrieval type” of an eutil object. See here for the available retrieval types for different NCBI databases.

Usage

rettype(x, ...)

## S4 method for signature 'eutil'
rettype(x, ...)
rettype(x, ...)

## S4 method for signature 'eutil'
rettype(x, ...)

Arguments

`x`	An `eutil` object.
`...`	Further arguments passed on to methods.

Value

A character string.

Methods (by class)

eutil: Access the “retrieval type” of an eutil object.

Examples

## Not run: 
e <- esearch("Mus musculus", "taxonomy")
rettype(e)

## End(Not run)
## Not run: 
e <- esearch("Mus musculus", "taxonomy")
rettype(e)

## End(Not run)

uid

Description

Retrieve the list of UIDs returned by a call to ESearch or ELink.

Usage

uid(x, ...)

## S4 method for signature 'entrez_linkset'
uid(x, ...)

## S4 method for signature 'elink'
uid(x, ...)

## S4 method for signature 'entrez_uid'
uid(x, ...)

## S4 method for signature 'esearch'
uid(x, ...)
uid(x, ...)

## S4 method for signature 'entrez_linkset'
uid(x, ...)

## S4 method for signature 'elink'
uid(x, ...)

## S4 method for signature 'entrez_uid'
uid(x, ...)

## S4 method for signature 'esearch'
uid(x, ...)

Arguments

`x`	An `eutil` object.
`...`	Further arguments passed on to methods.

Value

A character vector.

Methods (by class)

entrez_linkset: Retrieve the list of UIDs from an entrez_linkset object.
elink: Retrieve the list of UIDs from an elink object.
entrez_uid: Retrieve the list of UIDs from an entrez_uid object.
esearch: Retrieve the list of UIDs from an esearch object.

Examples

## Not run: 
e <- esearch("Mus musculus", "taxonomy")
uid(e)

## End(Not run)
## Not run: 
e <- esearch("Mus musculus", "taxonomy")
uid(e)

## End(Not run)

webenv

Description

Retrieve the Web environment string returned from an ESearch, EPost or ELink call. NA if the History server was not used.

Usage

webenv(x, ...)

## S4 method for signature 'epost'
webenv(x, ...)

## S4 method for signature 'entrez_uid'
webenv(x, ...)

## S4 method for signature 'esearch'
webenv(x, ...)
webenv(x, ...)

## S4 method for signature 'epost'
webenv(x, ...)

## S4 method for signature 'entrez_uid'
webenv(x, ...)

## S4 method for signature 'esearch'
webenv(x, ...)

Arguments

`x`	An `eutil` object.
`...`	Further arguments passed on to methods.

Value

A character string or NA.

Methods (by class)

epost: Retrieve the webenv string from an epost object.
entrez_uid: Retrieve the webenv string from an entrez_uid object.
esearch: Retrieve the webenv string from an esearch object.

Examples

## Not run: 
e <- esearch("Mus musculus", "taxonomy", usehistory = TRUE)
webenv(e)

## End(Not run)
## Not run: 
e <- esearch("Mus musculus", "taxonomy", usehistory = TRUE)
webenv(e)

## End(Not run)

Package 'reutils'

Help Index

reutils: Talk to the NCBI EUtils

Description

Details

Main functions

Package options

Author(s)

See Also

Examples

EFetch accessors

Description

Usage

Arguments

Value

Examples

EInfo accessors

Description

Usage

Arguments

Value

See Also

Examples

ELink Accessors

Description

Usage

Arguments

Value

Examples

ESearch Accessors

Description

Usage

Arguments

Value

Examples

ESummary accessors

Description

Usage

Arguments

Value

Examples

Extract the data content from an Entrez request

Description

Usage

Arguments

Methods (by class)

See Also

Examples

database

Description

Usage

Arguments

Value

Methods (by class)

See Also

Examples

ecitmatch - searching PubMed with citation data

Description

Usage

Arguments

Value

Examples

efetch - downloading full records

Description

Usage

Arguments

Details

Value

Note

See Also

Examples

egquery - performing a global Entrez search

Description

Usage

Arguments

Details

Value

Examples

einfo - getting database statistics and search fields

Description