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_onlyandn_corpus_matched(the corpus records paired with a reference record, the numerator ofprecision; added after scimapR 0.4.0).sm_affiliation_summary()A tibble:
institution,match_signal(factor, seesm_affiliation_signals()),n_authorships,n_works,example_evidence.sm_affiliation_unmatched()A tibble:
raw_affiliation(character),n_authorshipsandn_works(integer), sorted byn_authorshipsdescending and then byraw_affiliation.sm_reconcile()(summary())A one-row tibble:
n_a,n_b,n_in_both,n_only_a,n_only_b,jaccard. The namen_in_bothis unchanged; earlier documentation incorrectly called itn_both.sm_metric_summary()A one-row tibble:
metric,n,mean,median, and (whenrobust = TRUE)median_ci_low,median_ci_high,pp_top10,n_boot. It carries the attributeimpact_source(character): where the summarised values come from, such as"works$fwci (OpenAlex)"formetric = "cnci"on a corpus with OpenAlex impact fields, andNAon then = 0row (added after scimapR 0.4.0, without changing the columns).pp_top10now shares ties fractionally: its default value equalstop_pctrelative to the corpus itself. Usetop_referencefor 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),yearandwindow(integer),citations(integer,NAfor a work without yearly counts or publication year) andcomplete(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().