Scrub projection and normalization transforms (#2865)

Author: wschin

docs/samples/Microsoft.ML.Samples/Dynamic/Normalizer.cs

@@ -66,7 +66,7 @@ public static void Example()
 
             // Composing a different pipeline if we wanted to normalize more than one column at a time. 
             // Using log scale as the normalization mode. 
-            var multiColPipeline = ml.Transforms.Normalize(NormalizingEstimator.NormalizerMode.LogMeanVariance, new ColumnOptions[] { ("LogInduced", "Induced"), ("LogSpontaneous", "Spontaneous") });
+            var multiColPipeline = ml.Transforms.Normalize(NormalizingEstimator.NormalizationMode.LogMeanVariance, new ColumnOptions[] { ("LogInduced", "Induced"), ("LogSpontaneous", "Spontaneous") });
             // The transformed data.
             var multiColtransformer = multiColPipeline.Fit(trainData);
             var multiColtransformedData = multiColtransformer.Transform(trainData);

docs/samples/Microsoft.ML.Samples/Dynamic/ProjectionTransforms.cs

@@ -37,7 +37,7 @@ public static void Example()
             };
 
             // A pipeline to project Features column into Random fourier space.
-            var rffPipeline = ml.Transforms.Projection.CreateRandomFourierFeatures(nameof(SamplesUtils.DatasetUtils.SampleVectorOfNumbersData.Features), newDim: 4);
+            var rffPipeline = ml.Transforms.RandomFourierKernelMap(nameof(SamplesUtils.DatasetUtils.SampleVectorOfNumbersData.Features), rank: 4);
             // The transformed (projected) data.
             var transformedData = rffPipeline.Fit(trainData).Transform(trainData);
             // Getting the data of the newly created column, so we can preview it.
@@ -55,7 +55,7 @@ public static void Example()
             //0.165 0.117 -0.547  0.014
 
             // A pipeline to project Features column into L-p normalized vector.
-            var lpNormalizePipeline = ml.Transforms.Projection.LpNormalize(nameof(SamplesUtils.DatasetUtils.SampleVectorOfNumbersData.Features), normKind: Transforms.LpNormalizingEstimatorBase.NormalizerKind.L1Norm);
+            var lpNormalizePipeline = ml.Transforms.LpNormalize(nameof(SamplesUtils.DatasetUtils.SampleVectorOfNumbersData.Features), normKind: Transforms.LpNormalizingEstimatorBase.NormFunction.L1);
             // The transformed (projected) data.
             transformedData = lpNormalizePipeline.Fit(trainData).Transform(trainData);
             // Getting the data of the newly created column, so we can preview it.
@@ -73,7 +73,7 @@ public static void Example()
             // 0.133 0.156 0.178 0.200 0.000 0.022 0.044 0.067 0.089 0.111
 
             // A pipeline to project Features column into L-p normalized vector.
-            var gcNormalizePipeline = ml.Transforms.Projection.GlobalContrastNormalize(nameof(SamplesUtils.DatasetUtils.SampleVectorOfNumbersData.Features), substractMean:false);
+            var gcNormalizePipeline = ml.Transforms.GlobalContrastNormalize(nameof(SamplesUtils.DatasetUtils.SampleVectorOfNumbersData.Features), ensureZeroMean:false);
             // The transformed (projected) data.
             transformedData = gcNormalizePipeline.Fit(trainData).Transform(trainData);
             // Getting the data of the newly created column, so we can preview it.

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/AnomalyDetection/RandomizedPcaSample.cs

@@ -29,7 +29,7 @@ public static void Example()
             var data = mlContext.Data.LoadFromEnumerable(samples);
 
             // Create an anomaly detector. Its underlying algorithm is randomized PCA.
-            var pipeline = mlContext.AnomalyDetection.Trainers.RandomizedPca(featureColumnName: nameof(DataPoint.Features), rank: 1, center: false);
+            var pipeline = mlContext.AnomalyDetection.Trainers.AnalyzeRandomizedPrincipalComponents(featureColumnName: nameof(DataPoint.Features), rank: 1, ensureZeroMean: false);
 
             // Train the anomaly detector.
             var model = pipeline.Fit(data);

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/AnomalyDetection/RandomizedPcaSampleWithOptions.cs

@@ -28,15 +28,15 @@ public static void Example()
             // Convert the List<DataPoint> to IDataView, a consumble format to ML.NET functions.
             var data = mlContext.Data.LoadFromEnumerable(samples);
 
-            var options = new ML.Trainers.RandomizedPcaTrainer.Options()
+            var options = new ML.Trainers.RandomizedPrincipalComponentAnalyzer.Options()
             {
                 FeatureColumnName = nameof(DataPoint.Features),
                 Rank = 1,
                 Seed = 10,
             };
 
             // Create an anomaly detector. Its underlying algorithm is randomized PCA.
