Test GAM Public APIs (#2188)

* Refactoring the GAM Trainer / Predictor to move all Training information into the trainer, and make the GAM predictor generic.
* Adding a test for IsSorted<double>, changing all IsSorted to use IList and renaming to IsMonotonicallyIncreasing.

Author: rogancarr

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

@@ -77,10 +77,13 @@ public static void RunExample()
             // First, let's get the index of the variable we want to look at
             var studentTeacherRatioIndex = featureNames.ToList().FindIndex(str => str.Equals("TeacherRatio"));
 
-            // Next, let's get the array of bin upper bounds from the model for this feature
-            var teacherRatioBinUpperBounds = gamModel.GetFeatureBinUpperBounds(studentTeacherRatioIndex);
-            // And the array of bin weights; these are the effect size for each bin
-            var teacherRatioFeatureWeights = gamModel.GetFeatureWeights(studentTeacherRatioIndex);
+            // Next, let's get the array of histogram bin upper bounds from the model for this feature
+            // For each feature, the shape function is calculated at `MaxBins` locations along the range of 
+            // values that the feature takes, and the resulting shape function can be seen as a histogram of
+            // effects.
+            var teacherRatioBinUpperBounds = gamModel.GetBinUpperBounds(studentTeacherRatioIndex);
+            // And the array of bin effects; these are the effect size for each bin
+            var teacherRatioBinEffects = gamModel.GetBinEffects(studentTeacherRatioIndex);
 
             // Now, write the function to the console. The function is a set of bins, and the corresponding
             // function values. You can think of GAMs as building a bar-chart lookup table.
@@ -118,7 +121,7 @@ public static void RunExample()
             Console.WriteLine("Student-Teacher Ratio");
             for (int i = 0; i < teacherRatioBinUpperBounds.Length; i++)
             {
-                Console.WriteLine($"x < {teacherRatioBinUpperBounds[i]:0.00} => {teacherRatioFeatureWeights[i]:0.000}");
+                Console.WriteLine($"x < {teacherRatioBinUpperBounds[i]:0.00} => {teacherRatioBinEffects[i]:0.000}");
             }
             Console.WriteLine();
         }

src/Microsoft.ML.Core/Utilities/Utils.cs

@@ -534,14 +534,6 @@ public static int[] GetRandomPermutation(Random rand, int size)
             return res;
         }
 
-        public static void Shuffle<T>(Random rand, Span<T> rgv)
-        {
-            Contracts.AssertValue(rand);
-
-            for (int iv = 0; iv < rgv.Length; iv++)
-                Swap(ref rgv[iv], ref rgv[iv + rand.Next(rgv.Length - iv)]);
-        }
-
         public static bool AreEqual(float[] arr1, float[] arr2)
         {
             if (arr1 == arr2)
@@ -576,6 +568,14 @@ public static bool AreEqual(double[] arr1, double[] arr2)
             return true;
         }
 
+        public static void Shuffle<T>(Random rand, Span<T> rgv)
+        {
+            Contracts.AssertValue(rand);
+
+            for (int iv = 0; iv < rgv.Length; iv++)
+                Swap(ref rgv[iv], ref rgv[iv + rand.Next(rgv.Length - iv)]);
+        }
+
         public static bool AreEqual(int[] arr1, int[] arr2)
         {
             if (arr1 == arr2)
@@ -615,37 +615,80 @@ public static string ExtractLettersAndNumbers(string value)
             return Regex.Replace(value, "[^A-Za-z0-9]", "");
         }
 
-        public static bool IsSorted(IList<float> values)
+        /// <summary>
+        /// Checks that an input IList is monotonically increasing.
+        /// </summary>
+        /// <param name="values">An array of values</param>
+        /// <returns>True if the array is monotonically increasing (if each element is greater
+        /// than or equal to previous elements); false otherwise. ILists containing NaN values
+        /// are considered to be not monotonically increasing.</returns>
+        public static bool IsMonotonicallyIncreasing(IList<float> values)
         {
             if (Utils.Size(values) <= 1)
                 return true;
 
-            var prev = values[0];
-
-            for (int i = 1; i < values.Count; i++)
+            var previousValue = values[0];
+            var listLength = values.Count;
+            for (int i = 1; i < listLength; i++)
             {
-                if (!(values[i] >= prev))
+                var currentValue = values[i];
+                // Inverted check for NaNs
+                if (!(currentValue >= previousValue))
                     return false;
 
-                prev = values[i];
+                previousValue = currentValue;
             }
 
             return true;
         }
 
