Add pabutools.recommendation: a recommendation system for participatory budgeting

[roeiyanku]

Implements "A Recommendation System for Participatory Budgeting" by Gil
Leibiker and Nimrod Talmon (AAMAS 2023):
https://optlearnmas23.github.io/files/p17.pdf

The module addresses the paper's information overload problem — the cognitive
burden of judging every project on a long ballot. Instead of asking every voter
about every project, it queries each voter for a partial ballot, estimates the
votes it did not ask for, and runs the voting rule on the completion.

Contents

• The five sampling setups of §3.1: random, offline by popularity, consensus
  and controversiality, and the online adaptive setup. next_adaptive_question
  exposes a single step of the adaptive loop so it can drive a live process,
  not only a simulation.
• The three prediction modules of §2.1: binary classification with XGBoost,
  matrix factorization, and factorization machines.
• The LV/TV partiality arithmetic of §3.0.1 (plan_sampling, split_lv_tv),
  greedy approval, elect for running a real process where no ground truth
  exists, and the evaluation metrics of §5.
• 43 tests in tests/test_recommendation.py, plus doctests throughout.

Dependencies

The machine-learning libraries are an optional recommendation extra and are
imported lazily inside the functions that need them, so the module imports and
every non-ML algorithm works without them. Tests that fit a model skip rather
than fail when the library is absent, which keeps CI green on the standard
.[dev] install.

Notes on the paper

Two points are under-specified or inconsistent; both are documented in the
docstrings alongside the reading that was implemented:

• §2.1.1 states that binary classification is used and that XGBoost suits it,
  but never defines what a training row is or which features it carries.
• §5.2.1 defines symmetric distance as |rb △ pb|, yet its second example gives
  SD({1,2,3}, {1,3,4}) = 1 where the definition yields 2. The first and third
  examples agree with the definition, which is what is implemented.

[Simon-Rey]

Hey :) Thank you for your contribution. I don't fully understand what the code offers, could you explain to me how a user would use these functions and what they would provide?

[roeiyanku]

Thank you for the quick response! I'll explain below and also add an rst file.

In short: it lets a PB election run without asking every voter about every project. You ask each person about a handful, estimate the votes you never asked for, and the usual voting rule takes it from there. (For context, this came out of #58, which Erel opened for our Research Algorithms course.)

There are two flows.

Running an actual PB process where you cannot ask everyone about everything. You hold the ballots of the people who did fill one in completely, you choose which projects to put to everyone else, collect their partial answers, and get an outcome:

asked = offline_controversiality(instance, lv_profile, k=2)

{Library, Shade} <- the two projects the complete ballots most disagree about

answers = {
"v5": partial_ballot(approved={garden}, disapproved={crossings}),
"v6": partial_ballot(approved={crossings}, disapproved={garden}),
}

elect(instance, lv_profile, answers, predictor="classification")

BudgetAllocation([Garden, Shade])

So a user provides the instance, the ballots collected in full, and one partial ballot per remaining voter. They get back a BudgetAllocation, the same as from any other rule. The prediction only fills in projects a voter was never asked about; anything she actually answered is kept as given.

Evaluating the idea instead.
Here a user provides a complete profile and two numbers — how much of the vote to collect, and how much of that should come from complete ballots — and gets back the allocation that partial information would have produced, to compare against the real one:

real = set(greedy_approval(instance, profile))
predicted = set(run_experiment(instance, profile, 0.5, 0.5,
setup="offline_controversiality", seed=17))

fractional_allocation_score(real, predicted, instance.budget_limit) # 0.75

run_experiment is a simulation:
it splits the profile you already hold into the voters who answer in full and the ones who do not, reads each of the latter's answers to her k asked projects off her real ballot, and withholds the rest for the predictor to estimate. That is why it needs a complete profile, and why elect is the one to use when you actually collected the answers yourself. run_all_experiments repeats it across a whole grid of those two numbers, for every sampling setup and prediction module at once.

Everything else is the individual steps of those two flows, for anyone who wants to assemble them differently.

I pushed a usage page, docs-source/source/usage/recommendation.rst. It covers the above with runnable examples. Building the docs to check it also turned up two markup errors in my own docstrings (|LV| is substitution syntax in reStructuredText, and one :py:func: target was wrong); both are fixed in the same commit.

Happy to restructure any of it to fit your conventions.