galeShapley.validate {matchingR}

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,jth 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,jth 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,jth element refers to proposer j's ith 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,jth element refers to reviewer j's ith 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