cleaning up references to L2,L2, Lambda etc, in favor of more readable parameter names like w_pen and v_pen

Author: =

SparseSC/__init__.py

@@ -7,11 +7,14 @@
 from SparseSC.fit_ct import ct_v_matrix, ct_weights, ct_score
 
 # Public API
-from SparseSC.cross_validation import score_train_test, score_train_test_sorted_lambdas, \
-    CV_score
+from SparseSC.cross_validation import (
+    score_train_test,
+    score_train_test_sorted_v_pens, 
+    CV_score,
+)
 from SparseSC.tensor import tensor
 from SparseSC.weights import weights
-from SparseSC.lambda_utils import get_max_lambda, L2_pen_guestimate
+from SparseSC.lambda_utils import get_max_v_pen, w_pen_guestimate
 
 # The version as used in the setup.py
 __version__ = "0.1.0"

SparseSC/cross_validation.py

@@ -158,7 +158,7 @@ def score_train_test(X,
     return v_mat, w_pen, s
 
 
-def score_train_test_sorted_lambdas(v_pen,
+def score_train_test_sorted_v_pens(v_pen,
                                     start=None,
                                     cache=False,
                                     progress=False,
@@ -184,14 +184,14 @@ def score_train_test_sorted_lambdas(v_pen,
         if progress > 0 and (i % progress) == 0:
             t1 = time.time()
             if FoldNumber is None:
-                print("lambda: %0.4f, value %s of %s, time elapsed: %0.4f sec." %
+                print("v_pen: %0.4f, value %s of %s, time elapsed: %0.4f sec." %
                       (Lam, i+1, len(v_pen), t1 - t0, ))
-                #print("iteration %s of %s time: %0.4f ,lambda: %0.4f, diags: %s" %
+                #print("iteration %s of %s time: %0.4f ,v_pen: %0.4f, diags: %s" %
                 #      (i+1, len(v_pen), t1 - t0, Lam, np.diag(v_mat),))
             else:
-                print("Fold %s,lambda: %0.4f, value %s of %s, time elapsed: %0.4f sec." %
+                print("Fold %s,v_pen: %0.4f, value %s of %s, time elapsed: %0.4f sec." %
                       (FoldNumber, Lam, i+1, len(v_pen), t1 - t0, ))
-                #print("Fold %s, iteration %s of %s, time: %0.4f ,lambda: %0.4f, diags: %s" %
+                #print("Fold %s, iteration %s of %s, time: %0.4f ,v_pen: %0.4f, diags: %s" %
                 #      (FoldNumber, i+1, len(v_pen), t1 - t0, Lam, np.diag(v_mat),))
             t0 = time.time()
 
@@ -209,7 +209,7 @@ def CV_score(X,Y,
              max_workers=None,
              progress=None,
              **kwargs):
-    """ Cross fold validation for 1 or more L1 Penalties, holding the L2 penalty fixed.
+    """ Cross fold validation for 1 or more v Penalties, holding the w penalty fixed.
     """
 
     # PARAMETER QC
@@ -234,13 +234,13 @@ def CV_score(X,Y,
     try:
         _v_pen = iter(v_pen)
     except TypeError:
-        # Lambda is a single value
-        multi_lambda = False
+        # v_pen is a single value
+        multi_v_pen = False
         __score_train_test__ = score_train_test
     else:
-        # Lambda is an iterable of values
-        multi_lambda = True
-        __score_train_test__ = score_train_test_sorted_lambdas
+        # v_pen is an iterable of values
+        multi_v_pen = True
+        __score_train_test__ = score_train_test_sorted_v_pens
 
     if X_treat is not None:
 
@@ -381,7 +381,7 @@ def CV_score(X,Y,
     # extract the score.
     _, _, scores = list(zip(* results))
 
-    if multi_lambda:
+    if multi_v_pen:
         total_score = [sum(s) for s in zip(*scores)]
     else:
         total_score = sum(scores)

SparseSC/fit.py

@@ -7,7 +7,7 @@
 from sklearn.model_selection import KFold
 
 # From the Public API
-from SparseSC.lambda_utils import get_max_lambda, L2_pen_guestimate
+from SparseSC.lambda_utils import get_max_v_pen, w_pen_guestimate
 from SparseSC.cross_validation import CV_score
 from SparseSC.tensor import tensor
 from SparseSC.weights import weights
@@ -23,8 +23,8 @@ def fit(X,Y,
         covariate_penalties = None, # Float or an array of floats
         # PARAMETERS USED TO CONSTRUCT DEFAULT GRID COVARIATE_PENALTIES
         grid = None, # USER SUPPLIED GRID OF COVARIATE PENALTIES
-        Lambda_min = 1e-6,
-        Lambda_max = 1,
+        min_v_pen = 1e-6,
+        max_v_pen = 1,
         grid_points = 20,
         choice = "min",
         cv_folds = 10,
@@ -54,36 +54,36 @@ def fit(X,Y,
 
         :param weight_penalty: Penalty applied to the difference
             between the current weights and the null weights (1/n). default
-            provided by :func:``L2_pen_guestimate``.
+            provided by :func:``w_pen_guestimate``.
         :type weight_penalty: float, Optional
 
         :param covariate_penalties: penalty
             (penalties) applied to the magnitude of the covariate weights.
             Defaults to ``[ Lambda_c_max * g for g in grid]``, where
-            `Lambda_c_max` is determined via :func:`get_max_lambda` .
+            `Lambda_c_max` is determined via :func:`get_max_v_pen` .
         :type covariate_penalties: float | float[], optional
 
         :param grid: only used when `covariate_penalties` is not provided.
-            Defaults to ``np.exp(np.linspace(np.log(Lambda_min),np.log(Lambda_max),grid_points))``
+            Defaults to ``np.exp(np.linspace(np.log(min_v_pen),np.log(max_v_pen),grid_points))``
         :type grid: float | float[], optional
 
-        :param Lambda_min: Lower bound for ``grid`` when
+        :param min_v_pen: Lower bound for ``grid`` when
             ``covariate_penalties`` and ``grid`` are not provided.  Must be in the
             range ``(0,1)``
-        :type Lambda_min: float, default = 1e-6
+        :type min_v_pen: float, default = 1e-6
 
-        :param Lambda_max: Upper bound for ``grid`` when
+        :param max_v_pen: Upper bound for ``grid`` when
             ``covariate_penalties`` and ``grid`` are not provided.  Must be in the
             range ``(0,1]``
-        :type Lambda_max: float, default = 1
+        :type max_v_pen: float, default = 1
 
         :param grid_points: number of points in the ``grid`` parameter when
             ``covariate_penalties`` and ``grid`` are not provided
         :type grid_points: int, default = 20
 
         :param choice: Method for choosing from among the
             covariate_penalties.  Only used when covariate_penalties is an
-            iterable.  Defaults to ``"min"`` which selects the lambda parameter
+            iterable.  Defaults to ``"min"`` which selects the v_pen parameter
             associated with the lowest cross validation error.
         :type choice: str or function. default = ``"min"``
 
@@ -193,14 +193,14 @@ def fit(X,Y,
         # --------------------------------------------------
         # (sensible?) defaults
         # --------------------------------------------------
-        # Get the L2 penalty guestimate:  very quick ( milliseconds )
+        # Get the weight penalty guestimate:  very quick ( milliseconds )
         if weight_penalty is None:
-            weight_penalty  = L2_pen_guestimate(Xtrain)
+            weight_penalty  = w_pen_guestimate(Xtrain)
         if covariate_penalties is None:
             if grid is None:
-                grid = np.exp(np.linspace(np.log(Lambda_min),np.log(Lambda_max),grid_points))
+                grid = np.exp(np.linspace(np.log(min_v_pen),np.log(max_v_pen),grid_points))
             # GET THE MAXIMUM v_penS: quick ~ ( seconds to tens of seconds )
-            v_pen_max = get_max_lambda(Xtrain,
+            v_pen_max = get_max_v_pen(Xtrain,
                                         Ytrain,
                                         w_pen = weight_penalty,
                                         grad_splits = gradient_folds,
@@ -212,7 +212,7 @@ def fit(X,Y,
             # Retrospective Treatment Effects:  ( *model_type = "prospective"*)
 
             # --------------------------------------------------
-            # Phase 1: extract cross fold residual errors for each lambda
+            # Phase 1: extract cross fold residual errors for each v_pen
             # --------------------------------------------------
 
             # SCORES FOR EACH VALUE OF THE GRID: very slow ( minutes to hours )
@@ -228,15 +228,15 @@ def fit(X,Y,
                                **kwargs)
 
             # GET THE INDEX OF THE BEST SCORE
-            best_V_lambda = __choose(scores, covariate_penalties, choice)
+            best_v_pen = __choose(scores, covariate_penalties, choice)
 
             # --------------------------------------------------
             # Phase 2: extract V and weights: slow ( tens of seconds to minutes )
             # --------------------------------------------------
 
             best_V = tensor(X = Xtrain,
                             Y = Ytrain,
-                            v_pen = best_V_lambda,
+                            v_pen = best_v_pen,
                             grad_splits = gradient_folds,
                             random_state = gradient_seed, # TODO: Cleanup Task 1
                             **kwargs)
@@ -270,7 +270,7 @@ def fit(X,Y,
                     gradient_folds.append([control_units, treated_units])
 
             # --------------------------------------------------
-            # Phase 1: extract cross fold residual errors for each lambda
+            # Phase 1: extract cross fold residual errors for each v_pen
             # --------------------------------------------------
 
             # SCORES FOR EACH VALUE OF THE GRID: very slow ( minutes to hours )
@@ -286,15 +286,15 @@ def fit(X,Y,
                                **kwargs)
 
             # GET THE INDEX OF THE BEST SCORE
-            best_V_lambda = __choose(scores, covariate_penalties, choice)
+            best_v_pen = __choose(scores, covariate_penalties, choice)
 
             # --------------------------------------------------
             # Phase 2: extract V and weights: slow ( tens of seconds to minutes )
             # --------------------------------------------------
 
             best_V = tensor(X = X,
                             Y = Y,
-                            v_pen = best_V_lambda,
+                            v_pen = best_v_pen,
                             grad_splits = gradient_folds,
                             random_state = gradient_seed, # TODO: Cleanup Task 1
                             **kwargs)
@@ -306,7 +306,7 @@ def fit(X,Y,
             # unobserved ( || Y_treat - W Y_ctrl || ) in counter factual
 
             # --------------------------------------------------
-            # Phase 1: extract cross fold residual errors for each lambda
+            # Phase 1: extract cross fold residual errors for each v_pen
             # --------------------------------------------------
 
             # SCORES FOR EACH VALUE OF THE GRID: very slow ( minutes to hours )
@@ -322,7 +322,7 @@ def fit(X,Y,
                                **kwargs)
 
             # GET THE INDEX OF THE BEST SCORE
-            best_V_lambda = __choose(scores, covariate_penalties, choice)
+            best_v_pen = __choose(scores, covariate_penalties, choice)
 
             # --------------------------------------------------
             # Phase 2: extract V and weights: slow ( tens of seconds to minutes )
@@ -332,7 +332,7 @@ def fit(X,Y,
                             Y = Ytrain,
                             X_treat = Xtest,
                             Y_treat = Ytest,
-                            v_pen = best_V_lambda,
+                            v_pen = best_v_pen,
                             **kwargs)
 
 
@@ -368,21 +368,21 @@ def fit(X,Y,
         # --------------------------------------------------
         if covariate_penalties is None:
             if grid is None:
-                grid = np.exp(np.linspace(np.log(Lambda_min),np.log(Lambda_max),grid_points))
+                grid = np.exp(np.linspace(np.log(min_v_pen),np.log(max_v_pen),grid_points))
             # GET THE MAXIMUM v_penS: quick ~ ( seconds to tens of seconds )
-            v_pen_max = get_max_lambda(X,
+            v_pen_max = get_max_v_pen(X,
                                         Y,
                                         w_pen = weight_penalty,
                                         grad_splits = gradient_folds,
                                         verbose=verbose)
             covariate_penalties = grid * v_pen_max
 
-        # Get the L2 penalty guestimate:  very quick ( milliseconds )
+        # Get the weight penalty guestimate:  very quick ( milliseconds )
         if weight_penalty is None:
-            weight_penalty  = L2_pen_guestimate(X)
+            weight_penalty  = w_pen_guestimate(X)
 
         # --------------------------------------------------
-        # Phase 1: extract cross fold residual errors for each lambda
+        # Phase 1: extract cross fold residual errors for each v_pen
         # --------------------------------------------------
 
         # SCORES FOR EACH VALUE OF THE GRID: very slow ( minutes to hours )
@@ -398,15 +398,15 @@ def fit(X,Y,
                           **kwargs)
 
         # GET THE INDEX OF THE BEST SCORE
-        best_V_lambda = __choose(scores, covariate_penalties, choice)
+        best_v_pen = __choose(scores, covariate_penalties, choice)
 
         # --------------------------------------------------
         # Phase 2: extract V and weights: slow ( tens of seconds to minutes )
         # --------------------------------------------------
 
         best_V = tensor(X = X,
                         Y = Y,
-                        v_pen = best_V_lambda,
+                        v_pen = best_v_pen,
                         grad_splits = gradient_folds,
                         random_state = gradient_seed, # TODO: Cleanup Task 1
                         **kwargs)
@@ -423,7 +423,7 @@ def fit(X,Y,
                        treated_units,
                        model_type,
                        # fitting parameters
-                       best_V_lambda,
+                       best_v_pen,
                        weight_penalty,
                        covariate_penalties,
                        best_V,
@@ -437,18 +437,18 @@ def __choose(scores, covariate_penalties, choice):
     try:
         iter(covariate_penalties)
     except TypeError:
-        best_lambda = scores
+        best_v_pen = scores
     else:
         if choice == "min":
             best_i = np.argmin(scores)
-            best_lambda = (covariate_penalties)[best_i]
+            best_v_pen = (covariate_penalties)[best_i]
         elif callable(choice):
-            best_lambda = choice(scores)
+            best_v_pen = choice(scores)
         else:
             # TODO: this is a terrible place to throw this error
             raise ValueError("Unexpected value for choice parameter: %s" % choice)
 
-    return best_lambda
+    return best_v_pen
 
 
 class SparseSCFit(object):

SparseSC/fit_ct.py

@@ -15,7 +15,7 @@ def ct_v_matrix(X,
                 start = None,
                 w_pen = None,
                 method = cdl_search,
-                max_lambda = False,  # this is terrible at least without documentation...
+                return_max_v_pen = False,  # this is terrible at least without documentation...
                 verbose = False,
                 gradient_message = "Calculating gradient",
                 **kwargs):
@@ -41,18 +41,18 @@ def ct_v_matrix(X,
     :param start: initial values for the diagonals of the tensor matrix
     :type start: float[] or numpy.ndarray
 
-    :param w_pen: L2 penalty on the magnitude of the deviance of the weight
+    :param w_pen: weight penalty on the magnitude of the deviance of the weight
                      vector from null. Optional.
     :type w_pen: float
 
     :param method: The name of a method to be used by scipy.optimize.minimize,
                    or a callable with the same API as scipy.optimize.minimize
     :type method: str or callable
 
-    :param max_lambda: (Internal API) If ``True``, the return value is the maximum L1 penalty for
+    :param return_max_v_pen: (Internal API) If ``True``, the return value is the maximum L1 penalty for
                        which at least one element of the tensor matrix is
                        non-zero.
-    :type max_lambda: boolean
+    :type return_max_v_pen: boolean
 
     :param verbose: If true, print progress to the console (default: false)
     :type verbose: boolean
@@ -168,7 +168,7 @@ def _weights(V):
             raise exc
         return weights, A, B,b
 
-    if max_lambda:
+    if return_max_v_pen:
         grad0 = _grad(zeros(K))
         return -grad0[grad0 < 0].min()