Add CategoryAdherence metric (#475)

sdmetrics/single_column/__init__.py

@@ -3,6 +3,7 @@
 from sdmetrics.single_column import base
 from sdmetrics.single_column.base import SingleColumnMetric
 from sdmetrics.single_column.statistical.boundary_adherence import BoundaryAdherence
+from sdmetrics.single_column.statistical.category_adherence import CategoryAdherence
 from sdmetrics.single_column.statistical.category_coverage import CategoryCoverage
 from sdmetrics.single_column.statistical.cstest import CSTest
 from sdmetrics.single_column.statistical.kscomplement import KSComplement
@@ -16,6 +17,7 @@
     'SingleColumnMetric',
     'BoundaryAdherence',
     'CategoryCoverage',
+    'CategoryAdherence',
     'CSTest',
     'KSComplement',
     'MissingValueSimilarity',

sdmetrics/single_column/statistical/__init__.py

@@ -1,6 +1,7 @@
 """Univariate goodness-of-fit tests."""
 
 from sdmetrics.single_column.statistical.boundary_adherence import BoundaryAdherence
+from sdmetrics.single_column.statistical.category_adherence import CategoryAdherence
 from sdmetrics.single_column.statistical.category_coverage import CategoryCoverage
 from sdmetrics.single_column.statistical.cstest import CSTest
 from sdmetrics.single_column.statistical.kscomplement import KSComplement
@@ -12,6 +13,7 @@
 __all__ = [
     'BoundaryAdherence',
     'CategoryCoverage',
+    'CategoryAdherence',
     'CSTest',
     'KSComplement',
     'MissingValueSimilarity',

sdmetrics/single_column/statistical/category_adherence.py

@@ -0,0 +1,64 @@
+"""Category Adherence Metric."""
+
+import numpy as np
+
+from sdmetrics.goal import Goal
+from sdmetrics.single_column.base import SingleColumnMetric
+
+
+class CategoryAdherence(SingleColumnMetric):
+    """Category adherence metric.
+
+    The proportion of synthetic data points that match an existing category from the real data.
+
+    Attributes:
+        name (str):
+            Name to use when reports about this metric are printed.
+        goal (sdmetrics.goal.Goal):
+            The goal of this metric.
+        min_value (Union[float, tuple[float]]):
+            Minimum value or values that this metric can take.
+        max_value (Union[float, tuple[float]]):
+            Maximum value or values that this metric can take.
+    """
+
+    name = 'CategoryAdherence'
+    goal = Goal.MAXIMIZE
+    min_value = 0.0
+    max_value = 1.0
+
+    @classmethod
+    def compute_breakdown(cls, real_data, synthetic_data):
+        """Compute the score breakdown of the category adherence metric.
+
+        Args:
+            real_data (pandas.Series):
+                The real data.
+            synthetic_data (pandas.Series):
+                The synthetic data.
+
+        Returns:
+            dict:
+                The score breakdown of the category adherence metric.
+        """
+        real_data = real_data.fillna(np.nan)
+        synthetic_data = synthetic_data.fillna(np.nan)
+        score = synthetic_data.isin(real_data).mean()
+
+        return {'score': score}
+
+    @classmethod
+    def compute(cls, real_data, synthetic_data):
+        """Compute the category adherence of two columns.
+
+        Args:
+            real_data (pandas.Series):
+                The real data.
+            synthetic_data (pandas.Series):
+                The synthetic data.
+
+        Returns:
+            float:
+                The category adherence metric score.
+        """
+        return cls.compute_breakdown(real_data, synthetic_data)['score']

tests/unit/single_column/statistical/test_category_adherence.py

@@ -0,0 +1,54 @@
+from unittest.mock import patch
+
+import numpy as np
+import pandas as pd
+
+from sdmetrics.single_column.statistical import CategoryAdherence
+
+
+class TestCategoryAdherence:
+
+    def test_compute_breakdown(self):
+        """Test the ``compute_breakdown`` method."""
+        # Setup
+        real_data = pd.Series(['A', 'B', 'C', 'B', 'A'])
+        synthetic_data = pd.Series(['A', 'B', 'C', 'D', 'E'])
+
+        metric = CategoryAdherence()
+
+        # Run
+        result = metric.compute_breakdown(real_data, synthetic_data)
+
+        # Assert
+        assert result == {'score': 0.6}
+
+    def test_compute_breakdown_with_nans(self):
+        """Test the ``compute_breakdown`` method with NaNs."""
+        # Setup
+        real_data = pd.Series(['A', 'B', 'C', 'B', 'A', None])
+        synthetic_data = pd.Series(['A', 'B', np.nan, 'C', np.nan, 'B', 'A', None, 'D', 'C'])
+
+        metric = CategoryAdherence()
+
+        # Run
+        result = metric.compute_breakdown(real_data, synthetic_data)
+
+        # Assert
+        assert result == {'score': 0.9}
+
+    @patch('sdmetrics.single_column.statistical.category_adherence.'
+           'CategoryAdherence.compute_breakdown')
+    def test_compute(self, compute_breakdown_mock):
+        """Test the ``compute`` method."""
+        # Setup
+        real_data = pd.Series(['A', 'B', 'C', 'B', 'A'])
+        synthetic_data = pd.Series(['A', 'B', 'C', 'D', 'E'])
+        metric = CategoryAdherence()
+        compute_breakdown_mock.return_value = {'score': 0.6}
+
+        # Run
+        result = metric.compute(real_data, synthetic_data)
+
+        # Assert
+        compute_breakdown_mock.assert_called_once_with(real_data, synthetic_data)
+        assert result == 0.6