Implement matching

matching() implements matching between two groups of individuals.

matching(
  g1_prefs,
  g2_prefs,
  g1_names = NULL,
  g2_names = NULL,
  algorithm = "DA",
  switch = FALSE,
  verbose = TRUE,
  mt1 = FALSE
)

Arguments

g1_prefs

A list of preferences of individuals who make proposals.

g2_prefs

A named list of preferences of individuals who receives proposals.

g1_names

A vector of names of the proposers. You can pass a named list to g1_prefs instead of specifying g1_names.

g2_names

A vector of names of the proposers. You can pass a named list to g2_prefs instead of specifying g2_names.

algorithm

A algorithm for matching. "DA" ("Gale-Shapley") or "Boston".

switch

A logical value. If TRUE, the roles of g1 and g2 are switched. That is, g2 will be the proposer group, and g1 the prposed if TRUE. Default is FALSE.

verbose

If TRUE, matching steps will be printed on screen. Default to TRUE.

mt1

A logical valu. TRUE for many-to-one matching. Default to FALSE

Value

A list of "matching" class containing (1) a data frame of the matching results, (2) a character string showing which algorithm was used, (3) a character string of the matching results, (4) a character string of the history of matching steps, and (5) a list of preferences of each group.

Author

Yoshio Kamijo and Yuki Yanai yanai.yuki@kochi-tech.ac.jp

Examples

test1 <- matching(
  g1_prefs = list(w1 = c(1, 2),
                  w2 = c(2, 1),
                  w3 = c(1, 2)),
  g2_prefs = list(m1 = c(1, 2, 3),
                  m2 = c(2, 3, 1)))
#>  Step 1 
#>     w1 proposes m1 
#>     w1 and m1 temporarily match
#>  
#>     w2 proposes m2 
#>     w2 and m2 temporarily match
#>  
#>     w3 proposes m1 
#>     m1 rejects w3 
#>  
#>  Step 2 
#>     w3 proposes m2 
#>     m2 rejects w3 
#>  

test2 <- matching(
  g1_names = c("w1", "w2", "w3"),
  g1_prefs = list(c(1, 2),
                  c(2, 1),
                  c(1, 2)),
  g2_names = c("m1", "m2"),
  g2_prefs = list(c(1, 2, 3),
                  c(2, 3, 1)))
#>  Step 1 
#>     w1 proposes m1 
#>     w1 and m1 temporarily match
#>  
#>     w2 proposes m2 
#>     w2 and m2 temporarily match
#>  
#>     w3 proposes m1 
#>     m1 rejects w3 
#>  
#>  Step 2 
#>     w3 proposes m2 
#>     m2 rejects w3 
#>  

test3 <- matching(
  g1_names = c("Amy", "Beatrice", "Cindy"),
  g1_prefs = list(c("Dick", "Eric"),
                  c("Eric", "Dick"),
                  c("Dick", "Eric")),
  g2_names = c("Dick", "Eric"),
  g2_prefs = list(c("Amy", "Beatrice", "Cindy"),
                  c("Beatrice", "Cindy", "Amy")))
#>  Step 1 
#>     Amy proposes Dick 
#>     Amy and Dick temporarily match
#>  
#>     Beatrice proposes Eric 
#>     Beatrice and Eric temporarily match
#>  
#>     Cindy proposes Dick 
#>     Dick rejects Cindy 
#>  
#>  Step 2 
#>     Cindy proposes Eric 
#>     Eric rejects Cindy 
#>  

test4 <- matching(
  g1_prefs <- list(w1 = c(1, 2),
                   w2 = c(2, 1),
                   w3 = c(1, 2)),
  g2_prefs <- list(m1 = c(1, 2),
                   m2 = c(2, 3)))
#>  Step 1 
#>     w1 proposes m1 
#>     w1 and m1 temporarily match
#>  
#>     w2 proposes m2 
#>     w2 and m2 temporarily match
#>  
#>     w3 proposes m1 
#>     m1 rejects w3 
#>  
#>  Step 2 
#>     w3 proposes m2 
#>     m2 rejects w3 
#>  

if (FALSE) {
  ## The following function throws an error because a name (Jack) does not
  ## exist in the opponent's pool.

  test5 <- matching(
    g1_names = c("Amy", "Beatrice", "Cindy"),
    g1_prefs = list(c("Dick", "Eric"),
                    c("Eric", "Dick"),
                    c("Dick", "Jack")),
    g2_names = c("Dick", "Eric"),
    g2_prefs = list(c("Amy", "Beatrice", "Cindy"),
                    c("Beatrice", "Cindy", "Amy")))
}