-            var pipeline = mlContext.AnomalyDetection.Trainers.RandomizedPca(options);
+            var pipeline = mlContext.AnomalyDetection.Trainers.AnalyzeRandomizedPrincipalComponents(options);
 
             // Train the anomaly detector.
             var model = pipeline.Fit(data);

docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/Projection/VectorWhiten.cs

@@ -38,10 +38,9 @@ public static void Example()
                     Console.WriteLine($"{string.Join(" ", row.DenseValues().Select(x => x.ToString("f3")))} ");
             };
 
-          
             // A pipeline to project Features column into white noise vector.
-            var whiteningPipeline = ml.Transforms.Projection.VectorWhiten(nameof(SamplesUtils.DatasetUtils.SampleVectorOfNumbersData.Features),
-                kind: Transforms.WhiteningKind.Zca);
+            var whiteningPipeline = ml.Transforms.VectorWhiten(nameof(SamplesUtils.DatasetUtils.SampleVectorOfNumbersData.Features),
+                kind: Transforms.WhiteningKind.ZeroPhaseComponentAnalysis);
             // The transformed (projected) data.
             var transformedData = whiteningPipeline.Fit(trainData).Transform(trainData);
             // Getting the data of the newly created column, so we can preview it.

docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/Projection/VectorWhitenWithColumnOptions.cs

@@ -39,8 +39,8 @@ public static void Example()
 
 
             // A pipeline to project Features column into white noise vector.
-            var whiteningPipeline = ml.Transforms.Projection.VectorWhiten(new Transforms.VectorWhiteningEstimator.ColumnOptions(
-                nameof(SamplesUtils.DatasetUtils.SampleVectorOfNumbersData.Features), kind: Transforms.WhiteningKind.Pca, pcaNum: 4));
+            var whiteningPipeline = ml.Transforms.VectorWhiten(new Transforms.VectorWhiteningEstimator.ColumnOptions(
+                nameof(SamplesUtils.DatasetUtils.SampleVectorOfNumbersData.Features), kind: Transforms.WhiteningKind.PrincipalComponentAnalysis, rank: 4));
             // The transformed (projected) data.
             var transformedData = whiteningPipeline.Fit(trainData).Transform(trainData);
             // Getting the data of the newly created column, so we can preview it.

src/Microsoft.ML.Data/Transforms/Normalizer.cs

@@ -39,7 +39,7 @@ internal static class Defaults
             public const long MaxTrainingExamples = 1000000000;
         }
 
