fcc takes transformer instead of model parameters

Author: artidoro

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

@@ -2,6 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 // See the LICENSE file in the project root for more information.
 
+using Microsoft.ML.Calibrators;
 using Microsoft.ML.Data;
 using Microsoft.ML.Trainers;
 using Microsoft.ML.Transforms;
@@ -36,6 +37,34 @@ public static FeatureContributionCalculatingEstimator CalculateFeatureContributi
             int numberOfPositiveContributions = FeatureContributionDefaults.NumberOfPositiveContributions,
             int numberOfNegativeContributions = FeatureContributionDefaults.NumberOfNegativeContributions,
             bool normalize = FeatureContributionDefaults.Normalize)
-            => new FeatureContributionCalculatingEstimator(CatalogUtils.GetEnvironment(catalog), predictionTransformer, numberOfPositiveContributions, numberOfNegativeContributions, normalize);
+            => new FeatureContributionCalculatingEstimator(CatalogUtils.GetEnvironment(catalog), predictionTransformer.Model, numberOfPositiveContributions, numberOfNegativeContributions, predictionTransformer.FeatureColumn, normalize);
+
+        /// <summary>
+        /// Feature Contribution Calculation computes model-specific contribution scores for each feature.
+        /// Note that this functionality is not supported by all the models. See <see cref="FeatureContributionCalculatingTransformer"/> for a list of the suported models.
+        /// </summary>
+        /// <param name="catalog">The model explainability operations catalog.</param>
+        /// <param name="predictionTransformer">A <see cref="ISingleFeaturePredictionTransformer{TModel}"/> that supports Feature Contribution Calculation,
+        /// and which will also be used for scoring.</param>
+        /// <param name="numberOfPositiveContributions">The number of positive contributions to report, sorted from highest magnitude to lowest magnitude.
+        /// Note that if there are fewer features with positive contributions than <paramref name="numberOfPositiveContributions"/>, the rest will be returned as zeros.</param>
+        /// <param name="numberOfNegativeContributions">The number of negative contributions to report, sorted from highest magnitude to lowest magnitude.
+        /// Note that if there are fewer features with negative contributions than <paramref name="numberOfNegativeContributions"/>, the rest will be returned as zeros.</param>
+        /// <param name="normalize">Whether the feature contributions should be normalized to the [-1, 1] interval.</param>
+        /// <example>
+        /// <format type="text/markdown">
+        /// <![CDATA[
+        /// [!code-csharp[FCT](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/FeatureContributionCalculationTransform.cs)]
+        /// ]]>
+        /// </format>
+        /// </example>
+        public static FeatureContributionCalculatingEstimator CalculateFeatureContribution<TModelParameters, TCalibrator>(this TransformsCatalog catalog,
+            ISingleFeaturePredictionTransformer<CalibratedModelParametersBase<TModelParameters, TCalibrator>> predictionTransformer,
+            int numberOfPositiveContributions = FeatureContributionDefaults.NumberOfPositiveContributions,
+            int numberOfNegativeContributions = FeatureContributionDefaults.NumberOfNegativeContributions,
+            bool normalize = FeatureContributionDefaults.Normalize)
+            where TModelParameters : class, ICalculateFeatureContribution
+            where TCalibrator : class, ICalibrator
+            => new FeatureContributionCalculatingEstimator(CatalogUtils.GetEnvironment(catalog), predictionTransformer.Model.SubModel, numberOfPositiveContributions, numberOfNegativeContributions, predictionTransformer.FeatureColumn, normalize);
     }
 }

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

@@ -286,22 +286,24 @@ internal static class Defaults
         /// Note that this functionality is not supported by all the models. See <see cref="FeatureContributionCalculatingTransformer"/> for a list of the suported models.
         /// </summary>
         /// <param name="env">The environment to use.</param>
-        /// <param name="predictionTransformer">A <see cref="ISingleFeaturePredictionTransformer{TModel}"/> that supports Feature Contribution Calculation,
+        /// <param name="model">A <see cref="ISingleFeaturePredictionTransformer{TModel}"/> that supports Feature Contribution Calculation,
         /// and which will also be used for scoring.</param>
         /// <param name="numberOfPositiveContributions">The number of positive contributions to report, sorted from highest magnitude to lowest magnitude.
         /// Note that if there are fewer features with positive contributions than <paramref name="numberOfPositiveContributions"/>, the rest will be returned as zeros.</param>
         /// <param name="numberOfNegativeContributions">The number of negative contributions to report, sorted from highest magnitude to lowest magnitude.
         /// Note that if there are fewer features with negative contributions than <paramref name="numberOfNegativeContributions"/>, the rest will be returned as zeros.</param>
+        /// <param name="featureColumnName">TODO</param>
         /// <param name="normalize">Whether the feature contributions should be normalized to the [-1, 1] interval.</param>
