Package {puremoe}

Build a Citation Network from an iCite Corpus

Description

Converts an icites data.table into a tidy graph representation (nodes + edges) suitable for igraph or tidygraph. Only edges where both endpoints are present in the corpus are retained, so the graph is bounded to the papers you already have metadata for.

Usage

citation_network(icites)

Arguments

Details

RCR and is_clinical are carried as node attributes, making the resulting graph immediately weighted by field-normalized impact and enabling bench-to-bedside edge filtering without any additional API calls.

Value

A named list with two data.tables:

nodes

One row per PMID. Contains all iCite metadata columns except citation_net. Key columns: pmid, relative_citation_ratio, nih_percentile, is_clinical.

edges

One row per within-corpus directed citation. Columns: from_pmid (the citing paper), to_pmid (the cited paper).

Examples

## Not run: 
# network from a seed corpus
pmids |>
  get_records(endpoint = "icites") |>
  citation_network()

# expand first, then fetch iCite metadata for the full network
snowball <- pmids |>
  get_records(endpoint = "icites") |>
  citation_snowball()

snowball$pmid |>
  get_records(endpoint = "icites") |>
  citation_network()

# filter to clinical citation targets
snowball <- pmids |>
  get_records(endpoint = "icites") |>
  citation_snowball()

net <- snowball$pmid |>
  get_records(endpoint = "icites") |>
  citation_network()

clinical_edges <- net$edges |>
  merge(net$nodes[, .(pmid, is_clinical)],
        by.x = "to_pmid", by.y = "pmid") |>
  subset(is_clinical == TRUE)

## End(Not run)

Expand a PMID Corpus via One-Hop iCite Citation Snowballing

Description

Starting from an icites data.table returned by get_records(endpoint = "icites"), follows the citation links already present in the citation_net column and returns a candidate table. The function does not call iCite again; use get_records(endpoint = "icites") explicitly on the returned PMIDs if metadata is needed for the expanded corpus.

Usage

citation_snowball(
  icites,
  max_nodes = 2000,
  direction = c("both", "citing", "cited"),
  min_links = 2
)

Arguments

Value

A data.table with one row per seed or candidate PMID. Columns are pmid, seed, cited_links, citing_links, and link_count. cited_links counts seed papers that cite the candidate; citing_links counts seed papers cited by the candidate.

Examples

## Not run: 
pmids <- search_pubmed("metformin AND PCOS [TiAb]")

snowball <- pmids |>
  get_records(endpoint = "icites") |>
  citation_snowball(direction = "cited", min_links = 2)

snowball$pmid |> get_records(endpoint = "pubmed_abstracts")

## End(Not run)

MeSH Descriptor Frequencies Across PubMed

Description

Baseline frequencies for MeSH descriptors computed from a local PostgreSQL mirror of PubMed (April 2026). For each descriptor, counts reflect the number of distinct PMIDs indexed with that term; proportions use the full PubMed corpus of 39,703,112 PMIDs as denominator. Descriptor UI and canonical name are joined from the NLM MeSH thesaurus. Intended as a baseline for mesh_keyness against arbitrary PubMed subsets.

Usage

data_mesh_frequencies

Format

A data.table with 30,521 rows and 4 columns:

DescriptorUI

MeSH descriptor unique identifier (e.g., D000001)

DescriptorName

Canonical MeSH descriptor name

n_pmids

Number of distinct PubMed records indexed with this descriptor

prop_total

Proportion of all 39,703,112 PubMed PMIDs indexed with this descriptor

Source

Computed from mesh_descriptor table in a local PubMed PostgreSQL mirror; descriptor metadata from the NLM MeSH Thesaurus (April 2026).

Download and Combine 'MeSH' and Supplemental Thesauruses

Description

This function downloads and combines the 'MeSH' (Medical Subject Headings) Thesaurus and a supplemental concept thesaurus. The data is sourced from specified URLs and stored locally for subsequent use. By default, the data is stored in a temporary directory. Users can opt into persistent storage by setting 'use_persistent_storage' to TRUE and optionally specifying a path.

Usage

data_mesh_thesaurus(
  path = NULL,
  use_persistent_storage = FALSE,
  force_install = FALSE
)

Arguments

Value

A data.table containing the combined MeSH and supplemental thesaurus data.

Examples

if (interactive()) {
  data <- data_mesh_thesaurus()
}

Download and Load 'MeSH' Trees Data

Description

This function downloads and loads the 'MeSH' (Medical Subject Headings) Trees data.

