ValueMappingEstimator example

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

@@ -0,0 +1,85 @@
+using System;
+using System.Collections.Generic;
+using Microsoft.Data.DataView;
+using Microsoft.ML.Data;
+
+namespace Microsoft.ML.Samples.Dynamic
+{
+    public class ValueMappingExample
+    {
+        class SampleInfertDataWithFeatures
+        {
+            public float Age = 0;
+            public string Education = default;
+            public string EducationCategory = default;
+        }
+
+        /// 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, 
+            // 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();
+            IDataView trainData = mlContext.Data.ReadFromEnumerable(data);
+
+            // Preview of the data.
+            //
+            // Age    Case  Education  induced     parity  pooled.stratum  row_num  ...
+            // 26.0   1.0   0-5yrs      1.0         6.0       3.0      1.0  ...
+            // 42.0   1.0   0-5yrs      1.0         1.0       1.0      2.0  ...
+            // 39.0   1.0   12+yrs      2.0         6.0       4.0      3.0  ...
+            // 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  ...
+
+            // 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",
+                "6-11yrs",
+                "12+yrs"
+            };
+
+            // Creating a list of associated values that will map respectively to each educationKey
+            var educationValues = new List<string>()
+            {
+                "Undergraduate",
+                "Postgraduate",
+                "Postgraduate"
+            };
+
+            // Constructs the ValueMappingEstimator making the ML.net pipeline
+            var pipeline = mlContext.Transforms.Conversion.ValueMap(educationKeys, educationValues, ("EducationCategory", "Education"));
+
+            // Fits the ValueMappingEstimator and transforms the data converting the Education to EducationCategory.
+            IDataView transformedData = pipeline.Fit(trainData).Transform(trainData);
+
+            // Getting the resulting data as an IEnumerable of SampleInfertDataWithFeatures. This will contain the newly created column EducationCategory
+            IEnumerable<SampleInfertDataWithFeatures> featureRows = mlContext.CreateEnumerable<SampleInfertDataWithFeatures>(transformedData, reuseRowObject: false);
+
+            Console.WriteLine($"Example of mapping string->string");
+            Console.WriteLine($"Age\tEducation\tEducationCategory");
+            foreach (var featureRow in featureRows)
+            {
+                Console.WriteLine($"{featureRow.Age}\t{featureRow.Education}  \t{featureRow.EducationCategory}");
+            }
+
+            // Features column obtained post-transformation.
+            //
+            // Age Education    EducationCategory
+            // 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

@@ -0,0 +1,79 @@
+using System;
+using System.Collections.Generic;
+using Microsoft.Data.DataView;
+using Microsoft.ML.Data;
+
+namespace Microsoft.ML.Samples.Dynamic
+{
+    public class ValueMappingFloatToStringExample
+    {
+        /// <summary>
+        /// Helper class for retrieving the resulting data
+        /// </summary>
+        class SampleTemperatureDataWithCategory
+        {
+            public DateTime Date = default;
+            public float Temperature = 0.0f;
+            public string TemperatureCategory = default;
+        }
+
+        /// 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.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
+            var temperatureKeys = new List<float>()
+            {
+                39.0F,
+                67.0F,
+                75.0F,
+                82.0F,
+            };
+
+            // Creating a list of values, these strings will map accordingly to each key.
+            var classificationValues = new List<string>()
+            {
+                "T1",
+                "T2",
+                "T3", 
+                "T4"
+            };
+
+            // Constructs the ValueMappingEstimator making the ML.net pipeline
+            var pipeline = mlContext.Transforms.Conversion.ValueMap(temperatureKeys, classificationValues, ("TemperatureCategory", "Temperature"));
+
+            // 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 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($"Date\t\tTemperature\tTemperatureCategory");
+            foreach (var featureRow in featureRows)
+            {
+                Console.WriteLine($"{featureRow.Date.ToString("d")}\t{featureRow.Temperature}\t\t{featureRow.TemperatureCategory}");
+            }
+
+            // Features column obtained post-transformation.
+            //
+            // Example of mapping float->string
+            // 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

@@ -0,0 +1,81 @@
+using System;
+using System.Collections.Generic;
+using Microsoft.Data.DataView;
+using Microsoft.ML.Data;
+using Microsoft.ML.Transforms.Conversions;
+
+namespace Microsoft.ML.Samples.Dynamic
+{
+    public class ValueMappingStringToArrayExample
+    {
+        /// <summary>
+        /// Helper class for retrieving the resulting data
+        /// </summary>
+        class SampleInfertDataWithIntArray
+        {
+            public float Age = 0;
+            public string Education = default;
+            public int[] EducationFeature = default;
+        }
+
+        /// 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
+        ///     6-11yrs -> 5, 6, 7
+        ///     12+yrs  -> 42,32,64
+        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();
+            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>()
+            {
+                "0-5yrs",
+                "6-11yrs",
+                "12+yrs"
+            };
+
+            // Sample list of associated array values
+            var educationValues = new List<int[]>()
+            {
+                new int[] { 1,2,3 },
+                new int[] { 5,6,7 },
+                new int[] { 42,32,64 }
+            };
+
+            // Constructs the ValueMappingEstimator making the ML.net pipeline
+            var pipeline = new ValueMappingEstimator<string, int>(mlContext, educationKeys, educationValues, ("EducationFeature", "Education"));
+
+            // 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\tEducationFeature");
+            foreach (var featureRow in featuresColumn)
+            {
+                Console.WriteLine($"{featureRow.Age}\t{featureRow.Education}  \t{string.Join(",", featureRow.EducationFeature)}");
+            }
+
+            // Features column obtained post-transformation.
+            //
+            // Example of mapping string->array
+            // Age     Education   EducationFeature
+            // 26      0 - 5yrs    1,2,3
+            // 42      0 - 5yrs    1,2,3
+            // 39      12 + yrs    42,32,64
+            // 34      0 - 5yrs    1,2,3
+            // 35      6 - 11yrs   5,6,7
+        }
+    }
+}

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

@@ -0,0 +1,87 @@
+using System;
+using System.Collections.Generic;
+using Microsoft.Data.DataView;
+using Microsoft.ML.Data;
+using Microsoft.ML.Transforms.Conversions;
+
+namespace Microsoft.ML.Samples.Dynamic
+{
+    public class ValueMappingStringToKeyTypeExample
+    {
+        /// <summary>
+        /// Helper class for retrieving the resulting data
+        /// </summary>
+        class SampleInfertDataWithFeatures
+
+        {
+            public float Age = 0;
+            public string Education = default;
+            public string EducationCategory = default;
+        }
+
+        /// 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 education data is mapped to a grouping of 'Undergraduate' 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, 
+            // 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();
+            IDataView trainData = mlContext.Data.ReadFromEnumerable(data);
+
+            // 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.
+            var educationKeys = new List<string>()
+            {
+                "0-5yrs",
+                "6-11yrs",
+                "12+yrs"
+            };
+
+            // Creating a list of values that are sample strings. These will be converted to KeyTypes
+            var educationValues = new List<string>()
+            {
+                "Undergraduate",
+                "Postgraduate",
+                "Postgraduate"
+            };
+
+            // Generate the ValueMappingEstimator that will output KeyTypes even though our values are strings.
+            // The KeyToValueMappingEstimator is added to provide a reverse lookup of the KeyType, converting the KeyType value back
+            // to the original value.
+            var pipeline = new ValueMappingEstimator<string, string>(mlContext, educationKeys, educationValues, true, ("EducationKeyType", "Education"))
+                              .Append(new KeyToValueMappingEstimator(mlContext, ("EducationCategory", "EducationKeyType")));
+
+            // Fits the ValueMappingEstimator and transforms the data adding the EducationKeyType column.
+            IDataView transformedData = pipeline.Fit(trainData).Transform(trainData);
+
+            // Getting the resulting data as an IEnumerable of SampleInfertDataWithFeatures.
+            IEnumerable<SampleInfertDataWithFeatures> featureRows = mlContext.CreateEnumerable<SampleInfertDataWithFeatures>(transformedData, reuseRowObject: false);
+
+            Console.WriteLine($"Example of mapping string->keytype");
+            Console.WriteLine($"Age\tEducation\tEducationCategory");
+            foreach (var featureRow in featureRows)
+            {
+                Console.WriteLine($"{featureRow.Age}\t{featureRow.Education}  \t{featureRow.EducationCategory}");
+            }
+
+            // Features column obtained post-transformation.
+            //
+            // Age Education    EducationCategory
+            // 26  0-5yrs       Undergraduate 
+            // 42  0-5yrs       Undergraduate 
+            // 39  12+yrs       Postgraduate 
+            // 34  0-5yrs       Undergraduate 
+            // 35  6-11yrs      Postgraduate 
+        }
+    }
+}