JOSS review (#97)

daffidwilde · web-flow · commit 269ebb4a9c15 · 2020-04-14T10:38:08.000+01:00
* Incorporate player copying (#83) * Alter tests to support copies of players. Player instances are now internal to a Game instance so the tests have to reflect that. Without designing some overly elaborate __eq__ and __hash__ methods, this seems sensible for now (other aspects of a Game instance require the Player class to be hashable). * Implement player copying. Player instances are copied at the instantiation of a Game subclass. This is done using `copy.deepcopy`. That way, multiple Game instances can be created from one set of player lists. * Add hypothesis to setup.py (#87) * Add test for inconsistent coverage. (#86) Occasionally, coverage falls below 100% because of an edge case in HR where no resident is removed from consideration for forgetting all of their preferences. This simple example test rectifies that. * Add hypothesis to `tests_require` in `setup.py` * Make Game a metaclass (#94) * Reimplement `test_game.py` for `abc.ABCMeta`. * Change `Game` to `BaseGame` as `ABCMeta` subclass. * Change inheritance in each game. * Format with black, blackbook and isort. * Format with black, blackbook and isort. * Edit paper for JOSS review (#93) * Add test for inconsistent coverage. (#86) Occasionally, coverage falls below 100% because of an edge case in HR where no resident is removed from consideration for forgetting all of their preferences. This simple example test rectifies that. * Fix flaky `Player.forget()` behaviour (#88) * Add `ValueError` to exceptions in SR(2) test. Since the first phase is not being completed, the preferences have not been reduced and the all-or-nothing cycles can contain repeats of pairs. This means players attempt to forget someone they've already forgotten. * Remove the try-except from `Player.forget()`. No longer necessary as the tests catch this edge case (that would not ever actually happen in SR). * Flesh out example paragraph. * Remove fluff around edu infrastructure. * Fix documentation for JOSS review (#85) * Add sphinxcontrib-bibtex to docs/env file. * Remove "Search Page" from "Indices and Tables" * Add notebook pointer prologue. * Clarify installation instructions for pyversion. * Move install intro to a note directive. * Update README (and supporting files) (#84) * Add CONTRIBUTING file to the top level. * Remove duplicate "Documentation" sect from README * Change "PR" to "pull request" in README * Add python_requires parameter to setup (#92)
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -0,0 +1,26 @@
+If you are interested in contributing to the Matching library then first of all
+we would like to offer our thanks and say welcome!
+
+Whether you're looking to provide a fix for a current `issue
+<https://github.com/daffidwilde/matching/issues>`_, report a bug or implement a
+new feature to the library, your contributions are always welcome. Pull requests
+are a good place to discuss contributions so please do not feel you must present
+a perfect product from the off.
+
+To make a contribution via a pull request, follow these steps:
+
+1. Go to the `GitHub repo <https://github.com/daffidwilde/matching>`_,
+   make a fork, and clone the repo locally::
+
+       $ git clone git@github.com/<your-username>/matching.git
+
+2. Assuming you have all the dependencies installed, the next step is to ensure
+   that all the tests pass (this should not take very long at all)::
+
+       $ cd matching
+       $ pytest tests
+
+3. Make your changes and write tests to go with them -- ensuring they pass, too.
+
+4. Push to your fork and open a pull request.
+
diff --git a/INSTALLATION.rst b/INSTALLATION.rst
@@ -1,13 +1,14 @@
-Matching is written in Python 3, and relies only on `NumPy
-<http://www.numpy.org/>`_ for general use.
+.. note::
+    Matching requires a Python version of 3.5 or above and relies only on `NumPy
+    <http://www.numpy.org/>`_ for installation and general use.
 
 The library is most easily installed using :code:`pip`::
 
     $ python -m pip install matching
 
 However, if you would like to install it from source then go ahead and clone the
-GitHub repo::
+GitHub repository before installing locally::
 
     $ git clone https://github.com/daffidwilde/matching.git
     $ cd matching
-    $ python setup.py install
+    $ python -m pip install .
diff --git a/README.rst b/README.rst
@@ -200,14 +200,9 @@ solved in less than one tenth of a second:
 >>> _ = game.solve() # 48.6 ms ± 963 µs per loop
 
 
-Documentation
--------------
-
-Full documentation is available here: `<https://matching.readthedocs.io>`_
-
 Get in contact!
 ---------------
 
 I hope this package is useful, and feel free to contact me here (or on Twitter:
 `@daffidwilde <https://twitter.com/daffidwilde>`_) with any issues or
-recommendations. PRs always welcome!
+recommendations. Pull requests are always welcome!
diff --git a/docs/conf.py b/docs/conf.py
@@ -195,10 +195,20 @@
     "reference/source/modules.rst",
 ]
 
-# nbsphinx_prolog = """
-# Go there: https://github.com/daffidwilde/matching/blob/docs/{{ env.doc2path(env.docname, base=None) }}
-# ----
-# """
+nbsphinx_prolog = """
+
+{% set docname = 'docs/' + env.doc2path(env.docname, base=None) %}
+
+.. raw:: html
+
+    <div class="admonition note">
+      <p>This page was generated from
+        <a class="reference external"
+        href="https://github.com/daffidwilde/matching/blob/master/{{ docname|e }}">{{ docname|e }}</a>.
+      </p>
+    </div>
+
+"""
 
 nbsphinx_epilog = """
 ----
diff --git a/docs/environment.yml b/docs/environment.yml
@@ -12,3 +12,4 @@ dependencies:
         - matching
         - nbsphinx
         - sphinx_rtd_theme
+        - sphinxcontrib-bibtex
diff --git a/docs/how-to/check_matching_status.ipynb b/docs/how-to/check_matching_status.ipynb
@@ -1,96 +1 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "# Check the status of a matching\n",
-    "\n",
-    "Verifying the validity and stability of a matching is paramount in any matching game. In matching this is done by creating an instance of a game and using the `check_validity` and `check_stability` methods of the instance.\n",
-    "\n",
-    "Consider the following instance of SA."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 1,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from matching.games import StudentAllocation\n",
-    "\n",
-    "student_preferences = {\n",
-    "    \"A\": [\"X1\", \"X2\"],\n",
-    "    \"B\": [\"Y2\", \"X1\"],\n",
-    "    \"C\": [\"X1\", \"Y1\"],\n",
-    "    \"D\": [\"Y2\", \"Y1\"],\n",
-    "}\n",
-    "\n",
-    "supervisor_preferences = {\"X\": [\"C\", \"A\", \"B\"], \"Y\": [\"C\", \"D\", \"B\"]}\n",
-    "\n",
-    "project_supervisors = {\"X1\": \"X\", \"X2\": \"X\", \"Y1\": \"Y\", \"Y2\": \"Y\"}\n",
-    "project_capacities = {project: 1 for project in project_supervisors}\n",
-    "supervisor_capacities = {supervisor: 2 for supervisor in supervisor_preferences}\n",
-    "\n",
-    "\n",
-    "game = StudentAllocation.create_from_dictionaries(\n",
-    "    student_preferences,\n",
-    "    supervisor_preferences,\n",
-    "    project_supervisors,\n",
-    "    project_capacities,\n",
-    "    supervisor_capacities,\n",
-    ")\n"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "An easy way to get a matching is just to solve the game. From there we can verify the status of the current matching."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 2,
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "(True, True)"
-      ]
-     },
-     "execution_count": 2,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "game.solve()\n",
-    "\n",
-    "game.check_validity(), game.check_stability()"
-   ]
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "Matching docs",
-   "language": "python",
-   "name": "matching-docs"
-  },
-  "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.7.6"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 4
-}
+{"cells": [{"cell_type": "markdown", "metadata": {}, "source": ["# Check the status of a matching\n", "\n", "Verifying the validity and stability of a matching is paramount in any matching game. In matching this is done by creating an instance of a game and using the `check_validity` and `check_stability` methods of the instance.\n", "\n", "Consider the following instance of SA."]}, {"cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": ["from matching.games import StudentAllocation\n", "\n", "student_preferences = {\n", "    \"A\": [\"X1\", \"X2\"],\n", "    \"B\": [\"Y2\", \"X1\"],\n", "    \"C\": [\"X1\", \"Y1\"],\n", "    \"D\": [\"Y2\", \"Y1\"],\n", "}\n", "\n", "supervisor_preferences = {\"X\": [\"C\", \"A\", \"B\"], \"Y\": [\"C\", \"D\", \"B\"]}\n", "\n", "project_supervisors = {\"X1\": \"X\", \"X2\": \"X\", \"Y1\": \"Y\", \"Y2\": \"Y\"}\n", "project_capacities = {project: 1 for project in project_supervisors}\n", "supervisor_capacities = {supervisor: 2 for supervisor in supervisor_preferences}\n", "\n", "\n", "game = StudentAllocation.create_from_dictionaries(\n", "    student_preferences,\n", "    supervisor_preferences,\n", "    project_supervisors,\n", "    project_capacities,\n", "    supervisor_capacities,\n", ")\n"]}, {"cell_type": "markdown", "metadata": {}, "source": ["An easy way to get a matching is just to solve the game. From there we can verify the status of the current matching."]}, {"cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [{"data": {"text/plain": ["(True, True)"]}, "execution_count": 2, "metadata": {}, "output_type": "execute_result"}], "source": ["game.solve()\n", "\n", "game.check_validity(), game.check_stability()\n"]}], "metadata": {"kernelspec": {"display_name": "Matching docs", "language": "python", "name": "matching-docs"}, "language_info": {"codemirror_mode": {"name": "ipython", "version": 3}, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.7.6"}}, "nbformat": 4, "nbformat_minor": 4}
diff --git a/docs/index.rst b/docs/index.rst
@@ -36,4 +36,3 @@ Indices and tables
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
diff --git a/docs/reference/contributing.rst b/docs/reference/contributing.rst
@@ -1,28 +1,4 @@
 Contributing to the library
 ===========================
 
-If you are interested in contributing to the Matching library then first of all
-we would like to offer our thanks and say welcome!
-
-Whether you're looking to provide a fix for a current `issue
-<https://github.com/daffidwilde/matching/issues>`_, report a bug or implement a
-new feature to the library, your contributions are always welcome. Pull requests
-(PRs) are a good place to discuss contributions so please do not feel you must
-present a perfect product from the off.
-
-To make a contribution via a PR, follow these steps:
-
-1. Go to the `GitHub repo <https://github.com/daffidwilde/matching>`_,
-   make a fork, and clone the repo locally::
-
-       $ git clone git@github.com/<your-username>/matching.git
-
-2. Assuming you have all the dependencies installed, the next step is to ensure
-   that all the tests pass (this should not take very long at all)::
-
-       $ cd matching
-       $ pytest tests
-
-3. Make your changes and write tests to go with them -- ensuring they pass, too.
-
-4. Push to your fork and open a pull request.
+.. include:: ../../CONTRIBUTING.rst
diff --git a/docs/tutorials/project_allocation/data.py b/docs/tutorials/project_allocation/data.py
@@ -188,9 +188,10 @@ def main():
     print("Seed set:", SEED)
 
     supervisor_to_projects = create_supervisor_to_projects_map()
-    supervisor_to_capacity, project_to_capacity = create_player_to_capacity_maps(
-        supervisor_to_projects
-    )
+    (
+        supervisor_to_capacity,
+        project_to_capacity,
+    ) = create_player_to_capacity_maps(supervisor_to_projects)
     print("Supervisor and project dictionaries created...")
 
     all_projects = list(get_all_projects(supervisor_to_projects))
diff --git a/paper.bib b/paper.bib
@@ -114,18 +114,6 @@ @misc{numpy
     note = {[Online; accessed 2020-02-24]},
 }
 
-@article{okun1995,
-    title = {Social Norms and Random Matching Games},
-    journal = {Games and Economic Behavior},
-    volume = {9},
-    number = {1},
-    pages = {79 - 109},
-    year = {1995},
-    issn = {0899-8256},
-    doi = {10.1006/game.1995.1006},
-    author = {Okuno-Fujiwara, Masahiro and Postlewaite, Andrew},
-}
-
 @article{roth1984,
     author = {Roth, Alvin},
     title = {The Evolution of the Labor Market for Medical Interns and
diff --git a/paper.md b/paper.md
@@ -84,8 +84,10 @@ require the use of software to be solved in reasonable time.
 
 # Statement of Need
 
-Matching games have applications in a number of fields including social and
-market economics [@agar2017; @okun1995], wireless communication [@baya2016], and
+Matching games have applications in many fields where relationships between
+rational agents must be managed. Some example applications include: being able
+to inform on healthcare finance policy [@agar2017]; helping to reduce the
+complexity of automated wireless communication networks [@baya2016]; and
 education infrastructure [@chia2019]. Thus, having access to software
 implementations of algorithms that are able to solve such games is essential.
 
diff --git a/setup.py b/setup.py
@@ -19,5 +19,6 @@
     keywords=["game-theory gale-shapley matching-games"],
     packages=find_packages("src"),
     package_dir={"": "src"},
-    tests_require=["pytest", "numpy"],
+    python_requires=">=3.5",
+    tests_require=["pytest", "hypothesis", "numpy"],
 )
diff --git a/src/matching/__init__.py b/src/matching/__init__.py
@@ -1,6 +1,6 @@
 """ Top-level imports only. """
 
-from .game import Game
+from .game import BaseGame
 from .matching import Matching
 from .player import Player
 from .version import __version__
diff --git a/src/matching/game.py b/src/matching/game.py
@@ -1,11 +1,10 @@
 """ The base game class for facilitating and solving matching games. """
 
+import abc
 
-class Game:
-    """ A class to store information about, and facilitate the solving of, a
-    matching game.
 
-    **This is a base class and is not intended for use other than inheritance.**
+class BaseGame(metaclass=abc.ABCMeta):
+    """ An abstract base class for facilitating various matching games.
 
     Attributes
     ----------
@@ -23,17 +22,14 @@ def __init__(self):
         self.matching = None
         self.blocking_pairs = None
 
+    @abc.abstractmethod
     def solve(self):
         """ Placeholder for solving the given matching game. """
 
-        raise NotImplementedError()
-
+    @abc.abstractmethod
     def check_stability(self):
         """ Placeholder for checking the stability of the current matching. """
 
-        raise NotImplementedError()
-
+    @abc.abstractmethod
     def check_validity(self):
         """ Placeholder for checking the validity of the current matching. """
-
-        raise NotImplementedError()
diff --git a/src/matching/games/hospital_resident.py b/src/matching/games/hospital_resident.py
@@ -1,13 +1,15 @@
 """ The HR solver and algorithm. """
 
-from matching import Game, Matching
+import copy
+
+from matching import BaseGame, Matching
 from matching import Player as Resident
 from matching.players import Hospital
 
 from .util import delete_pair, match_pair
 
 
-class HospitalResident(Game):
+class HospitalResident(BaseGame):
     """ A class for solving instances of the hospital-resident assignment
     problem (HR).
 
@@ -40,8 +42,9 @@ class HospitalResident(Game):
         blocking pairs.
     """
 
-    def __init__(self, residents=None, hospitals=None):
+    def __init__(self, residents, hospitals):
 
+        residents, hospitals = copy.deepcopy([residents, hospitals])
         self.residents = residents
         self.hospitals = hospitals
 
diff --git a/src/matching/games/stable_marriage.py b/src/matching/games/stable_marriage.py
@@ -1,11 +1,13 @@
 """ The SM solver and algorithm. """
 
-from matching import Game, Matching, Player
+import copy
+
+from matching import BaseGame, Matching, Player
 
 from .util import delete_pair, match_pair
 
 
-class StableMarriage(Game):
+class StableMarriage(BaseGame):
     """ A class for solving instances of the stable marriage problem (SM).
 
     Parameters
@@ -30,6 +32,7 @@ class StableMarriage(Game):
 
     def __init__(self, suitors, reviewers):
 
+        suitors, reviewers = copy.deepcopy([suitors, reviewers])
         self.suitors = suitors
         self.reviewers = reviewers
 
diff --git a/src/matching/games/stable_roommates.py b/src/matching/games/stable_roommates.py
diff --git a/src/matching/games/student_allocation.py b/src/matching/games/student_allocation.py
diff --git a/tests/hospital_resident/test_solver.py b/tests/hospital_resident/test_solver.py
diff --git a/tests/stable_marriage/test_solver.py b/tests/stable_marriage/test_solver.py
diff --git a/tests/stable_roommates/test_solver.py b/tests/stable_roommates/test_solver.py
diff --git a/tests/student_allocation/test_solver.py b/tests/student_allocation/test_solver.py
diff --git a/tests/unit/test_game.py b/tests/unit/test_game.py

Original file line number	Diff line number	Diff line change
`@@ -36,4 +36,3 @@ Indices and tables`
`36`	`36`
`37`	`37`	* :ref:`genindex`
`38`	`38`	* :ref:`modindex`
`39`		-* :ref:`search`
Original file line number	Diff line number	Diff line change
`@@ -19,5 +19,6 @@`
`19`	`19`	`keywords=["game-theory gale-shapley matching-games"],`
`20`	`20`	`packages=find_packages("src"),`
`21`	`21`	`package_dir={"": "src"},`
`22`		`- tests_require=["pytest", "numpy"],`
	`22`	`+ python_requires=">=3.5",`
	`23`	`+ tests_require=["pytest", "hypothesis", "numpy"],`
`23`	`24`	`)`