Joins cached enrichment data into the matching sm_corpus sub-tibbles by
their key columns, returning an updated, schema-valid sm_corpus. This
replaces hand-written cache-to-corpus joins (which are easy to get wrong —
e.g. a bind_rows() that coerces a NULL element to a logical column).
Usage
sm_materialise(
corpus,
sources,
.by = NULL,
overwrite = FALSE,
call = rlang::caller_env()
)Arguments
- corpus
An
sm_corpus.- sources
Either a named list whose names are corpus sub-tables (
works,authors,authorships,sources,institutions,references,concepts, ...) and whose elements are tibbles or paths to cached.rds/.parquetfiles; or a single directory path containing<table>.rds/<table>.parquetfiles.- .by
Optional named list mapping table name to its join key column(s). Missing or empty key values never match. Defaults:
works,provenanceandscreeningusework_id;authorsuseauthor_id;institutionsuseinstitution_id;sourcesusesource_id;authorshipsuse(work_id, author_id);referencesuse(work_id, ref_index)(formerly(work_id, cited_work_id));conceptsuse(work_id, concept_id). For keywords, use.by = list(concepts = c("work_id", "vocabulary", "concept_name")).- overwrite
Logical (default
FALSE). WhenFALSE, enrichment only fillsNAcells of overlapping columns; populated cells are never overwritten. WhenTRUE, non-NAenrichment values win.- call
Caller environment for error reporting.
Value
An updated, validated sm_corpus with the enrichment columns merged
into the relevant sub-tables. New columns are added; existing rows are
preserved (this is a column-enrichment join, not a row append).
Details
Missing key columns warn and skip the source. Enrichment rows with a
missing key value are dropped with scimapR_materialise_na_keys;
corpus rows with missing keys keep their values and produce a
scimapR_materialise_unmatched_rows message. A repeated complete key in
works, authors, institutions, sources, references or concepts
aborts with scimapR_materialise_key_not_unique. The group keys in
authorships, provenance and screening can repeat: every matching row
receives the enrichment. Duplicate enrichment keys warn and keep the first.
Concept vocabularies used as keys are normalised on both sides before
matching. After a merge into concepts,
legacy spellings in its vocabulary column are renamed to the names of
sm_concept_vocabularies(), without a message.
Examples
corpus <- sm_example_corpus(n_works = 10, seed = 1)
metrics <- tibble::tibble(work_id = corpus$works$work_id,
cnci = runif(10, 0.5, 2))
corpus2 <- sm_materialise(corpus, sources = list(works = metrics))
#> ✔ Materialised 10 enrichment rows into works (+1 column).
"cnci" %in% names(corpus2$works)
#> [1] TRUE