Update the PFI Binary Classification XML Docs (#1792)

Updating Binary Classification XML Docs to the latest version of the PFI documentation text.

Author: rogancarr

src/Microsoft.ML.Transforms/PermutationFeatureImportanceExtensions.cs

@@ -18,7 +18,7 @@ public static class PermutationFeatureImportanceExtensions
         /// <remarks>
         /// <para>
         /// Permutation feature importance (PFI) is a technique to determine the global importance of features in a trained
-        /// machine learning model. PFI is a simple yet powerul technique motivated by Breiman in his Random Forest paper, section 10
+        /// machine learning model. PFI is a simple yet powerful technique motivated by Breiman in his Random Forest paper, section 10
         /// (Breiman. <a href='https://www.stat.berkeley.edu/~breiman/randomforest2001.pdf'>&quot;Random Forests.&quot;</a> Machine Learning, 2001.)
         /// The advantage of the PFI method is that it is model agnostic -- it works with any model that can be
         /// evaluated -- and it can use any dataset, not just the training set, to compute feature importance metrics.
@@ -33,7 +33,7 @@ public static class PermutationFeatureImportanceExtensions
         /// </para>
         /// <para>
         /// In this implementation, PFI computes the change in all possible regression evaluation metrics for each feature, and an
-        /// <code>ImmutableArray</code> of <code>RegressionEvaluator.Result</code> objects is returned. See the sample below for an
+        /// <code>ImmutableArray</code> of <code>RegressionMetrics</code> objects is returned. See the sample below for an
         /// example of working with these results to analyze the feature importance of a model.
         /// </para>
         /// </remarks>
@@ -85,10 +85,37 @@ private static RegressionMetrics RegressionDelta(
         }
 
         /// <summary>
-        /// Permutation Feature Importance is a technique that calculates how much each feature 'matters' to the predictions.
-        /// Namely, how much the model's predictions will change if we randomly permute the values of one feature across the evaluation set.
-        /// If the quality doesn't change much, this feature is not very important. If the quality drops drastically, this was a really important feature.
+        /// Permutation Feature Importance (PFI) for Binary Classification
         /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Permutation feature importance (PFI) is a technique to determine the global importance of features in a trained
+        /// machine learning model. PFI is a simple yet powerful technique motivated by Breiman in his Random Forest paper, section 10
+        /// (Breiman. <a href='https://www.stat.berkeley.edu/~breiman/randomforest2001.pdf'>&quot;Random Forests.&quot;</a> Machine Learning, 2001.)
+        /// The advantage of the PFI method is that it is model agnostic -- it works with any model that can be
+        /// evaluated -- and it can use any dataset, not just the training set, to compute feature importance metrics.
+        /// </para>
+        /// <para>
+        /// PFI works by taking a labeled dataset, choosing a feature, and permuting the values
+        /// for that feature across all the examples, so that each example now has a random value for the feature and
+        /// the original values for all other features. The evalution metric (e.g. AUC or R-squared) is then calculated
+        /// for this modified dataset, and the change in the evaluation metric from the original dataset is computed.
+        /// The larger the change in the evaluation metric, the more important the feature is to the model.
+        /// PFI works by performing this permutation analysis across all the features of a model, one after another.
+        /// </para>
+        /// <para>
+        /// In this implementation, PFI computes the change in all possible binary classification evaluation metrics for each feature, and an
+        /// <code>ImmutableArray</code> of <code>BinaryClassificationMetrics</code> objects is returned. See the sample below for an
+        /// example of working with these results to analyze the feature importance of a model.
+        /// </para>
+        /// </remarks>
+        /// <example>
+        /// <format type="text/markdown">
+        /// <![CDATA[
+        /// [!code-csharp[PFI](~/../docs/samples/doc/samples/Microsoft.ML.Samples/Dynamic/PermutationFeatureImportance.cs)]
+        /// ]]>
+        /// </format>
+        /// </example>
         /// <param name="ctx">The binary classification context.</param>
         /// <param name="model">The model to evaluate.</param>
         /// <param name="data">The evaluation data set.</param>