Link to the concat transform sample in the catalog (#2317)

Adding a link to the concat transform sample; adding a bit more explanation to the concat transform sample.

Author: rogancarr

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

@@ -8,20 +8,15 @@ namespace Microsoft.ML.Samples.Dynamic
 {
     public class ConcatTransformExample
     {
-        class SampleInfertDataWithFeatures
-        {
-            public VBuffer<float> Features { get; set; }
-        }
-
         public static void ConcatTransform()
         {
             // Create a new ML context, for ML.NET operations. It can be used for exception tracking and logging, 
             // as well as the source of randomness.
-            var ml = new MLContext();
+            var mlContext = new MLContext();
 
             // Get a small dataset as an IEnumerable and them read it as ML.NET's data type.
             IEnumerable<SamplesUtils.DatasetUtils.SampleInfertData> data = SamplesUtils.DatasetUtils.GetInfertData();
-            var trainData = ml.Data.ReadFromEnumerable(data);
+            var trainData = mlContext.Data.ReadFromEnumerable(data);
 
             // Preview of the data.
             //
@@ -32,16 +27,20 @@ public static void ConcatTransform()
             // 34.0   1.0   0-5yrs      2.0         4.0       2.0      4.0  ...
             // 35.0   1.0   6-11yrs     1.0         3.0       32.0     5.0  ...
 
-            // A pipeline for concatenating the age, parity and induced columns together in the Features column.
+            // A pipeline for concatenating the Age, Parity and Induced columns together into a vector that will be the Features column.
+            // Concatenation is necessary because learners take **feature vectors** as inputs.
+            //   e.g. var regressionTrainer = mlContext.Regression.Trainers.FastTree(labelColumn: "Label", featureColumn: "Features");
             string outputColumnName = "Features";
-            var pipeline = new ColumnConcatenatingEstimator(ml, outputColumnName, new[] { "Age", "Parity", "Induced"});
+            var pipeline = mlContext.Transforms.Concatenate(outputColumnName, new[] { "Age", "Parity", "Induced" });
 
             // The transformed data.
             var transformedData = pipeline.Fit(trainData).Transform(trainData);
 
-            // Getting the data of the newly created column as an IEnumerable of SampleInfertDataWithFeatures.
-            var featuresColumn = ml.CreateEnumerable<SampleInfertDataWithFeatures>(transformedData, reuseRowObject: false);
+            // Now let's take a look at what this concatenation did.
+            // We can extract the newly created column as an IEnumerable of SampleInfertDataWithFeatures, the class we define above.
+            var featuresColumn = mlContext.CreateEnumerable<SampleInfertDataWithFeatures>(transformedData, reuseRowObject: false);
 
+            // And we can write out a few rows
             Console.WriteLine($"{outputColumnName} column obtained post-transformation.");
             foreach (var featureRow in featuresColumn)
             {
@@ -50,6 +49,7 @@ public static void ConcatTransform()
                 Console.WriteLine("");
             }
 
+            // Expected output:
             // Features column obtained post-transformation.
             //
             // 26 6 1
@@ -58,5 +58,10 @@ public static void ConcatTransform()
             // 34 4 2
             // 35 3 1
         }
+
+        private class SampleInfertDataWithFeatures
+        {
+            public VBuffer<float> Features { get; set; }
+        }
     }
 }

docs/samples/Microsoft.ML.Samples/Program.cs

@@ -6,7 +6,7 @@ internal static class Program
     {
         static void Main(string[] args)
         {
-            FeatureContributionCalculationTransform_RegressionExample.FeatureContributionCalculationTransform_Regression();
+            ConcatTransformExample.ConcatTransform();
         }
     }
 }

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

@@ -36,6 +36,13 @@ public static ColumnCopyingEstimator CopyColumns(this TransformsCatalog catalog,
         /// <param name="catalog">The transform's catalog.</param>
         /// <param name="outputColumnName">Name of the column resulting from the transformation of <paramref name="inputColumnNames"/>.</param>
         /// <param name="inputColumnNames">Name of the columns to transform.</param>
+        /// <example>
+        /// <format type="text/markdown">
+        /// <![CDATA[
+        /// [!code-csharp[Concat](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/ConcatTransform.cs)]
+        /// ]]>
+        /// </format>
+        /// </example>
         public static ColumnConcatenatingEstimator Concatenate(this TransformsCatalog catalog, string outputColumnName, params string[] inputColumnNames)
             => new ColumnConcatenatingEstimator(CatalogUtils.GetEnvironment(catalog), outputColumnName, inputColumnNames);