...updating from feedback

Author: singlis

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

@@ -14,12 +14,12 @@ class SampleInfertDataWithFeatures
             public string EducationCategory = default;
         }
 
-        /// This example demonstrates the use of the ValueMappingEstimator by mapping string-to-string values. The ValueMappingEstimator uses
-        /// level of education as keys to a respective string label which is the value.
-        /// The mapping looks like the following:
-        ///  0-5yrs  -> Cat1
-        ///  6-11yrs -> Cat2
-        ///  12+yrs  -> Cat3
+        /// This example demonstrates the use of the ValueMappingEstimator by mapping string-to-string values. This is useful
+        /// to map strings to a grouping. In this example, the Education data maps to the groups Undergraduate and Postgraduate:
+        ///   0-5yrs  -> Undergraduate 
+        ///   6-11yrs -> Postgraduate
+        ///   12+yrs  -> Postgraduate
+        /// Its possible to have multiple keys map to the same value.
         public static void Run()
         {
             // Create a new ML context, for ML.NET operations. It can be used for exception tracking and logging, 
@@ -39,8 +39,8 @@ public static void Run()
             // 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  ...
 
-            // Creating a list of keys based on the Education values from the dataset
-            // These lists are created by hand for the demonstration, but the ValueMappingEstimator does take an IEnumerable.
+            // If the list of keys and values are known, they can be passed to the API. The ValueMappingEstimator can also get the mapping through an IDataView
+            // Creating a list of keys based on the Education values from the dataset. 
             var educationKeys = new List<string>()
             {
                 "0-5yrs",
@@ -51,9 +51,9 @@ public static void Run()
             // Creating a list of associated values that will map respectively to each educationKey
             var educationValues = new List<string>()
             {
-                "Cat1",
-                "Cat2",
-                "Cat3"
+                "Undergraduate",
+                "Postgraduate",
+                "Postgraduate"
             };
 
             // Constructs the ValueMappingEstimator making the ML.net pipeline
@@ -75,11 +75,11 @@ public static void Run()
             // Features column obtained post-transformation.
             //
             // Age Education    EducationCategory
-            // 26  0-5yrs       Cat1
-            // 42  0-5yrs       Cat1
-            // 39  12+yrs       Cat3
-            // 34  0-5yrs       Cat1
-            // 35  6-11yrs      Cat2
+            // 26  0-5yrs       Undergraduate 
+            // 42  0-5yrs       Undergraudate 
+            // 39  12+yrs       Postgraduate 
+            // 34  0-5yrs       Undergraduate 
+            // 35  6-11yrs      Postgraduate 
         }
     }
 }

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

@@ -10,67 +10,71 @@ public class ValueMappingFloatToStringExample
         /// <summary>
         /// Helper class for retrieving the resulting data
         /// </summary>
-        class SampleInfertDataWithInducedCategory
+        class SampleTemperatureDataWithCategory
         {
-            public float Age = 0;
-            public float Induced = 0.0f;
-            public string InducedCategory = default;
+            public DateTime Date = default;
+            public float Temperature = 0.0f;
+            public string TemperatureCategory = default;
         }
 
