[SPARK-15790][MLlib] Audit @Since annotations in ML

mllib/src/main/scala/org/apache/spark/ml/Model.scala

@@ -17,7 +17,7 @@
 
 package org.apache.spark.ml
 
-import org.apache.spark.annotation.DeveloperApi
+import org.apache.spark.annotation.{DeveloperApi, Since}
 import org.apache.spark.ml.param.ParamMap
 
 /**
@@ -27,6 +27,7 @@ import org.apache.spark.ml.param.ParamMap
  * @tparam M model type
  */
 @DeveloperApi
+@Since("1.2.0")
 abstract class Model[M <: Model[M]] extends Transformer {
   /**
    * The parent estimator that produced this model.

mllib/src/main/scala/org/apache/spark/ml/ann/BreezeUtil.scala

@@ -17,12 +17,14 @@
 
 package org.apache.spark.ml.ann
 
+import org.apache.spark.annotation.Since
 import breeze.linalg.{DenseMatrix => BDM, DenseVector => BDV}
 import com.github.fommil.netlib.BLAS.{getInstance => NativeBLAS}
 
 /**
  * In-place DGEMM and DGEMV for Breeze
  */
+@Since("1.5.0")
 private[ann] object BreezeUtil {
 
   // TODO: switch to MLlib BLAS interface

mllib/src/main/scala/org/apache/spark/ml/ann/Layer.scala

@@ -20,7 +20,7 @@ package org.apache.spark.ml.ann
 import java.util.Random
 
 import breeze.linalg.{*, axpy => Baxpy, DenseMatrix => BDM, DenseVector => BDV, Vector => BV}
-
+import org.apache.spark.annotation.Since
 import org.apache.spark.ml.linalg.{Vector, Vectors}
 import org.apache.spark.mllib.linalg.{Vector => OldVector, Vectors => OldVectors}
 import org.apache.spark.mllib.linalg.VectorImplicits._
@@ -34,6 +34,7 @@ import org.apache.spark.util.random.XORShiftRandom
  * Implements Layer instantiation.
  *
  */
+@Since("1.5.0")
 private[ann] trait Layer extends Serializable {
 
   /**
@@ -83,6 +84,7 @@ private[ann] trait Layer extends Serializable {
  * Implements functions needed for forward propagation, computing delta and gradient.
  * Can return weights in Vector format.
  */
+@Since("1.5.0")
 private[ann] trait LayerModel extends Serializable {
 
   val weights: BDV[Double]
@@ -130,6 +132,7 @@ private[ann] trait LayerModel extends Serializable {
  * @param numIn number of inputs
  * @param numOut number of outputs
  */
+@Since("1.5.0")
 private[ann] class AffineLayer(val numIn: Int, val numOut: Int) extends Layer {
 
   override val weightSize = numIn * numOut + numOut
@@ -150,6 +153,7 @@ private[ann] class AffineLayer(val numIn: Int, val numOut: Int) extends Layer {
  * @param weights weights
  * @param layer layer properties
  */
+@Since("1.5.0")
 private[ann] class AffineLayerModel private[ann] (
     val weights: BDV[Double],
     val layer: AffineLayer) extends LayerModel {
@@ -185,6 +189,7 @@ private[ann] class AffineLayerModel private[ann] (
 /**
  * Fabric for Affine layer models
  */
+@Since("1.5.0")
 private[ann] object AffineLayerModel {
 
   /**
@@ -229,6 +234,7 @@ private[ann] object AffineLayerModel {
 /**
  * Trait for functions and their derivatives for functional layers
  */
+@Since("1.5.0")
 private[ann] trait ActivationFunction extends Serializable {
 
   /**
@@ -245,6 +251,7 @@ private[ann] trait ActivationFunction extends Serializable {
 /**
  * Implements in-place application of functions in the arrays
  */
+@Since("1.5.0")
 private[ann] object ApplyInPlace {
 
   // TODO: use Breeze UFunc
@@ -281,6 +288,7 @@ private[ann] object ApplyInPlace {
 /**
  * Implements Sigmoid activation function
  */
+@Since("1.5.0")
 private[ann] class SigmoidFunction extends ActivationFunction {
 
   override def eval: (Double) => Double = x => 1.0 / (1 + math.exp(-x))
@@ -312,6 +320,7 @@ private[ann] class FunctionalLayer (val activationFunction: ActivationFunction)
  *
  * @param layer functional layer
  */
+@Since("1.5.0")
 private[ann] class FunctionalLayerModel private[ann] (val layer: FunctionalLayer)
   extends LayerModel {
 
@@ -336,6 +345,7 @@ private[ann] class FunctionalLayerModel private[ann] (val layer: FunctionalLayer
 /**
  * Trait for the artificial neural network (ANN) topology properties
  */
+@Since("1.5.0")
 private[ann] trait Topology extends Serializable {
   def model(weights: Vector): TopologyModel
   def model(seed: Long): TopologyModel
@@ -344,6 +354,7 @@ private[ann] trait Topology extends Serializable {
 /**
  * Trait for ANN topology model
  */
+@Since("1.5.0")
 private[ann] trait TopologyModel extends Serializable {
 
   val weights: Vector
@@ -391,6 +402,7 @@ private[ann] trait TopologyModel extends Serializable {
  *
  * @param layers Array of layers
  */
+@Since("1.5.0")
 private[ann] class FeedForwardTopology private(val layers: Array[Layer]) extends Topology {
   override def model(weights: Vector): TopologyModel = FeedForwardModel(this, weights)
 
@@ -400,6 +412,7 @@ private[ann] class FeedForwardTopology private(val layers: Array[Layer]) extends
 /**
  * Factory for some of the frequently-used topologies
  */
+@Since("1.5.0")
 private[ml] object FeedForwardTopology {
   /**
    * Creates a feed forward topology from the array of layers
@@ -448,6 +461,7 @@ private[ml] object FeedForwardTopology {
  * @param weights network weights
  * @param topology network topology
  */
+@Since("1.5.0")
 private[ml] class FeedForwardModel private(
     val weights: Vector,
     val topology: FeedForwardTopology) extends TopologyModel {
@@ -535,6 +549,7 @@ private[ml] class FeedForwardModel private(
 /**
  * Fabric for feed forward ANN models
  */
+@Since("1.5.0")
 private[ann] object FeedForwardModel {
 
   /**
@@ -579,6 +594,7 @@ private[ann] object FeedForwardModel {
  * @param topology topology
  * @param dataStacker data stacker
  */
+@Since("1.5.0")
 private[ann] class ANNGradient(topology: Topology, dataStacker: DataStacker) extends Gradient {
   override def compute(
     data: OldVector,
@@ -601,6 +617,7 @@ private[ann] class ANNGradient(topology: Topology, dataStacker: DataStacker) ext
  * @param inputSize size of the input vectors
  * @param outputSize size of the output vectors
  */
+@Since("1.5.0")
 private[ann] class DataStacker(stackSize: Int, inputSize: Int, outputSize: Int)
   extends Serializable {
 
@@ -655,6 +672,7 @@ private[ann] class DataStacker(stackSize: Int, inputSize: Int, outputSize: Int)
 /**
  * Simple updater
  */
+@Since("1.5.0")
 private[ann] class ANNUpdater extends Updater {
 
   override def compute(
@@ -677,6 +695,7 @@ private[ann] class ANNUpdater extends Updater {
  * @param inputSize input size
  * @param outputSize output size
  */
+@Since("1.5.0")
 private[ml] class FeedForwardTrainer(
     topology: Topology,
     val inputSize: Int,

mllib/src/main/scala/org/apache/spark/ml/ann/LossFunction.scala

@@ -18,13 +18,14 @@
 package org.apache.spark.ml.ann
 
 import java.util.Random
-
+import org.apache.spark.annotation.Since
 import breeze.linalg.{sum => Bsum, DenseMatrix => BDM, DenseVector => BDV}
 import breeze.numerics.{log => brzlog}
 
 /**
  * Trait for loss function
  */
+@Since("2.0.0")
 private[ann] trait LossFunction {
   /**
    * Returns the value of loss function.
@@ -41,6 +42,7 @@ private[ann] trait LossFunction {
   def loss(output: BDM[Double], target: BDM[Double], delta: BDM[Double]): Double
 }
 
+@Since("2.0.0")
 private[ann] class SigmoidLayerWithSquaredError extends Layer {
   override val weightSize = 0
   override val inPlace = true
@@ -52,6 +54,7 @@ private[ann] class SigmoidLayerWithSquaredError extends Layer {
     new SigmoidLayerModelWithSquaredError()
 }
 
+@Since("2.0.0")
 private[ann] class SigmoidLayerModelWithSquaredError
   extends FunctionalLayerModel(new FunctionalLayer(new SigmoidFunction)) with LossFunction {
   override def loss(output: BDM[Double], target: BDM[Double], delta: BDM[Double]): Double = {
@@ -62,6 +65,7 @@ private[ann] class SigmoidLayerModelWithSquaredError
   }
 }
 
+@Since("2.0.0")
 private[ann] class SoftmaxLayerWithCrossEntropyLoss extends Layer {
   override val weightSize = 0
   override val inPlace = true
@@ -73,6 +77,7 @@ private[ann] class SoftmaxLayerWithCrossEntropyLoss extends Layer {
     new SoftmaxLayerModelWithCrossEntropyLoss()
 }
 
+@Since("2.0.0")
 private[ann] class SoftmaxLayerModelWithCrossEntropyLoss extends LayerModel with LossFunction {
 
   // loss layer models do not have weights

mllib/src/main/scala/org/apache/spark/ml/attribute/AttributeGroup.scala

@@ -18,8 +18,7 @@
 package org.apache.spark.ml.attribute
 
 import scala.collection.mutable.ArrayBuffer
-
-import org.apache.spark.annotation.DeveloperApi
+import org.apache.spark.annotation.{DeveloperApi, Since}
 import org.apache.spark.ml.linalg.VectorUDT
 import org.apache.spark.sql.types.{Metadata, MetadataBuilder, StructField}
 
@@ -34,6 +33,7 @@ import org.apache.spark.sql.types.{Metadata, MetadataBuilder, StructField}
  *              indices in the array.
  */
 @DeveloperApi
+@Since("1.4.0")
 class AttributeGroup private (
     val name: String,
     val numAttributes: Option[Int],
@@ -192,6 +192,7 @@ class AttributeGroup private (
  * Factory methods to create attribute groups.
  */
 @DeveloperApi
+@Since("1.4.0")
 object AttributeGroup {
 
   import AttributeKeys._

mllib/src/main/scala/org/apache/spark/ml/attribute/AttributeKeys.scala

@@ -17,9 +17,12 @@
 
 package org.apache.spark.ml.attribute
 
+import org.apache.spark.annotation.Since
+
 /**
  * Keys used to store attributes.
  */
+@Since("1.4.0")
 private[attribute] object AttributeKeys {
   val ML_ATTR: String = "ml_attr"
   val TYPE: String = "type"

mllib/src/main/scala/org/apache/spark/ml/attribute/AttributeType.scala

@@ -17,20 +17,22 @@
 
 package org.apache.spark.ml.attribute
 
-import org.apache.spark.annotation.DeveloperApi
+import org.apache.spark.annotation.{DeveloperApi, Since}
 
 /**
  * :: DeveloperApi ::
  * An enum-like type for attribute types: [[AttributeType$#Numeric]], [[AttributeType$#Nominal]],
  * and [[AttributeType$#Binary]].
  */
 @DeveloperApi
+@Since("1.4.0")
 sealed abstract class AttributeType(val name: String)
 
 /**
  * :: DeveloperApi ::
  */
 @DeveloperApi
+@Since("1.4.0")
 object AttributeType {
 
   /** Numeric type. */

mllib/src/main/scala/org/apache/spark/ml/attribute/attributes.scala

@@ -19,14 +19,15 @@ package org.apache.spark.ml.attribute
 
 import scala.annotation.varargs
 
-import org.apache.spark.annotation.DeveloperApi
+import org.apache.spark.annotation.{DeveloperApi, Since}
 import org.apache.spark.sql.types.{DoubleType, Metadata, MetadataBuilder, NumericType, StructField}
 
 /**
  * :: DeveloperApi ::
  * Abstract class for ML attributes.
  */
 @DeveloperApi
+@Since("1.4.0")
 sealed abstract class Attribute extends Serializable {
 
   name.foreach { n =>
@@ -118,6 +119,7 @@ sealed abstract class Attribute extends Serializable {
 }
 
 /** Trait for ML attribute factories. */
+@Since("1.4.0")
 private[attribute] trait AttributeFactory {
 
   /**
@@ -154,6 +156,7 @@ private[attribute] trait AttributeFactory {
  * :: DeveloperApi ::
  */
 @DeveloperApi
+@Since("1.4.0")
 object Attribute extends AttributeFactory {
 
   private[attribute] override def fromMetadata(metadata: Metadata): Attribute = {
@@ -192,6 +195,7 @@ object Attribute extends AttributeFactory {
  * @param sparsity optional sparsity (ratio of zeros)
  */
 @DeveloperApi
+@Since("1.4.0")
 class NumericAttribute private[ml] (
     override val name: Option[String] = None,
     override val index: Option[Int] = None,
@@ -303,6 +307,7 @@ class NumericAttribute private[ml] (
  * Factory methods for numeric attributes.
  */
 @DeveloperApi
+@Since("1.4.0")
 object NumericAttribute extends AttributeFactory {
 
   /** The default numeric attribute. */
@@ -331,6 +336,7 @@ object NumericAttribute extends AttributeFactory {
  * @param values optional values. At most one of `numValues` and `values` can be defined.
  */
 @DeveloperApi
+@Since("1.4.0")
 class NominalAttribute private[ml] (
     override val name: Option[String] = None,
     override val index: Option[Int] = None,
@@ -468,6 +474,7 @@ class NominalAttribute private[ml] (
  * Factory methods for nominal attributes.
  */
 @DeveloperApi
+@Since("1.4.0")
 object NominalAttribute extends AttributeFactory {
 
   /** The default nominal attribute. */
@@ -494,6 +501,7 @@ object NominalAttribute extends AttributeFactory {
  * @param values optional values. If set, its size must be 2.
  */
 @DeveloperApi
+@Since("1.4.0")
 class BinaryAttribute private[ml] (
     override val name: Option[String] = None,
     override val index: Option[Int] = None,
@@ -570,6 +578,7 @@ class BinaryAttribute private[ml] (
  * Factory methods for binary attributes.
  */
 @DeveloperApi
+@Since("1.4.0")
 object BinaryAttribute extends AttributeFactory {
 
   /** The default binary attribute. */
@@ -590,6 +599,7 @@ object BinaryAttribute extends AttributeFactory {
  * An unresolved attribute.
  */
 @DeveloperApi
+@Since("1.4.0")
 object UnresolvedAttribute extends Attribute {
 
   override def attrType: AttributeType = AttributeType.Unresolved