merged with elastic net pr

Author: jkbradley

mllib/src/main/scala/org/apache/spark/ml/param/shared/SharedParamsCodeGen.scala

@@ -54,7 +54,9 @@ private[shared] object SharedParamsCodeGen {
         isValid = "ParamValidate.gtEq[Int](1)"),
       ParamDesc[Boolean]("fitIntercept", "whether to fit an intercept term", Some("true")),
       ParamDesc[Long]("seed", "random seed", Some("Utils.random.nextLong()")),
-      ParamDesc[Double]("elasticNetParam", "the ElasticNet mixing parameter"),
+      ParamDesc[Double]("elasticNetParam", "the ElasticNet mixing parameter, in range [0, 1]." +
+        " For alpha = 0, the penalty is an L2 penalty. For alpha = 1, it is an L1 penalty.",
+        isValid = "ParamValidate.inRange[Double](0, 1)"),
       ParamDesc[Double]("tol", "the convergence tolerance for iterative algorithms"),
       ParamDesc[Double]("stepSize", "Step size to be used for each iteration of optimization."))
 

mllib/src/main/scala/org/apache/spark/ml/param/shared/sharedParams.scala

@@ -250,37 +250,33 @@ private[ml] trait HasSeed extends Params {
 }
 
 /**
- * :: DeveloperApi ::
- * Trait for shared param elasticNetParam.
+ * (private[ml]) Trait for shared param elasticNetParam.
  */
-@DeveloperApi
-trait HasElasticNetParam extends Params {
+private[ml] trait HasElasticNetParam extends Params {
 
   /**
-   * Param for the ElasticNet mixing parameter.
+   * Param for the ElasticNet mixing parameter, in range [0, 1]. For alpha = 0, the penalty is an L2 penalty. For alpha = 1, it is an L1 penalty..
    * @group param
    */
-  final val elasticNetParam: DoubleParam = new DoubleParam(this, "elasticNetParam", "the ElasticNet mixing parameter")
+  final val elasticNetParam: DoubleParam = new DoubleParam(this, "elasticNetParam", "the ElasticNet mixing parameter, in range [0, 1]. For alpha = 0, the penalty is an L2 penalty. For alpha = 1, it is an L1 penalty.", ParamValidate.inRange[Double](0, 1))
 
   /** @group getParam */
   final def getElasticNetParam: Double = getOrDefault(elasticNetParam)
 }
 
 /**
- * :: DeveloperApi ::
- * Trait for shared param tol.
+ * (private[ml]) Trait for shared param convergenceTol.
  */
-@DeveloperApi
-trait HasTol extends Params {
+private[ml] trait HasConvergenceTol extends Params {
 
   /**
    * Param for the convergence tolerance for iterative algorithms.
    * @group param
    */
-  final val tol: DoubleParam = new DoubleParam(this, "tol", "the convergence tolerance for iterative algorithms")
+  final val convergenceTol: DoubleParam = new DoubleParam(this, "convergenceTol", "the convergence tolerance for iterative algorithms")
 
   /** @group getParam */
-  final def getTol: Double = getOrDefault(tol)
+  final def getConvergenceTol: Double = getOrDefault(convergenceTol)
 }
 
 /**

mllib/src/main/scala/org/apache/spark/ml/regression/LinearRegression.scala

@@ -25,7 +25,8 @@ import breeze.optimize.{CachedDiffFunction, DiffFunction}
 
 import org.apache.spark.annotation.AlphaComponent
 import org.apache.spark.ml.param.{Params, ParamMap}
-import org.apache.spark.ml.param.shared.{HasElasticNetParam, HasMaxIter, HasRegParam, HasTol}
+import org.apache.spark.ml.param.shared.{HasConvergenceTol, HasElasticNetParam, HasMaxIter,
+  HasRegParam}
 import org.apache.spark.mllib.stat.MultivariateOnlineSummarizer
 import org.apache.spark.mllib.linalg.{Vector, Vectors}
 import org.apache.spark.mllib.linalg.BLAS._
@@ -40,12 +41,22 @@ import org.apache.spark.Logging
  * Params for linear regression.
  */
 private[regression] trait LinearRegressionParams extends RegressorParams
-  with HasRegParam with HasElasticNetParam with HasMaxIter with HasTol // TODO: elasticnetparam, tol
+  with HasRegParam with HasElasticNetParam with HasMaxIter with HasConvergenceTol
 
 /**
  * :: AlphaComponent ::
  *
  * Linear regression.
+ *
+ * The learning objective is to minimize the squared error, with regularization.
+ * The specific squared error loss function used is:
+ *   L = 1/2n ||A weights - y||^2^
+ *
+ * This support multiple types of regularization:
+ *  - none (a.k.a. ordinary least squares)
+ *  - L2 (ridge regression)
+ *  - L1 (Lasso)
+ *  - L2 + L1 (elastic net)
  */
 @AlphaComponent
 class LinearRegression extends Regressor[Vector, LinearRegression, LinearRegressionModel]
@@ -83,8 +94,8 @@ class LinearRegression extends Regressor[Vector, LinearRegression, LinearRegress
    * Default is 1E-6.
    * @group setParam
    */
-  def setTol(value: Double): this.type = set(tol, value)
-  setDefault(tol -> 1E-6)
+  def setTol(value: Double): this.type = set(convergenceTol, value)
+  setDefault(convergenceTol -> 1E-6)
 
   override protected def train(dataset: DataFrame, paramMap: ParamMap): LinearRegressionModel = {
     // Extract columns from data.  If dataset is persisted, do not persist instances.
@@ -133,9 +144,10 @@ class LinearRegression extends Regressor[Vector, LinearRegression, LinearRegress
       featuresStd, featuresMean, effectiveL2RegParam)
 
     val optimizer = if (paramMap(elasticNetParam) == 0.0 || effectiveRegParam == 0.0) {
-      new BreezeLBFGS[BDV[Double]](paramMap(maxIter), 10, paramMap(tol))
+      new BreezeLBFGS[BDV[Double]](paramMap(maxIter), 10, paramMap(convergenceTol))
     } else {
-      new BreezeOWLQN[Int, BDV[Double]](paramMap(maxIter), 10, effectiveL1RegParam, paramMap(tol))
+      new BreezeOWLQN[Int, BDV[Double]](paramMap(maxIter), 10, effectiveL1RegParam,
+        paramMap(convergenceTol))
     }
 
     val initialWeights = Vectors.zeros(numFeatures)