-        /// This example demonstrates the use of floating types as the key type for ValueMappingEstimator by mapping a float-to-string value.
-        /// The mapping looks like the following:
-        ///     1.0 -> Cat1
-        ///     2.0 -> Cat2
+        /// This example demonstrates the use of ValueMappingEstimator by mapping float-to-string values. This is useful if the key
+        /// data are floating point and need to be grouped into string values. In this example, the Induction value is mapped to 
+        /// "T1", "T2", "T3", and "T4" groups.
         public static void Run()
         {
             // 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();
 
             // Get a small dataset as an IEnumerable.
-            IEnumerable<SamplesUtils.DatasetUtils.SampleInfertData> data = SamplesUtils.DatasetUtils.GetInfertData();
+            IEnumerable<SamplesUtils.DatasetUtils.SampleTemperatureData> data = SamplesUtils.DatasetUtils.GetSampleTemperatureData();
             IDataView trainData = mlContext.Data.ReadFromEnumerable(data);
 
+            // If the list of keys and values are known, they can be passed to the API. The ValueMappingEstimator can also get the mapping through an IDataView
+            
             // Creating a list of keys based on the induced value from the dataset
-            // These lists are created by hand for the demonstration, but the ValueMappingEstimator does take an IEnumerable.
-            var inducedKeys = new List<float>()
+            var temperatureKeys = new List<float>()
             {
-                1.0f,
-                2.0f
+                39.0F,
+                67.0F,
+                75.0F,
+                82.0F,
             };
 
             // Creating a list of values, these strings will map accordingly to each key.
-            var inducedValues = new List<string>()
+            var classificationValues = new List<string>()
             {
-                "Cat1",
-                "Cat2"
+                "T1",
+                "T2",
+                "T3", 
+                "T4"
             };
 
             // Constructs the ValueMappingEstimator making the ML.net pipeline
-            var pipeline = mlContext.Transforms.Conversion.ValueMap(inducedKeys, inducedValues, ("InducedCategory", "Induced"));
+            var pipeline = mlContext.Transforms.Conversion.ValueMap(temperatureKeys, classificationValues, ("TemperatureCategory", "Temperature"));
 
-            // Fits the ValueMappingEstimator and transforms the data adding the InducedCategory column.
+            // Fits the ValueMappingEstimator and transforms the data adding the TemperatureCategory column.
             IDataView transformedData = pipeline.Fit(trainData).Transform(trainData);
 
-            // Getting the resulting data as an IEnumerable of SampleInfertDataWithInducedCategory. This will contain the newly created column InducedCategory
-            IEnumerable<SampleInfertDataWithInducedCategory> featureRows = mlContext.CreateEnumerable<SampleInfertDataWithInducedCategory>(transformedData, reuseRowObject: false);
+            // Getting the resulting data as an IEnumerable of SampleTemperatureDataWithCategory. This will contain the newly created column TemperatureCategory
+            IEnumerable<SampleTemperatureDataWithCategory> featureRows = mlContext.CreateEnumerable<SampleTemperatureDataWithCategory>(transformedData, reuseRowObject: false);
 
             Console.WriteLine($"Example of mapping float->string");
-            Console.WriteLine($"Age\tInduced\tInducedCategory");
+            Console.WriteLine($"Date\t\tTemperature\tTemperatureCategory");
             foreach (var featureRow in featureRows)
             {
-                Console.WriteLine($"{featureRow.Age}\t{featureRow.Induced}\t{featureRow.InducedCategory}");
+                Console.WriteLine($"{featureRow.Date.ToString("d")}\t{featureRow.Temperature}\t\t{featureRow.TemperatureCategory}");
             }
 
             // Features column obtained post-transformation.
             //
             // Example of mapping float->string
-            // Age     Induced InducedCategory
-            // 26      1       Cat1
-            // 42      1       Cat1
-            // 39      2       Cat2
-            // 34      2       Cat2
-            // 35      1       Cat1
+            // Date         Temperature TemperatureCategory
+            // 1/1/2012     39          T1
+            // 1/2/2012     82          T4
+            // 1/3/2012     75          T3
+            // 1/4/2012     67          T2
+            // 1/5/2012     75          T3
         }
     }
 }

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

@@ -2,6 +2,7 @@
 using System.Collections.Generic;
 using Microsoft.Data.DataView;
 using Microsoft.ML.Data;
