Skip to contents

scimapR treats the return type of its documented accessors as a contract. The column set (names and types) of an accessor's documented return value will not change without a lifecycle deprecation and a corresponding NEWS.md entry. New columns may be added (a non-breaking change); existing documented columns will not be removed or retyped silently.

This policy exists because a silent list -> tibble change in sm_coverage_breakdowns() between 0.2.0 and 0.3.0 broke downstream code. From 0.4.0, accessors that expose a tidy table take a tidy = TRUE argument whose column set is the stable contract.

Audited accessors and their stable return shapes

sm_coverage_breakdowns() (tidy = TRUE)

A long tibble: dimension, level, n_reference, n_matched, recall, n_corpus, precision, f1.

summary.sm_coverage()

A one-row tibble: recall, precision, f1, n_corpus, n_reference, n_matched, n_corpus_only, n_reference_only and n_corpus_matched (the corpus records paired with a reference record, the numerator of precision; added after scimapR 0.4.0).

sm_affiliation_summary()

A tibble: institution, match_signal (factor, see sm_affiliation_signals()), n_authorships, n_works, example_evidence.

sm_affiliation_unmatched()

A tibble: raw_affiliation (character), n_authorships and n_works (integer), sorted by n_authorships descending and then by raw_affiliation.

sm_reconcile() (summary())

A one-row tibble: n_a, n_b, n_in_both, n_only_a, n_only_b, jaccard. The name n_in_both is unchanged; earlier documentation incorrectly called it n_both.

sm_metric_summary()

A one-row tibble: metric, n, mean, median, and (when robust = TRUE) median_ci_low, median_ci_high, pp_top10, n_boot. It carries the attribute impact_source (character): where the summarised values come from, such as "works$fwci (OpenAlex)" for metric = "cnci" on a corpus with OpenAlex impact fields, and NA on the n = 0 row (added after scimapR 0.4.0, without changing the columns). pp_top10 now shares ties fractionally: its default value equals top_pct relative to the corpus itself. Use top_reference for an external comparison. The column name and numeric type are unchanged.

sm_citation_window()

A tibble with one row per work, in the order of corpus$works: work_id (character), year and window (integer), citations (integer, NA for a work without yearly counts or publication year) and complete (logical); a 0-row tibble with these columns for a corpus without works (added after scimapR 0.4.0).

sm_self_citation() (by_entity / by_work / provenance)

Tidy tibbles with the columns documented at sm_self_citation().

Controlled vocabularies

Free-text controlled columns are emitted as factors with exported level sets, so downstream filtering is reliable: see sm_affiliation_signals() (match_signal), sm_affiliation_methods() (match_method), and sm_match_types() (coverage and reconciliation match_type).

The vocabulary column of corpus$concepts is the exception: it stays character, so concept tables bind and hash as before, and its values are the names returned by sm_concept_vocabularies(). Readers write these names, and sm_corpus() and sm_corpus_from_tables() rename legacy spellings to them. sm_concept_vocabularies(describe = TRUE) returns a tibble with the factor columns level and family and a character description.

The works$oa_status column also stays character, so tables bind and hash as before. Its values are those of sm_oa_statuses().