review comments

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.Transforms.CalculateFeatureContribution(model.Model, model.FeatureColumn, numberOfPositiveContributions: 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.Transforms.CalculateFeatureContribution(model.Model, model.FeatureColumn, numberOfPositiveContributions: 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, labelColumnName: labelName, featureColumnName: "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, labelColumnName: labelName, featureColumnName: "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/Transforms/ExplainabilityCatalog.cs

@@ -17,8 +17,8 @@ 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="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.
@@ -32,11 +32,10 @@ public static class ExplainabilityCatalog
         /// </format>
         /// </example>
         public static FeatureContributionCalculatingEstimator CalculateFeatureContribution(this TransformsCatalog catalog,
-            ICalculateFeatureContribution modelParameters,
-            string featureColumnName = DefaultColumnNames.Features,
+            ISingleFeaturePredictionTransformer<ICalculateFeatureContribution> predictionTransformer,
             int numberOfPositiveContributions = FeatureContributionDefaults.NumberOfPositiveContributions,
             int numberOfNegativeContributions = FeatureContributionDefaults.NumberOfNegativeContributions,
             bool normalize = FeatureContributionDefaults.Normalize)
-            => new FeatureContributionCalculatingEstimator(CatalogUtils.GetEnvironment(catalog), modelParameters, featureColumnName, numberOfPositiveContributions, numberOfNegativeContributions, normalize);
+            => new FeatureContributionCalculatingEstimator(CatalogUtils.GetEnvironment(catalog), predictionTransformer, numberOfPositiveContributions, numberOfNegativeContributions, normalize);
     }
 }

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

@@ -286,23 +286,22 @@ 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="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="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>
-        internal FeatureContributionCalculatingEstimator(IHostEnvironment env, ICalculateFeatureContribution modelParameters,
-            string featureColumnName = DefaultColumnNames.Features,
+        internal FeatureContributionCalculatingEstimator(IHostEnvironment env, ISingleFeaturePredictionTransformer<ICalculateFeatureContribution> predictionTransformer,
             int numberOfPositiveContributions = Defaults.NumberOfPositiveContributions,
             int numberOfNegativeContributions = Defaults.NumberOfNegativeContributions,
             bool normalize = Defaults.Normalize)
             : base(Contracts.CheckRef(env, nameof(env)).Register(nameof(FeatureContributionCalculatingTransformer)),
-                  new FeatureContributionCalculatingTransformer(env, modelParameters, featureColumnName, numberOfPositiveContributions, numberOfNegativeContributions, normalize))
+                  new FeatureContributionCalculatingTransformer(env, predictionTransformer.Model, predictionTransformer.FeatureColumn, numberOfPositiveContributions, numberOfNegativeContributions, normalize))
         {
-            _featureColumn = featureColumnName;
-            _predictor = modelParameters;
+            _featureColumn = predictionTransformer.FeatureColumn;
+            _predictor = predictionTransformer.Model;
         }
 
         /// <summary>

src/Microsoft.ML.Transforms/PermutationFeatureImportanceExtensions.cs

@@ -46,33 +46,31 @@ public static class PermutationFeatureImportanceExtensions
         /// </format>
         /// </example>
         /// <param name="catalog">The regression catalog.</param>
-        /// <param name="model">The model on which to evaluate feature importance.</param>
+        /// <param name="predictionTransformer">The model on which to evaluate feature importance.</param>
         /// <param name="data">The evaluation data set.</param>
         /// <param name="labelColumnName">Label column name.</param>
