Merge pull request #660 from Axelrod-Python/652

Adding documentation for result set

Author: drvinceknight

axelrod/result_set.py

@@ -590,7 +590,7 @@ def build_cooperating_rating(self):
         Returns:
         --------
 
-            The list of cooperation counts
+            The list of cooperation ratings
             List of the form:
 
             [ML1, ML2, ML3..., MLn]

docs/tutorials/further_topics/morality_metrics.rst

@@ -1,3 +1,5 @@
+.. _morality-metrics:
+
 Morality Metrics
 ================
 

docs/tutorials/further_topics/probabilistict_end_tournaments.rst

@@ -11,8 +11,8 @@ probability::
     >>> tournament = axl.ProbEndTournament(players, prob_end=0.5)
 
 
-We can view the results in a similar way as for described in
-:ref:`payoff-matrix`::
+We can view the results in a similar way as described in
+:ref:`tournament-results`::
 
     >>> results = tournament.play()
     >>> m = results.payoff_matrix

docs/tutorials/getting_started/index.rst

@@ -12,7 +12,7 @@ Contents:
    installation.rst
    match.rst
    tournament.rst
-   payoff_matrix.rst
+   tournament_results.rst
    interactions.rst
    visualising_results.rst
    moran.rst

docs/tutorials/getting_started/interactions.rst

@@ -14,7 +14,7 @@ To access the detailed interaction results we create a tournament as usual
     >>> tournament = axl.Tournament(players, turns=3, repetitions=1)
     >>> results = tournament.play()
 
-The tournament object has an 'interactions' attribute which contains all the
+The result set object has an 'interactions' attribute which contains all the
 interactions between the players.
 (Actually, it's a list of lists: one list for each repetition which, in
 turn, has a list of Match objects). These can be used to view the history of the

docs/tutorials/getting_started/payoff_matrix.rst

