diff --git a/axelrod/result_set.py b/axelrod/result_set.py index ad250897e..f437f5f99 100644 --- a/axelrod/result_set.py +++ b/axelrod/result_set.py @@ -573,7 +573,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] diff --git a/docs/tutorials/further_topics/morality_metrics.rst b/docs/tutorials/further_topics/morality_metrics.rst index f4f16a3c2..12de1d2f3 100644 --- a/docs/tutorials/further_topics/morality_metrics.rst +++ b/docs/tutorials/further_topics/morality_metrics.rst @@ -1,3 +1,5 @@ +.. _morality-metrics: + Morality Metrics ================ diff --git a/docs/tutorials/further_topics/probabilistict_end_tournaments.rst b/docs/tutorials/further_topics/probabilistict_end_tournaments.rst index becf0cf20..e5cbbec86 100644 --- a/docs/tutorials/further_topics/probabilistict_end_tournaments.rst +++ b/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 diff --git a/docs/tutorials/getting_started/index.rst b/docs/tutorials/getting_started/index.rst index 252746de4..11ce0962a 100644 --- a/docs/tutorials/getting_started/index.rst +++ b/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 diff --git a/docs/tutorials/getting_started/interactions.rst b/docs/tutorials/getting_started/interactions.rst index 9f42ec923..49cded9f5 100644 --- a/docs/tutorials/getting_started/interactions.rst +++ b/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 diff --git a/docs/tutorials/getting_started/payoff_matrix.rst b/docs/tutorials/getting_started/payoff_matrix.rst deleted file mode 100644 index d859f36f0..000000000 --- a/docs/tutorials/getting_started/payoff_matrix.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _payoff-matrix: - -Accessing the payoff matrix -=========================== - -This tutorial will show you briefly how to access the payoff matrix -corresponding to the tournament. - -As shown in :ref:`getting-started` let us create a tournament:: - - >>> import axelrod as axl - >>> players = [axl.Cooperator(), axl.Defector(), - ... axl.TitForTat(), axl.Grudger()] - >>> tournament = axl.Tournament(players) - >>> results = tournament.play() - -We can view the payoff matrix of our tournament showing the score of the row-th -strategy when played against the column-th strategy:: - - >>> m = results.payoff_matrix - >>> for row in m: - ... print([round(ele, 1) for ele in row]) # Rounding output - [3.0, 0.0, 3.0, 3.0] - [5.0, 1.0, 1.0, 1.0] - [3.0, 1.0, 3.0, 3.0] - [3.0, 1.0, 3.0, 3.0] - -Here we see that the second strategy (:code:`Defector`) obtains an average -utility per game of :code:`5.0` against the first strategy (:code:`Cooperator`) -as expected. - diff --git a/docs/tutorials/getting_started/tournament_results.rst b/docs/tutorials/getting_started/tournament_results.rst new file mode 100644 index 000000000..11b101e3c --- /dev/null +++ b/docs/tutorials/getting_started/tournament_results.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`. diff --git a/docs/tutorials/getting_started/visualising_results.rst b/docs/tutorials/getting_started/visualising_results.rst index fc640f1a2..d0db28c2f 100644 --- a/docs/tutorials/getting_started/visualising_results.rst +++ b/docs/tutorials/getting_started/visualising_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()