-        /// <param name="featureColumnName">Feature column name.</param>
         /// <param name="useFeatureWeightFilter">Use features weight to pre-filter features.</param>
         /// <param name="numberOfExamplesToUse">Limit the number of examples to evaluate on. <cref langword="null"/> means up to ~2 bln examples from <paramref param="data"/> will be used.</param>
         /// <param name="permutationCount">The number of permutations to perform.</param>
         /// <returns>Array of per-feature 'contributions' to the score.</returns>
         public static ImmutableArray<RegressionMetricsStatistics>
             PermutationFeatureImportance<TModel>(
                 this RegressionCatalog catalog,
-                IPredictionTransformer<TModel> model,
+                ISingleFeaturePredictionTransformer<TModel> predictionTransformer,
                 IDataView data,
                 string labelColumnName = DefaultColumnNames.Label,
-                string featureColumnName = DefaultColumnNames.Features,
                 bool useFeatureWeightFilter = false,
                 int? numberOfExamplesToUse = null,
                 int permutationCount = 1)
         {
             return PermutationFeatureImportance<TModel, RegressionMetrics, RegressionMetricsStatistics>.GetImportanceMetricsMatrix(
                             catalog.GetEnvironment(),
-                            model,
+                            predictionTransformer,
                             data,
                             () => new RegressionMetricsStatistics(),
                             idv => catalog.Evaluate(idv, labelColumnName),
                             RegressionDelta,
-                            featureColumnName,
+                            predictionTransformer.FeatureColumn,
                             permutationCount,
                             useFeatureWeightFilter,
                             numberOfExamplesToUse);
@@ -124,33 +122,31 @@ private static RegressionMetrics RegressionDelta(
         /// </format>
         /// </example>
         /// <param name="catalog">The binary classification catalog.</param>
-        /// <param name="model">The model on which to evaluate feature importance.</param>
+        /// <param name="predictionTransformer">The model on which to evaluate feature importance.</param>
         /// <param name="data">The evaluation data set.</param>
         /// <param name="labelColumnName">Label column name.</param>
-        /// <param name="featureColumnName">Feature column name.</param>
         /// <param name="useFeatureWeightFilter">Use features weight to pre-filter features.</param>
         /// <param name="numberOfExamplesToUse">Limit the number of examples to evaluate on. <cref langword="null"/> means up to ~2 bln examples from <paramref param="data"/> will be used.</param>
         /// <param name="permutationCount">The number of permutations to perform.</param>
         /// <returns>Array of per-feature 'contributions' to the score.</returns>
         public static ImmutableArray<BinaryClassificationMetricsStatistics>
             PermutationFeatureImportance<TModel>(
                 this BinaryClassificationCatalog catalog,
-                IPredictionTransformer<TModel> model,
+                ISingleFeaturePredictionTransformer<TModel> predictionTransformer,
                 IDataView data,
                 string labelColumnName = DefaultColumnNames.Label,
-                string featureColumnName = DefaultColumnNames.Features,
                 bool useFeatureWeightFilter = false,
                 int? numberOfExamplesToUse = null,
                 int permutationCount = 1)
         {
             return PermutationFeatureImportance<TModel, BinaryClassificationMetrics, BinaryClassificationMetricsStatistics>.GetImportanceMetricsMatrix(
                             catalog.GetEnvironment(),
-                            model,
+                            predictionTransformer,
                             data,
                             () => new BinaryClassificationMetricsStatistics(),
                             idv => catalog.Evaluate(idv, labelColumnName),
                             BinaryClassifierDelta,
-                            featureColumnName,
+                            predictionTransformer.FeatureColumn,
                             permutationCount,
                             useFeatureWeightFilter,
                             numberOfExamplesToUse);
@@ -199,33 +195,31 @@ private static BinaryClassificationMetrics BinaryClassifierDelta(
         /// </para>
         /// </remarks>
         /// <param name="catalog">The clustering catalog.</param>
-        /// <param name="model">The model on which to evaluate feature importance.</param>
+        /// <param name="predictionTransformer">The model on which to evaluate feature importance.</param>
         /// <param name="data">The evaluation data set.</param>
         /// <param name="labelColumnName">Label column name.</param>
-        /// <param name="featureColumnName">Feature column name.</param>
         /// <param name="useFeatureWeightFilter">Use features weight to pre-filter features.</param>
         /// <param name="numberOfExamplesToUse">Limit the number of examples to evaluate on. <cref langword="null"/> means up to ~2 bln examples from <paramref param="data"/> will be used.</param>
         /// <param name="permutationCount">The number of permutations to perform.</param>
         /// <returns>Array of per-feature 'contributions' to the score.</returns>
         public static ImmutableArray<MulticlassClassificationMetricsStatistics>
             PermutationFeatureImportance<TModel>(
                 this MulticlassClassificationCatalog catalog,
-                IPredictionTransformer<TModel> model,
+                ISingleFeaturePredictionTransformer<TModel> predictionTransformer,
                 IDataView data,
                 string labelColumnName = DefaultColumnNames.Label,
-                string featureColumnName = DefaultColumnNames.Features,
                 bool useFeatureWeightFilter = false,
                 int? numberOfExamplesToUse = null,
                 int permutationCount = 1)
         {
             return PermutationFeatureImportance<TModel, MulticlassClassificationMetrics, MulticlassClassificationMetricsStatistics>.GetImportanceMetricsMatrix(
                             catalog.GetEnvironment(),
-                            model,
+                            predictionTransformer,
                             data,
                             () => new MulticlassClassificationMetricsStatistics(),
                             idv => catalog.Evaluate(idv, labelColumnName),
                             MulticlassClassificationDelta,
-                            featureColumnName,
+                            predictionTransformer.FeatureColumn,
                             permutationCount,
                             useFeatureWeightFilter,
                             numberOfExamplesToUse);
@@ -279,35 +273,33 @@ private static MulticlassClassificationMetrics MulticlassClassificationDelta(
         /// </para>
         /// </remarks>
         /// <param name="catalog">The clustering catalog.</param>
-        /// <param name="model">The model on which to evaluate feature importance.</param>
+        /// <param name="predictionTransformer">The model on which to evaluate feature importance.</param>
         /// <param name="data">The evaluation data set.</param>
         /// <param name="labelColumnName">Label column name.</param>
         /// <param name="rowGroupColumnName">GroupId column name</param>
-        /// <param name="featureColumnName">Feature column name.</param>
         /// <param name="useFeatureWeightFilter">Use features weight to pre-filter features.</param>
         /// <param name="numberOfExamplesToUse">Limit the number of examples to evaluate on. <cref langword="null"/> means up to ~2 bln examples from <paramref param="data"/> will be used.</param>
         /// <param name="permutationCount">The number of permutations to perform.</param>
         /// <returns>Array of per-feature 'contributions' to the score.</returns>
         public static ImmutableArray<RankingMetricsStatistics>
             PermutationFeatureImportance<TModel>(
                 this RankingCatalog catalog,
-                IPredictionTransformer<TModel> model,
+                ISingleFeaturePredictionTransformer<TModel> predictionTransformer,
                 IDataView data,
                 string labelColumnName = DefaultColumnNames.Label,
                 string rowGroupColumnName = DefaultColumnNames.GroupId,
-                string featureColumnName = DefaultColumnNames.Features,
                 bool useFeatureWeightFilter = false,
                 int? numberOfExamplesToUse = null,
                 int permutationCount = 1)
         {
             return PermutationFeatureImportance<TModel, RankingMetrics, RankingMetricsStatistics>.GetImportanceMetricsMatrix(
                             catalog.GetEnvironment(),
-                            model,
+                            predictionTransformer,
                             data,
                             () => new RankingMetricsStatistics(),
                             idv => catalog.Evaluate(idv, labelColumnName, rowGroupColumnName),
                             RankingDelta,
-                            featureColumnName,
+                            predictionTransformer.FeatureColumn,
                             permutationCount,
                             useFeatureWeightFilter,
                             numberOfExamplesToUse);