pmCollect: Collect and process PubMed bibliographic data in one step

Description

A convenience wrapper that executes the full pubmedR workflow: query building, record count check, metadata download, conversion to data frame, and (optionally) citation enrichment via NCBI E-Link.

Usage

pmCollect(
  query = NULL,
  terms = NULL,
  fields = "Title/Abstract",
  language = NULL,
  pub_type = NULL,
  date_range = NULL,
  mesh_terms = NULL,
  limit = 2000,
  enrich = FALSE,
  format = "bibliometrix",
  api_key = NULL,
  batch_size = 200,
  verbose = TRUE
)

Value

a data frame containing bibliographic records, compatible with the bibliometrix package when format = "bibliometrix".

Arguments

query: is a character. A PubMed search query in Entrez syntax. Alternatively, if terms is provided, the query is built automatically using pmQueryBuild and this argument is ignored.
terms: is a character or character vector or NULL. Search terms passed to pmQueryBuild. When provided, a query is built automatically and the query argument is ignored. Default is NULL.
fields: is a character or character vector. PubMed search tags used when building the query from terms. Default is "Title/Abstract".
language: is a character or NULL. Language filter for query building. Default is NULL.
pub_type: is a character or NULL. Publication type filter for query building. Default is NULL.
date_range: is a character vector of length 2 or NULL. Date range in format c("YYYY", "YYYY"). Default is NULL.
mesh_terms: is a character or character vector or NULL. MeSH terms for query building. Default is NULL.
limit: is numeric. Maximum number of records to download. Default is 2000.
enrich: is logical. If TRUE, citation counts (TC) and cited references (CR) are added via pmEnrichCitations. Default is FALSE because enrichment makes 2 API calls per article and can be slow for large collections.
format: is a character. Output format passed to pmApi2df. Either "bibliometrix" (default) or "raw".
api_key: is a character or NULL. NCBI API key. Can also be set via the environment variable PUBMED_API_KEY or ENTREZ_KEY. Default is NULL.
batch_size: is numeric. Records per API request. Default is 200.
verbose: is logical. If TRUE (default), prints progress messages.

Details

This function chains together the core pubmedR functions in the recommended order:

Query: If terms is provided, builds the query with pmQueryBuild; otherwise uses the query string directly.
Count: Checks the total number of matching records with pmQueryTotalCount.
Download: Fetches metadata with pmApiRequest.
Convert: Transforms XML to a data frame with pmApi2df.
Enrich (optional): Adds citation data with pmEnrichCitations.

Examples

Run this code


# \donttest{
# Using a raw query string
M <- pmCollect(
  query = "bibliometric*[Title/Abstract] AND english[LA] AND 2020:2024[DP]",
  limit = 50
)

# Using the query builder parameters
M <- pmCollect(
  terms = "bibliometric*",
  language = "english",
  pub_type = "Journal Article",
  date_range = c("2020", "2024"),
  limit = 50
)

# With citation enrichment (slower, requires extra API calls)
M <- pmCollect(
  terms = "bibliometric*",
  date_range = c("2023", "2024"),
  limit = 10,
  enrich = TRUE
)
# }