Usage

data_mesh_trees(
  path = NULL,
  use_persistent_storage = FALSE,
  force_install = FALSE
)

Arguments

Details

The data is sourced from specified URLs and stored locally for subsequent use. By default, the data is stored in a temporary directory. Users can opt into persistent storage by setting 'use_persistent_storage' to TRUE and optionally specifying a path.

Value

A data frame containing the MeSH Trees data.

Examples

if (interactive()) {
  data <- data_mesh_trees()
}

Get Information About Available Endpoints

Description

This function provides detailed information about the available endpoints in the package, including column descriptions, parameters, rate limits, and usage notes.

Usage

endpoint_info(endpoint = NULL, format = c("list", "json"))

Arguments

Value

If endpoint is NULL, returns a character vector of available endpoint names. If endpoint is specified, returns a list (or JSON string) with detailed information about that endpoint including description, columns, parameters, rate limits, and notes.

Examples

if (interactive()) {
  # List all available endpoints
  endpoint_info()
  
  # Get information about a specific endpoint
  endpoint_info("pubmed_abstracts")
  
  # Get information in JSON format
  endpoint_info("icites", format = "json")
}

Retrieve Data from 'NLM'/'PubMed' databases Based on PMIDs

Description

This function retrieves different types of data (like 'PubMed' records, affiliations, 'iCites 'data, etc.) from 'PubMed' based on provided PMIDs. It supports parallel processing for efficiency.

Usage

get_records(
  pmids,
  endpoint = c("pubtator", "pubtations", "icites", "pubmed_affiliations",
    "pubmed_abstracts", "pmc_fulltext"),
  cores = 3,
  sleep = 1,
  ncbi_key = NULL,
  icite_timeout = getOption("puremoe.icite_timeout", 15)
)

Arguments

Details

For the 'pmc_fulltext' endpoint, provide full URLs to PMC Cloud Service XML files. Use pmid_to_ftp to convert PMIDs to PMC IDs and full-text URLs first.

Value

A data.table containing combined results from the specified endpoint, except for the PubTator endpoint, which returns a list with entities and relations data.tables.

Examples

if (interactive()) {
  pmids <- c("38136652")
  results <- get_records(pmids, endpoint = "pubmed_abstracts", cores = 1)
}

MeSH Descriptor Keyness for a Retrieved Corpus

Description

Scores the MeSH descriptors of a retrieved corpus against PubMed-wide descriptor frequencies, identifying the terms that are over- or under-represented relative to PubMed as a whole. This is a local transform of the pubmed_abstracts output – it makes no API calls – and is intended to characterise a corpus and to guide search refinement and expansion.

Usage

mesh_keyness(
  records,
  frequencies = NULL,
  measure = c("log_odds", "g2"),
  smoothing = 0.5,
  min_count = 1L
)

Arguments

Details

Keyness is computed on document incidence: for each descriptor, the number of distinct corpus PMIDs indexed with it is compared against the number of distinct PubMed PMIDs indexed with it (data_mesh_frequencies).

Value

A data.table, one row per scored descriptor, ordered by keyness (descending). Common columns: DescriptorUI, DescriptorName, corpus_count, corpus_total, corpus_prop, baseline_count, baseline_total, baseline_prop, and direction ("over"/"under"). With measure = "log_odds": log_odds, std_error, z. With measure = "g2": g2.

Examples

## Not run: 
pmids   <- search_pubmed('"doxorubicin"[TiAb] AND "cardiotoxicity"[TiAb]')
records <- get_records(pmids, endpoint = "pubmed_abstracts")

mesh_keyness(records)                       # most over-represented descriptors
mesh_keyness(records, measure = "g2")

## End(Not run)

Convert PubMed IDs (PMIDs) to PMC IDs and Full-Text URLs

Description

This function converts PMIDs to PMC IDs, then fetches the full-text file URLs from the PMC Open Access service. It combines both steps into a single workflow.

Usage

pmid_to_ftp(
  pmids,
  batch_size = 200L,
  sleep = 0.5,
  verbose = FALSE,
  ncbi_key = NULL
)

Arguments

Value

A data.table with columns:

• pmid: The input PubMed ID

• pmcid: The corresponding PMC ID

• doi: The corresponding DOI (NA if not available)

• url: The full HTTPS URL for downloading PMC full text

Results are filtered to only include rows with valid URLs (open access articles), ordered by PMID. Returns NULL with a message if the API is unavailable or returns invalid data.

