From 5494915f989cafc4ad5dd1b3810ba03496f316d2 Mon Sep 17 00:00:00 2001
From: erkankarabulut <erkankkarabulut@gmail.com>
Date: Thu, 14 Mar 2024 23:27:32 +0100
Subject: [PATCH] add leverage rule quality criterion

---
 interest_measures.md  | 15 +++++++++++++++
 niaarm/rule.py        | 15 +++++++++++++++
 tests/test_metrics.py |  4 ++++
 3 files changed, 34 insertions(+)

diff --git a/interest_measures.md b/interest_measures.md
index 4f9e066..9fa5926 100644
--- a/interest_measures.md
+++ b/interest_measures.md
@@ -208,3 +208,18 @@ and 0 reflects independence)
 
 **Reference:** T. Zhang, “Association Rules,” in Knowledge Discovery and Data Mining. Current Issues and New 
 Applications, 2000, pp. 245–256. doi: 10.1007/3-540-45571-X_31. 
+
+## Leverage
+
+Leverage metric is difference between the frequency of antecedent and the consequent appearing together and the expected
+frequency of them appearing separately based on their individual support
+
+```math
+leverage(X \implies Y) = support(X \implies Y) - (support(X) \times support(Y))
+```
+
+**Range:** `[-1, 1]` (-1 reflects total negative association, 1 reflects perfect positive association
+and 0 reflects independence)
+
+**Reference:** Gregory Piatetsky-Shapiro. 1991. Discovery, Analysis, and Presentation of Strong Rules. In
+Knowledge Discovery in Databases, Gregory Piatetsky-Shapiro and William J. Frawley (Eds.). AAAI/MIT Press, 229–248.
\ No newline at end of file
diff --git a/niaarm/rule.py b/niaarm/rule.py
index e3d3e8d..3e72307 100644
--- a/niaarm/rule.py
+++ b/niaarm/rule.py
@@ -156,6 +156,16 @@ class Rule:
          **Reference:** T. Zhang, “Association Rules,” in Knowledge Discovery and Data Mining. Current Issues and New
          Applications, 2000, pp. 245–256. doi: 10.1007/3-540-45571-X_31.
 
+        leverage: difference between the frequency of antecedent and the consequent appearing together and the expected
+        frequency of them appearing separately based on their individual support
+
+        :math: `leverage(X \implies Y) = support(X \implies Y) - (support(X) \times support(Y))`
+
+        **Range:** :math: `[-1, 1]` (-1 reflects total negative association, 1 reflects perfect positive association
+         and 0 reflects independence)
+
+        **Reference:** Gregory Piatetsky-Shapiro. 1991. Discovery, Analysis, and Presentation of Strong Rules. In
+        Knowledge Discovery in Databases, Gregory Piatetsky-Shapiro and William J. Frawley (Eds.). AAAI/MIT Press, 229–248.
     """
 
     __slots__ = (
@@ -327,6 +337,11 @@ def zhang(self):
 
         return numerator / denominator
 
+    @property
+    def leverage(self):
+        return self.support - (
+                (self.antecedent_count / self.num_transactions) * (self.consequent_count / self.num_transactions))
+
     def __eq__(self, other):
         return (
             self.antecedent == other.antecedent and self.consequent == other.consequent
diff --git a/tests/test_metrics.py b/tests/test_metrics.py
index c0e8cb9..2805588 100644
--- a/tests/test_metrics.py
+++ b/tests/test_metrics.py
@@ -70,3 +70,7 @@ def test_yulesq(self):
     def test_zhang(self):
         self.assertAlmostEqual(self.rule_one.zhang, 5 / 9)
         self.assertAlmostEqual(self.rule_two.zhang, 5 / 8)
+
+    def test_leverage(self):
+        self.assertAlmostEqual(self.rule_one.leverage, 0.102040816326)
+        self.assertAlmostEqual(self.rule_two.leverage, 0.102040816326)