add diversity measures

HISTORY.rst

@@ -0,0 +1,8 @@
+Release History
+---------------
+
+0.1.0 (2018-01-07)
+~~~~~~~~~~~~~~~~~~
+
+* First release.
+* Various quotas, disproportionality measures, and apportionment functions

README.rst

@@ -1,8 +1,5 @@
-Release History
----------------
+voting
+======
 
-0.1.0 (2018-01-07)
-~~~~~~~~~~~~~~~~~~
-
-* First release.
-* Various quotas, disproportionality measures, and apportionment functions
+A pure Python module for election quotas, voting measures, and apportionment
+methods.

docs/apportionment.rst

@@ -14,17 +14,10 @@ according to lists of votes.
 * :py:func:`voting.apportionment.webster`
 
 .. autofunction:: voting.apportionment.adams
-
 .. autofunction:: voting.apportionment.dhondt
-
 .. autofunction:: voting.apportionment.hagenbach_bischoff
-
 .. autofunction:: voting.apportionment.hamilton
-
 .. autofunction:: voting.apportionment.huntington_hill
-
 .. autofunction:: voting.apportionment.jefferson
-
 .. autofunction:: voting.apportionment.vinton
-
 .. autofunction:: voting.apportionment.webster

docs/diversity.rst

@@ -0,0 +1,28 @@
+Diversity measures
+==================
+
+The :py:mod:`diversity` module provides functions for measuring the diversity
+among quantities of groups in a population.
+
+The quantity :math:`p_i` represents the proportion of the population belonging
+to group :math:`i`.
+
+* :py:func:`voting.diversity.berger_parker`
+* :py:func:`voting.diversity.general`
+* :py:func:`voting.diversity.gini_simpson`
+* :py:func:`voting.diversity.golosov`
+* :py:func:`voting.diversity.inverse_simpson`
+* :py:func:`voting.diversity.laakso_taagepera`
+* :py:func:`voting.diversity.renyi`
+* :py:func:`voting.diversity.shannon`
+* :py:func:`voting.diversity.simpson`
+
+.. autofunction:: voting.diversity.berger_parker
+.. autofunction:: voting.diversity.general
+.. autofunction:: voting.diversity.gini_simpson
+.. autofunction:: voting.diversity.golosov
+.. autofunction:: voting.diversity.inverse_simpson
+.. autofunction:: voting.diversity.laakso_taagepera
+.. autofunction:: voting.diversity.renyi
+.. autofunction:: voting.diversity.shannon
+.. autofunction:: voting.diversity.simpson

docs/index.rst

@@ -14,7 +14,8 @@ disproportionality, election quotas, and electoral apportionment.
    :caption: Contents:
 
    apportionment
-   measure
+   diversity
+   proportion
    quota
    notes
 

docs/measure.rst

@@ -1,39 +0,0 @@
-Measures
-========
-
-The :py:mod:`measure` module contains functions for measuring
-disproportionality in electoral systems.
-
-* :py:func:`voting.measure.adjusted_loosemore_hanby`
-* :py:func:`voting.measure.dhondt`
-* :py:func:`voting.measure.gallagher`
-* :py:func:`voting.measure.grofman`
-* :py:func:`voting.measure.least_square`
-* :py:func:`voting.measure.lijphart`
-* :py:func:`voting.measure.loosemore_hanby`
-* :py:func:`voting.measure.rae`
-* :py:func:`voting.measure.regression`
-* :py:func:`voting.measure.rose`
-* :py:func:`voting.measure.saint_lague`
-
-.. autofunction:: voting.measure.adjusted_loosemore_hanby
-
-.. autofunction:: voting.measure.dhondt
-
-.. autofunction:: voting.measure.gallagher
-
-.. autofunction:: voting.measure.grofman
-
-.. autofunction:: voting.measure.least_square
-
-.. autofunction:: voting.measure.lijphart
-
-.. autofunction:: voting.measure.loosemore_hanby
-
-.. autofunction:: voting.measure.rae
-
-.. autofunction:: voting.measure.regression
-
-.. autofunction:: voting.measure.rose
-
-.. autofunction:: voting.measure.saint_lague

docs/proportion.rst

@@ -0,0 +1,29 @@
+(Dis)proportionality Measures
+=============================
+
+The :py:mod:`proportion` module contains functions for measuring
+disproportionality in electoral systems.
+
+* :py:func:`voting.proportion.adjusted_loosemore_hanby`
+* :py:func:`voting.proportion.dhondt`
+* :py:func:`voting.proportion.gallagher`
+* :py:func:`voting.proportion.grofman`
+* :py:func:`voting.proportion.least_square`
+* :py:func:`voting.proportion.lijphart`
+* :py:func:`voting.proportion.loosemore_hanby`
+* :py:func:`voting.proportion.rae`
+* :py:func:`voting.proportion.regression`
+* :py:func:`voting.proportion.rose`
+* :py:func:`voting.proportion.saint_lague`
+
+.. autofunction:: voting.proportion.adjusted_loosemore_hanby
+.. autofunction:: voting.proportion.dhondt
+.. autofunction:: voting.proportion.gallagher
+.. autofunction:: voting.proportion.grofman
+.. autofunction:: voting.proportion.least_square
+.. autofunction:: voting.proportion.lijphart
+.. autofunction:: voting.proportion.loosemore_hanby
+.. autofunction:: voting.proportion.rae
+.. autofunction:: voting.proportion.regression
+.. autofunction:: voting.proportion.rose
+.. autofunction:: voting.proportion.saint_lague

