Projection documentation

docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/ApproximatedKernelMap.cs

@@ -0,0 +1,52 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using Microsoft.ML;
+using Microsoft.ML.Data;
+using Microsoft.ML.Transforms;
+
+namespace Samples.Dynamic
+{
+    public static class ApproximatedKernelMap
+    {
+        // Transform feature vector to another non-linear space. See https://people.eecs.berkeley.edu/~brecht/papers/07.rah.rec.nips.pdf.
+        public static void Example()
+        {
+            // 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 mlContext = new MLContext();
+            var samples = new List<DataPoint>()
+            {
+                new DataPoint(){ Features = new float[7] { 1, 1, 0, 0, 1, 0, 1} },
+                new DataPoint(){ Features = new float[7] { 0, 0, 1, 0, 0, 1, 1} },
+                new DataPoint(){ Features = new float[7] {-1, 1, 0,-1,-1, 0,-1} },
+                new DataPoint(){ Features = new float[7] { 0,-1, 0, 1, 0,-1,-1} }
+            };
+            // Convert training data to IDataView, the general data type used in ML.NET.
+            var data = mlContext.Data.LoadFromEnumerable(samples);
+            // ApproximatedKernel map takes data and maps it's to a random low-dimensional space.
+            var approximation = mlContext.Transforms.ApproximatedKernelMap("Features", rank: 4, generator: new GaussianKernel(gamma: 0.7f), seed: 1);
+
+            // Now we can transform the data and look at the output to confirm the behavior of the estimator.
+            // This operation doesn't actually evaluate data until we read the data below.
+            var tansformer = approximation.Fit(data);
+            var transformedData = tansformer.Transform(data);
+
+            var column = transformedData.GetColumn<float[]>("Features").ToArray();
+            foreach (var row in column)
+                Console.WriteLine(string.Join(", ", row.Select(x => x.ToString("f4"))));
+            // Expected output:
+            // -0.0119, 0.5867, 0.4942,  0.7041
+            //  0.4720, 0.5639, 0.4346,  0.2671
+            // -0.2243, 0.7071, 0.7053, -0.1681
+            //  0.0846, 0.5836, 0.6575,  0.0581
+        }
+
+        private class DataPoint
+        {
+            [VectorType(7)]
+            public float[] Features { get; set; }
+        }
+
+    }
+}

docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/NormalizeGlobalContrast.cs

@@ -0,0 +1,48 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using Microsoft.ML;
+using Microsoft.ML.Data;
+
+namespace Samples.Dynamic
+{
+    class NormalizeGlobalContrast
+    {
+        public static void Example()
+        {
+            // 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 mlContext = new MLContext();
+            var samples = new List<DataPoint>()
+            {
+                new DataPoint(){ Features = new float[4] { 1, 1, 0, 0} },
+                new DataPoint(){ Features = new float[4] { 2, 2, 0, 0} },
+                new DataPoint(){ Features = new float[4] { 1, 0, 1, 0} },
+                new DataPoint(){ Features = new float[4] { 0, 1, 0, 1} }
+            };
+            // Convert training data to IDataView, the general data type used in ML.NET.
+            var data = mlContext.Data.LoadFromEnumerable(samples);
+            var approximation = mlContext.Transforms.NormalizeGlobalContrast("Features", ensureZeroMean: false, scale:2, ensureUnitStandardDeviation:true);
+
+            // Now we can transform the data and look at the output to confirm the behavior of the estimator.
+            // This operation doesn't actually evaluate data until we read the data below.
+            var tansformer = approximation.Fit(data);
+            var transformedData = tansformer.Transform(data);
+
+            var column = transformedData.GetColumn<float[]>("Features").ToArray();
+            foreach (var row in column)
+                Console.WriteLine(string.Join(", ", row.Select(x => x.ToString("f4"))));
+            // Expected output:
+            //  2.0000, 2.0000,-2.0000,-2.0000
+            //  2.0000, 2.0000,-2.0000,-2.0000
+            //  2.0000,-2.0000, 2.0000,-2.0000
+            //- 2.0000, 2.0000,-2.0000, 2.0000
+        }
+
+        private class DataPoint
+        {
+            [VectorType(4)]
+            public float[] Features { get; set; }
+        }
+    }
+}

docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/NormalizeLpNorm.cs