+using Microsoft.ML.Transforms.Conversions;
 
 namespace Microsoft.ML.Samples.Dynamic
 {
@@ -14,12 +15,12 @@ class SampleInfertDataWithIntArray
         {
             public float Age = 0;
             public string Education = default;
-            public int[] EducationCategory = default;
+            public int[] EducationFeature = default;
         }
 
-        /// This example demonstrates the use arrays as the values for the ValueMappingEstimator. It maps a set of keys that are type string
-        /// to a integer arrays of variable length.
-        /// The mapping looks like the following:
+        /// This example demonstrates the use of the ValueMappingEstimator by mapping string-to-array values which allows for mapping string data
+        /// to numeric arrays that can then be used as a feature set for a trainer. In this example, we are mapping the education data to
+        /// arbitrary integer arrays with the following association:
         ///     0-5yrs  -> 1,2,3,4
         ///     6-11yrs -> 5,6,7
         ///     12+yrs  -> 42, 32
@@ -33,6 +34,8 @@ public static void Run()
             IEnumerable<SamplesUtils.DatasetUtils.SampleInfertData> data = SamplesUtils.DatasetUtils.GetInfertData();
             IDataView trainData = mlContext.Data.ReadFromEnumerable(data);
 
+            // If the list of keys and values are known, they can be passed to the API. The ValueMappingEstimator can also get the mapping through an IDataView
+
             // Creating a list of keys based on the Education values from the dataset
             var educationKeys = new List<string>()
             {
@@ -50,25 +53,25 @@ public static void Run()
             };
 
             // Constructs the ValueMappingEstimator making the ML.net pipeline
-            var pipeline = mlContext.Transforms.Conversion.ValueMap(educationKeys, educationValues, ("EducationCategory", "Education"));
+            var pipeline = new ValueMappingEstimator<string, int>(mlContext, educationKeys, educationValues, ("EducationFeature", "Education"));
 
-            // Fits the ValueMappingEstimator and transforms the data adding the EducationCategory column.
+            // Fits the ValueMappingEstimator and transforms the data adding the EducationFeature column.
             IDataView transformedData = pipeline.Fit(trainData).Transform(trainData);
 
             // Getting the resulting data as an IEnumerable of SampleInfertDataWithIntArray. This will contain the newly created column EducationCategory
             IEnumerable<SampleInfertDataWithIntArray> featuresColumn = mlContext.CreateEnumerable<SampleInfertDataWithIntArray>(transformedData, reuseRowObject: false);
 
             Console.WriteLine($"Example of mapping string->array");
-            Console.WriteLine($"Age\tEducation\tEducationCategory");
+            Console.WriteLine($"Age\tEducation\tEducationFeature");
             foreach (var featureRow in featuresColumn)
             {
-                Console.WriteLine($"{featureRow.Age}\t{featureRow.Education}  \t{string.Join(",", featureRow.EducationCategory)}");
+                Console.WriteLine($"{featureRow.Age}\t{featureRow.Education}  \t{string.Join(",", featureRow.EducationFeature)}");
             }
 
             // Features column obtained post-transformation.
             //
             // Example of mapping string->array
-            // Age     Education   EducationCategory
+            // Age     Education   EducationFeature
             // 26      0 - 5yrs    1,2,3,4
             // 42      0 - 5yrs    1,2,3,4
             // 39      12 + yrs    42,32

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

@@ -19,19 +19,15 @@ class SampleInfertDataWithFeatures
             public string EducationCategory = default;
         }
 
-        /// This example demonstrates the use of KeyTypes in the ValueMappingEstimator by setting treatValuesAsKeyTypes to true, 
-        /// This is useful in cases where you want the output to be integer based rather than the actual value.
-        ///
-        /// When using KeyTypes as a Value, the ValueMappingEstimator will do one of the following:
-        /// 1) If the Value type is an unsigned int or unsigned long, the specified values are used directly as the KeyType values. 
-        /// 2) If the Value type is not an unsigned int or unsigned long, new KeyType values are generated for each unique value.
+        /// This example demonstrates the use of KeyTypes using both the ValueMappingEstimator and KeyToValueEstimator. Using a KeyType
+        /// instead of the actual value provides a unique integer representation of the value. When the treatValueAsKeyTypes is true, 
+        /// the ValueMappingEstimator will generate a KeyType for each unique value.
         /// 
