Merge 34e259e into 19d5359

jtilly · Sep 12, 2015 · fbbec15 · fbbec15
2 parents 19d5359 + 34e259e
commit fbbec15
Show file tree

Hide file tree

Showing 15 changed files with 340 additions and 622 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -10,7 +10,6 @@ sudo: false
 branches:
   only:
    - master
-   - feature/roommate
 
 # install r-base-dev:
 # use r-packages-precise (https://cran.r-project.org/bin/linux/ubuntu/precise/) as source
@@ -49,7 +48,6 @@ install:
 
 # build and check package
 script:
-  - rm GALESHAPLEY.md IRVING.md TOPTRADINGCYCLE.md
   - R CMD build . --no-manual --no-build-vignettes
   - PKG_FILE_NAME=$(ls -1t *.tar.gz | head -n 1)
   - R CMD check "${PKG_FILE_NAME}" --as-cran --no-manual --no-build-vignettes

diff --git a/GALESHAPLEY.md b/GALESHAPLEY.md
diff --git a/IRVING.md b/IRVING.md
diff --git a/R/matchingR.R b/R/matchingR.R
@@ -4,27 +4,36 @@
 #' @docType package
 #' @title matchingR: Efficient Computation of Matching Algorithms in R
 #'   and C++
-#' @description matchingR is an R Package that efficiently computes matching
-#'   algorithms for large scale matching markets. It currently implements the
-#'   Gale-Shapley Algorithm for two-sided matching markets and Irving's
-#'   Algorithm for one-sided matching markets. This package can be useful when
-#'   the number of market participants is large or when very many matchings need
-#'   to be computed (e.g. for extensive simulations or for estimation purposes).
-#'   The package has successfully been used to simulate preferences and compute
-#'   the matching with 30,000 participants on each side of the market. The
-#'   package provides functions to compute the solution to the
-#'   \href{http://en.wikipedia.org/wiki/Stable_matching}{stable marriage
-#'   problem}, to the
-#'   \href{http://en.wikipedia.org/wiki/Hospital_resident}{college admission
-#'   problem}, and to the
-#'   \href{https://en.wikipedia.org/wiki/Stable_roommates_problem}{stable
-#'   roommates problem}
+#' @description matchingR is an R package that efficiently computes the 
+#'   Gale-Shapley algorithm for both the stable marriage problem and the college
+#'   admissions problem, Irving's algorithm for the stable roommate problem, and
+#'   the top trading cycle algorithm for large matching markets. The package 
+#'   provides functions to compute the solutions to the stable marriage problem,
+#'   to the college admission problem, the stable roommates problem, and the 
+#'   house allocation problem.
+#'   
+#'   The package can be useful when the number of market participants is large
+#'   or when very many matchings need to be computed (e.g. for extensive
+#'   simulations or for estimation purposes). The Gale-Shapley function of this
+#'   package has successfully been used to simulate preferences and compute the
+#'   matching with 30,000 participants on each side of the market.
+#'   
+#'   Matching markets are very common in practice and widely studied by
+#'   economists. Popular examples include
+#'   
+#'   the National Resident Matching Program that matches graduates from medical
+#'   school to residency programs at teaching hospitals throughout the United
+#'   States the matching of students to schools including the New York City High
+#'   School Match or the the Boston Public School Match (and many more) the
+#'   matching of kidney donors to recipients in kidney exchanges.
 #' @author Jan Tilly, Nick Janetos
 #' @references Gale, D. and Shapley, L.S. (1962). College admissions and the
 #'   stability of marriage. \emph{The American Mathematical Monthly}, 69(1):
 #'   9--15.
 #' @references Irving, R. W. (1985). An efficient algorithm for the "stable
 #'   roommates" problem. \emph{Journal of Algorithms}, 6(4): 577--595
+#' @references Shapley, L., & Scarf, H. (1974). On cores and indivisibility.
+#'   \emph{Journal of Mathematical Economics}, 1(1), 23-37.
 #' @examples
 #' # stable marriage problem
 #' nmen = 25
@@ -46,6 +55,11 @@
 #' N = 10
 #' u = matrix(runif(N^2),  nrow = N, ncol = N)
 #' results = onesided(utils = u)
+#' 
+#' # top trading cycle algorithm
+#' N = 10
+#' u = matrix(runif(N^2),  nrow = N, ncol = N)
+#' results = toptrading(utils = u)
 NULL
 
 #' Make a package environmental variable with the storage order
