Research software · R package
Choose names for your experiment.
We built validatednamesr to help choose experimental names using evidence about how people perceive them.
Provenance
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.
This documentation copy is maintained by Charles Crabtree. The upstream package and original documentation are maintained by Jae Yeon Kim. Package code comes from the pinned upstream source. I’ve edited the explanatory text in this documentation copy; the function arguments and behaviour are unchanged.
Authors: Jae Yeon Kim and Charles Crabtree
Why we built it
A name can signal more than the racial category a researcher intends. People may also make assumptions about citizenship, education, or income. We want to see those perceptions before choosing names for an experiment.
This R package provides functions to perform each task based on a validated dataset of 600 names (100 white, 300 Asian, 100 black, and 100 Hispanic) published in Nature Scientific Data (Crabtree, Kim, Gaddis, Holbein, Guage, and Marx, 2023).
Use several names per group, then check whether their perceived attributes fit your design. You might want similar income ratings across racial groups, or you might want to vary both. The package helps you select names under those constraints; the design decision is yours.
Installation
devtools::install_github("jaeyk/validatednamesr", dependencies = TRUE)Usage
View and load datasets
Start with view_data() to see the available files and their descriptions.
Use load_data() to read one of those files. You can identify it by filename or note.
Select names
Pass "Asian", "Black", "Hispanic", or "White" to race in select_names(). These are the intended signals used in the study.
The pinned package returns six columns: name, identity, pct_correct, avg_income, avg_education, and avg_citizenship. The first two identify the name and its intended signal. pct_correct is the share who perceived that signal. Income and education are average ratings on 1–5 scales; citizenship is a share on a 0–1 scale.
asian_names <- select_names(race = "Asian") # Asian signalling names
asian_namesBy default, at least 80% of respondents must have perceived the intended racial signal. Set pct_correct to change that threshold.
# Lower the required share from 80% to 70%.
lower_threshold_names <- select_names(race = "Asian", pct_correct = 0.7)The function samples five names by default. Set n_names to request more, and set a random seed if you need to reproduce the selection.
# Sample ten eligible names.
set.seed(42)
greater_n_names <- select_names(race = "Asian", n_names = 10)You can order eligible names by a validation measure with order_by_var. Use pct_correct for the share who perceived the intended racial signal, avg_income or avg_education for average ratings, or avg_citizenship for the share perceived as citizens. It selects the highest values and keeps ties, so an ordered result can contain more than n_names rows.
top_correct_names <- select_names(race = "Asian", order_by_var = "pct_correct")select_names_all() combines the four racial groups using the default selection for each. In this pinned version, it accepts selection arguments but doesn’t pass them to select_names(). Call select_names() separately for each group if you want to change the threshold, ordering, or sample size.
all_race_names <- select_names_all()