vse_sim.data_classes

  1import random
  2
  3from .compat import isnum, mean
  4from .decorators import autoassign, decorator
  5
  6
  7class VseOneRun:
  8    @autoassign
  9    def __init__(self, result, tallyItems, strat):
 10        pass
 11
 12
 13class VseMethodRun:
 14    @autoassign
 15    def __init__(self, method, choosers, results):
 16        pass
 17
 18
 19####data holders for output
 20from collections import defaultdict
 21
 22
 23class SideTally(defaultdict):
 24    """Used for keeping track of how many voters are being strategic, etc.
 25
 26    DO NOT use plain +; for this class, it is equivalent to +=, but less readable.
 27
 28    """
 29
 30    def __init__(self):
 31        super().__init__(int)
 32
 33    def initKeys(self, chooser):
 34        try:
 35            self.keyList = chooser.allTallyKeys()
 36        except AttributeError:
 37            try:
 38                self.keyList = list(chooser)
 39            except TypeError:
 40                self.keyList = []
 41        self.initKeys = staticmethod(lambda x: x)  # don't do it again
 42
 43    def serialize(self):
 44        try:
 45            return [self[key] for key in self.keyList]
 46        except AttributeError:
 47            return []
 48
 49    def fullSerialize(self):
 50        if not hasattr(self, "keyList"):
 51            return [self[key] for key in self.keys()]
 52        return [self[key] for key in self.keyList]
 53
 54    def itemList(self):
 55        try:
 56            kl = self.keyList
 57            return [(k, self[k]) for k in kl] + [(k, self[k]) for k in self.keys() if k not in kl]
 58        except AttributeError:
 59            return list(self.items())
 60
 61
 62class Tallies(list):
 63    """Used (ONCE) as an enumerator, gives an inexhaustible flow of SideTally objects.
 64    After that, use as list to see those objects.
 65
 66    >>> ts = Tallies()
 67    >>> for i, j in zip(ts, [5,4,3]):
 68    ...     i[j] += j
 69    ...
 70    >>> [t.serialize() for t in ts]
 71    [[], [], [], []]
 72    >>> [t.fullSerialize() for t in ts]
 73    [[5], [4], [3], []]
 74    >>> [t.initKeys([k]) for (t,k) in zip(ts,[6,4,3])]
 75    [None, None, None]
 76    >>> [t.serialize() for t in ts]
 77    [[0], [4], [3], []]
 78    """
 79
 80    def __iter__(self):
 81        if getattr(self, "used", False):
 82            return super().__iter__()
 83        self.used = True
 84        return self._generated_tallies()
 85
 86    def __eq__(self, other):
 87        if not isinstance(other, Tallies):
 88            return super().__eq__(other)
 89        return super().__eq__(other) and getattr(self, "used", False) == getattr(
 90            other, "used", False
 91        )
 92
 93    def _generated_tallies(self):
 94        while True:
 95            tally = SideTally()
 96            self.append(tally)
 97            yield tally
 98
 99
