Merge pull request #24 from lchipchase/mes-and-greedy

Address Feedback and Fix Bugs

docs-source/source/usage/outcomevisualisation.rst

@@ -14,20 +14,23 @@ Greedy Utilitarian Welfare
 
 The visualisation for the Greedy Utilitarian Welfare currently works only on additive utility functions.
 
-We provide a way to visualise the results using the class :py:class:`~pabutools.visualisation.GreedyWelfareVisualiser`. Note the analytics flag in the function :py:func:`~pabutools.rules.greedywelfare.greedy_utilitarian_welfare` must be set to True to generate the visualisation.
+We provide a way to visualise the results using the class :py:class:`~pabutools.visualisation.visualisation.GreedyWelfareVisualiser`. Note the analytics flag in the function :py:func:`~pabutools.rules.greedywelfare.greedy_utilitarian_welfare` must be set to True to generate the visualisation.
 
 .. code-block:: python
 
-    from pabutools.visualisation import GreedyWelfareVisualiser
+    from pabutools.visualisation.visualisation import GreedyWelfareVisualiser
     from pabutools.rules.greedywelfare import greedy_utilitarian_welfare
     from pabutools import election
     from pabutools.election import Cost_Sat
 
     instance, profile = election.parse_pabulib("./{path_to_election_file}.pb")
     outcome = greedy_utilitarian_welfare(instance, profile, sat_class=Cost_Sat, analytics=True)
 
-    visualiser = GreedyWelfareVisualiser(profile, instance, outcome.details)
-    visualiser.render("./{path_to_output_file}/")
+    # The visualiser takes the profile, instance, and outcome as arguments
+    visualiser = GreedyWelfareVisualiser(profile, instance, outcome)
+
+    # output_filename is option and defaults to greedy_explanation.html
+    visualiser.render("./{path_to_output_file}/", output_filename="{output_filename}")
 
 The visualisation will be saved in the specified path as a standalone HTML file called round_analysis.html. 
 
@@ -36,18 +39,22 @@ Note that the visualisation is only available for additive utility functions.
 Method of Equal Shares
 ----------------------
 
-We provide a way to visualise the results using the class :py:class:`~pabutools.visualisation.MESVisualiser`. Note the analytics flag in the function :py:func:`~pabutools.rules.mes.method_of_equal_shares` must be set to True to generate the visualisation. The visualisations for MES consist of two pages: one for the summary of the election, containing the allocation of the budget, information about all the elected projects, and summary statistics about the election as a whole. The second page contains the details of the election, giving statistics about each round of the election, including the selected project, and how each round impacts the effective vote count of others. This captures the essence of the method of equal shares, where the effective vote count of each project is updated after each round.
+We provide a way to visualise the results using the class :py:class:`~pabutools.visualisation.visualisation.MESVisualiser`. Note the analytics flag in the function :py:func:`~pabutools.rules.mes.method_of_equal_shares` must be set to True to generate the visualisation. The visualisations for MES consist of two pages: one for the summary of the election, containing the allocation of the budget, information about all the elected projects, and summary statistics about the election as a whole. The second page contains the details of the election, giving statistics about each round of the election, including the selected project, and how each round impacts the effective vote count of others. This captures the essence of the method of equal shares, where the effective vote count of each project is updated after each round.
 
 .. code-block:: python
 
-    from pabutools.visualisation import MESVisualiser
+    from pabutools.visualisation.visualisation import MESVisualiser
     from pabutools.rules.mes import method_of_equal_shares
     from pabutools import election
+    from pabutools.election import Cost_Sat
 
     instance, profile = election.parse_pabulib("./{path_to_election_file}.pb")
-    outcome = method_of_equal_shares(instance, profile, analytics=True)
+    outcome = method_of_equal_shares(instance, profile, sat_class=Cost_Sat analytics=True)
+
+    # The visualiser takes the profile, instance, and outcome as arguments
+    visualiser = MESVisualiser(profile, instance, outcome)
 
-    visualiser = MESVisualiser(profile, instance, outcome.details)
-    visualiser.render("./{path_to_output_file}/")
+    # name is optional and defaults to the empty string
+    visualiser.render("./{path_to_output_file}/", name="{name}")
 
-The visualisations will be saved with the filenames summary.html and round_analysis.html respectively in the specified path. These work as standalone HTML files, and must be stored in the same directory to ensure the links between different pages work correctly.
+The visualisations will be saved with the filenames {name}_summary.html and {name}_round_analysis.html respectively in the specified path. These work as standalone HTML files, and must be stored in the same directory to ensure the links between different pages work correctly.

