galeShapley.validate: Input validation of preferences

In matchingR: Matching Algorithms in R and C++

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

Example output

Loading required package: Rcpp
$proposerPref
     [,1] [,2] [,3] [,4] [,5]
[1,]    0    0    2    3    2
[2,]    3    3    3    2    0
[3,]    1    1    1    1    1
[4,]    2    2    0    0    3

$proposerUtils
          [,1]      [,2]       [,3]      [,4]      [,5]
[1,] 0.8968331 0.8824699 0.08673746 0.1455073 0.6466394
[2,] 0.1991731 0.4560731 0.28994067 0.2021957 0.4444299
[3,] 0.1191426 0.1613136 0.67325034 0.2065653 0.8571080
[4,] 0.3601538 0.5530184 0.32950257 0.6495634 0.2303705

$reviewerUtils
             [,1]      [,2]      [,3]      [,4]
[1,] 0.0107504672 0.5055308 0.3529845 0.3740398
[2,] 0.4002213576 0.2688893 0.5171446 0.8344071
[3,] 0.3076481493 0.6358441 0.3668626 0.3937609
[4,] 0.0005187173 0.7791329 0.2764105 0.4926634
[5,] 0.0259823990 0.9755690 0.5047511 0.2709816

$proposerPref
     [,1] [,2] [,3] [,4] [,5]
[1,]    0    0    2    3    2
[2,]    3    3    3    2    0
[3,]    1    1    1    1    1
[4,]    2    2    0    0    3

$proposerUtils
     [,1] [,2] [,3] [,4] [,5]
[1,]    0    0   -3   -3   -1
[2,]   -2   -2   -2   -2   -2
[3,]   -3   -3    0   -1    0
[4,]   -1   -1   -1    0   -3

$reviewerUtils
     [,1] [,2] [,3] [,4]
[1,]   -3   -3   -3   -3
[2,]    0   -4    0    0
[3,]   -1   -2   -2   -2
[4,]   -4   -1   -4   -1
[5,]   -2    0   -1   -4

$proposerPref
     [,1] [,2] [,3] [,4] [,5]
[1,]    0    0    2    3    2
[2,]    3    3    3    2    0
[3,]    1    1    1    1    1
[4,]    2    2    0    0    3

$proposerUtils
     [,1] [,2] [,3] [,4] [,5]
[1,]    0    0   -3   -3   -1
[2,]   -2   -2   -2   -2   -2
[3,]   -3   -3    0   -1    0
[4,]   -1   -1   -1    0   -3

$reviewerUtils
     [,1] [,2] [,3] [,4]
[1,]   -3   -3   -3   -3
[2,]    0   -4    0    0
[3,]   -1   -2   -2   -2
[4,]   -4   -1   -4   -1
[5,]   -2    0   -1   -4

$proposerPref
     [,1] [,2] [,3] [,4] [,5]
[1,]    0    0    2    3    2
[2,]    3    3    3    2    0
[3,]    1    1    1    1    1
[4,]    2    2    0    0    3

$proposerUtils
          [,1]      [,2]       [,3]      [,4]      [,5]
[1,] 0.8968331 0.8824699 0.08673746 0.1455073 0.6466394
[2,] 0.1991731 0.4560731 0.28994067 0.2021957 0.4444299
[3,] 0.1191426 0.1613136 0.67325034 0.2065653 0.8571080
[4,] 0.3601538 0.5530184 0.32950257 0.6495634 0.2303705

$reviewerUtils
     [,1] [,2] [,3] [,4]
[1,]   -3   -3   -3   -3
[2,]    0   -4    0    0
[3,]   -1   -2   -2   -2
[4,]   -4   -1   -4   -1
[5,]   -2    0   -1   -4

matchingR documentation built on May 25, 2021, 9:07 a.m.