adding version 1.0.1

.gitignore

@@ -0,0 +1,8 @@
+bcubed_metrics.egg-info/
+build/
+dist/
+pyproject.toml
+setup.py
+tests/__pycache__/
+bcubed_metrics/__pycache__
+venv/

LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (c) 2018 The Python Packaging Authority
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,63 @@
+# B-Cubed Metrics
+
+<div style="text-align: justify">
+A simple Python package to calculate B-Cubed precision, recall, and F1-score for clustering evaluation.
+</div>
+
+## What are B-Cubed Metrics
+<div style="text-align: justify">
+The B-Cubed algorithm was first introduced by Bagga, A. and Baldwin B. (1998) in their paper on Entity-Based Cross-Document Coreferencing Using the Vector Space Model. The algorithm compares a predicted clustering with a ground truth (or gold standard) clustering through element-wise precision and recall scores. For each element, the predicted and ground truth clusters containing the element are compared, and then the mean over all elements is taken. The B-Cubed algorithm can be useful in unsupervised techniques where the cluster labels are not available, because unlike macro-averaged metrics, it focuses on element-wise operations.
+</div>
+
+<div style="text-align: justify">
+From the paper, two simple equations were devised calculating precision and recall scores for the predicted clustering:
+</div>
+
+$$
+Precision = \frac{1}{\sum {elements}}\sum_{i=1}^n {\frac{(count \; of \; element)^2}{count \; of \; all \; elements \; in \; cluster}}
+$$
+
+$$
+Recall = \frac{1}{\sum {elements}}\sum_{i=1}^n {\frac{(count \; of \; element)^2}{count \; of \; total \; elements \; from \; this \; category}}
+$$
+
+$$
+F-score = \frac{1}{k}\sum_{i=1}^n {\frac{2\times Precision(C)_k \times Recall(C)_k}{Precision(C)_k + Recall(C)_k}}
+$$
+
+<div style="text-align: justify">
+
+where $n$ above denotes the number of categories in the cluster and $k$ is the number of predicted clusters. $Precision(C)_k$ and $Recall(C)_k$ are the 'partial' precision and recalls for each cluster. 
+</div>
+
+
+## Installation and Use
+<div style="text-align: justify">
+Download the package from any terminal using:
+</div>
+
+```bash
+pip install bcubed-metrics
+```
+<div style="text-align: justify">
+To use the B-Cubed class you need to import it and provide 2 dictionaries - one for the predicted clustering, and one for the ground truth clustering (actual labels):
+</div>
+
+```python
+from bcubed_metrics.bcubed import Bcubed
+
+predicted_clustering = [
+            {'blue': 4, 'red': 2, 'green': 1},
+            {'blue': 2, 'red': 2, 'green': 3},
+            {'blue': 1, 'red': 5},
+            {'blue': 1, 'red': 2, 'green': 3}
+        ]
+
+ground_truth_clustering = {'blue': 8, 'red': 11, 'green': 7}
+
+bcubed = Bcubed(predicted_clustering=predicted_clustering, ground_truth_clustering=ground_truth_clustering)
+
+metrics = bcubed.get_metrics() # returns all metrics as dictionary
+
+bcubed.print_metrics() # prints all metrics
+```

bcubed_metrics/__init__.py

@@ -0,0 +1,9 @@
+"""
+Bcubed metrics
+
+A package to calculate BCubed precision, recall, and F1-score for clustering evaluation.
+"""
+
+__version__ = "1.0.0"
+__author__ = 'Vasiliki Nikolaidi'
+__url__ = 'https://github.com/nezumiCodes/bcubed-metrics'

bcubed_metrics/bcubed.py