docs/quota.rst

@@ -10,9 +10,6 @@ elect candidates in single transferrable vote elections.
 * :py:func:`voting.quota.imperiali`
 
 .. autofunction:: voting.quota.droop
-
 .. autofunction:: voting.quota.hagenbach_bischoff
-
 .. autofunction:: voting.quota.hare
-
 .. autofunction:: voting.quota.imperiali

voting/diversity.py

@@ -0,0 +1,125 @@
+"""Measures of diversity."""
+from math import log
+
+from voting.util import normalize
+
+
+def berger_parker(groups):
+    r"""Calculate the Berger-Parker index.
+
+    .. math::
+
+        max(p_i)
+
+    :param list group: a list of integers representing populations of groups
+    """
+    groups = normalize(groups)
+    return max(groups)
+
+
+def general(groups, q):
+    r"""Calculate the general diversity index.
+
+    .. math::
+
+        \left( \sum_{i=1}^n p_i^q \right) ^ {1/(1-q)}
+
+    :param list groups: a list of integers representing populations of groups
+    :param float q: weight value
+    """
+    groups = normalize(groups)
+    return sum([g ** q for g in groups]) ** (1.0 / (1 - q))
+
+
+def gini_simpson(groups):
+    r"""Calculate the Gini-Simpson index.
+
+    .. math::
+
+        1 - \sum_{i=1}^n p_i^2
+
+    :param list group: a list of integers representing populations of groups
+    """
+    return 1 - simpson(groups)
+
+
+def golosov(groups):
+    r"""Calculate the effective number of parties using Golosov.
+
+    .. math::
+
+        \sum_{i=1}^n \frac{p_i}{p_i + p_1^2 - p_i^2}
+
+    where :math:`p_1` is the largest proportion.
+
+    :param list group: a list of integers representing populations of a group
+    """
+    groups = normalize(groups)
+    p1 = max(groups)
+    return sum([g / (g + p1 ** 2 - g ** 2) for g in groups])
+
+
+def inverse_simpson(groups):
+    r"""Calculate the Inverse-Simpson index.
+
+    .. math::
+
+        \frac{1}{\sum_{i=1}^n p_i^2}
+
+    :param list group: a list of integers representing populations of groups
+    """
+    return 1.0 / simpson(groups)
+
+
+def laakso_taagepera(groups):
+    r"""Calculate the effective number of parties using Laakso-Taagepera.
+
+    .. math::
+
+        \frac{1}{\sum_{i=1}^n p_i^2}
+
+    :param list group: a list of integers representing populations of groups
+    """
+    groups = normalize(groups)
+    return 1.0 / sum([g ** 2 for g in groups])
+
+
+def renyi(groups, q=1):
+    r"""Calculate the Renyi entropy.
+
+    .. math::
+
+        \frac{1}{1-q} \ln \left( \sum_{i=1}^n p_i ^ q \right)
+
+    :param list groups: a list of integers representing populations of groups
+    :param float q: weight value
+
+    """
+    groups = normalize(groups)
+    return 1.0 / (1 - q) * log(sum([g ** q for g in groups]))
+
+
+def shannon(groups):
+    r"""Calculate the Shannon index.
+
+    .. math::
+
+        \sum_{i=1}^n p_i \ln (p_i)
+
+    :param list groups: a list of integers representing populations of groups
+    """
+    groups = normalize(groups)
+    return sum([g * log(g) for g in groups])
+
+
+def simpson(groups):
+    r"""Calculate the Simpson index.
+
+    .. math::
+
+        \sum_{i=1}^n p_i^2
+
+    :param list groups: a list of integers representing populations of groups
+    """
+    groups = normalize(groups)
+    return sum([g ** 2 for g in groups])

voting/proportion.py

@@ -1,11 +1,7 @@
 """Measures of disproportionality."""
 from math import sqrt
 
-
-def normalize(values):
-    """Normalize a list of values."""
-    total = sum(values)
-    return [1.0 * value / total for value in values]
+from voting.util import normalize
 
 
 def adjusted_loosemore_hanby(votes, seats, parties='votes'):

voting/util.py

@@ -0,0 +1,7 @@
+"""Utility functions."""
+
+
+def normalize(values):
+    """Normalize a list of values."""
+    total = sum(values)
+    return [1.0 * value / total for value in values]