model: scratch: SAG LR documentation

Author: Naman1233

docs/plugins/dffml_model.rst

@@ -417,12 +417,64 @@ dffml_model_scratch
     pip install dffml-model-scratch
 
 
-scratchlgr
-~~~~~~~~~~
+scratchlgrsag
+~~~~~~~~~~~~~
 
 *Official*
 
-No description
+Logistic Regression using stochastic average gradient descent optimizer
+
+
+.. code-block:: console
+
+    $ cat > dataset.csv << EOF
+    f1,ans
+    0.1,0
+    0.7,1
+    0.6,1
+    0.2,0
+    0.8,1
+    EOF
+    $ dffml train \
+        -model scratchlgrsag \
+        -model-features f1:float:1 \
+        -model-predict ans:int:1 \
+        -sources f=csv \
+        -source-filename dataset.csv \
+        -log debug
+    $ dffml accuracy \
+        -model scratchlgrsag \
+        -model-features f1:float:1 \
+        -model-predict ans:int:1 \
+        -sources f=csv \
+        -source-filename dataset.csv \
+        -log debug
+    1.0
+    $ echo -e 'f1,ans\n0.8,0\n' | \
+      dffml predict all \
+        -model scratchlgrsag \
+        -model-features f1:float:1 \
+        -model-predict ans:int:1 \
+        -sources f=csv \
+        -source-filename /dev/stdin \
+        -log debug
+    [
+        {
+            "extra": {},
+            "features": {
+                "ans": 0,
+                "f1": 0.8
+            },
+            "last_updated": "2020-03-19T13:41:08Z",
+            "prediction": {
+                "ans": {
+                    "confidence": 1.0,
+                    "value": 1
+                }
+            },
+            "key": "0"
+        }
+    ]
 
 **Args**
 

model/scratch/dffml_model_scratch/logisticregression.py

@@ -27,9 +27,64 @@ class LogisticRegressionConfig:
     )
 
 
-@entrypoint("scratchlgr")
+@entrypoint("scratchlgrsag")
 class LogisticRegression(SimpleModel):
+    r"""
+    Logistic Regression using stochastic average gradient descent optimizer
 
+
+    .. code-block:: console
+
+        $ cat > dataset.csv << EOF
+        f1,ans
+        0.1,0
+        0.7,1
+        0.6,1
+        0.2,0
+        0.8,1
+        EOF
+        $ dffml train \
+            -model scratchlgrsag \
+            -model-features f1:float:1 \
+            -model-predict ans:int:1 \
+            -sources f=csv \
+            -source-filename dataset.csv \
+            -log debug
+        $ dffml accuracy \
+            -model scratchlgrsag \
+            -model-features f1:float:1 \
+            -model-predict ans:int:1 \
+            -sources f=csv \
+            -source-filename dataset.csv \
+            -log debug
+        1.0
+        $ echo -e 'f1,ans\n0.8,0\n' | \
+          dffml predict all \
+            -model scratchlgrsag \
+            -model-features f1:float:1 \
+            -model-predict ans:int:1 \
+            -sources f=csv \
+            -source-filename /dev/stdin \
+            -log debug
+        [
+            {
+                "extra": {},
+                "features": {
+                    "ans": 0,
+                    "f1": 0.8
+                },
+                "last_updated": "2020-03-19T13:41:08Z",
+                "prediction": {
+                    "ans": {
+                        "confidence": 1.0,
+                        "value": 1
+                    }
+                },
+                "key": "0"
+            }
+        ]
+
+    """
     # The configuration class needs to be set as the CONFIG property
     CONFIG = LogisticRegressionConfig
     # Logistic Regression only supports training on a single feature
@@ -50,16 +105,15 @@ def separating_line(self):
         return self.storage.get("separating_line", None)
 
     @separating_line.setter
-    def separating_line(self, rline):
+    def separating_line(self, sline):
         """
         Set separating_line in self.storage so it will be saved to disk
         """
-        self.storage["separating_line"] = rline
+        self.storage["separating_line"] = sline
 
     def predict_input(self, x):
         """
-        Use the regression
-        line to make a prediction by returning ``m * x + b``.
+        The Logistic regression with SAG optimizer: returns w * x + b > 0.5
         """
         prediction = self.separating_line[0] * x + self.separating_line[1]
         if prediction > 0.5:
@@ -73,24 +127,30 @@ def predict_input(self, x):
         )
         return prediction
 
-    def best_fit_line(self):
+    def best_separating_line(self):
+        """
+        Determine the best separating hyperplane (here, the integer weight) 
+        s.t. w * x + b is well separable from 0.5.
+        """
         self.logger.debug(
             "Number of input records: {}".format(len(self.xData))
         )
-        x = self.xData
-        y = self.yData
-        learning_rate = 0.01
-        w = 0.01
-        b = 0.0
-        for _ in range(1, 1500):
+        x = self.xData  # feature array
+        y = self.yData  # class array
+        learning_rate = 0.01  # learning rate for step: weight -= lr * step
+        w = 0.01  # initial weight
+        b = 0.0  # here unbiased data is considered so b = 0
+        # epochs' loop: 1500 epochs
+        for _ in range(0, 1500):
             z = w * x + b
             val = -np.multiply(y, z)
             num = -np.multiply(y, np.exp(val))
             den = 1 + np.exp(val)
-            f = num / den
-            gradJ = np.sum(x * f)
-            w = w - learning_rate * gradJ / len(x)
-        error = 0
+            f = num / den  # f is gradient dJ for each data point
+            gradJ = np.sum(x * f)  # total dJ
+            w = w - learning_rate * gradJ / len(x)  # SAG subtraction
+        # Accuracy calculation
+        error = 0  # incorrect values
         for x_id in range(len(x)):
             yhat = x[x_id] * w + b > 0.5
             if yhat:
@@ -113,7 +173,7 @@ async def train(self, sources: Sources):
             self.yData = np.append(
                 self.yData, feature_data[self.config.predict.NAME]
             )
-        self.separating_line = self.best_fit_line()
+        self.separating_line = self.best_separating_line()
 
     async def accuracy(self, sources: Sources) -> Accuracy:
         # Ensure the model has been trained before we try to make a prediction

model/scratch/setup.py

@@ -68,7 +68,7 @@
     entry_points={
         "dffml.model": [
             "scratchslr = dffml_model_scratch.slr:SLR",
-            "scratchlgr = dffml_model_scratch.logisticregression:LogisticRegression",
+            "scratchlgrsag = dffml_model_scratch.logisticregression:LogisticRegression",
         ]
     },
 )

model/scratch/tests/test_lgr_integration.py

@@ -23,7 +23,7 @@ async def test_run(self):
         # Arguments for the model
         model_args = [
             "-model",
-            "scratchlgr",
+            "scratchlgrsag",
             "-model-features",
             "f1:int:1",
             "-model-predict",