A tested, extensible institution matcher for the authorships table. It
tags each authorship with the institution it belongs to, using a dictionary
of name variants (multilingual and synonym-aware) and an optional
email-domain fallback for records whose affiliation string is missing.
Because the matcher operates per authorship row, it naturally handles secondary / multiple affiliations per author (each authorship row is matched independently).
Usage
sm_affiliation_match(
corpus,
patterns = sm_affiliation_dict,
fields = NULL,
email_domain_fallback = TRUE,
postcode_signal = FALSE,
unicode = TRUE,
call = rlang::caller_env()
)Arguments
- corpus
An
sm_corpusobject.- patterns
A dictionary of institution name variants. Either:
a named list mapping each canonical institution name to a character vector of case-insensitive regex variant patterns, or
a data frame with columns
institution,pattern, and an optionalemail_domain(the form of the bundled sm_affiliation_dict).
Defaults to sm_affiliation_dict.
- fields
Character vector of
authorshipscolumns to search for affiliation text. Defaults to"raw_affiliation"(plus"email"if such a column exists). Values across multiple fields are concatenated per row.- email_domain_fallback
Logical; if
TRUE(default) and an authorship has no pattern match but does have an email address (in anemailcolumn), match the email's domain against the dictionary'semail_domainentries.- postcode_signal
Logical (default
FALSE). WhenTRUEand the dictionary carries apostcodecolumn, a postcode match is attempted as a last resort (lowest priority, after name tokens and email domains) so existing matches do not shift. Off by default.- unicode
Logical (default
TRUE). Match the patterns in Unicode mode, so\w,\b,\d,\sand POSIX classes such as[[:alpha:]]know non-ASCII letters, digits and spaces (see Details).FALSEgives the ASCII-only classes of scimapR 0.4.0 and earlier, to reproduce earlier results.- call
Caller environment for error reporting.
Value
The corpus with its authorships table gaining (or having
updated) four columns:
- institution_match
Canonical institution name, or
NA.- match_method
"pattern","email_domain","postcode", or"none".- match_signal
The signal that fired:
"name_token","email_domain","postcode", or"none". Precedence (highest first): name token, email domain, postcode.- match_evidence
The actual substring / domain / postcode that triggered the match (an audit trail), or
NA.
Type-stable: a corpus with no authorships is returned unchanged with the
four columns present and 0 rows. See sm_affiliation_summary() for a tidy
breakdown.
Details
Dictionary patterns are case-insensitive Perl-compatible regular
expressions (PCRE) with Unicode-aware \w, \b, \d and \s, matched
against the affiliation text of each authorship. The rows are tried in
dictionary order and the first pattern that matches wins, so list specific
patterns before generic ones. sm_affiliation_unmatched() lists the most
frequent affiliation strings that nothing matched.
In Unicode mode (unicode = TRUE, the default) each pattern is prefixed
with the PCRE item (*UCP) unless its leading items already include it.
Umlauts, accented letters and the sharp s are then word characters: \w
consumes them, \b finds the edge of a word that starts or ends with one,
and POSIX classes such as [[:alpha:]] are Unicode-aware too. In ASCII
mode (unicode = FALSE) every non-ASCII letter is a non-word character,
like punctuation: a pattern such as veterin\w+rwesens cannot match the
German word spelled with an a-umlaut, and \b finds no edge between a
space and a word that starts with an umlaut. Unicode mode can therefore
also lose matches. A pattern that used \W, \S, \D or \B to stand
for a non-ASCII letter no longer matches it, and \b no longer finds an
edge between an ASCII letter and a non-ASCII letter next to it: the
shipped pattern \bembl\b does not match "EMBL" directly followed by an
umlaut, as in a German compound word. To keep ASCII semantics in one
place, write the class out, for example [A-Za-z0-9_] instead of \w.
unicode = FALSE gives the matches of scimapR 0.4.0.
sm_attribute_institution() calls sm_affiliation_match() with its
defaults, and so matches in Unicode mode, when the corpus has no
institution_match column; running sm_affiliation_match(unicode = FALSE)
first gives its earlier results. sm_count(level = "institution") no
longer matches affiliations itself: it counts each authorship by its
institution label, institution_match first, and by its raw affiliation
string when it has none (see sm_count()).
The optional postcode column (used with postcode_signal = TRUE) is
matched case-sensitively as a whole word, in the same mode: it is wrapped
in \b, any run of whitespace in it matches any amount of whitespace
(including none), and it is used as a regular expression without escaping.
To extend the dictionary, append rows to sm_affiliation_dict (or build your
own data frame with the same columns) and pass it as patterns. For example
rbind(sm_affiliation_dict, tibble::tibble(institution = "My Uni", pattern = "my university", email_domain = "myuni.edu")).
Examples
corpus <- sm_example_corpus(n_works = 5, n_authors = 5)
corpus$authorships$raw_affiliation[1] <- "Diakoniekrankenhaus Berlin"
matched <- sm_affiliation_match(corpus)
#> ✔ Affiliation matching flagged 1 authorship across 1 institution.
#> ℹ By signal: name_token: 1. See `sm_affiliation_summary()` for the full
#> breakdown.
matched$authorships$institution_match[1]
#> [1] "Diakonie Hospital"
# In Unicode mode \w consumes the umlaut of a German unit name
corpus$authorships$raw_affiliation[2] <-
"Zentrales Institut des Veterin\u00e4rwesens Nordstadt"
dict <- list("Central Medical Institute" = "veterin\\w+rwesens")
matched <- sm_affiliation_match(corpus, patterns = dict)
#> ✔ Affiliation matching flagged 1 authorship across 1 institution.
#> ℹ By signal: name_token: 1. See `sm_affiliation_summary()` for the full
#> breakdown.
matched$authorships$institution_match[2]
#> [1] "Central Medical Institute"
ascii <- sm_affiliation_match(corpus, patterns = dict, unicode = FALSE)
ascii$authorships$institution_match[2]
#> [1] NA