Examples

if (interactive()) {
  # Convert PMIDs to PMC IDs and get full-text URLs
  result <- pmid_to_ftp(c("11250746", "11573492"))
}

Convert PubMed IDs (PMIDs) to PMC IDs

Description

This function converts a vector of PubMed IDs (PMIDs) to their corresponding PubMed Central (PMC) IDs and DOIs using the NCBI ID Converter API.

Usage

pmid_to_pmc(pmids, batch_size = 200L, sleep = 0.5)

Arguments

Value

A data.table with columns:

• pmid: The input PubMed ID

• pmcid: The corresponding PMC ID (NA if not available in PMC)

• doi: The corresponding DOI (NA if not available)

Results are ordered by PMID. Returns NULL with a message if the API is unavailable or returns invalid data.

Examples

if (interactive()) {
  # Convert a single PMID to PMC ID
  result <- pmid_to_pmc("12345678")
  
  # Convert multiple PMIDs
  pmids <- c("12345678", "23456789", "34567890")
  result <- pmid_to_pmc(pmids, batch_size = 10, sleep = 1)
}

Add Sentence Context to PubTator Entities and Relations

Description

Adds sentence identifiers and sentence-relative spans to PubTator entity mentions, then carries compact sentence anchors onto relation rows.

Usage

pubtator_context(pubtator)

Arguments

Value

A list with entities, relations, and sentences data.tables. Entity rows preserve their original start/end spans and gain sentence_id, sentence_start, and sentence_end. Relation rows gain role-specific entity labels and sentence anchors, plus same_sentence and sentence_distance.

Count PubTator Entity Co-occurrence from Sentence Context

Description

Counts pairs of biomedical entities that co-occur in the same sentence (window = 0) or within window sentences of each other, using the contextualized entity table returned by pubtator_context. Co-occurrence is computed within each pmid/tiab passage; title and abstract sentence IDs are not compared to one another.

Usage

pubtator_cooccurrence(x, window = 0L, by = c("type", "entity"))

Arguments

Details

Entities are de-duplicated to one mention per sentence before pairing, and pairs of the same entity (identical type, identifier, and text) are dropped.

Value

A data.table. With by = "type": type_x, type_y, n (co-occurrence instances), and n_pmids (distinct documents), ordered by n. With by = "entity": the same plus identifier_x/text_x/identifier_y/ text_y.

Examples

## Not run: 
pmids <- search_pubmed('"biomarker"[TiAb] AND "cancer"[TiAb]')

ctx <- pmids |>
  get_records(endpoint = "pubtator") |>
  pubtator_context()

ctx |> pubtator_cooccurrence(window = 0, by = "type")
ctx |> pubtator_cooccurrence(window = 1, by = "entity")

## End(Not run)

Build a PubTator Relation Network with Evidence

Description

Converts a pubtator_context result into a relation network: graph-ready nodes and edges, plus a lean evidence table that maps each edge back to the PubTator relation row and, when the endpoint mentions share a sentence, the supporting sentence.

Usage

pubtator_network(x)

Arguments

Value

A named list with three data.tables:

nodes

One row per normalized relation endpoint. Columns: id, type, label, n_mentions, and n_pmids. Entity identifiers are used when present; otherwise nodes fall back to type:text.

edges

One row per directed PubTator relation edge. Columns: from, to, relation_type, weight, n_pmids, and n_sentences.

evidence

One row per PubTator relation row. Columns: from, to, relation_type, pmid, relation_id, same_sentence, sentence_distance, and sentence. The sentence is populated only when the relation endpoints share a sentence.

See Also

pubtator_context, pubtator_cooccurrence

Examples

## Not run: 
pmids <- search_pubmed('"doxorubicin"[TiAb] AND "cardiotoxicity"[TiAb]')

ctx <- pmids |>
  get_records(endpoint = "pubtator") |>
  pubtator_context()

net <- pubtator_network(ctx)
net$nodes
net$edges
net$evidence

## End(Not run)

Search 'PubMed' Records

Description

Performs a 'PubMed' search based on a query, optionally filtered by publication years. Returns a unique set of 'PubMed' IDs matching the query.

Usage

search_pubmed(
  x,
  start_year = NULL,
  end_year = NULL,
  retmax = 9999,
  use_pub_years = FALSE
)

Arguments

Value

Numeric vector of unique PubMed IDs.

Examples

if (interactive()) {
  ethnob1 <- search_pubmed("ethnobotany")
}