Clean FeatureContributionCalculation and PermutationFeatureImportance (#2966)

Author: artidoro

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

@@ -35,12 +35,12 @@ public static void Example()
             // Create a Feature Contribution Calculator
             // Calculate the feature contributions for all features given trained model parameters
             // And don't normalize the contribution scores
-            var featureContributionCalculator = mlContext.Model.Explainability.FeatureContributionCalculation(model.Model, model.FeatureColumnName, numPositiveContributions: 11, normalize: false);
+            var featureContributionCalculator = mlContext.Transforms.CalculateFeatureContribution(model, numberOfPositiveContributions: 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.FeatureColumnName, numPositiveContributions: 11)
+            var pipeline = mlContext.Transforms.CalculateFeatureContribution(model, numberOfPositiveContributions: 11)
                 .Append(mlContext.Regression.Trainers.Ols(featureColumnName: "FeatureContributions"));
             var outData = featureContributionCalculator.Fit(scoredData).Transform(scoredData);
 

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

@@ -31,7 +31,7 @@ public static void Example()
             // Compute the permutation metrics using the properly normalized data.
             var transformedData = model.Transform(data);
             var permutationMetrics = mlContext.Regression.PermutationFeatureImportance(
-                linearPredictor, transformedData, label: labelName, features: "Features", permutationCount: 3);
+                linearPredictor, transformedData, labelColumnName: labelName, permutationCount: 3);
 
             // Now let's look at which features are most important to the model overall
             // Get the feature indices sorted by their impact on R-Squared

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

@@ -35,7 +35,7 @@ public static void Example()
             // Compute the permutation metrics using the properly normalized data.
             var transformedData = model.Transform(data);
             var permutationMetrics = mlContext.BinaryClassification.PermutationFeatureImportance(
-                linearPredictor, transformedData, label: labelName, features: "Features", permutationCount: 3);
+                linearPredictor, transformedData, labelColumnName: labelName, permutationCount: 3);
 
             // Now let's look at which features are most important to the model overall.
             // Get the feature indices sorted by their impact on AreaUnderRocCurve.

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

@@ -22,14 +22,10 @@ public sealed class ModelOperationsCatalog : IInternalCatalog
         IHostEnvironment IInternalCatalog.Environment => _env;
         private readonly IHostEnvironment _env;
 
-        public ExplainabilityTransforms Explainability { get; }
-
         internal ModelOperationsCatalog(IHostEnvironment env)
         {
             Contracts.AssertValue(env);
             _env = env;
-
-            Explainability = new ExplainabilityTransforms(this);
         }
 
         /// <summary>
@@ -228,20 +224,6 @@ public ITransformer LoadWithDataLoader(Stream stream, out IDataLoader<IMultiStre
             return new TransformerChain<ITransformer>();
         }
 
-        /// <summary>
-        /// The catalog of model explainability operations.
-        /// </summary>
-        public sealed class ExplainabilityTransforms : IInternalCatalog
-        {
-            IHostEnvironment IInternalCatalog.Environment => _env;
-            private readonly IHostEnvironment _env;
-
-            internal ExplainabilityTransforms(ModelOperationsCatalog owner)
-            {
-                _env = owner._env;
-            }
-        }
-
         /// <summary>
         /// Create a prediction engine for one-time prediction.
         /// </summary>

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;
@@ -17,19 +18,53 @@ public static class ExplainabilityCatalog
         /// 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="modelParameters">Trained model parameters that support Feature Contribution Calculation and which will be used for scoring.</param>
-        /// <param name="featureColumnName">The name of the feature column that will be used as input.</param>
-        /// <param name="numPositiveContributions">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="numPositiveContributions"/>, the rest will be returned as zeros.</param>
-        /// <param name="numNegativeContributions">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="numNegativeContributions"/>, the rest will be returned as zeros.</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>
-        public static FeatureContributionCalculatingEstimator FeatureContributionCalculation(this ModelOperationsCatalog.ExplainabilityTransforms catalog,
-            ICalculateFeatureContribution modelParameters,
-            string featureColumnName = DefaultColumnNames.Features,
-            int numPositiveContributions = FeatureContributionDefaults.NumPositiveContributions,
-            int numNegativeContributions = FeatureContributionDefaults.NumNegativeContributions,
+        /// <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(this TransformsCatalog catalog,
+            ISingleFeaturePredictionTransformer<ICalculateFeatureContribution> predictionTransformer,
+            int numberOfPositiveContributions = FeatureContributionDefaults.NumberOfPositiveContributions,
+            int numberOfNegativeContributions = FeatureContributionDefaults.NumberOfNegativeContributions,
             bool normalize = FeatureContributionDefaults.Normalize)
-            => new FeatureContributionCalculatingEstimator(CatalogUtils.GetEnvironment(catalog), modelParameters, featureColumnName, numPositiveContributions, numNegativeContributions, normalize);
+            => new FeatureContributionCalculatingEstimator(CatalogUtils.GetEnvironment(catalog), predictionTransformer.Model, numberOfPositiveContributions, numberOfNegativeContributions, predictionTransformer.FeatureColumnName, 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.FeatureColumnName, normalize);
     }
 }