R: Input validation of preferences

galeShapley.validate {matchingR} | R Documentation

## 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

[Package matchingR version 1.3.2 Index]