add example

Author: statmlben

dist/rehline-0.0.1.tar.gz

@@ -3,4 +3,4 @@
 
 from ._loss import ReHLoss, PQLoss
 from ._class import ReHLine, ReHLine_solver
-
+from ._base import make_fair_classification

rehline/__init__.py

@@ -7,6 +7,8 @@
 
 import numpy as np
 from scipy.special import huber
+from sklearn.datasets import make_classification
+from sklearn.preprocessing import StandardScaler
 
 def relu(x):
     """
@@ -49,3 +51,40 @@ def _check_rehu(rehu_coef, rehu_intercept, rehu_cut):
     assert rehu_coef.shape == rehu_intercept.shape, "`rehu_coef` and `rehu_intercept` should be the same shape!"
     if len(rehu_coef) > 0:
         assert (rehu_cut >= 0.0).all(), "`rehu_cut` must be non-negative!"
+
+def make_fair_classification(n_samples=100, n_features=5, ind_sensitive=0):
+    """
+    Generate a random binary fair classification problem.
+
+    Parameters
+    ----------
+    n_samples : int, default=100
+        The number of samples.
+
+    n_features : int, default=5
+        The total number of features. 
+
+    ind_sensitive : int, default=0
+        The index of the sensitive feature.
+
+    Returns
+    -------
+    X : ndarray of shape (n_samples, n_features)
+        The generated samples.
+
+    y : ndarray of shape (n_samples,)
+        The +/- labels for class membership of each sample.
+
+    X_sen: ndarray of shape (n_samples,)
+        The centered samples of the sensitive feature.
+    """
+
+    X, y = make_classification(n_samples, n_features)
+    y = 2*y - 1
+
+    scaler = StandardScaler()
+    X = scaler.fit_transform(X)
+
+    X_sen = X[:, ind_sensitive]
+
+    return X, y, X_sen

rehline/_base.py

@@ -47,6 +47,45 @@ class ReHLine(BaseEstimator):
 
     n_iter_: int
         Maximum number of iterations run across all classes.
+
+    Examples
+    --------
+
+    ## test SVM on simulated dataset
+    
+    import numpy as np
+    from rehline import ReHLine 
+
+    # simulate classification dataset
+    >>> n, d, C = 1000, 3, 0.5
+    >>> np.random.seed(1024)
+    >>> X = np.random.randn(1000, 3)
+    >>> beta0 = np.random.randn(3)
+    >>> y = np.sign(X.dot(beta0) + np.random.randn(n))
+
+    ## solution provided by ReHLine
+    # build-in loss
+    >>> clf = ReHLine(loss={'name': 'svm'}, C=C)
+    >>> clf.make_ReLHLoss(X=X, y=y, loss={'name': 'svm'})
+    >>> clf.fit(X=X)
+    >>> print('sol privided by rehline: %s' %clf.coef_)
+    >>> sol privided by rehline: [ 0.74104604 -0.00622664  2.66991198]
+    >>> print(clf.decision_function([[1,2,3]]))
+    >>> [0.87383287]
+
+    # manually specify params
+    >>> n, d = X.shape
+    >>> U = -(C*y).reshape(1,-1)
+    >>> L = U.shape[0]
+    >>> V = (C*np.array(np.ones(n))).reshape(1,-1)
+
+    >>> clf = ReHLine(loss={'name': 'svm'}, C=C)
+    >>> clf.U, clf.V = U, V
+    >>> clf.fit(X=X)
+    >>> print('sol privided by rehline: %s' %clf.coef_)
+    >>> sol privided by rehline: [ 0.7410154  -0.00615574  2.66990408]
+    >>> print(clf.decision_function([[1,2,3]]))
+    >>> [0.87384162]
     """
 
     def __init__(self, loss={'name':'QR', 'qt':[.25, .75]}, C=1.,
@@ -73,11 +112,15 @@ def __init__(self, loss={'name':'QR', 'qt':[.25, .75]}, C=1.,
         self.H = S.shape[0]
         self.K = A.shape[0]
 
-    def make_ReLHLoss(self, X, y, loss={'name':'QR', 'qt':[.25, .75]}):
+    def make_ReLHLoss(self, X, y, loss={}):
         """Generate ReLoss params based on the given training data.
 
         """
-        self.loss.update(loss)
+        if (loss=={}) or (loss==self.loss):
+            pass
+        else:
+            print('Loss has been updated!')
+            self.loss.update(loss)
 
         n, d = X.shape
 

rehline/_class.py

@@ -0,0 +1,26 @@
+## Test SVM on simulated dataset
+import numpy as np
+from rehline import ReHLine 
+from rehline import make_fair_classification
+
+# simulate classification dataset
+X, y, X_sen = make_fair_classification()
+n, d = X.shape
+
+## solution provided by ReHLine
+# build-in hinge loss for svm
+clf = ReHLine(loss={'name': 'svm'}, C=C)
+clf.make_ReLHLoss(X=X, y=y, loss={'name': 'svm'})
+
+# specific the param of FairSVM
+A = np.repeat([X_sen @ X], repeats=[2], axis=0) / n
+A[1] = -A[1]
+# suppose the fair tolerance is 0.01
+b = np.array([.01, .01])
+clf.A, clf.b = A, b
+clf.fit(X=X)
+
+print('solution privided by rehline: %s' %clf.coef_)
+score = X@clf.coef_
+cor_sen = np.mean(score * X_sen)
+print('correlation btw score and X_sen is: %.3f' %cor_sen)

tests/_test_fairsvm.py

@@ -0,0 +1,41 @@
+## Test SVM on simulated dataset
+import numpy as np
+from rehline import ReHLine
+
+np.random.seed(1024)
+# simulate classification dataset
+n, d, C = 1000, 3, 0.5
+X = np.random.randn(1000, 3)
+beta0 = np.random.randn(3)
+y = np.sign(X.dot(beta0) + np.random.randn(n))
+
+## solution provided by sklearn
+from sklearn.svm import LinearSVC
+clf = LinearSVC(C=C, loss='hinge', fit_intercept=False, 
+                random_state=0, tol=1e-6, max_iter=1000000)
+clf.fit(X, y)
+sol = clf.coef_.flatten()
+
+print('solution privided by liblinear: %s' %sol)
+
+## solution provided by ReHLine
+# build-in loss
+clf = ReHLine(loss={'name': 'svm'}, C=C)
+clf.make_ReLHLoss(X=X, y=y, loss={'name': 'svm'})
+clf.fit(X=X)
+
+print('solution privided by rehline: %s' %clf.coef_)
+print(clf.decision_function([[.1,.2,.3]]))
+
+# manually specify params
+n, d = X.shape
+U = -(C*y).reshape(1,-1)
+L = U.shape[0]
+V = (C*np.array(np.ones(n))).reshape(1,-1)
+
+clf = ReHLine(loss={'name': 'svm'}, C=C)
+clf.U, clf.V = U, V
+clf.fit(X=X)
+
+print('solution privided by rehline: %s' %clf.coef_)
+print(clf.decision_function([[.1,.2,.3]]))