Generalise mpr to concentration ratios

Author: LadyChristina

config.yaml

@@ -8,7 +8,9 @@ metrics:
   hhi:
   nakamoto_coefficient:
   theil_index:
-  max_power_ratio:
+  concentration_ratio:
+    - 1
+    - 3
   tau_index:
     - 0.33
     - 0.66

consensus_decentralization/analyze.py

@@ -6,7 +6,7 @@
 from consensus_decentralization.metrics.entropy import compute_entropy, compute_entropy_percentage  # noqa: F401
 from consensus_decentralization.metrics.herfindahl_hirschman_index import compute_hhi  # noqa: F401
 from consensus_decentralization.metrics.theil_index import compute_theil_index  # noqa: F401
-from consensus_decentralization.metrics.max_power_ratio import compute_max_power_ratio  # noqa: F401
+from consensus_decentralization.metrics.concentration_ratio import compute_concentration_ratio  # noqa: F401
 from consensus_decentralization.metrics.tau_index import compute_tau_index  # noqa: F401
 from consensus_decentralization.metrics.total_entities import compute_total_entities  # noqa: F401
 

consensus_decentralization/metrics/concentration_ratio.py

@@ -0,0 +1,9 @@
+def compute_concentration_ratio(block_distribution, topn):
+    """
+    Calculates the n-concentration ratio of a distribution of balances
+    :param block_distribution: a list of integers, each being the blocks that an entity has produced, sorted in descending order
+    :param topn: the number of top block producers to consider
+    :returns: float that represents the ratio of blocks produced by the top n block producers (0 if there weren't any)
+    """
+    total_blocks = sum(block_distribution)
+    return sum(block_distribution[:topn]) / total_blocks if total_blocks else 0

consensus_decentralization/metrics/max_power_ratio.py

@@ -29,8 +29,9 @@ The metrics that have been implemented so far are the following:
    or the redundancy, in a population. In practice, it is calculated as the maximum possible entropy minus the observed
    entropy. The output is a real number. Values close to 0 indicate equality and values towards infinity indicate
    inequality. Therefore, a high Theil Index suggests a population that is highly centralized.
-6. **Max power ratio**: The max power ratio represents the share of blocks that are produced by the most "powerful"
-   entity, i.e. the entity that produces the most blocks. The output of the metric is a decimal number in [0,1].
+6. **Concentration ratio**: The n-concentration ratio represents the share of blocks that are produced by the n most 
+   "powerful" entities, i.e. the entities that produce the most blocks. The output of the metric is a decimal 
+   number in [0,1]. Values typically used are the 1-concentration ratio and the 3-concentration ratio.
 7. **Tau-decentralization index**: The tau-decentralization index is a generalization of the Nakamoto coefficient.
    It is defined as the minimum number of entities that collectively produce more than a given threshold of the total
    blocks within a given timeframe. The threshold parameter is a decimal in [0, 1] (0.66 by default) and the output of

docs/metrics.md

@@ -1,5 +1,5 @@
 from consensus_decentralization.metrics import (entropy, gini, nakamoto_coefficient, herfindahl_hirschman_index,
-                                                theil_index, max_power_ratio, tau_index, total_entities)
+                                                theil_index, concentration_ratio, tau_index, total_entities)
 import numpy as np
 
 
@@ -72,6 +72,9 @@ def test_gini():
     g6 = gini.compute_gini([0, 0])
     assert g6 is None
 
+    g7 = gini.compute_gini([1])
+    assert g7 == 0
+
 
 def test_nc():
     nc1 = nakamoto_coefficient.compute_nakamoto_coefficient([3, 2, 1])
@@ -137,21 +140,36 @@ def test_compute_theil_index():
     assert theil_t == 0
 
 
-def test_compute_max_power_ratio():
-    max_mpr = max_power_ratio.compute_max_power_ratio([3, 2, 1])
-    assert max_mpr == 0.5
+def test_compute_concentration_ratio():
+    cr1 = concentration_ratio.compute_concentration_ratio([3, 2, 1], 1)
+    assert cr1 == 0.5
+
+    cr3 = concentration_ratio.compute_concentration_ratio([3, 2, 1], 3)
+    assert cr3 == 1
+
+    cr1 = concentration_ratio.compute_concentration_ratio([3, 2, 1, 1, 1, 1], 1)
+    assert cr1 == 1 / 3
+
+    cr3 = concentration_ratio.compute_concentration_ratio([3, 2, 1, 1, 1, 1], 3)
+    assert cr3 == 6/9
+
+    cr1 = concentration_ratio.compute_concentration_ratio([1], 1)
+    assert cr1 == 1
+
+    cr3 = concentration_ratio.compute_concentration_ratio([1], 3)
+    assert cr3 == 1
 
-    max_mpr = max_power_ratio.compute_max_power_ratio([3, 2, 1, 1, 1, 1])
-    assert max_mpr == 1 / 3
+    cr1 = concentration_ratio.compute_concentration_ratio([1, 1, 1], 1)
+    assert cr1 == 1 / 3
 
-    max_mpr = max_power_ratio.compute_max_power_ratio([1])
-    assert max_mpr == 1
+    cr3 = concentration_ratio.compute_concentration_ratio([1, 1, 1], 3)
+    assert cr3 == 1
 
-    max_mpr = max_power_ratio.compute_max_power_ratio([1, 1, 1])
-    assert max_mpr == 1 / 3
+    cr1 = concentration_ratio.compute_concentration_ratio([], 1)
+    assert cr1 == 0
 
-    max_mpr = max_power_ratio.compute_max_power_ratio([])
-    assert max_mpr == 0
+    cr3 = concentration_ratio.compute_concentration_ratio([], 3)
+    assert cr3 == 0
 
 
 def test_tau_33():