-        public static bool IsSorted(int[] values)
+        /// <summary>
+        /// Checks that an input array is monotonically increasing.
+        /// </summary>
+        /// <param name="values">An array of values</param>
+        /// <returns>True if the array is monotonically increasing (if each element is greater
+        /// than or equal to previous elements); false otherwise.</returns>
+        public static bool IsMonotonicallyIncreasing(IList<int> values)
         {
             if (Utils.Size(values) <= 1)
                 return true;
 
-            var prev = values[0];
+            var previousValue = values[0];
+            var listLength = values.Count;
+            for (int i = 1; i < listLength; i++)
+            {
+                var currentValue = values[i];
+                if (currentValue < previousValue)
+                    return false;
 
-            for (int i = 1; i < values.Length; i++)
+                previousValue = currentValue;
+            }
+
+            return true;
+        }
+
+        /// <summary>
+        /// Checks that an input array is monotonically increasing.
+        /// </summary>
+        /// <param name="values">An array of values</param>
+        /// <returns>True if the array is monotonically increasing (if each element is greater
+        /// than or equal to previous elements); false otherwise. Arrays containing NaN values
+        /// are considered to be not monotonically increasing.</returns>
+        public static bool IsMonotonicallyIncreasing(IList<double> values)
+        {
+            if (Utils.Size(values) <= 1)
+                return true;
+
+            var previousValue = values[0];
+            var listLength = values.Count;
+            for (int i = 1; i < listLength; i++)
             {
-                if (values[i] < prev)
+                var currentValue = values[i];
+                // Inverted check for NaNs
+                if (!(currentValue >= previousValue))
                     return false;
 
-                prev = values[i];
+                previousValue = currentValue;
             }
 
             return true;

src/Microsoft.ML.Data/Prediction/Calibrator.cs

@@ -1653,9 +1653,9 @@ public PavCalibrator(IHostEnvironment env, ImmutableArray<float> mins, Immutable
             _host.AssertNonEmpty(mins);
             _host.AssertNonEmpty(maxes);
             _host.AssertNonEmpty(values);
-            _host.Assert(Utils.IsSorted(mins));
-            _host.Assert(Utils.IsSorted(maxes));
-            _host.Assert(Utils.IsSorted(values));
+            _host.Assert(Utils.IsMonotonicallyIncreasing(mins));
+            _host.Assert(Utils.IsMonotonicallyIncreasing(maxes));
+            _host.Assert(Utils.IsMonotonicallyIncreasing(values));
             _host.Assert(values.Length == 0 || (0 <= values[0] && values[values.Length - 1] <= 1));
             _host.Assert(mins.Zip(maxes, (min, max) => min <= max).All(x => x));
 

src/Microsoft.ML.FastTree/Dataset/FeatureFlock.cs

@@ -1170,7 +1170,7 @@ protected SinglePartitionedIntArrayFlockBase(TIntArray bins, int[] hotFeatureSta
             Contracts.AssertValue(binUpperBounds);
             Contracts.Assert(Utils.Size(hotFeatureStarts) == binUpperBounds.Length + 1); // One more than number of features.
             Contracts.Assert(hotFeatureStarts[0] == 1);
-            Contracts.Assert(Utils.IsSorted(hotFeatureStarts));
+            Contracts.Assert(Utils.IsMonotonicallyIncreasing(hotFeatureStarts));
             Contracts.Assert(bins.Max() < hotFeatureStarts[hotFeatureStarts.Length - 1]);
 
             Bins = bins;

src/Microsoft.ML.FastTree/GamModelParameters.cs

@@ -89,6 +89,7 @@ private protected GamModelParametersBase(IHostEnvironment env, string name,
                 // Check data validity
                 Host.CheckValue(binEffects[i], nameof(binEffects), "Array contained null entries");
                 Host.CheckParam(binUpperBounds[i].Length == binEffects[i].Length, nameof(binEffects), "Array contained wrong number of effect values");
+                Host.CheckParam(Utils.IsMonotonicallyIncreasing(binUpperBounds[i]), nameof(binUpperBounds), "Array must be monotonically increasing");
 
                 // Update the value at zero
                 _valueAtAllZero += GetBinEffect(i, 0, out _binsAtAllZero[i]);
@@ -282,44 +283,74 @@ private double GetBinEffect(int featureIndex, double featureValue, out int binIn
         /// Get the bin upper bounds for each feature.
         /// </summary>
         /// <param name="featureIndex">The index of the feature (in the training vector) to get.</param>
-        /// <returns>The bin upper bounds. May be null if this feature has no bins.</returns>
-        public double[] GetFeatureBinUpperBounds(int featureIndex)
+        /// <returns>The bin upper bounds. May be zero length if this feature has no bins.</returns>
+        public double[] GetBinUpperBounds(int featureIndex)
         {
             Host.Check(0 <= featureIndex && featureIndex < NumShapeFunctions, "Index out of range.");
-            double[] featureBins;
-            if (_inputFeatureToShapeFunctionMap.TryGetValue(featureIndex, out int j))
-            {
-                featureBins = new double[_binUpperBounds[j].Length];
-                _binUpperBounds[j].CopyTo(featureBins, 0);
-            }
-            else
+            if (!_inputFeatureToShapeFunctionMap.TryGetValue(featureIndex, out int j))
+                return new double[0];
+
+            var binUpperBounds = new double[_binUpperBounds[j].Length];
+            _binUpperBounds[j].CopyTo(binUpperBounds, 0);
+            return binUpperBounds;
+        }
+
+        /// <summary>
+        /// Get all the bin upper bounds.
+        /// </summary>
+        public double[][] GetBinUpperBounds()
+        {
+            double[][] binUpperBounds = new double[NumShapeFunctions][];
+            for (int i = 0; i < NumShapeFunctions; i++)
             {
-                featureBins = new double[0];
+                if (_inputFeatureToShapeFunctionMap.TryGetValue(i, out int j))
+                {
+                    binUpperBounds[i] = new double[_binUpperBounds[j].Length];
+                    _binUpperBounds[j].CopyTo(binUpperBounds[i], 0);
+                }
+                else
+                {
+                    binUpperBounds[i] = new double[0];
+                }
             }
-
-            return featureBins;
+            return binUpperBounds;
         }
 
         /// <summary>
         /// Get the binned weights for each feature.
         /// </summary>
         /// <param name="featureIndex">The index of the feature (in the training vector) to get.</param>
-        /// <returns>The binned weights for each feature.</returns>
-        public double[] GetFeatureWeights(int featureIndex)
+        /// <returns>The binned effects for each feature. May be zero length if this feature has no bins.</returns>
+        public double[] GetBinEffects(int featureIndex)
         {
             Host.Check(0 <= featureIndex && featureIndex < NumShapeFunctions, "Index out of range.");
-            double[] featureWeights;
-            if (_inputFeatureToShapeFunctionMap.TryGetValue(featureIndex, out int j))
-            {
-                featureWeights = new double[_binEffects[j].Length];
-                _binEffects[j].CopyTo(featureWeights, 0);
-            }
-            else
+            if (!_inputFeatureToShapeFunctionMap.TryGetValue(featureIndex, out int j))
+                return new double[0];
+
+            var binEffects = new double[_binEffects[j].Length];
+            _binEffects[j].CopyTo(binEffects, 0);
+            return binEffects;
+        }
+
+        /// <summary>
+        /// Get all the binned effects.
+        /// </summary>
+        public double[][] GetBinEffects()
+        {
+            double[][] binEffects = new double[NumShapeFunctions][];
+            for (int i = 0; i < NumShapeFunctions; i++)
             {
-                featureWeights = new double[0];
+                if (_inputFeatureToShapeFunctionMap.TryGetValue(i, out int j))
+                {
+                    binEffects[i] = new double[_binEffects[j].Length];
+                    _binEffects[j].CopyTo(binEffects[i], 0);
+                }
+                else
+                {
+                    binEffects[i] = new double[0];
+                }
             }
-
-            return featureWeights;
+            return binEffects;
         }
 
         void ICanSaveInTextFormat.SaveAsText(TextWriter writer, RoleMappedSchema schema)

src/Microsoft.ML.FastTree/QuantileStatistics.cs

@@ -60,7 +60,7 @@ public QuantileStatistics(float[] data, float[] weights = null, bool isSorted =
             if (!isSorted)
                 Array.Sort(_data);
             else
-                Contracts.Assert(Utils.IsSorted(_data));
+                Contracts.Assert(Utils.IsMonotonicallyIncreasing(_data));
         }
 
         /// <summary>

src/Microsoft.ML.StandardLearners/Standard/LogisticRegression/MulticlassLogisticRegression.cs

@@ -512,7 +512,7 @@ private MulticlassLogisticRegressionModelParameters(IHostEnvironment env, ModelL
                 Host.CheckDecode(numStarts == _numClasses + 1);
                 int[] starts = ctx.Reader.ReadIntArray(numStarts);
                 Host.CheckDecode(starts[0] == 0);
-                Host.CheckDecode(Utils.IsSorted(starts));
+                Host.CheckDecode(Utils.IsMonotonicallyIncreasing(starts));
 
                 int numIndices = ctx.Reader.ReadInt32();
                 Host.CheckDecode(numIndices == starts[starts.Length - 1]);