@@ -0,0 +1,49 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using Microsoft.ML;
+using Microsoft.ML.Data;
+using Microsoft.ML.Transforms;
+
+namespace Samples.Dynamic
+{
+    class NormalizeLpNorm
+    {
+        public static void Example()
+        {
+            // 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 mlContext = new MLContext();
+            var samples = new List<DataPoint>()
+            {
+                new DataPoint(){ Features = new float[4] { 1, 1, 0, 0} },
+                new DataPoint(){ Features = new float[4] { 2, 2, 0, 0} },
+                new DataPoint(){ Features = new float[4] { 1, 0, 1, 0} },
+                new DataPoint(){ Features = new float[4] { 0, 1, 0, 1} }
+            };
+            // Convert training data to IDataView, the general data type used in ML.NET.
+            var data = mlContext.Data.LoadFromEnumerable(samples);
+            var approximation = mlContext.Transforms.NormalizeLpNorm("Features", norm: LpNormNormalizingEstimatorBase.NormFunction.L1, ensureZeroMean: true);
+
+            // Now we can transform the data and look at the output to confirm the behavior of the estimator.
+            // This operation doesn't actually evaluate data until we read the data below.
+            var tansformer = approximation.Fit(data);
+            var transformedData = tansformer.Transform(data);
+
+            var column = transformedData.GetColumn<float[]>("Features").ToArray();
+            foreach (var row in column)
+                Console.WriteLine(string.Join(", ", row.Select(x => x.ToString("f4"))));
+            // Expected output:
+            //  0.2500,  0.2500, -0.2500, -0.2500
+            //  0.2500,  0.2500, -0.2500, -0.2500
+            //  0.2500, -0.2500,  0.2500, -0.2500
+            // -0.2500,  0.2500, -0.2500,  0.2500
+        }
+
+        private class DataPoint
+        {
+            [VectorType(4)]
+            public float[] Features { get; set; }
+        }
+    }
+}

src/Microsoft.ML.Transforms/FourierDistributionSampler.cs

@@ -203,7 +203,7 @@ internal sealed class Options : IComponentFactory<KernelBase>
         /// <summary>
         /// Create a new instance of a LaplacianKernel.
         /// </summary>
-        /// <param name="a">The coefficient in the exponent of the kernel function</param>
+        /// <param name="a">The coefficient in the exponent of the kernel function.</param>
         public LaplacianKernel(float a = 1)
         {
             Contracts.CheckParam(a > 0, nameof(a));

src/Microsoft.ML.Transforms/KernelCatalog.cs

@@ -26,7 +26,7 @@ public static class KernelExpansionCatalog
         /// <example>
         /// <format type="text/markdown">
         /// <![CDATA[
-        /// [!code-csharp[CreateRandomFourierFeatures](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/ProjectionTransforms.cs?range=1-6,12-112)]
+        /// [!code-csharp[ApproximatedKernelMap](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/ApproximatedKernelMap.cs)]
         /// ]]>
         /// </format>
         /// </example>

src/Microsoft.ML.Transforms/NormalizerCatalog.cs

@@ -246,10 +246,15 @@ internal static NormalizingEstimator Normalize(this TransformsCatalog catalog,
         /// <param name="inputColumnName">Name of column to transform. If set to <see langword="null"/>, the value of the <paramref name="outputColumnName"/> will be used as source.</param>
         /// <param name="norm">Type of norm to use to normalize each sample. The indicated norm of the resulted vector will be normalized to one.</param>
         /// <param name="ensureZeroMean">If <see langword="true"/>, subtract mean from each value before normalizing and use the raw input otherwise.</param>
+        /// <remarks>
+        /// This transform performs the following operation on a each row X:  Y = (X - M(X)) / D(X)
+        /// where M(X) is scalar value of mean for all elements in the current row if <paramref name="ensureZeroMean"/>set to <see langword="true"/> or <value>0</value> othewise
+        /// and D(X) is scalar value of selected <paramref name="norm"/>.
+        /// </remarks>
         /// <example>
         /// <format type="text/markdown">
         /// <![CDATA[
-        /// [!code-csharp[LpNormalize](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/ProjectionTransforms.cs?range=1-6,12-112)]
+        /// [!code-csharp[NormalizeLpNorm](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/NormalizeLpNorm.cs)]
         /// ]]>
         /// </format>
         /// </example>
@@ -276,10 +281,16 @@ internal static LpNormNormalizingEstimator NormalizeLpNorm(this TransformsCatalo
         /// <param name="ensureZeroMean">If <see langword="true"/>, subtract mean from each value before normalizing and use the raw input otherwise.</param>
         /// <param name="ensureUnitStandardDeviation">If <see langword="true"/>, resulted vector's standard deviation would be one. Otherwise, resulted vector's L2-norm would be one.</param>
         /// <param name="scale">Scale features by this value.</param>
+        /// <remarks>
+        /// This transform performs the following operation on a row X: Y = scale * (X - M(X)) / D(X)
+        /// where M(X) is scalar value of mean for all elements in the current row if <paramref name="ensureZeroMean"/>set to <see langword="true"/> or <value>0</value> othewise
+        /// D(X) is scalar value of standard deviation for row if <paramref name="ensureUnitStandardDeviation"/> set to <see langword="true"/> or
+        /// L2 norm of this row vector if <paramref name="ensureUnitStandardDeviation"/> set to <see langword="false"/> and scale is <paramref name="scale"/>.
+        /// </remarks>
         /// <example>
         /// <format type="text/markdown">
         /// <![CDATA[
-        /// [!code-csharp[GlobalContrastNormalize](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/ProjectionTransforms.cs?range=1-6,12-112)]
+        /// [!code-csharp[NormalizeGlobalContrast](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/NormalizeGlobalContrast.cs)]
         /// ]]>
         /// </format>
         /// </example>