-        internal FeatureContributionCalculatingEstimator(IHostEnvironment env, ISingleFeaturePredictionTransformer<ICalculateFeatureContribution> predictionTransformer,
+        internal FeatureContributionCalculatingEstimator(IHostEnvironment env, ICalculateFeatureContribution model,
             int numberOfPositiveContributions = Defaults.NumberOfPositiveContributions,
             int numberOfNegativeContributions = Defaults.NumberOfNegativeContributions,
+            string featureColumnName = DefaultColumnNames.Features,
             bool normalize = Defaults.Normalize)
             : base(Contracts.CheckRef(env, nameof(env)).Register(nameof(FeatureContributionCalculatingTransformer)),
-                  new FeatureContributionCalculatingTransformer(env, predictionTransformer.Model, predictionTransformer.FeatureColumn, numberOfPositiveContributions, numberOfNegativeContributions, normalize))
+                  new FeatureContributionCalculatingTransformer(env, model, featureColumnName, numberOfPositiveContributions, numberOfNegativeContributions, normalize))
         {
-            _featureColumn = predictionTransformer.FeatureColumn;
-            _predictor = predictionTransformer.Model;
+            _featureColumn = featureColumnName;
+            _predictor = model;
         }
 
         /// <summary>

test/Microsoft.ML.Tests/FeatureContributionTests.cs

@@ -4,6 +4,7 @@
 
 using System;
 using System.IO;
+using Microsoft.ML.Calibrators;
 using Microsoft.ML.Data;
 using Microsoft.ML.Data.IO;
 using Microsoft.ML.Internal.Utilities;
@@ -174,36 +175,62 @@ public void TestGAMBinary()
         }
 
         private void TestFeatureContribution(
-            ITrainerEstimator<ISingleFeaturePredictionTransformer<IPredictor>, IPredictor> trainer,
+            ITrainerEstimator<ISingleFeaturePredictionTransformer<ICalculateFeatureContribution>, ICalculateFeatureContribution> trainer,
             IDataView data,
             string testFile,
             int precision = 6)
         {
             // Train the model.
             var model = trainer.Fit(data);
 
-            // Extract the predictor, check that it supports feature contribution.
-            var fccModel = model as ISingleFeaturePredictionTransformer<ICalculateFeatureContribution>;
-            Assert.NotNull(fccModel);
+            // Calculate feature contributions.
+            var est = ML.Transforms.CalculateFeatureContribution(model, numberOfPositiveContributions: 3, numberOfNegativeContributions: 0)
+                .Append(ML.Transforms.CalculateFeatureContribution(model, numberOfPositiveContributions: 0, numberOfNegativeContributions: 3))
+                .Append(ML.Transforms.CalculateFeatureContribution(model, numberOfPositiveContributions: 1, numberOfNegativeContributions: 1))
+                .Append(ML.Transforms.CalculateFeatureContribution(model, numberOfPositiveContributions: 1, numberOfNegativeContributions: 1, normalize: false));
+
+            TestEstimatorCore(est, data);
+
+            // Verify output.
+            CheckOutput(est, data, testFile, precision);
+            Done();
+        }
+
+        private void TestFeatureContribution<TModelParameters, TCalibrator>(
+            ITrainerEstimator<ISingleFeaturePredictionTransformer<CalibratedModelParametersBase<TModelParameters, TCalibrator>>, CalibratedModelParametersBase<TModelParameters, TCalibrator>> trainer,
+            IDataView data,
+            string testFile,
+            int precision = 6)
+            where TModelParameters : class, ICalculateFeatureContribution
+            where TCalibrator : class, ICalibrator
+        {
+            // Train the model.
+            var model = trainer.Fit(data);
 
             // Calculate feature contributions.
-            var est = ML.Transforms.CalculateFeatureContribution(fccModel, numberOfPositiveContributions: 3, numberOfNegativeContributions: 0)
-                .Append(ML.Transforms.CalculateFeatureContribution(fccModel, numberOfPositiveContributions: 0, numberOfNegativeContributions: 3))
-                .Append(ML.Transforms.CalculateFeatureContribution(fccModel, numberOfPositiveContributions: 1, numberOfNegativeContributions: 1))
-                .Append(ML.Transforms.CalculateFeatureContribution(fccModel, numberOfPositiveContributions: 1, numberOfNegativeContributions: 1, normalize: false));
+            var est = ML.Transforms.CalculateFeatureContribution(model, numberOfPositiveContributions: 3, numberOfNegativeContributions: 0)
+                .Append(ML.Transforms.CalculateFeatureContribution(model, numberOfPositiveContributions: 0, numberOfNegativeContributions: 3))
+                .Append(ML.Transforms.CalculateFeatureContribution(model, numberOfPositiveContributions: 1, numberOfNegativeContributions: 1))
+                .Append(ML.Transforms.CalculateFeatureContribution(model, numberOfPositiveContributions: 1, numberOfNegativeContributions: 1, normalize: false));
 
             TestEstimatorCore(est, data);
+
             // Verify output.
+            CheckOutput(est, data, testFile, precision);
+            Done();
+        }
+
+        private void CheckOutput(IEstimator<ITransformer> estimator, IDataView data, string testFile, int precision = 6)
+        {
             var outputPath = GetOutputPath("FeatureContribution", testFile + ".tsv");
             using (var ch = Env.Start("save"))
             {
                 var saver = new TextSaver(ML, new TextSaver.Arguments { Silent = true, OutputHeader = false });
-                var savedData = ML.Data.TakeRows(est.Fit(data).Transform(data), 4);
+                var savedData = ML.Data.TakeRows(estimator.Fit(data).Transform(data), 4);
                 using (var fs = File.Create(outputPath))
                     DataSaverUtils.SaveDataView(ch, saver, savedData, fs, keepHidden: true);
             }
             CheckEquality("FeatureContribution", testFile + ".tsv", digitsOfPrecision: precision);
-            Done();
         }
 
         /// <summary>