Merge pull request #3174 from shauheen/release/rc1

Cherry-pick for RC1

Author: shauheen

build/vsts-ci.yml

@@ -236,12 +236,12 @@ phases:
       nuGetFeedType: internal 
       feedPublish: MachineLearning
 
-  - task: MSBuild@1
-    displayName: Publish Packages to MyGet Feed
-    inputs:
-      solution: build/publish.proj
-      msbuildArguments: /t:PublishPackages /p:NuGetFeedUrl=$(_NuGetFeedUrl) /p:NuGetApiKey=$(dotnet-myget-org-api-key)
-      msbuildVersion: 15.0
+  # - task: MSBuild@1
+  #   displayName: Publish Packages to MyGet Feed
+  #   inputs:
+  #     solution: build/publish.proj
+  #     msbuildArguments: /t:PublishPackages /p:NuGetFeedUrl=$(_NuGetFeedUrl) /p:NuGetApiKey=$(dotnet-myget-org-api-key)
+  #     msbuildVersion: 15.0
 
   - task: MSBuild@1
     displayName: Publish Symbols to SymWeb Symbol Server

docs/code/MlNetCookBook.md

@@ -344,7 +344,7 @@ var cachedTrainData = mlContext.Data.Cache(trainData);
 var pipeline =
     // First 'normalize' the data (rescale to be
     // between -1 and 1 for all examples)
-    mlContext.Transforms.Normalize("FeatureVector")
+    mlContext.Transforms.NormalizeMinMax("FeatureVector")
     // We add a step for caching data in memory so that the downstream iterative training
     // algorithm can efficiently scan through the data multiple times. Otherwise, the following
     // trainer will load data from disk multiple times. The caching mechanism uses an on-demand strategy.
@@ -625,18 +625,15 @@ var trainData = mlContext.Data.LoadFromTextFile<IrisInputAllFeatures>(dataPath,
     separatorChar: ','
 );
 
-// Apply all kinds of standard ML.NET normalization to the raw features.
+// Apply MinMax normalization to the raw features.
 var pipeline =
-    mlContext.Transforms.Normalize(
-        new NormalizingEstimator.MinMaxColumnOptions("MinMaxNormalized", "Features", fixZero: true),
-        new NormalizingEstimator.MeanVarianceColumnOptions("MeanVarNormalized", "Features", fixZero: true),
-        new NormalizingEstimator.BinningColumnOptions("BinNormalized", "Features", maximumBinCount: 256));
+    mlContext.Transforms.NormalizeMinMax("MinMaxNormalized", "Features");
 
 // Let's train our pipeline of normalizers, and then apply it to the same data.
 var normalizedData = pipeline.Fit(trainData).Transform(trainData);
 
 // Inspect one column of the resulting dataset.