@@ -0,0 +1,89 @@
+class Bcubed():
+    """
+    Class to calculate Bcubed precision, recall, and F1-score for clustering evaluation.
+    
+    Attributes:
+        predicted_clustering (list): A list of dictionaries representing the predicted clustering.
+        ground_truth_clustering (dict): A dictionary representing the ground truth clustering.
+        decimals (int): Number of decimal places to round the results.
+    """
+
+    def __init__(self, predicted_clustering=None, ground_truth_clustering=None, decimals=5):
+        """
+        Initialises the Bcubed object with predicted clustering and ground truth data.
+        
+        Args:
+            predicted_clustering (list): A list of dictionaries representing the predicted clustering.
+            ground_truth_clustering (dict): A dictionary representing the ground truth clustering.
+            decimals (int): Number of decimal places to round the results (default is 5).
+        """
+        self.predicted_clustering = predicted_clustering
+        self.ground_truth_clustering = ground_truth_clustering
+        self.decimals = decimals
+
+        self.total_precision = 0
+        self.total_recall = 0
+        self.total_f1 = 0
+        self.total_items = sum(sum(cluster.values()) for cluster in self.predicted_clustering) # count of all cluster items
+
+        self.bcubed_precision = 0
+        self.bcubed_recall = 0
+        self.bcubed_f1 = 0
+        self.bcubed_f1_micro = 0
+
+        self.calculate_metrics()
+        # self.print_metrics()
+
+    def calculate_metrics(self):
+        """
+        Calculate Bcubed precision, recall, and F1-score based on the predicted clustering 
+        and ground truth data.
+        """
+        for cluster in self.predicted_clustering:
+            cluster_total = sum(cluster.values())
+            for item, count in cluster.items():
+                true_total = self.ground_truth_clustering[item]
+
+                precision = count / cluster_total
+                recall = count / true_total
+                f1 = 2 * precision * recall / (precision + recall) if precision + recall != 0 else 0
+
+                self.bcubed_precision += precision * count
+                self.bcubed_recall += recall * count
+                self.bcubed_f1 += f1 * count
+
+        self.bcubed_precision = self.bcubed_precision / self.total_items
+        self.bcubed_recall = self.bcubed_recall / self.total_items
+        self.bcubed_f1 = self.bcubed_f1 / self.total_items
+        self.bcubed_f1_micro = 2*self.bcubed_precision*self.bcubed_recall / (self.bcubed_precision + self.bcubed_recall)
+
+    def get_metrics(self):
+        """
+        Returns the calculated Bcubed metrics as a dictionary.
+        
+        Returns:
+            dict: A dictionary containing the precision, recall, F1-score, and micro F1-score.
+        """
+        return {
+            'precision': round(self.bcubed_precision, self.decimals),
+            'recall': round(self.bcubed_recall, self.decimals),
+            'f1_score': round(self.bcubed_f1, self.decimals),
+            'micro_f1_score': round(self.bcubed_f1_micro, self.decimals),
+        }
+
+
+    def print_metrics(self):
+        """
+        Print the calculated Bcubed metrics: precision, recall, F1-score, and micro F1-score.
+        """
+        print('BCubed Metrics\n--------------------------------')
+        print(f'Precision: {round(self.bcubed_precision, self.decimals)}')
+        print(f'Recall: {round(self.bcubed_recall, self.decimals)}')
+        print(f'F1-score: {round(self.bcubed_f1, self.decimals)}')
+        print(f'Micro F1-score: {round(self.bcubed_f1_micro, self.decimals)}')
+
+def main():
+    Bcubed(predicted_clustering={}, ground_truth_clustering={})
+
+if __name__ == '__main__':
+    main()

tests/test_metrics.py

@@ -0,0 +1,25 @@
+import unittest
+from bcubed_metrics.bcubed import Bcubed
+
+class TestBCubed(unittest.TestCase):
+    def test_bcubed_metrics(self):
+        predicted_clustering = [
+            {'blue': 4, 'red': 2, 'green': 1},
+            {'blue': 2, 'red': 2, 'green': 3},
+            {'blue': 1, 'red': 5},
+            {'blue': 1, 'red': 2, 'green': 3}
+        ]
+
+        ground_truth_clustering = {'blue': 8, 'red': 11, 'green': 7}
+
+        bcubed = Bcubed(predicted_clustering=predicted_clustering, ground_truth_clustering=ground_truth_clustering)
+        metrics = bcubed.get_metrics()
+        bcubed.print_metrics()
+
+        self.assertAlmostEqual(metrics['precision'], 0.4652, places=4)
+        self.assertAlmostEqual(metrics['recall'], 0.33954, places=4)
+        self.assertAlmostEqual(metrics['f1_score'], 0.38716, places=4)
+        self.assertAlmostEqual(metrics['micro_f1_score'], 0.39256, places=4)
+
+if __name__ == "__main__":
+    unittest.main()