Update of FeatureContributionCalculation to new API (#1847)

Author: artidoro

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

@@ -48,32 +48,36 @@ public static void FeatureContributionCalculationTransform_Regression()
             var transformPipeline = mlContext.Transforms.Concatenate("Features", "CrimesPerCapita", "PercentResidental",
                 "PercentNonRetail", "CharlesRiver", "NitricOxides", "RoomsPerDwelling", "PercentPre40s",
                 "EmploymentDistance", "HighwayDistance", "TaxRate", "TeacherRatio");
-            var learner = mlContext.Regression.Trainers.StochasticDualCoordinateAscent(
+            var learner = mlContext.Regression.Trainers.OrdinaryLeastSquares(
                         labelColumn: "MedianHomeValue", featureColumn: "Features");
 
             var transformedData = transformPipeline.Fit(data).Transform(data);
 
+            // Now we train the model and score it on the transformed data.
             var model = learner.Fit(transformedData);
+            var scoredData = model.Transform(transformedData);
 
             // Create a Feature Contribution Calculator
-            // Calculate the feature contributions for all features
+            // Calculate the feature contributions for all features given trained model parameters
             // And don't normalize the contribution scores
-            var args = new FeatureContributionCalculationTransform.Arguments()
-            {
-                Top = 11,
-                Normalize = false
-            };
-            var featureContributionCalculator = FeatureContributionCalculationTransform.Create(mlContext, args, transformedData, model.Model, model.FeatureColumn);
+            var featureContributionCalculator = mlContext.Model.Explainability.FeatureContributionCalculation(model.Model, model.FeatureColumn, top: 11, normalize: false);
+            var outputData = featureContributionCalculator.Fit(scoredData).Transform(scoredData);
+
+            // FeatureContributionCalculatingEstimator can be use as an intermediary step in a pipeline. 
+            // The features retained by FeatureContributionCalculatingEstimator will be in the FeatureContribution column.
+            var pipeline = mlContext.Model.Explainability.FeatureContributionCalculation(model.Model, model.FeatureColumn, top: 11)
+                .Append(mlContext.Regression.Trainers.OrdinaryLeastSquares(featureColumn: "FeatureContributions"));
+            var outData = featureContributionCalculator.Fit(scoredData).Transform(scoredData);
 
             // Let's extract the weights from the linear model to use as a comparison
             var weights = new VBuffer<float>();
             model.Model.GetFeatureWeights(ref weights);
 
             // Let's now walk through the first ten reconds and see which feature drove the values the most
             // Get prediction scores and contributions
-            var scoringEnumerator = featureContributionCalculator.AsEnumerable<HousingRegressionScoreAndContribution>(mlContext, true).GetEnumerator();
+            var scoringEnumerator = outputData.AsEnumerable<HousingRegressionScoreAndContribution>(mlContext, true).GetEnumerator();
             int index = 0;
-            Console.WriteLine("Label\tScore\tBiggestFeature\tValue\tWeight\tContribution\tPercent");
+            Console.WriteLine("Label\tScore\tBiggestFeature\tValue\tWeight\tContribution");
             while (scoringEnumerator.MoveNext() && index < 10)
             {
                 var row = scoringEnumerator.Current;
@@ -84,26 +88,34 @@ public static void FeatureContributionCalculationTransform_Regression()
                 // And the corresponding information about the feature
                 var value = row.Features[featureOfInterest];
                 var contribution = row.FeatureContributions[featureOfInterest];
-                var percentContribution = 100 * contribution / row.Score;
-                var name = data.Schema[(int) (featureOfInterest + 1)].Name;
+                var name = data.Schema[featureOfInterest + 1].Name;
                 var weight = weights.GetValues()[featureOfInterest];
 
-                Console.WriteLine("{0:0.00}\t{1:0.00}\t{2}\t{3:0.00}\t{4:0.00}\t{5:0.00}\t{6:0.00}",
+                Console.WriteLine("{0:0.00}\t{1:0.00}\t{2}\t{3:0.00}\t{4:0.00}\t{5:0.00}",
                     row.MedianHomeValue,
                     row.Score,
                     name,
                     value,
                     weight,
-                    contribution,
-                    percentContribution
+                    contribution
                     );
 
                 index++;
             }
-
-            // For bulk scoring, the ApplyToData API can also be used
-            var scoredData = featureContributionCalculator.ApplyToData(mlContext, transformedData);
-            var preview = scoredData.Preview(100);
+            Console.ReadLine();
+
+            // The output of the above code is:
+            // Label Score   BiggestFeature Value   Weight Contribution
+            // 24.00   27.74   RoomsPerDwelling        6.58    98.55   39.95
+            // 21.60   23.85   RoomsPerDwelling        6.42    98.55   39.01
+            // 34.70   29.29   RoomsPerDwelling        7.19    98.55   43.65
+            // 33.40   27.17   RoomsPerDwelling        7.00    98.55   42.52
+            // 36.20   27.68   RoomsPerDwelling        7.15    98.55   43.42
+            // 28.70   23.13   RoomsPerDwelling        6.43    98.55   39.07
+            // 22.90   22.71   RoomsPerDwelling        6.01    98.55   36.53
+            // 27.10   21.72   RoomsPerDwelling        6.17    98.55   37.50
+            // 16.50   18.04   RoomsPerDwelling        5.63    98.55   34.21
+            // 18.90   20.14   RoomsPerDwelling        6.00    98.55   36.48
         }
 
         private static int GetMostContributingFeature(float[] featureContributions)

docs/samples/Microsoft.ML.Samples/Program.cs

@@ -6,7 +6,7 @@ internal static class Program
     {
         static void Main(string[] args)
         {
-            TensorFlowTransformExample.TensorFlowScoringSample();
+            FeatureContributionCalculationTransform_RegressionExample.FeatureContributionCalculationTransform_Regression();
         }
     }
 }

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

@@ -448,11 +448,11 @@ internal static bool TryGetCategoricalFeatureIndices(Schema schema, int colIndex
             if (!(schema[colIndex].Type is VectorType vecType && vecType.Size > 0))
                 return isValid;
 
-            var type = schema[colIndex].Metadata.Schema.GetColumnOrNull(MetadataUtils.Kinds.CategoricalSlotRanges)?.Type;
+            var type = schema[colIndex].Metadata.Schema.GetColumnOrNull(Kinds.CategoricalSlotRanges)?.Type;
             if (type?.RawType == typeof(VBuffer<int>))
             {
                 VBuffer<int> catIndices = default(VBuffer<int>);
-                schema[colIndex].Metadata.GetValue(MetadataUtils.Kinds.CategoricalSlotRanges, ref catIndices);
+                schema[colIndex].Metadata.GetValue(Kinds.CategoricalSlotRanges, ref catIndices);
                 VBufferUtils.Densify(ref catIndices);
                 int columnSlotsCount = vecType.Size;
                 if (catIndices.Length > 0 && catIndices.Length % 2 == 0 && catIndices.Length <= columnSlotsCount * 2)
@@ -498,14 +498,15 @@ internal static bool TryGetCategoricalFeatureIndices(Schema schema, int colIndex
         }
 
         /// <summary>
-        /// Produces sequence of columns that are generated by multiclass trainer estimators.
+        /// Produces metadata for the score column generated by trainer estimators for multiclass classification.
+        /// If input LabelColumn is not available it produces slotnames metadata by default.
         /// </summary>
         /// <param name="labelColumn">Label column.</param>
         [BestFriend]
-        internal static IEnumerable<SchemaShape.Column> MetadataForMulticlassScoreColumn(SchemaShape.Column labelColumn)
+        internal static IEnumerable<SchemaShape.Column> MetadataForMulticlassScoreColumn(SchemaShape.Column? labelColumn = null)
         {
             var cols = new List<SchemaShape.Column>();
-            if (labelColumn.IsKey && HasKeyValues(labelColumn))
+            if (labelColumn != null && labelColumn.Value.IsKey && HasKeyValues(labelColumn.Value))
                 cols.Add(new SchemaShape.Column(Kinds.SlotNames, SchemaShape.Column.VectorKind.Vector, TextType.Instance, false));
             cols.AddRange(GetTrainerOutputMetadata());
             return cols;

src/Microsoft.ML.Data/Dirty/PredictorBase.cs

@@ -5,7 +5,6 @@
 using Float = System.Single;
 
 using System;
-using Microsoft.ML.Runtime;
 using Microsoft.ML.Runtime.Model;
 
 namespace Microsoft.ML.Runtime.Internal.Internallearn

src/Microsoft.ML.Data/Dirty/PredictorInterfaces.cs

@@ -203,6 +203,23 @@ internal interface IFeatureContributionMapper : IPredictor
         ValueMapper<TSrc, VBuffer<float>> GetFeatureContributionMapper<TSrc, TDst>(int top, int bottom, bool normalize);
     }
 
+    /// <summary>
+    /// Allows support for feature contribution calculation.
+    /// </summary>
+    public interface ICalculateFeatureContribution : IPredictor
+    {
+        FeatureContributionCalculator FeatureContributionClaculator { get; }
+    }
+
+    /// <summary>
+    /// Support for feature contribution calculation.
+    /// </summary>
+    public sealed class FeatureContributionCalculator
+    {
+        internal IFeatureContributionMapper ContributionMapper { get; }
+        internal FeatureContributionCalculator(IFeatureContributionMapper contributionMapper) => ContributionMapper = contributionMapper;
+    }
+
     /// <summary>
     /// Interface for predictors that can return a string array containing the label names from the label column they were trained on.
     /// If the training label is a key with text key value metadata, it should return this metadata. The order of the labels should be consistent

src/Microsoft.ML.Data/Model/ModelOperationsCatalog.cs

@@ -16,10 +16,25 @@ public sealed class ModelOperationsCatalog
     {
         internal IHostEnvironment Environment { get; }
 
+        public ExplainabilityTransforms Explainability { get; }
+
         internal ModelOperationsCatalog(IHostEnvironment env)
         {
             Contracts.AssertValue(env);
             Environment = env;
+
+            Explainability = new ExplainabilityTransforms(this);
+        }
+
+        public abstract class SubCatalogBase
+        {
+            internal IHostEnvironment Environment { get; }
+
+            protected SubCatalogBase(ModelOperationsCatalog owner)
+            {
+                Environment = owner.Environment;
+            }
+
         }
 
         /// <summary>
@@ -36,6 +51,16 @@ internal ModelOperationsCatalog(IHostEnvironment env)
         /// <returns>The loaded model.</returns>
         public ITransformer Load(Stream stream) => TransformerChain.LoadFrom(Environment, stream);
 
+        /// <summary>
+        /// The catalog of model explainability operations.
+        /// </summary>
+        public sealed class ExplainabilityTransforms : SubCatalogBase
+        {
+            internal ExplainabilityTransforms(ModelOperationsCatalog owner) : base(owner)
+            {
+            }
+        }
+
         /// <summary>
         /// Create a prediction engine for one-time prediction.
         /// </summary>

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

@@ -206,7 +206,7 @@ protected static ICalibrator GetCalibrator(IHostEnvironment env, ModelLoadContex
         }
     }
 
-    public abstract class ValueMapperCalibratedPredictorBase : CalibratedPredictorBase, IValueMapperDist, IFeatureContributionMapper,
+    public abstract class ValueMapperCalibratedPredictorBase : CalibratedPredictorBase, IValueMapperDist, IFeatureContributionMapper, ICalculateFeatureContribution,
         IDistCanSavePfa, IDistCanSaveOnnx
     {
         private readonly IValueMapper _mapper;
@@ -216,6 +216,9 @@ public abstract class ValueMapperCalibratedPredictorBase : CalibratedPredictorBa
         ColumnType IValueMapper.OutputType => _mapper.OutputType;
         ColumnType IValueMapperDist.DistType => NumberType.Float;
         bool ICanSavePfa.CanSavePfa => (_mapper as ICanSavePfa)?.CanSavePfa == true;
+
+        public FeatureContributionCalculator FeatureContributionClaculator => new FeatureContributionCalculator(this);
+
         bool ICanSaveOnnx.CanSaveOnnx(OnnxContext ctx) => (_mapper as ICanSaveOnnx)?.CanSaveOnnx(ctx) == true;
 
         protected ValueMapperCalibratedPredictorBase(IHostEnvironment env, string name, IPredictorProducing<float> predictor, ICalibrator calibrator)