100##Election Methods
101class Method:
102    """Base class for election methods. Holds some of the duct tape."""
103
104    def __str__(self):
105        return self.__class__.__name__
106
107    def results(self, ballots, isHonest=False, **kwargs):
108        """Combines ballots into results. Override for comparative
109        methods.
110
111        Ballots is an iterable of list-or-tuple of numbers (utility) higher is better for the choice of that index.
112
113        Returns a results-array which should be a list of the same length as a ballot with a number (higher is better) for the choice at that index.
114
115        Test for subclasses, makes no sense to test this method in the abstract base class.
116        """
117        from .dataframe import ballots_from_dataframe
118
119        ballots = ballots_from_dataframe(ballots)
120        return list(map(self.candScore, zip(*ballots)))
121
122    def honest_ballots(self, voters):
123        """Return honest ballots for voters as method-ready lists."""
124        sentinel = object()
125        previous_cuts = getattr(self.__class__, "specificCuts", sentinel)
126        try:
127            ballot_factory = self.honBallotFor(voters)
128            return [ballot_factory(self.__class__, voter) for voter in voters]
129        finally:
130            if previous_cuts is sentinel:
131                try:
132                    delattr(self.__class__, "specificCuts")
133                except AttributeError:
134                    pass
135            else:
136                self.__class__.specificCuts = previous_cuts
137
138    def ballots_dataframe(self, voters, wide=False):
139        """Return honest ballots for voters as a tidy or wide DataFrame."""
140        from .dataframe import ballots_to_dataframe
141
142        return ballots_to_dataframe(self.honest_ballots(voters), wide=wide, method=self)
143
144    def results_dataframe(self, ballots, isHonest=False, **kwargs):
145        """Return candidate scores for ballots as a DataFrame."""
146        from .dataframe import scores_to_dataframe
147
148        self.__class__.extraEvents = {}
149        return scores_to_dataframe(
150            self.results(ballots, isHonest=isHonest, **kwargs),
151            method=self,
152        )
153
154    @staticmethod  # cls is provided explicitly, not through binding
155    def honBallot(cls, utils):
156        """Takes utilities and returns an honest ballot"""
157        raise NotImplementedError(f"{cls} needs honBallot")
158
159    @staticmethod
160    def winner(results):
161        """Simply find the winner once scores are already calculated. Override for
162        ranked methods.
163
164
165        >>> Method().winner([1,2,3,2,-100])
166        2
167        >>> 2 < Method().winner([1,2,1,3,3,3,2,1,2]) < 6
168        True
169        """
170        winScore = max(result for result in results if isnum(result))
171        winners = [cand for (cand, score) in enumerate(results) if score == winScore]
172        return random.choice(winners)
173
174    def honBallotFor(self, voters):
175        """This is where you would do any setup necessary and create an honBallot
176        function. But the base version just returns the honBallot function."""
177        return self.honBallot
178
179    def dummyBallotFor(self, polls):
180        """Returns a (function which takes utilities and returns a dummy ballot)
181        for the given "polling" info."""
182        return lambda cls, utilities, stratTally: utilities
183
184    def resultsFor(self, voters, chooser, tally=None, **kwargs):
185        """create ballots and get results.
186
187        Again, test on subclasses.
188        """
189        if tally is None:
190            tally = SideTally()
191        tally.initKeys(chooser)
192        return dict(
193            results=self.results(
194                [chooser(self.__class__, voter, tally) for voter in voters], **kwargs
195            ),
196            chooser=chooser.__name__,
197            tally=tally,
198        )
199
200    def multiResults(self, voters, chooserFuns=(), media=(lambda x, t: x), checkStrat=True):
201        """Runs two base elections: first with honest votes, then
202        with strategic results based on the first results (filtered by
203        the media). Then, runs a series of elections using each chooserFun
204        in chooserFuns to select the votes for each voter.
205
206        Returns a tuple of (honResults, stratResults, ...). The stratresults
207        are based on common polling information, which is given by media(honresults).
208        """
209        from .strategies import OssChooser
210
211        honTally = SideTally()
212        self.__class__.extraEvents = {}
213        hon = self.resultsFor(voters, self.honBallotFor(voters), honTally, isHonest=True)
214
215        stratTally = SideTally()
216
217        polls = media(hon["results"], stratTally)
218        winner, _w, target, _t = self.stratTargetFor(sorted(enumerate(polls), key=lambda x: -x[1]))
219
220        strat = self.resultsFor(voters, self.stratBallotFor(polls), stratTally)
221
222        ossTally = SideTally()
223        oss = self.resultsFor(voters, self.ballotChooserFor(OssChooser()), ossTally)
224        ossWinner = oss["results"].index(max(oss["results"]))
225        ossTally["worked"] += 1 if ossWinner == target else (0 if ossWinner == winner else -1)
226
227        smart = dict(
228            results=(hon["results"] if ossTally["worked"] == 1 else oss["results"]),
229            chooser="smartOss",
230            tally=SideTally(),
231        )
232
233        extraTallies = Tallies()
234        results = [strat, oss, smart] + [
235            self.resultsFor(voters, self.ballotChooserFor(chooserFun), aTally)
236            for (chooserFun, aTally) in zip(chooserFuns, extraTallies)
237        ]
238        return [(hon["results"], hon["chooser"], list(self.__class__.extraEvents.items()))] + [
239            (r["results"], r["chooser"], r["tally"].itemList()) for r in results
240        ]
241
242    def vseOn(self, voters, chooserFuns=(), **args):
243        """Finds honest and strategic voter satisfaction efficiency (VSE)
244        for this method on the given electorate.
245        """
246        multiResults = self.multiResults(voters, chooserFuns, **args)
247        utils = voters.socUtils
248        best = max(utils)
249        rand = mean(utils)
250
251        # import pprint
252        # pprint.pprint(multiResults)
253        vses = VseMethodRun(
254            self.__class__,
255            chooserFuns,
256            [
257                VseOneRun(
258                    [(utils[self.winner(result)] - rand) / (best - rand)],
259                    tally,
260                    chooser,
261                )
262                for (result, chooser, tally) in multiResults[0]
263            ],
264        )
265        vses.extraEvents = multiResults[1]
266        return vses
267
268    def resultsTable(self, eid, emodel, cands, voters, chooserFuns=(), **args):
269        multiResults = self.multiResults(voters, chooserFuns, **args)
270        utils = voters.socUtils
271        best = max(utils)
272        rand = mean(utils)
273        rows = []
274        nvot = len(voters)
275        for result, chooser, tallyItems in multiResults:
276            row = {
277                "eid": eid,
278                "emodel": emodel,
279                "ncand": cands,
280                "nvot": nvot,
281                "best": best,
282                "rand": rand,
283                "method": str(self),
284                "chooser": chooser,  # .getName(),
285                "util": utils[self.winner(result)],
286                "vse": (utils[self.winner(result)] - rand) / (best - rand),
287            }
288            # print(tallyItems)
289            for i, (k, v) in enumerate(tallyItems):
290                # print("Result: tally ",i,k,v)
291                row[f"tallyName{str(i)}"] = str(k)
292                row[f"tallyVal{str(i)}"] = str(v)
293            rows.append(row)
294        return rows
295
296    @staticmethod
297    def ballotChooserFor(chooserFun):
298        """Takes a chooserFun; returns a ballot chooser using that chooserFun"""
299
300        def ballotChooser(cls, voter, tally):
301            return getattr(voter, f"{cls.__name__}_{chooserFun(cls, voter, tally)}")
302
303        ballotChooser.__name__ = chooserFun.getName()
304        return ballotChooser
305
306    def stratTarget2(self, places):
307        ((frontId, frontResult), (targId, targResult)) = places[:2]
308        return (frontId, frontResult, targId, targResult)
309
310    def stratTarget3(self, places):
311        ((frontId, frontResult), (targId, targResult)) = places[:3:2]
312        return (frontId, frontResult, targId, targResult)
313
314    stratTargetFor = stratTarget2
315
316    def stratBallotFor(self, polls):
317        """Returns a (function which takes utilities and returns a strategic ballot)
318        for the given "polling" info."""
319
320        places = sorted(enumerate(polls), key=lambda x: -x[1])  # from high to low
321        # print("places",places)
322        (frontId, frontResult, targId, targResult) = self.stratTargetFor(places)
323        n = len(polls)
324
325        @rememberBallots
326        def stratBallot(cls, voter):
327            stratGap = voter[targId] - voter[frontId]
328            ballot = [0] * len(voter)
329            isStrat = stratGap > 0
330            extras = cls.fillStratBallot(
331                voter,
332                polls,
333                places,
334                n,
335                stratGap,
336                ballot,
337                frontId,
338                frontResult,
339                targId,
340                targResult,
341            )
342            result = dict(strat=ballot, isStrat=isStrat, stratGap=stratGap)
343            if extras:
344                result.update(extras)
345            return result
346
347        return stratBallot
348
349
350@decorator
351def rememberBallot(fun):
352    """A decorator for a function of the form xxxBallot(cls, voter)
353    which memoizes the vote onto the voter in an attribute named <methName>_xxx
354    """
355
356    def getAndRemember(cls, voter, tally=None):
357        ballot = fun(cls, voter)
358        setattr(voter, f"{cls.__name__}_{fun.__name__[:-6]}", ballot)
359        return ballot
360
361    getAndRemember.__name__ = fun.__name__
362    getAndRemember.allTallyKeys = lambda: []
363    return getAndRemember
364
365
366@decorator
367def rememberBallots(fun):
368    """A decorator for a function of the form xxxBallot(cls, voter)
369    which memoizes the vote onto the voter in an attribute named <methName>_xxx
370    """
371
372    def getAndRemember(cls, voter, tally=None):
373        ballots = fun(cls, voter)
374        for bType, ballot in ballots.items():
375            setattr(voter, f"{cls.__name__}_{bType}", ballot)
376
377        return ballots[fun.__name__[:-6]]  # leave off the "...Ballot"
378
379    getAndRemember.__name__ = fun.__name__
380    getAndRemember.allTallyKeys = lambda: []
381    return getAndRemember
382
383
384class CandidateWithCount:
385    def __init__(self, c=[], v=0):
386        self.candidate = c
387        self.votes = v
388
389
390__all__ = [
391    "CandidateWithCount",
392    "Method",
393    "SideTally",
394    "Tallies",
395    "VseMethodRun",
396    "VseOneRun",
397    "rememberBallot",
398    "rememberBallots",
399]