@@ -81,8 +95,8 @@ set.column.major = function() {
         "=================================\n",
         "With this update, we changed the layout of payoff and preference order \n",
         "matrices. In the matrix `u`, element [i,j] now refers to the utility that \n",
-        "agent [j] receives from being  matched to agent [i]. Similarly, in the matrix \n",
-        "`pref`, element [i,j] refers to the id of the  individual that agent `j` \n", 
+        "agent [j] receives from being matched to agent [i]. Similarly, in the matrix \n",
+        "`pref`, element [i,j] refers to the id of the individual that agent `j` \n", 
         "ranks at position `i`. I.e., we store payoffs and preference orders in \n",
         "column-major order instead of row-major order.\n\n", 
         "If you rather store preferences in row-major order as in version 1.0 of \n", 

diff --git a/README.md b/README.md
@@ -63,12 +63,7 @@ u = matrix(runif(N^2),  nrow = n, ncol = n)
 results = toptrading(utils = u)
 ```
 
-## Readme
-* [Gale-Shapley Algorithm](GALESHAPLEY.md)
-* [Irving's Algorithm for the Stable Roommate Problem](IRVING.md)
-* [Top Trading Cycle Algorithm](TOPTRADINGCYCLE.md)
-
 ## Documentation
 * [Reference Manual](http://jtilly.io/matchingR/matchingR-documentation.pdf "Computing Stable Matchings in R: Reference Manual for matchingR")
 * [Vignette: Matching Algorithms in R: An Introduction to matchingR](http://jtilly.io/matchingR/matchingR-intro.pdf "Matching Algorithms in R: An Introduction to matchingR")
-* *Computational Performance*: [Gale-Shapley](http://jtilly.io/matchingR/matchingR-performance-galeshapley.html "Computing the Gale-Shapley Algorithm in R: Performance"), [Stable Roommate Problem](http://jtilly.io/matchingR/matchingR-performance-roommate.html "Solving the Stable Roommate Problem in R")
+* [Vignette: Matching Algorithms in R: Computational Performance](http://jtilly.io/matchingR/matchingR-performance.pdf "Matching Algorithms in R: Computational Performance")
diff --git a/TOPTRADINGCYCLE.md b/TOPTRADINGCYCLE.md
diff --git a/man/matchingR-package.Rd b/man/matchingR-package.Rd
@@ -6,21 +6,28 @@
 \title{matchingR: Efficient Computation of Matching Algorithms in R
   and C++}
 \description{
-matchingR is an R Package that efficiently computes matching
-  algorithms for large scale matching markets. It currently implements the
-  Gale-Shapley Algorithm for two-sided matching markets and Irving's
-  Algorithm for one-sided matching markets. This package can be useful when
-  the number of market participants is large or when very many matchings need
-  to be computed (e.g. for extensive simulations or for estimation purposes).
-  The package has successfully been used to simulate preferences and compute
-  the matching with 30,000 participants on each side of the market. The
-  package provides functions to compute the solution to the
-  \href{http://en.wikipedia.org/wiki/Stable_matching}{stable marriage
-  problem}, to the
-  \href{http://en.wikipedia.org/wiki/Hospital_resident}{college admission
-  problem}, and to the
-  \href{https://en.wikipedia.org/wiki/Stable_roommates_problem}{stable
-  roommates problem}
+matchingR is an R package that efficiently computes the
+  Gale-Shapley algorithm for both the stable marriage problem and the college
+  admissions problem, Irving's algorithm for the stable roommate problem, and
+  the top trading cycle algorithm for large matching markets. The package
+  provides functions to compute the solutions to the stable marriage problem,
+  to the college admission problem, the stable roommates problem, and the
+  house allocation problem.
+
+  The package can be useful when the number of market participants is large
+  or when very many matchings need to be computed (e.g. for extensive
+  simulations or for estimation purposes). The Gale-Shapley function of this
+  package has successfully been used to simulate preferences and compute the
+  matching with 30,000 participants on each side of the market.
+
+  Matching markets are very common in practice and widely studied by
+  economists. Popular examples include
+
+  the National Resident Matching Program that matches graduates from medical
+  school to residency programs at teaching hospitals throughout the United
+  States the matching of students to schools including the New York City High
+  School Match or the the Boston Public School Match (and many more) the
+  matching of kidney donors to recipients in kidney exchanges.
 }
 \examples{
 # stable marriage problem
@@ -43,6 +50,11 @@ checkStability(uStudents, uColleges, results$proposals, results$engagements)
 N = 10
 u = matrix(runif(N^2),  nrow = N, ncol = N)
 results = onesided(utils = u)
+
+# top trading cycle algorithm
+N = 10
+u = matrix(runif(N^2),  nrow = N, ncol = N)
+results = toptrading(utils = u)
 }
 \author{
 Jan Tilly, Nick Janetos
@@ -54,5 +66,8 @@ Gale, D. and Shapley, L.S. (1962). College admissions and the
 
 Irving, R. W. (1985). An efficient algorithm for the "stable
   roommates" problem. \emph{Journal of Algorithms}, 6(4): 577--595
+
+Shapley, L., & Scarf, H. (1974). On cores and indivisibility.
+  \emph{Journal of Mathematical Economics}, 1(1), 23-37.
 }
 
diff --git a/man/pkg.env.Rd b/man/pkg.env.Rd
@@ -4,7 +4,7 @@
 \name{pkg.env}
 \alias{pkg.env}
 \title{Make a package environmental variable with the storage order}
-\format{\preformatted{<environment: 0x40df720> 
+\format{\preformatted{<environment: 0x124b37df0> 
 }}
 \usage{
 pkg.env

diff --git a/man/toptrading.Rd b/man/toptrading.Rd
@@ -17,8 +17,8 @@ utility of 2.3 from being matched to agent j.}
 }
 \value{
 A vector of length n corresponding to the matchings being made, so that
-e.g. if the 4th element is 6 then agent 4 was matched with agent 6. This vector
-uses R style indexing. If no stable matching exists, it returns NULL.
+e.g. if the 4th element is 6 then agent 4 was matched to agent 6. This vector
+uses R style indexing.
 }
 \description{
 Compute the top trading cycle algorithm