added more description

COMSOC-Community · Jun 25, 2024 · 4cfecec · 4cfecec
1 parent 1b97560
commit 4cfecec
Show file tree

Hide file tree

Showing 3 changed files with 52 additions and 2 deletions.
diff --git a/docs-source/source/usage/rules.rst b/docs-source/source/usage/rules.rst
@@ -282,6 +282,30 @@ performances, one should use the following:
     )
 
 
+CSTV Algorithm
+--------------
+
+:py:func:`~pabutools.rules.cstv.cstv`
+
+The `cstv` function implements the Cost-Sensitive Approval Voting algorithm for participatory budgeting. It takes into account both voter preferences and project costs to allocate budgets efficiently.
+
+.. code-block:: python
+
+    from pabutools.election import Instance, Project, ApprovalProfile, ApprovalBallot
+    from pabutools.rules import cstv
+
+    projects = Instance(Project("Project A", 35), Project("Project B", 30))
+    instance = Instance(projects)
+
+    donors = Profile([CumulativeBallot({"Project A": 5, "Project B": 10), CumulativeBallot({"Project A": 5, "Project B": 10), CumulativeBallot({"Project A": 0, "Project B": 15), CumulativeBallot({"Project A": 8, "Project B": 7}), CumulativeBallot({"Project A": 10, "Project B": 5)])
+    outcome1 = cstv_allocation(instance, profile1)
+
+Details for the Budget Allocation Rule
+--------------------------------------
+
+The `cstv` function returns a :py:class:`~pabutools.rules.budgetallocation.BudgetAllocation` object, which includes information about the allocated budget and can be used for further analysis or visualization.
+
+
 Exhaustion Methods
 ------------------
 

diff --git a/docs/_sources/usage/rules.rst b/docs/_sources/usage/rules.rst
@@ -282,6 +282,30 @@ performances, one should use the following:
     )
 
 
+CSTV Algorithm
+--------------
+
+:py:func:`~pabutools.rules.cstv.cstv`
+
+The `cstv` function implements the Cost-Sensitive Approval Voting algorithm for participatory budgeting. It takes into account both voter preferences and project costs to allocate budgets efficiently.
+
+.. code-block:: python
+
+    from pabutools.election import Instance, Project, ApprovalProfile, ApprovalBallot
+    from pabutools.rules import cstv
+
+    projects = Instance(Project("Project A", 35), Project("Project B", 30))
+    instance = Instance(projects)
+
+    donors = Profile([CumulativeBallot({"Project A": 5, "Project B": 10), CumulativeBallot({"Project A": 5, "Project B": 10), CumulativeBallot({"Project A": 0, "Project B": 15), CumulativeBallot({"Project A": 8, "Project B": 7}), CumulativeBallot({"Project A": 10, "Project B": 5)])
+    outcome1 = cstv_allocation(instance, profile1)
+
+Details for the Budget Allocation Rule
+--------------------------------------
+
+The `cstv` function returns a :py:class:`~pabutools.rules.budgetallocation.BudgetAllocation` object, which includes information about the allocated budget and can be used for further analysis or visualization.
+
+
 Exhaustion Methods
 ------------------
 

diff --git a/pabutools/rules/CSTV.py b/pabutools/rules/CSTV.py
@@ -26,7 +26,10 @@
 def cstv_budgeting(projects: Instance, donors: Profile, project_to_fund_selection_procedure: callable, eligible_fn: callable,
                     no_eligible_project_procedure: callable, inclusive_maximality_postprocedure: callable) -> BudgetAllocation:
     """
-    The CSTV (Cumulative Support Transfer Voting) budgeting algorithm to select projects based on donor ballots.
+    The CSTV (Cumulative Support Transfer Voting) budgeting algorithm determines project funding based on cumulative support from donor ballots.
+    This function evaluates a list of projects and donor profiles, selecting projects for funding according to the CSTV methodology. 
+    It employs various procedures for project selection, eligibility determination, and handling of scenarios where no eligible projects exist or to ensure inclusive maximality.
+    You can read more about the algorithm in sections 4 and 5 in the paper here: https://arxiv.org/pdf/2009.02690 in sections 4 and 5.
 
     Parameters
     ----------
@@ -652,4 +655,3 @@ def regular_example():
     doctest.testmod()
     regular_example()
 
-