% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/race_prediction_funs.R
\name{modfuns}
\alias{modfuns}
\alias{.predict_race_old}
\alias{predict_race_new}
\alias{predict_race_me}
\alias{predict_race_embedding}
\title{Internal model fitting functions}
\usage{
.predict_race_old(
  voter.file,
  census.surname = TRUE,
  surname.only = FALSE,
  surname.year = 2020,
  name.dictionaries = NULL,
  census.geo,
  census.key = Sys.getenv("CENSUS_API_KEY"),
  census.data = NULL,
  age = FALSE,
  sex = FALSE,
  year = "2020",
  party,
  retry = 3,
  impute.missing = TRUE,
  use.counties = FALSE
)

predict_race_new(
  voter.file,
  names.to.use,
  year = "2020",
  age = FALSE,
  sex = FALSE,
  census.geo = c("tract", "block", "block_group", "county", "place", "zcta"),
  census.key = Sys.getenv("CENSUS_API_KEY"),
  name.dictionaries,
  surname.only = FALSE,
  census.data = NULL,
  retry = 0,
  impute.missing = TRUE,
  skip_bad_geos = FALSE,
  census.surname = FALSE,
  use.counties = FALSE
)

predict_race_me(
  voter.file,
  names.to.use,
  year = "2020",
  age = FALSE,
  sex = FALSE,
  census.geo = c("tract", "block", "block_group", "county", "place", "zcta"),
  census.key = Sys.getenv("CENSUS_API_KEY"),
  name.dictionaries,
  surname.only = FALSE,
  census.data = NULL,
  retry = 0,
  impute.missing = TRUE,
  census.surname = FALSE,
  use.counties = FALSE,
  race.init,
  ctrl
)

predict_race_embedding(
  voter.file,
  names.to.use,
  year = "2020",
  age = FALSE,
  sex = FALSE,
  census.geo = c("tract", "block", "block_group", "county", "place", "zcta"),
  census.key = Sys.getenv("CENSUS_API_KEY"),
  name.dictionaries,
  surname.only = FALSE,
  census.data = NULL,
  retry = 0,
  impute.missing = TRUE,
  skip_bad_geos = FALSE,
  census.surname = FALSE,
  use.counties = FALSE,
  ebisg.model = "intfloat/multilingual-e5-large"
)
}
\arguments{
\item{voter.file}{See documentation in \code{race_predict}.}

\item{census.surname}{See documentation in \code{race_predict}.}

\item{surname.only}{See documentation in \code{race_predict}.}

\item{surname.year}{See documentation in \code{race_predict}.}

\item{name.dictionaries}{See documentation in \code{race_predict}.}

\item{census.geo}{See documentation in \code{race_predict}.}

\item{census.key}{A character object specifying user's Census API key.
Required if \code{census.geo} is specified, because a valid Census API key is
required to download Census geographic data.

If \code{\link{NULL}}, the default, attempts to find a census key stored in an
\link[=Sys.getenv]{environment variable} named \code{CENSUS_API_KEY}.}

\item{census.data}{See documentation in \code{race_predict}.}

\item{age}{See documentation in \code{race_predict}.}

\item{sex}{See documentation in \code{race_predict}.}

\item{year}{See documentation in \code{race_predict}.}

\item{party}{See documentation in \code{race_predict}.}

\item{retry}{See documentation in \code{race_predict}.}

\item{impute.missing}{See documentation in \code{race_predict}.}

\item{use.counties}{A logical, defaulting to FALSE. Should census data be filtered by counties available in \var{census.data}?}

\item{names.to.use}{See documentation in \code{race_predict}.}

\item{skip_bad_geos}{See documentation in \code{race_predict}.}

\item{race.init}{See documentation in \code{race_predict}.}

\item{ctrl}{See \code{control} in documentation for \code{\link[=predict_race]{predict_race()}}.}

\item{ebisg.model}{Character string (HuggingFace model ID) or named list
specifying which embedding model to use when \code{model = "eBISG"}.
The only built-in option is \code{"intfloat/multilingual-e5-large"}
(default; 1024-dim), which is keyed by its full HuggingFace ID for
consistency with the Python side. To use a different sentence-transformer,
pass a named list with elements \code{transformer} (HuggingFace model ID),
\code{dim} (embedding dimension), and \code{surname_mlp},
\code{firstname_mlp} (paths to custom .pt checkpoints).}
}
\value{
Output will be an object of class \code{data.frame}. It will
consist of the original user-input \code{voter.file} with additional columns with
predicted probabilities for each of the five major racial categories:
\code{\var{pred.whi}} for White,
\code{\var{pred.bla}} for Black,
\code{\var{pred.his}} for Hispanic/Latino,
\code{\var{pred.asi}} for Asian/Pacific Islander, and
\code{\var{pred.oth}} for Other/Mixed.
}
\description{
These functions are intended for internal use only. Users should use the
\code{\link[=predict_race]{predict_race()}} interface rather any of these functions directly.
}
\details{
These functions fit different versions of WRU. \code{.predict_race_old} fits
the original WRU model, also known as BISG with census-based surname dictionary.
\code{.predict_race_new} fits a new version of BISG which uses a new, augmented
surname dictionary, and can also accommodate the use of first and middle
name information. Finally, \code{.predict_race_me} fits a fully Bayesian Improved
Surname Geocoding model (fBISG), which fits a model with measurement-error
correction of erroneous zeros in census tables, in addition to also accommodating
the augmented surname dictionary, and the first and middle name
dictionaries when making predictions.
}
\section{.predict_race_old}{

Original WRU race prediction function, implementing classical BISG with census-based
surname dictionary.
}

\section{.predict_race_new }{

New race prediction function, implementing classical BISG with augmented
surname dictionary, as well as first and middle name information.
}

\section{.predict_race_me}{

New race prediction function, implementing fBISG (i.e. measurement
error correction, fully Bayesian model) with augmented
surname dictionary, as well as first and middle name information.
}

\section{.predict_race_embedding}{

eBISG race prediction function, which uses pre-trained text embeddings
(E5-Large) to predict race probabilities for names not found in Census
surname lists, rather than falling back to generic population-level priors.
}

\keyword{internal}
