Add summarise and write_summary to resultset

Addresses one part of #701

At the moment I've just included the following tournament results:

- Rank
- Name
- Score
- Cooperation rating
- Wins

Easy enough to add more.

Author: drvinceknight

.gitignore

@@ -11,4 +11,5 @@ Axelrod.egg-info
 basic_strategies.csv
 cache.txt
 test.csv
+summary.csv
 basic_tournament.csv

axelrod/result_set.py

@@ -1,6 +1,7 @@
 import csv
 import tqdm
 
+from collections import namedtuple
 from numpy import mean, nanmedian, std
 
 from . import eigen
@@ -696,6 +697,53 @@ def __eq__(self, other):
     def __ne__(self, other):
         return not self.__eq__(other)
 
+    def summarise(self):
+        """
+        Obtain summary of performance of each strategy:
+        ordered by rank, including median normalised score and cooperation
+        rating.
+
+        Output
+        ------
+
+            A list of the form:
+
+            [[player name, median score, cooperation_rating],...]
+
+        """
+
+        median_scores = map(nanmedian, self.normalised_scores)
+        median_wins = map(nanmedian, self.wins)
+
+        self.player = namedtuple("Player", ["Rank", "Name", "Median_score",
+                                            "Cooperation_rating", "Wins"])
+
+        summary_data = [perf for perf in zip(self.players,
+                                             median_scores,
+                                             self.cooperating_rating,
+                                             median_wins)]
+        summary_data = [self.player(rank, *summary_data[i]) for
+                        rank, i in enumerate(self.ranking)]
+
+        return summary_data
+
+    def write_summary(self, filename):
+        """
+        Write a csv file containing summary data of the results of the form:
+
+            "Rank", "Name", "Median-score-per-turn", "Cooperation-rating"
+
+        Parameters
+        ----------
+            filename : a filepath to which to write the data
+        """
+        summary_data = self.summarise()
+        with open(filename, 'w') as csvfile:
+            writer = csv.writer(csvfile)
+            writer.writerow(self.player._fields)
+            for player in summary_data:
+                writer.writerow(player)
+
 
 class ResultSetFromFile(ResultSet):
     """

axelrod/tests/unit/test_resultset.py

@@ -2,9 +2,10 @@
 import axelrod
 import axelrod.interaction_utils as iu
 
-from numpy import mean, std
+from numpy import mean, std, nanmedian
 
 import tempfile
+import csv
 
 from hypothesis import given, settings
 from axelrod.tests.property import tournaments, prob_end_tournaments
@@ -384,6 +385,46 @@ def test_equality(self):
         results = tournament.play()
         self.assertNotEqual(results, rs_sets[0])
 
+    def test_summarise(self):
+        rs = axelrod.ResultSet(self.players, self.interactions,
+                               progress_bar=False)
+        sd = rs.summarise()
+
+        self.assertEqual(len(sd), len(rs.players))
+        self.assertEqual([str(player.Name) for player in sd], rs.ranked_names)
+        self.assertEqual([int(player.Rank) for player in sd],
+                         list(range(len(self.players))))
+
+        ranked_median_scores = [list(map(nanmedian, rs.normalised_scores))[i]
+                                for i in rs.ranking]
+        self.assertEqual([float(player.Median_score) for player in sd],
+                         ranked_median_scores)
+
+        ranked_cooperation_rating = [rs.cooperating_rating[i]
+                                     for i in rs.ranking]
+        self.assertEqual([float(player.Cooperation_rating) for player in sd],
+                         ranked_cooperation_rating)
+
+        ranked_median_wins = [nanmedian(rs.wins[i]) for i in rs.ranking]
+        self.assertEqual([float(player.Wins) for player in sd],
+                         ranked_median_wins)
+
+    def test_write_summary(self):
+        tmp_file = tempfile.NamedTemporaryFile()
+        rs = axelrod.ResultSet(self.players, self.interactions,
+                               progress_bar=False)
+        rs.write_summary(filename=tmp_file.name)
+        with open(tmp_file.name, "r") as csvfile:
+            ranked_names = []
+            csvreader = csv.reader(csvfile)
+            for row in csvreader:
+                ranked_names.append(row[1])
+                self.assertEqual(len(row), 5)
+        self.assertEqual(ranked_names[0], "Name")
+        self.assertEqual(ranked_names[1:], rs.ranked_names)
+
+
+
 
 class TestResultSetFromFile(unittest.TestCase):
     tmp_file = tempfile.NamedTemporaryFile(mode='w', delete=False)

docs/tutorials/getting_started/tournament_results.rst

@@ -233,3 +233,29 @@ of the cooperation rating::
     [0.57..., 0.0, 0.57..., 0.57...]
 
 For more information about these see :ref:`morality-metrics`.
+
+Summarising a tournament
+------------------------
+
+The results set can also return a list of named tuples, ordered by strategy rank
+that summarises the results of the tournament::
+
+    >>> summary = results.summarise()
+    >>> pprint.pprint(summary)
+    [Player(Rank=0, Name='Defector', Median_score=2.6..., Cooperation_rating=0.0, Wins=3.0),
+     Player(Rank=1, Name='Tit For Tat', Median_score=2.3..., Cooperation_rating=0.7, Wins=0.0),
+     Player(Rank=2, Name='Grudger', Median_score=2.3..., Cooperation_rating=0.7, Wins=0.0),
+     Player(Rank=3, Name='Cooperator', Median_score=2.0..., Cooperation_rating=1.0, Wins=0.0)]
+
+It is also possible to write this data directly to a csv file using the
+`write_summary` method::
+
+    >>> results.write_summary('summary.csv')
+    >>> with open('summary.csv', 'r') as outfile:
+    ...     out = outfile.read()
+    >>> pprint.pprint(out)
+    ('Rank,Name,Median_score,Cooperation_rating,Wins\n'
+     '0,Defector,2.6,0.0,3.0\n'
+     '1,Tit For Tat,2.3,0.7,0.0\n'
+     '2,Grudger,2.3,0.7,0.0\n'
+     '3,Cooperator,2.0,1.0,0.0\n')