-var meanVarValues = normalizedData.GetColumn<float[]>(normalizedData.Schema["MeanVarNormalized"]).ToArray();
+var meanVarValues = normalizedData.GetColumn<float[]>(normalizedData.Schema["MinMaxNormalized"]).ToArray();
 ```
 
 ## How do I train my model on categorical data?

docs/code/VBufferCareFeeding.md

@@ -12,7 +12,7 @@ public static void Example()
             var mlContext = new MLContext();
 
             // Get a small dataset as an IEnumerable and them read it as ML.NET's data type.
-            IEnumerable<SamplesUtils.DatasetUtils.BinaryLabelFloatFeatureVectorSample> enumerableOfData = SamplesUtils.DatasetUtils.GenerateBinaryLabelFloatFeatureVectorSamples(5);
+            IEnumerable<SamplesUtils.DatasetUtils.BinaryLabelFloatFeatureVectorFloatWeightSample> enumerableOfData = SamplesUtils.DatasetUtils.GenerateBinaryLabelFloatFeatureVectorFloatWeightSamples(5);
             var data = mlContext.Data.LoadFromEnumerable(enumerableOfData);
 
             // Look at the original dataset
@@ -43,7 +43,7 @@ public static void Example()
             {
                 var resample = mlContext.Data.BootstrapSample(data, seed: i);
 
-                var enumerable = mlContext.Data.CreateEnumerable<SamplesUtils.DatasetUtils.BinaryLabelFloatFeatureVectorSample>(resample, reuseRowObject: false);
+                var enumerable = mlContext.Data.CreateEnumerable<SamplesUtils.DatasetUtils.BinaryLabelFloatFeatureVectorFloatWeightSample>(resample, reuseRowObject: false);
                 Console.WriteLine($"Label\tFeatures[0]");
                 foreach (var row in enumerable)
                 {

docs/samples/Microsoft.ML.Samples/Dynamic/DataOperations/BootstrapSample.cs

@@ -1,8 +1,6 @@
 using System;
 using System.Collections.Generic;
-using System.Linq;
 using Microsoft.ML.Data;
-using Microsoft.ML.Transforms;
 
 namespace Microsoft.ML.Samples.Dynamic
 {
@@ -28,7 +26,7 @@ public static void Example()
             // 35   1       6-11yrs     1         3         32            5  ...
 
             // A pipeline for normalizing the Induced column.
-            var pipeline = ml.Transforms.Normalize("Induced");
+            var pipeline = ml.Transforms.NormalizeMinMax("Induced");
             // The transformed (normalized according to Normalizer.NormalizerMode.MinMax) data.
             var transformer = pipeline.Fit(trainData);
 
@@ -58,8 +56,8 @@ 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("LogInduced", "Induced", NormalizingEstimator.NormalizationMode.LogMeanVariance)
-                .Append(ml.Transforms.Normalize("LogSpontaneous", "Spontaneous", NormalizingEstimator.NormalizationMode.LogMeanVariance));
+            var multiColPipeline = ml.Transforms.NormalizeMinMax("LogInduced", "Induced")
+                .Append(ml.Transforms.NormalizeMinMax("LogSpontaneous", "Spontaneous"));
             // The transformed data.
             var multiColtransformer = multiColPipeline.Fit(trainData);
             var multiColtransformedData = multiColtransformer.Transform(trainData);

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

@@ -19,7 +19,7 @@ public static void Example()
             // Normalize the data set so that for each feature, its maximum value is 1 while its minimum value is 0.
             // Then append a linear regression trainer.
             var pipeline = mlContext.Transforms.Concatenate("Features", featureNames)
-                    .Append(mlContext.Transforms.Normalize("Features"))
+                    .Append(mlContext.Transforms.NormalizeMinMax("Features"))
                     .Append(mlContext.Regression.Trainers.Ols(
                         labelColumnName: labelName, featureColumnName: "Features"));
             var model = pipeline.Fit(data);

docs/samples/Microsoft.ML.Samples/Dynamic/PermutationFeatureImportance/PFIRegressionExample.cs

@@ -21,7 +21,7 @@ public static void Example()
             // Normalize the data set so that for each feature, its maximum value is 1 while its minimum value is 0.
             // Then append a logistic regression trainer.
             var pipeline = mlContext.Transforms.Concatenate("Features", featureNames)
-                    .Append(mlContext.Transforms.Normalize("Features"))
+                    .Append(mlContext.Transforms.NormalizeMinMax("Features"))
                     .Append(mlContext.BinaryClassification.Trainers.LbfgsLogisticRegression(
                         labelColumnName: labelName, featureColumnName: "Features"));
             var model = pipeline.Fit(data);

docs/samples/Microsoft.ML.Samples/Dynamic/PermutationFeatureImportance/PfiBinaryClassificationExample.cs

@@ -9,7 +9,7 @@ public static class StochasticDualCoordinateAscentNonCalibrated
         public static void Example()
         {
             // Generate IEnumerable<BinaryLabelFloatFeatureVectorSample> as training examples.
-            var rawData = SamplesUtils.DatasetUtils.GenerateBinaryLabelFloatFeatureVectorSamples(100);
+            var rawData = SamplesUtils.DatasetUtils.GenerateBinaryLabelFloatFeatureVectorFloatWeightSamples(100);
 
             // Information in first example.
             // Label: true

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/BinaryClassification/StochasticDualCoordinateAscentNonCalibrated.cs

@@ -441,8 +441,16 @@ public static bool TryGetCategoricalFeatureIndices(DataViewSchema schema, int co
         public static IEnumerable<SchemaShape.Column> AnnotationsForMulticlassScoreColumn(SchemaShape.Column? labelColumn = null)
         {
             var cols = new List<SchemaShape.Column>();
-            if (labelColumn != null && labelColumn.Value.IsKey && NeedsSlotNames(labelColumn.Value))
-                cols.Add(new SchemaShape.Column(Kinds.SlotNames, SchemaShape.Column.VectorKind.Vector, TextDataViewType.Instance, false));
+            if (labelColumn != null && labelColumn.Value.IsKey)
+            {
+                if (labelColumn.Value.Annotations.TryFindColumn(Kinds.KeyValues, out var metaCol) &&
+                    metaCol.Kind == SchemaShape.Column.VectorKind.Vector)
+                {
+                    if (metaCol.ItemType is TextDataViewType)
+                        cols.Add(new SchemaShape.Column(Kinds.SlotNames, SchemaShape.Column.VectorKind.Vector, TextDataViewType.Instance, false));
+                    cols.Add(new SchemaShape.Column(Kinds.TrainingLabelValues, SchemaShape.Column.VectorKind.Vector, metaCol.ItemType, false));
+                }
+            }
             cols.AddRange(GetTrainerOutputAnnotation());
             return cols;
         }

src/Microsoft.ML.Core/Data/AnnotationUtils.cs

@@ -390,7 +390,7 @@ private static ISchemaBoundMapper WrapIfNeeded(IHostEnvironment env, ISchemaBoun
             if (trainSchema?.Label == null)
                 return mapper; // We don't even have a label identified in a training schema.
             var keyType = trainSchema.Label.Value.Annotations.Schema.GetColumnOrNull(AnnotationUtils.Kinds.KeyValues)?.Type as VectorDataViewType;
-            if (keyType == null || !CanWrap(mapper, keyType))
+            if (keyType == null)
                 return mapper;
 
             // Great!! All checks pass.
@@ -409,11 +409,19 @@ private static ISchemaBoundMapper WrapIfNeeded(IHostEnvironment env, ISchemaBoun
         /// from the model of a bindable mapper)</param>
         /// <returns>Whether we can call <see cref="LabelNameBindableMapper.CreateBound{T}"/> with
         /// this mapper and expect it to succeed</returns>
-        internal static bool CanWrap(ISchemaBoundMapper mapper, DataViewType labelNameType)
+        internal static bool CanWrapTrainingLabels(ISchemaBoundMapper mapper, DataViewType labelNameType)
+        {
+            if (GetTypesForWrapping(mapper, labelNameType, AnnotationUtils.Kinds.TrainingLabelValues, out var scoreType))
+                // Check that the type is vector, and is of compatible size with the score output.
+                return labelNameType is VectorDataViewType vectorType && vectorType.Size == scoreType.GetVectorSize();
+            return false;
+        }
+
+        internal static bool GetTypesForWrapping(ISchemaBoundMapper mapper, DataViewType labelNameType, string metaKind, out DataViewType scoreType)
         {
             Contracts.AssertValue(mapper);
             Contracts.AssertValue(labelNameType);
-
+            scoreType = null;
             ISchemaBoundRowMapper rowMapper = mapper as ISchemaBoundRowMapper;
             if (rowMapper == null)
                 return false; // We could cover this case, but it is of no practical worth as far as I see, so I decline to do so.
@@ -423,12 +431,30 @@ internal static bool CanWrap(ISchemaBoundMapper mapper, DataViewType labelNameTy
             var scoreCol = outSchema.GetColumnOrNull(AnnotationUtils.Const.ScoreValueKind.Score);
             if (!outSchema.TryGetColumnIndex(AnnotationUtils.Const.ScoreValueKind.Score, out scoreIdx))
                 return false; // The mapper doesn't even publish a score column to attach the metadata to.
-            if (outSchema[scoreIdx].Annotations.Schema.GetColumnOrNull(AnnotationUtils.Kinds.SlotNames)?.Type != null)
-                return false; // The mapper publishes a score column, and already produces its own slot names.
-            var scoreType = outSchema[scoreIdx].Type;
+            if (outSchema[scoreIdx].Annotations.Schema.GetColumnOrNull(metaKind)?.Type != null)
+                return false; // The mapper publishes a score column, and already produces its own metakind.
+            scoreType = outSchema[scoreIdx].Type;
+            return true;
+        }
 
-            // Check that the type is vector, and is of compatible size with the score output.
-            return labelNameType is VectorDataViewType vectorType && vectorType.Size == scoreType.GetVectorSize() && vectorType.ItemType == TextDataViewType.Instance;
+        /// <summary>
+        /// This is a utility method used to determine whether <see cref="LabelNameBindableMapper"/>
+        /// can or should be used to wrap <paramref name="mapper"/>. This will not throw, since the
+        /// desired behavior in the event that it cannot be wrapped, is to just back off to the original
+        /// "unwrapped" bound mapper.
+        /// </summary>
+        /// <param name="mapper">The mapper we are seeing if we can wrap</param>
+        /// <param name="labelNameType">The type of the label names from the metadata (either
+        /// originating from the key value metadata of the training label column, or deserialized
+        /// from the model of a bindable mapper)</param>
+        /// <returns>Whether we can call <see cref="LabelNameBindableMapper.CreateBound{T}"/> with
+        /// this mapper and expect it to succeed</returns>
+        internal static bool CanWrapSlotNames(ISchemaBoundMapper mapper, DataViewType labelNameType)
+        {
+            if (GetTypesForWrapping(mapper, labelNameType, AnnotationUtils.Kinds.SlotNames, out var scoreType))
+                // Check that the type is vector, and is of compatible size with the score output.
+                return labelNameType is VectorDataViewType vectorType && vectorType.Size == scoreType.GetVectorSize() && vectorType.ItemType == TextDataViewType.Instance;
+            return false;
         }
 
         internal static ISchemaBoundMapper WrapCore<T>(IHostEnvironment env, ISchemaBoundMapper mapper, RoleMappedSchema trainSchema)
@@ -449,8 +475,12 @@ internal static ISchemaBoundMapper WrapCore<T>(IHostEnvironment env, ISchemaBoun
                 {
                     trainSchema.Label.Value.GetKeyValues(ref value);
                 };
-
-            return LabelNameBindableMapper.CreateBound<T>(env, (ISchemaBoundRowMapper)mapper, type as VectorDataViewType, getter, AnnotationUtils.Kinds.SlotNames, CanWrap);
+            var resultMapper = mapper;
+            if (CanWrapTrainingLabels(resultMapper, type))
+                resultMapper = LabelNameBindableMapper.CreateBound<T>(env, (ISchemaBoundRowMapper)resultMapper, type as VectorDataViewType, getter, AnnotationUtils.Kinds.TrainingLabelValues, CanWrapTrainingLabels);
+            if (CanWrapSlotNames(resultMapper, type))
+                resultMapper = LabelNameBindableMapper.CreateBound<T>(env, (ISchemaBoundRowMapper)resultMapper, type as VectorDataViewType, getter, AnnotationUtils.Kinds.SlotNames, CanWrapSlotNames);
+            return resultMapper;
         }
 
         [BestFriend]

src/Microsoft.ML.Data/Scorers/MulticlassClassificationScorer.cs

@@ -62,22 +62,12 @@ private BindingsImpl(DataViewSchema input, ISchemaBoundRowMapper mapper, string
                 {
                     var scoreColMetadata = mapper.OutputSchema[scoreColIndex].Annotations;
 
-                    var slotColumn = scoreColMetadata.Schema.GetColumnOrNull(AnnotationUtils.Kinds.SlotNames);
-                    if (slotColumn?.Type is VectorDataViewType slotColVecType && (ulong)slotColVecType.Size == predColKeyType.Count)
+                    var trainLabelColumn = scoreColMetadata.Schema.GetColumnOrNull(AnnotationUtils.Kinds.TrainingLabelValues);
+                    if (trainLabelColumn?.Type is VectorDataViewType trainLabelColVecType && (ulong)trainLabelColVecType.Size == predColKeyType.Count)
                     {
-                        Contracts.Assert(slotColVecType.Size > 0);
-                        _predColMetadata = Utils.MarshalInvoke(KeyValueMetadataFromMetadata<int>, slotColVecType.RawType,
-                            scoreColMetadata, slotColumn.Value);
-                    }
-                    else
-                    {
-                        var trainLabelColumn = scoreColMetadata.Schema.GetColumnOrNull(AnnotationUtils.Kinds.TrainingLabelValues);
-                        if (trainLabelColumn?.Type is VectorDataViewType trainLabelColVecType && (ulong)trainLabelColVecType.Size == predColKeyType.Count)
-                        {
-                            Contracts.Assert(trainLabelColVecType.Size > 0);
-                            _predColMetadata = Utils.MarshalInvoke(KeyValueMetadataFromMetadata<int>, trainLabelColVecType.RawType,
-                                scoreColMetadata, trainLabelColumn.Value);
-                        }
+                        Contracts.Assert(trainLabelColVecType.Size > 0);
+                        _predColMetadata = Utils.MarshalInvoke(KeyValueMetadataFromMetadata<int>, trainLabelColVecType.RawType,
+                            scoreColMetadata, trainLabelColumn.Value);
                     }
                 }
             }

src/Microsoft.ML.Data/Scorers/PredictedLabelScorerBase.cs

@@ -87,12 +87,12 @@ private SchemaShape.Column CheckInputsAndMakeColumn(
                 // Appending keys makes no real sense anyway.
                 if (col.IsKey)
                 {
-                    throw _host.Except($"Column '{sources[i]}' is key." +
+                    throw _host.Except($"Column '{sources[i]}' is key. " +
                         $"Concatenation of keys is unsupported.");
                 }
                 if (!col.ItemType.Equals(itemType))
                 {
-                    throw _host.Except($"Column '{sources[i]}' has values of {col.ItemType}" +
+                    throw _host.Except($"Column '{sources[i]}' has values of {col.ItemType}, " +
                         $"which is not the same as earlier observed type of {itemType}.");
                 }
                 varVector |= col.Kind == SchemaShape.Column.VectorKind.VariableVector;

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

@@ -39,7 +39,8 @@ internal static class Defaults
             public const long MaximumExampleCount = 1000000000;
         }
 
-        public enum NormalizationMode
+        [BestFriend]
+        internal enum NormalizationMode
         {
             /// <summary>
             /// Linear rescale such that minimum and maximum values are mapped between -1 and 1.