Enhance Zotero Records with External Metadata via Zotero Lookups

This function iterates over a data frame (or tibble) of Zotero records and attempts to enhance each record by retrieving additional metadata from external sources. It uses DOI or ISBN information, via the c2z package, to fetch external metadata and then merges these updates into the original Zotero record. Special handling is provided for records representing book sections.

Usage

ZoteroEnhancer(
  zotero.data,
  external.data = NULL,
  use.doi = TRUE,
  use.semantic = TRUE,
  use.isbn = TRUE
)

Arguments

zotero.data

A data frame (or tibble) containing Zotero records. Each row represents a record that may include fields such as abstractNote, DOI, url, ISBN, key, itemType, pages, and creators.

external.data

Optional. A data frame or list containing pre-fetched external metadata. If provided and non-empty, the function will use this external metadata to update the Zotero records instead of querying the external APIs. Defaults to NULL.

use.doi

Logical; if TRUE (default), the function will attempt to retrieve external metadata using DOI information. Defaults to TRUE.

use.semantic

Logical; if TRUE (default), the function will attempt to retrieve external metadata from Semantic Scholar using DOI information. Defaults to TRUE.

use.isbn

Logical; if TRUE (default), the function will attempt to retrieve external metadata using ISBN information when DOI retrieval is not successful. Defaults to TRUE.

Value

A data frame containing the enhanced Zotero records with external metadata merged into the original records.

Details

For each record in zotero.data, the function performs the following steps:

1. If external.data is provided and non-empty, that data is used to update the record.

2. Otherwise, the function skips processing the record if an abstract already exists.

3. It then attempts to extract a DOI from the DOI field, or if missing, from the url field.

4. The ISBN field is processed by removing spaces and extracting the first value (in case of comma separation).

5. If a valid DOI is found and use.doi is TRUE, external metadata is retrieved using c2z::ZoteroDoi(). Otherwise, if an ISBN is available and use.isbn is TRUE, metadata is retrieved using c2z::ZoteroIsbn().

6. Once external metadata is successfully retrieved, an internal helper function UpdateTibble is called. This helper function merges the external metadata into the original record. For book sections, additional adjustments are made to handle creator information, pages, and edition fields.

7. Finally, the enhanced record is merged back into the original data frame using UpdateInsert().

Examples

if (FALSE) { # \dontrun{
  # Enhance Zotero records using DOI/ISBN lookup:
  example <- Cristin("762394", silent = TRUE)$results
  print(example$libraryCatalog)
  example$DOI <- "https://doi.org/10.22358/jafs/74164/2007"
  enhanced.data <- ZoteroEnhancer(example)
  print(enhanced.data$libraryCatalog)
} # }