docs/_sources/usage/outcomevisualisation.rst

@@ -14,20 +14,23 @@ Greedy Utilitarian Welfare
 
 The visualisation for the Greedy Utilitarian Welfare currently works only on additive utility functions.
 
-We provide a way to visualise the results using the class :py:class:`~pabutools.visualisation.GreedyWelfareVisualiser`. Note the analytics flag in the function :py:func:`~pabutools.rules.greedywelfare.greedy_utilitarian_welfare` must be set to True to generate the visualisation.
+We provide a way to visualise the results using the class :py:class:`~pabutools.visualisation.visualisation.GreedyWelfareVisualiser`. Note the analytics flag in the function :py:func:`~pabutools.rules.greedywelfare.greedy_utilitarian_welfare` must be set to True to generate the visualisation.
 
 .. code-block:: python
 
-    from pabutools.visualisation import GreedyWelfareVisualiser
+    from pabutools.visualisation.visualisation import GreedyWelfareVisualiser
     from pabutools.rules.greedywelfare import greedy_utilitarian_welfare
     from pabutools import election
     from pabutools.election import Cost_Sat
 
     instance, profile = election.parse_pabulib("./{path_to_election_file}.pb")
     outcome = greedy_utilitarian_welfare(instance, profile, sat_class=Cost_Sat, analytics=True)
 
-    visualiser = GreedyWelfareVisualiser(profile, instance, outcome.details)
-    visualiser.render("./{path_to_output_file}/")
+    # The visualiser takes the profile, instance, and outcome as arguments
+    visualiser = GreedyWelfareVisualiser(profile, instance, outcome)
+
+    # output_filename is option and defaults to greedy_explanation.html
+    visualiser.render("./{path_to_output_file}/", output_filename="{output_filename}")
 
 The visualisation will be saved in the specified path as a standalone HTML file called round_analysis.html. 
 
@@ -36,18 +39,22 @@ Note that the visualisation is only available for additive utility functions.
 Method of Equal Shares
 ----------------------
 
-We provide a way to visualise the results using the class :py:class:`~pabutools.visualisation.MESVisualiser`. Note the analytics flag in the function :py:func:`~pabutools.rules.mes.method_of_equal_shares` must be set to True to generate the visualisation. The visualisations for MES consist of two pages: one for the summary of the election, containing the allocation of the budget, information about all the elected projects, and summary statistics about the election as a whole. The second page contains the details of the election, giving statistics about each round of the election, including the selected project, and how each round impacts the effective vote count of others. This captures the essence of the method of equal shares, where the effective vote count of each project is updated after each round.
+We provide a way to visualise the results using the class :py:class:`~pabutools.visualisation.visualisation.MESVisualiser`. Note the analytics flag in the function :py:func:`~pabutools.rules.mes.method_of_equal_shares` must be set to True to generate the visualisation. The visualisations for MES consist of two pages: one for the summary of the election, containing the allocation of the budget, information about all the elected projects, and summary statistics about the election as a whole. The second page contains the details of the election, giving statistics about each round of the election, including the selected project, and how each round impacts the effective vote count of others. This captures the essence of the method of equal shares, where the effective vote count of each project is updated after each round.
 
 .. code-block:: python
 
-    from pabutools.visualisation import MESVisualiser
+    from pabutools.visualisation.visualisation import MESVisualiser
     from pabutools.rules.mes import method_of_equal_shares
     from pabutools import election
+    from pabutools.election import Cost_Sat
 
     instance, profile = election.parse_pabulib("./{path_to_election_file}.pb")
-    outcome = method_of_equal_shares(instance, profile, analytics=True)
+    outcome = method_of_equal_shares(instance, profile, sat_class=Cost_Sat analytics=True)
+
+    # The visualiser takes the profile, instance, and outcome as arguments
+    visualiser = MESVisualiser(profile, instance, outcome)
 
-    visualiser = MESVisualiser(profile, instance, outcome.details)
-    visualiser.render("./{path_to_output_file}/")
+    # name is optional and defaults to the empty string
+    visualiser.render("./{path_to_output_file}/", name="{name}")
 
-The visualisations will be saved with the filenames summary.html and round_analysis.html respectively in the specified path. These work as standalone HTML files, and must be stored in the same directory to ensure the links between different pages work correctly.
+The visualisations will be saved with the filenames {name}_summary.html and {name}_round_analysis.html respectively in the specified path. These work as standalone HTML files, and must be stored in the same directory to ensure the links between different pages work correctly.