pmEnrichCitations: Enrich a PubMed dataframe with citation data

Description

Adds cited references (CR field), reference counts (NR field), and optionally citation counts (TC field) to a dataframe created by pmApi2df.

Usage

pmEnrichCitations(
  df,
  P = NULL,
  api_key = NULL,
  resolve_pmids = TRUE,
  only_multiple = FALSE,
  include_TC = TRUE,
  batch_size = 200
)

Value

The input dataframe with updated CR (cited references),

NR (number of references), and TC (times cited, if

include_TC = TRUE) fields.

Arguments

df: is a dataframe. A bibliometric dataframe produced by pmApi2df.
P: is the optional list returned by pmApiRequest or pmFetchById that produced df. Reuse it to avoid an extra round-trip when references are already available. If NULL, the function calls pmFetchById on df$PMID to retrieve the underlying XML.
api_key: is a character. It contains a valid API key for the NCBI E-utilities. Default is api_key=NULL. The API key can also be set via the environment variable PUBMED_API_KEY or ENTREZ_KEY.
resolve_pmids: logical. When TRUE (default) the function fetches metadata for every cited PMID present in the references and assembles structured WoS-style citation strings ("AUTHOR YYYY, JOURNAL, V##, P##, DOI ..."). When FALSE the free-text <Citation> block from the XML is used as-is.
only_multiple: logical. When TRUE only references cited by more than one source article are resolved to metadata (faster and cheaper). References not resolved keep their free-text citation. Defaults to FALSE.
include_TC: logical. When TRUE (default) also call pmCitedBy for each source article and write the citation count to df$TC. Disable to skip this step.
batch_size: integer. Number of records per API call when fetching metadata. Defaults to 200 (NCBI's hard cap for efetch).

Details

Cited references are extracted from the article's PubMed XML (<ReferenceList>). This is more reliable than the previous E-Link pubmed_pubmed_refs approach, which only worked for articles deposited in PMC. References whose XML carries an ArticleId IdType="pubmed" are resolved to bibliographic metadata in batched efetch requests so that CR matches the WoS convention used by bibliometrix; references with only free-text citations are kept verbatim (uppercased).

Examples

Run this code

# \donttest{
query <- "bibliometric*[Title/Abstract] AND english[LA]
         AND Journal Article[PT] AND 2000:2020[DP]"
D <- pmApiRequest(query = query, limit = 10, api_key = NULL)
M <- pmApi2df(D)
M <- pmEnrichCitations(M, P = D)        # avoid the extra fetch
# }