-        /// In this example, the Value type is a string. Since we are setting treatValueAsKeyTypes to true, 
-        /// the ValueMappingEstimator will generate its own KeyType values for each unique string.
-        /// As with KeyTypes, they contain the actual Value information as part of the metadata, therefore
-        /// we can convert a KeyType back to the actual value the KeyType represents. To demonstrate
-        /// the reverse lookup and to confirm the correct value is mapped, a KeyToValueEstimator is added
-        /// to the pipeline to convert back to the original value.
+        /// In this example, the education data is mapped to a grouping of 'Undergraudate' and 'Postgraduate'. Because KeyTypes are used, the
+        /// ValueMappingEstimator will output the KeyType value rather than string value of 'Undergraduate' or 'Postgraduate'.
+        /// 
+        /// The KeyToValueEstimator is added to the pipeline to convert the KeyType back to the original value. Therefore the output of this example 
+        /// results in the string value of 'Undergraduate' and 'Postgraduate'.
         public static void Run()
         {
             // Create a new ML context, for ML.NET operations. It can be used for exception tracking and logging, 
@@ -54,9 +50,9 @@ public static void Run()
             // Creating a list of values that are sample strings. These will be converted to KeyTypes
             var educationValues = new List<string>()
             {
-                "Cat1",
-                "Cat2",
-                "Cat3"
+                "Undergraduate",
+                "Postgraduate",
+                "Postgraduate"
             };
 
             // Generate the ValueMappingEstimator that will output KeyTypes even though our values are strings.
@@ -81,11 +77,11 @@ public static void Run()
             // Features column obtained post-transformation.
             //
             // Age Education    EducationCategory
-            // 26  0-5yrs       Cat1
-            // 42  0-5yrs       Cat1
-            // 39  12+yrs       Cat3
-            // 34  0-5yrs       Cat1
-            // 35  6-11yrs      Cat2
+            // 26  0-5yrs       Undergraduate 
+            // 42  0-5yrs       Undergraduate 
+            // 39  12+yrs       Postgraduate 
+            // 34  0-5yrs       Undergraduate 
+            // 35  6-11yrs      Postgraduate 
         }
     }
 }

src/Microsoft.ML.Data/Transforms/doc.xml

@@ -80,9 +80,8 @@
           </li>
           <li>
             <description>
-              Converting a float value to a string value and have the string value represented as a <see cref="KeyType"/>
-              (i.e. specific wind speeds could map to a group ('category1', 'category2',...) which will generate a unique integer identifier (1,2,...) that could used
-              as part of a feature set for a trainer).
+              Converting a integer value to a string value and have the string value represented as a <see cref="KeyType"/>
+              (i.e. convert zip codes to a state string value, which will generate a unique integer value that can be used as a label.
             </description>
           </li>
         </list>

src/Microsoft.ML.SamplesUtils/SamplesDatasetUtils.cs

@@ -118,6 +118,23 @@ public static IEnumerable<SampleTopicsData> GetTopicsData()
             return data;
         }
 
+        public class SampleTemperatureData
+        {
+            public DateTime Date {get; set; }
+            public float Temperature { get; set; }
+        }
+
+        public static IEnumerable<SampleTemperatureData> GetSampleTemperatureData()
+        {
+            var data = new List<SampleTemperatureData>();
+            data.Add(new SampleTemperatureData { Date = new DateTime(2012,1,1), Temperature = 39.0F });
+            data.Add(new SampleTemperatureData { Date = new DateTime(2012,1,2), Temperature = 82.0F });
+            data.Add(new SampleTemperatureData { Date = new DateTime(2012,1,3), Temperature = 75.0F });
+            data.Add(new SampleTemperatureData { Date = new DateTime(2012,1,4), Temperature = 67.0F });
+            data.Add(new SampleTemperatureData { Date = new DateTime(2012,1,5), Temperature = 75.0F });
+            return data;
+        }
+
         /// <summary>
         /// Represents the column of the infertility dataset.
         /// </summary>