matchingR: galeShapley.validate – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

galeShapley.validate

Input validation of preferences

Description

This function parses and validates the arguments that are passed on to the Gale-Shapley Algorithm. In particular, it checks if user-defined preference orders are complete and returns an error otherwise. If user-defined orderings are given in terms of R indices (starting at 1), then these are transformed into C++ indices (starting at zero).

Usage

galeShapley.validate(
  proposerUtils = NULL,
  reviewerUtils = NULL,
  proposerPref = NULL,
  reviewerPref = NULL
)

Arguments

`proposerUtils`	is a matrix with cardinal utilities of the proposing side of the market. If there are `n` proposers and `m` reviewers, then this matrix will be of dimension `m` by `n`. The `i,j`th element refers to the payoff that proposer `j` receives from being matched to reviewer `i`.
`reviewerUtils`	is a matrix with cardinal utilities of the courted side of the market. If there are `n` proposers and `m` reviewers, then this matrix will be of dimension `n` by `m`. The `i,j`th element refers to the payoff that reviewer `j` receives from being matched to proposer `i`.
`proposerPref`	is a matrix with the preference order of the proposing side of the market (only required when `proposerUtils` is not provided). If there are `n` proposers and `m` reviewers in the market, then this matrix will be of dimension `m` by `n`. The `i,j`th element refers to proposer `j`'s `i`th most favorite reviewer. Preference orders can either be specified using R-indexing (starting at 1) or C++ indexing (starting at 0).
`reviewerPref`	is a matrix with the preference order of the courted side of the market (only required when `reviewerUtils` is not provided). If there are `n` proposers and `m` reviewers in the market, then this matrix will be of dimension `n` by `m`. The `i,j`th element refers to reviewer `j`'s `i`th most favorite proposer. Preference orders can either be specified using R-indexing (starting at 1) or C++ indexing (starting at 0).

Value

a list containing proposerUtils, reviewerUtils, proposerPref (reviewerPref are not required after they are translated into reviewerUtils).

Examples

# market size
nmen <- 5
nwomen <- 4

# generate cardinal utilities
uM <- matrix(runif(nmen * nwomen), nrow = nwomen, ncol = nmen)
uW <- matrix(runif(nwomen * nmen), nrow = nmen, ncol = nwomen)

# turn cardinal utilities into ordinal preferences
prefM <- sortIndex(uM)
prefW <- sortIndex(uW)

# validate cardinal preferences
preferences <- galeShapley.validate(uM, uW)
preferences

# validate ordinal preferences
preferences <- galeShapley.validate(proposerPref = prefM, reviewerPref = prefW)
preferences

# validate ordinal preferences when these are in R style indexing
# (instead of C++ style indexing)
preferences <- galeShapley.validate(proposerPref = prefM + 1, reviewerPref = prefW + 1)
preferences

# validate preferences when proposer-side is cardinal and reviewer-side is ordinal
preferences <- galeShapley.validate(proposerUtils = uM, reviewerPref = prefW)
preferences

matchingR

Matching Algorithms in R and C++

v1.3.2

GPL (>= 2)

Authors

Jan Tilly, Nick Janetos

Initial release

2020-12-14