@@ -0,0 +1,239 @@
+.. _tournament-results:
+
+Accessing tournament results
+============================
+
+This tutorial will show you how to access the various results of a tournament:
+
+- Wins: the number of matches won by each player
+- Match lengths: the number of turns of each match played by each player
+  (relevant for tournaments like probabilistic ending tournaments).
+- Scores: the total scores of each player.
+- Normalised scores: the scores normalised by matches played and turns.
+- Ranking: ranking of players based on median score.
+- Ranked names: names of players in ranked order.
+- Payoffs: average payoff per turn of each player.
+- Payoff matrix: the payoff matrix showing the payoffs of each row player
+  against each column player.
+- Payoff standard deviation: the standard deviation of the payoffs matrix.
+- Score differences: the score difference between each player.
+- Payoff difference means: the mean score differences.
+- Cooperation counts: the number of times each player cooperated.
+- Normalised cooperation: cooperation count per turn.
+- Cooperation rating: cooperation rating of each player
+- Vengeful cooperation: a morality metric from the literature (see
+  :ref:`morality-metrics`).
+- Good partner matrix: a morality metric from the literature.
+- Good partner rating: a morality metric from the literature.
+- Eigenmoses rating: a morality metric from the literature.
+- Eigenjesus rating: a morality metric from the literature.
+
+As shown in :ref:`creating_tournaments` let us create a tournament::
+
+    >>> import axelrod as axl
+    >>> players = [axl.Cooperator(), axl.Defector(),
+    ...            axl.TitForTat(), axl.Grudger()]
+    >>> tournament = axl.Tournament(players, turns=10, repetitions=3)
+    >>> results = tournament.play()
+
+Wins
+----
+
+This gives the number of wins obtained by each player::
+
+    >>> results.wins
+    [[0, 0, 0], [3, 3, 3], [0, 0, 0], [0, 0, 0]]
+
+
+The :code:`Defector` is the only player to win any matches (all other matches
+are ties).
+
+Match lengths
+-------------
+
+This gives the length of the matches played by each player::
+
+    >>> import pprint  # Nicer formatting of output
+    >>> pprint.pprint(results.match_lengths)
+    [[[10, 10, 10, 10], [10, 10, 10, 10], [10, 10, 10, 10], [10, 10, 10, 10]],
+     [[10, 10, 10, 10], [10, 10, 10, 10], [10, 10, 10, 10], [10, 10, 10, 10]],
+     [[10, 10, 10, 10], [10, 10, 10, 10], [10, 10, 10, 10], [10, 10, 10, 10]]]
+
+Every player plays 200 turns against every other player for every repetition of
+the tournament.
+
+Scores
+------
+
+This gives all the total tournament scores (per player and per repetition)::
+
+    >>> results.scores
+    [[60, 60, 60], [78, 78, 78], [69, 69, 69], [69, 69, 69]]
+
+Normalised scores
+-----------------
+
+This gives the scores, averaged per opponent and turns::
+
+    >>> results.normalised_scores  # doctest: +SKIP
+    [[2.0, 2.0, 2.0], [2.6, 2.6, 2.6], [2.3, 2.3, 2.3], [2.3, 2.3, 2.3]]
+
+We see that Cooperator got on average a score of 2 per turn per opponent.
+Note: Here using string representation to deal with floating point numbers::
+
+    >>> results.normalised_scores[0]
+    [2.0, 2.0, 2.0]
+
+Ranking
+-------
+
+This gives the ranked index of each player::
+
+    >>> results.ranking
+    [1, 2, 3, 0]
+
+The first player has index 1 (:code:`Defector`) and the last has index 0
+(:code:`Cooperator`).
+
+Ranked names
+------------
+
+This gives the player names in ranked order::
+
+    >>> results.ranked_names
+    ['Defector', 'Tit For Tat', 'Grudger', 'Cooperator']
+
+
+Payoffs
+-------
+
+This gives for each player, against each opponent every payoff received for
+each repetition::
+
+    >>> pprint.pprint(results.payoffs)
+    [[[3.0, 3.0, 3.0], [0.0, 0.0, 0.0], [3.0, 3.0, 3.0], [3.0, 3.0, 3.0]],
+     [[5.0, 5.0, 5.0], [1.0, 1.0, 1.0], [1.4, 1.4, 1.4], [1.4, 1.4, 1.4]],
+     [[3.0, 3.0, 3.0], [0.9, 0.9, 0.9], [3.0, 3.0, 3.0], [3.0, 3.0, 3.0]],
+     [[3.0, 3.0, 3.0], [0.9, 0.9, 0.9], [3.0, 3.0, 3.0], [3.0, 3.0, 3.0]]]
+
+
+Payoff matrix
+-------------
+
+This gives the mean payoff of each player against every opponent::
+
+    >>> pprint.pprint(results.payoff_matrix)  # doctest: +SKIP
+    [[3.0, 0.0, 3.0, 3.0],
+     [5.0, 1.0, 1.4, 1.4],
+     [3.0, 0.9, 3.0, 3.0],
+     [3.0, 0.9, 3.0, 3.0]]
+
+We see that the :code:`Cooperator` gets a mean score of 3 against all players
+except the :code:`Defector`::
+
+    >>> results.payoff_matrix[0]
+    [3.0, 0.0, 3.0, 3.0]
+
+Payoff standard deviation
+-------------------------
+
+This gives the standard deviation of the payoff of each player against
+every opponent::
+
+    >>> pprint.pprint(results.payoff_stddevs)  # doctest: +SKIP
+    [[0.0, 0.0, 0.0, 0.0],
+     [0.0, 0.0, 2.2, 2.2],
+     [0.0, 0.0, 0.0, 0.0],
+     [0.0, 0.0, 0.0, 0.0]]
+
+We see that there is no variation for the payoff for :code:`Cooperator`::
+
+    >>> results.payoff_stddevs[0]
+    [0.0, 0.0, 0.0, 0.0]
+
+Score differences
+-----------------
+
+This gives the score difference for each player against each opponent for every
+repetition::
+
+    >>> pprint.pprint(results.score_diffs)  # doctest: +SKIP
+    [[[0.0, 0.0, 0.0], [-5.0, -5.0, -5.0], [0.0, 0.0, 0.0], [0.0, 0.0, 0.0]],
+     [[5.0, 5.0, 5.0], [0.0, 0.0, 0.0], [0.5, 0.5, 0.5], [0.5, 0.5, 0.5]],
+     [[0.0, 0.0, 0.0], [-0.5, -0.5, -0.5], [0.0, 0.0, 0.0], [0.0, 0.0, 0.0]],
+     [[0.0, 0.0, 0.0], [-0.5, -0.5, -0.5], [0.0, 0.0, 0.0], [0.0, 0.0, 0.0]]]
+
+We see that :code:`Cooperator` has no difference in score with all players
+except against the :code:`Defector`::
+
+    >>> results.score_diffs[0]
+    [[0.0, 0.0, 0.0], [-5.0, -5.0, -5.0], [0.0, 0.0, 0.0], [0.0, 0.0, 0.0]]
+
+Payoff difference means
+-----------------------
+
+This gives the mean payoff differences over each repetition::
+
+    >>> pprint.pprint(results.payoff_diffs_means)  # doctest: +SKIP
+    [[0.0, -5.0, 0.0, 0.0],
+     [5.0, 0.0, 0.49999999999999983, 0.49999999999999983],
+     [0.0, -0.49999999999999983, 0.0, 0.0],
+     [0.0, -0.49999999999999983, 0.0, 0.0]]
+
+Here is the mean payoff difference for the :code:`Cooperator` strategy, shows
+that it has no difference with all players except against the
+:code:`Defector`::
+
+    >>> results.payoff_diffs_means[0]
+    [0.0, -5.0, 0.0, 0.0]
+
+Cooperation counts
+------------------
+
+This gives a total count of cooperation for each player against each opponent::
+
+    >>> results.cooperation
+    [[0, 30, 30, 30], [0, 0, 0, 0], [30, 3, 0, 30], [30, 3, 30, 0]]
+
+Normalised cooperation
+----------------------
+
+This gives the average rate of cooperation against each opponent::
+
+    >>> pprint.pprint(results.normalised_cooperation)  # doctest: +SKIP
+    [[1.0, 1.0, 1.0, 1.0],
+     [0.0, 0.0, 0.0, 0.0],
+     [1.0, 0.1, 1.0, 1.0],
+     [1.0, 0.1, 1.0, 1.0]]
+
+We see that :code:`Cooperator` for all the rounds (as expected)::
+
+    >>> results.normalised_cooperation[0]
+    [1.0, 1.0, 1.0, 1.0]
+
+Morality Metrics
+----------------
+
+The following morality metrics are available, they are calculated as a function
+of the cooperation rating::
+
+    >>> results.cooperating_rating
+    [1.0, 0.0, 0.7, 0.7]
+    >>> pprint.pprint(results.vengeful_cooperation)  # doctest: +SKIP
+    [[1.0, 1.0, 1.0, 1.0],
+     [-1.0, -1.0, -1.0, -1.0],
+     [1.0, -0.8, 1.0, 1.0],
+     [1.0, -0.78 1.0, 1.0]]
+    >>> pprint.pprint(results.good_partner_matrix)
+    [[0, 3, 3, 3], [0, 0, 0, 0], [3, 3, 0, 3], [3, 3, 3, 0]]
+    >>> pprint.pprint(results.good_partner_rating)
+    [1.0, 0.0, 1.0, 1.0]
+    >>> pprint.pprint(results.eigenmoses_rating)  # doctest: +SKIP
+    [0.37956816961269385,
+     -0.37956816961269385,
+     0.5965970202882925,
+     0.5965970202882925]
+    >>> pprint.pprint(results.eigenjesus_rating)  # doctest: +SKIP
+    [0.5773502691896258, 0.0, 0.5773502691896258, 0.5773502691896258]
+
+For more information about these see :ref:`morality-metrics`.

docs/tutorials/getting_started/tournament_results.rst

@@ -43,9 +43,9 @@ We can view the distributions of wins for each strategy::
 Visualising the payoff matrix
 -----------------------------
 
-We can also easily view the payoff matrix described in :doc:`payoff_matrix`, this
-becomes particularly useful when viewing the outputs of tournaments with a large
-number of strategies::
+We can also easily view the payoff matrix described in
+:ref:`tournament-results`, this becomes particularly useful when viewing the
+outputs of tournaments with a large number of strategies::
 
     >>> p = plot.payoff()
     >>> p.show()