Package documentation · Function reference
We built nomine to request name-based predictions from NamePrism and NamSor
without writing a separate API client. The functions return the provider's
results in a data frame, with the input names alongside them.
These predictions can help with a research task when names are the information we have. They don't tell us how a person identifies. I'd start by checking whether the provider's categories fit the question I'm asking.
Authors: Charles Crabtree, Volha Chykina, Micah Gell-Redman, and Christian Chacua.
Install the development version from GitHub:
# install.packages("remotes")
# remotes::install_github("lobsterbush/nomine")
install.packages("nomine", repos = c('https://lobsterbush.r-universe.dev', 'https://cloud.r-project.org'))
You'll need R and the dependencies listed in DESCRIPTION. API calls also need
a network connection and your own provider credentials.
NamePrism supplies probabilities over six U.S. ethnicity categories and 39 leaf nationality categories. Get a token through its API page.
NamSor supplies gender predictions from given and family names. Get an API key from NamSor. Its API documentation describes the service.
Check the providers' current access terms and charges before running a batch. The package doesn't set those terms.
Store your token in NAMEPRISM_TOKEN, then pass a vector of full names:
library(nomine)
names <- c("Charles Crabtree", "Volha Chykina", "Maria Garcia")
ethnicity <- get_ethnicities(names, t = Sys.getenv("NAMEPRISM_TOKEN"))
ethnicity[, c("input", "White", "Hispanic", "Black")]
The six prediction columns are 2PRACE, Hispanic, API, Black, AIAN,
and White. Those labels come from NamePrism. The values depend on the service's response.
nationality <- get_nationalities(names, t = Sys.getenv("NAMEPRISM_TOKEN"))
names(nationality)
head(nationality)
The output includes 39 leaf categories. See NamePrism's category descriptions before interpreting them as a measure of national origin.
NamSor takes given and family names separately. Store the key in
NAMSOR_API_KEY:
gender <- get_gender(
given = c("Volha", "Charles", "Maria"),
family = c("Chykina", "Crabtree", "Garcia"),
api_key = Sys.getenv("NAMSOR_API_KEY")
)
gender[, c("first_name", "last_name", "gender", "scale")]
Read gender and scale as outputs of the provider's classifier. The function
help lists the returned columns.
NamePrism requests that fail are recorded with missing prediction values.
Set warnings = TRUE if you'd like a warning for each failed name. Inspect
missing results before analysing a batch; a missing prediction isn't a zero.
The package sends names to the provider when you call these functions. The examples in the function help show their inputs without making a request; the live examples are marked separately.
Please use the issue tracker for bugs or questions. You can also email Charles Crabtree or Christian Chacua. We welcome pull requests.
Thanks to Karl Broman and Hadley Wickham for providing excellent free guides to building R packages.
Browse the documentation and function reference.
Human – AI (editor) 👤✏️🤖
We wrote every initial version ourselves, without AI. We've used AI only for later updates and code fixes. I'm Charles Crabtree, and this is my account of how the package was made.
The label follows The Latent Review’s provenance standard, shared under CC BY 4.0. The software remains MIT licensed.
Install R and the package dependencies listed in DESCRIPTION, then install
pkgdown and here. From the repository root, run:
source(here::here("data-raw", "01_build_site.R"))
The site is built locally in docs/. Publish the rendered contents to the
gh-pages branch; GitHub Pages serves that branch.