XML documentation for GAM binary classifier trainer.

docs/api-reference/algo-details-gam.md

@@ -0,0 +1,18 @@
+### Training Algorithm Details
+Generalized Additive Models, or GAMs, model the data as a set of linearly
+independent features similar to a linear model. For each feature, the GAM
+trainer learns a non-linear function, called a "shape function", that computes
+the response as a function of the feature's value. (In contrast, a linear model
+fits a linear response (e.g. a line) to each feature.) To score an input, the
+outputs of all the shape functions are summed and the score is the total value.
+
+This GAM trainer is implemented using shallow gradient boosted trees (e.g. tree
+stumps) to learn nonparametric shape functions, and is based on the method
+described in Lou, Caruana, and Gehrke. ["Intelligible Models for Classification
+and Regression."](http://www.cs.cornell.edu/~yinlou/papers/lou-kdd12.pdf)
+KDD'12, Beijing, China. 2012. After training, an intercept is added to represent
+the average prediction over the training set, and the shape functions are
+normalized to represent the deviation from the average prediction. This results
+in models that are easily interpreted simply by inspecting the intercept and the
+shape functions. See the sample below for an example of how to train a GAM model
+and inspect and interpret the results.

src/Microsoft.ML.FastTree/GamClassification.cs

@@ -29,14 +29,36 @@ namespace Microsoft.ML.Trainers.FastTree
     /// <summary>
     /// The <see cref="IEstimator{TTransformer}"/> for training a binary classification model with generalized additive models (GAM).
     /// </summary>
-    /// <include file='doc.xml' path='doc/members/member[@name="GAM_remarks"]/*' />
+    /// <remarks>
+    /// <format type="text/markdown"><![CDATA[
+    /// To create this trainer, use [Gam](xref:Microsoft.ML.TreeExtensions.Gam(Microsoft.ML.BinaryClassificationCatalog.BinaryClassificationTrainers,System.String,System.String,System.String,System.Int32,System.Int32,System.Double))
+    /// or [Gam(Options)](xref:Microsoft.ML.TreeExtensions.Gam(Microsoft.ML.BinaryClassificationCatalog.BinaryClassificationTrainers,Microsoft.ML.Trainers.FastTree.GamBinaryTrainer.Options)).
+    ///
+    /// [!include[io](~/../docs/samples/docs/api-reference/io-columns-binary-classification.md)]
+    ///
+    /// ### Trainer Characteristics
+    /// |  |  |
+    /// | -- | -- |
+    /// | Machine learning task | Binary classification |
+    /// | Is normalization required? | No |
+    /// | Is caching required? | No |
+    /// | Required NuGet in addition to Microsoft.ML | Microsoft.ML.FastTree |
+    ///
+    /// [!include[algorithm](~/../docs/samples/docs/api-reference/algo-details-gam.md)]
+    /// ]]>
+    /// </format>
+    /// </remarks>
+    /// <seealso cref="TreeExtensions.Gam(BinaryClassificationCatalog.BinaryClassificationTrainers, string, string, string, int, int, double)"/>
+    /// <seealso cref="TreeExtensions.Gam(BinaryClassificationCatalog.BinaryClassificationTrainers, GamBinaryTrainer.Options)"/>
+    /// <seealso cref="Options"/>
     public sealed class GamBinaryTrainer :
         GamTrainerBase<GamBinaryTrainer.Options,
         BinaryPredictionTransformer<CalibratedModelParametersBase<GamBinaryModelParameters, PlattCalibrator>>,
         CalibratedModelParametersBase<GamBinaryModelParameters, PlattCalibrator>>
     {
         /// <summary>
-        /// Options for the <see cref="GamBinaryTrainer"/>.
+        /// Options for the <see cref="GamBinaryTrainer"/> as used in
+        /// [Gam(Options)](xref:Microsoft.ML.TreeExtensions.Gam(Microsoft.ML.BinaryClassificationCatalog.BinaryClassificationTrainers,Microsoft.ML.Trainers.FastTree.GamBinaryTrainer.Options)).
         /// </summary>
         public sealed class Options : OptionsBase
         {

src/Microsoft.ML.FastTree/TreeTrainersCatalog.cs

@@ -178,11 +178,11 @@ public static FastTreeRankingTrainer FastTree(this RankingCatalog.RankingTrainer
         }
 
         /// <summary>
-        /// Predict a target using generalized additive models (GAM) trained with the <see cref="GamBinaryTrainer"/>.
+        /// Create <see cref="GamBinaryTrainer"/>, which predicts a target using generalized additive models (GAM).
         /// </summary>
         /// <param name="catalog">The <see cref="BinaryClassificationCatalog"/>.</param>
-        /// <param name="labelColumnName">The name of the label column.</param>
-        /// <param name="featureColumnName">The name of the feature column.</param>
+        /// <param name="labelColumnName">The name of the label column. The column data must be <see cref="System.Boolean"/>.</param>
+        /// <param name="featureColumnName">The name of the feature column. The column data must be a known-sized vector of <see cref="System.Single"/>.</param>
         /// <param name="exampleWeightColumnName">The name of the example weight column (optional).</param>
         /// <param name="numberOfIterations">The number of iterations to use in learning the features.</param>
         /// <param name="maximumBinCountPerFeature">The maximum number of bins to use to approximate features.</param>
@@ -208,7 +208,7 @@ public static GamBinaryTrainer Gam(this BinaryClassificationCatalog.BinaryClassi
         }
 
         /// <summary>
-        /// Predict a target using generalized additive models (GAM) trained with the <see cref="GamBinaryTrainer"/>.
+        /// Create <see cref="GamBinaryTrainer"/> using advanced options, which predicts a target using generalized additive models (GAM).
         /// </summary>
         /// <param name="catalog">The <see cref="BinaryClassificationCatalog"/>.</param>
         /// <param name="options">Trainer options.</param>