-        public enum NormalizerMode
+        public enum NormalizationMode
         {
             /// <summary>
             /// Linear rescale such that minimum and maximum values are mapped between -1 and 1.
@@ -82,19 +82,19 @@ private protected ColumnOptionsBase(string name, string inputColumnName, long ma
 
             internal abstract IColumnFunctionBuilder MakeBuilder(IHost host, int srcIndex, DataViewType srcType, DataViewRowCursor cursor);
 
-            internal static ColumnOptionsBase Create(string outputColumnName, string inputColumnName, NormalizerMode mode)
+            internal static ColumnOptionsBase Create(string outputColumnName, string inputColumnName, NormalizationMode mode)
             {
                 switch (mode)
                 {
-                    case NormalizerMode.MinMax:
+                    case NormalizationMode.MinMax:
                         return new MinMaxColumnOptions(outputColumnName, inputColumnName);
-                    case NormalizerMode.MeanVariance:
+                    case NormalizationMode.MeanVariance:
                         return new MeanVarColumnOptions(outputColumnName, inputColumnName);
-                    case NormalizerMode.LogMeanVariance:
+                    case NormalizationMode.LogMeanVariance:
                         return new LogMeanVarColumnOptions(outputColumnName, inputColumnName);
-                    case NormalizerMode.Binning:
+                    case NormalizationMode.Binning:
                         return new BinningColumnOptions(outputColumnName, inputColumnName);
-                    case NormalizerMode.SupervisedBinning:
+                    case NormalizationMode.SupervisedBinning:
                         return new SupervisedBinningColumOptions(outputColumnName, inputColumnName);
                     default:
                         throw Contracts.ExceptParam(nameof(mode), "Unknown normalizer mode");
@@ -202,8 +202,8 @@ internal override IColumnFunctionBuilder MakeBuilder(IHost host, int srcIndex, D
         /// <param name="outputColumnName">Name of the column resulting from the transformation of <paramref name="inputColumnName"/>.</param>
         /// <param name="inputColumnName">Name of the column to transform.
         /// If set to <see langword="null"/>, the value of the <paramref name="outputColumnName"/> will be used as source.</param>
-        /// <param name="mode">The <see cref="NormalizerMode"/> indicating how to the old values are mapped to the new values.</param>
-        internal NormalizingEstimator(IHostEnvironment env, string outputColumnName, string inputColumnName = null, NormalizerMode mode = NormalizerMode.MinMax)
+        /// <param name="mode">The <see cref="NormalizationMode"/> indicating how to the old values are mapped to the new values.</param>
+        internal NormalizingEstimator(IHostEnvironment env, string outputColumnName, string inputColumnName = null, NormalizationMode mode = NormalizationMode.MinMax)
             : this(env, mode, (outputColumnName, inputColumnName ?? outputColumnName))
         {
         }
@@ -212,9 +212,9 @@ internal NormalizingEstimator(IHostEnvironment env, string outputColumnName, str
         /// Initializes a new instance of <see cref="NormalizingEstimator"/>.
         /// </summary>
         /// <param name="env">The private instance of <see cref="IHostEnvironment"/>.</param>
-        /// <param name="mode">The <see cref="NormalizerMode"/> indicating how to the old values are mapped to the new values.</param>
+        /// <param name="mode">The <see cref="NormalizationMode"/> indicating how to the old values are mapped to the new values.</param>
         /// <param name="columns">An array of (outputColumnName, inputColumnName) tuples.</param>
-        internal NormalizingEstimator(IHostEnvironment env, NormalizerMode mode, params (string outputColumnName, string inputColumnName)[] columns)
+        internal NormalizingEstimator(IHostEnvironment env, NormalizationMode mode, params (string outputColumnName, string inputColumnName)[] columns)
         {
             Contracts.CheckValue(env, nameof(env));
             _host = env.Register(nameof(NormalizingEstimator));

src/Microsoft.ML.Data/Transforms/NormalizerCatalog.cs

@@ -30,11 +30,6 @@ public sealed class TransformsCatalog : IInternalCatalog
         /// </summary>
         public TextTransforms Text { get; }
 
-        /// <summary>
-        /// The list of operations for data projection.
-        /// </summary>
-        public ProjectionTransforms Projection { get; }
-
         /// <summary>
         /// The list of operations for selecting features based on some criteria.
         /// </summary>
@@ -48,7 +43,6 @@ internal TransformsCatalog(IHostEnvironment env)
             Categorical = new CategoricalTransforms(this);
             Conversion = new ConversionTransforms(this);
             Text = new TextTransforms(this);
-            Projection = new ProjectionTransforms(this);
             FeatureSelection = new FeatureSelectionTransforms(this);
         }
 
@@ -94,20 +88,6 @@ internal TextTransforms(TransformsCatalog owner)
             }
         }
 
-        /// <summary>
-        /// The catalog of projection operations.
-        /// </summary>
-        public sealed class ProjectionTransforms : IInternalCatalog
-        {
-            IHostEnvironment IInternalCatalog.Environment => _env;
-            private readonly IHostEnvironment _env;
-
-            internal ProjectionTransforms(TransformsCatalog owner)
-            {
-                _env = owner.GetEnvironment();
-            }
-        }
-
         /// <summary>
         /// The catalog of feature selection operations.
         /// </summary>

src/Microsoft.ML.Data/Transforms/TransformsCatalog.cs

@@ -61,18 +61,18 @@ public override IEstimator<ITransformer> Reconcile(IHostEnvironment env,
         /// <param name="maxRows">Maximum number of rows used to train the transform.</param>
         /// <param name="pcaNum">In case of PCA whitening, indicates the number of components to retain.</param>
         public static Vector<float> PcaWhitening(this Vector<float> input,
-            float eps = VectorWhiteningEstimator.Defaults.Eps,
-            int maxRows = VectorWhiteningEstimator.Defaults.MaxRows,
-            int pcaNum = VectorWhiteningEstimator.Defaults.PcaNum)
-            => new OutPipelineColumn(input, WhiteningKind.Pca, eps, maxRows, pcaNum);
+            float eps = VectorWhiteningEstimator.Defaults.Epsilon,
+            int maxRows = VectorWhiteningEstimator.Defaults.MaximumNumberOfRows,
+            int pcaNum = VectorWhiteningEstimator.Defaults.Rank)
+            => new OutPipelineColumn(input, WhiteningKind.PrincipalComponentAnalysis, eps, maxRows, pcaNum);
 
         /// <include file='../Microsoft.ML.Mkl.Components/doc.xml' path='doc/members/member[@name="Whitening"]/*'/>
         /// <param name="input">The column to which the transform will be applied.</param>
         /// <param name="eps">Whitening constant, prevents division by zero.</param>
         /// <param name="maxRows">Maximum number of rows used to train the transform.</param>
         public static Vector<float> ZcaWhitening(this Vector<float> input,
-            float eps = VectorWhiteningEstimator.Defaults.Eps,
-            int maxRows = VectorWhiteningEstimator.Defaults.MaxRows)
-            => new OutPipelineColumn(input, WhiteningKind.Zca, eps, maxRows, VectorWhiteningEstimator.Defaults.PcaNum);
+            float eps = VectorWhiteningEstimator.Defaults.Epsilon,
+            int maxRows = VectorWhiteningEstimator.Defaults.MaximumNumberOfRows)
+            => new OutPipelineColumn(input, WhiteningKind.ZeroPhaseComponentAnalysis, eps, maxRows, VectorWhiteningEstimator.Defaults.Rank);
     }
 }