Scrubbing task: rest of transforms (#2876)

Author: artidoro

docs/code/MlNetCookBook.md

@@ -944,9 +944,9 @@ public static IDataView PrepareData(MLContext mlContext, IDataView data)
 {
     // Define the operation code.
     Action<InputRow, OutputRow> mapping = (input, output) => output.Label = input.Income > 50000;
-    // Make a custom transformer and transform the data.
-    var transformer = mlContext.Transforms.CustomMappingTransformer(mapping, null);
-    return transformer.Transform(data);
+    // Make a custom estimator and transform the data.
+    var estimator = mlContext.Transforms.CustomMapping(mapping, null);
+    return estimator.Fit(data).Transform(data);
 }
 ```
 

docs/samples/Microsoft.ML.Samples/Dynamic/PermutationFeatureImportance/PFIHelper.cs

@@ -19,7 +19,7 @@ public static IDataView GetHousingRegressionIDataView(MLContext mlContext, out s
             if (binaryPrediction)
             {
                 labelColumn = nameof(BinaryOutputRow.AboveAverage);
-                data = mlContext.Transforms.CustomMappingTransformer(GreaterThanAverage, null).Transform(data);
+                data = mlContext.Transforms.CustomMapping(GreaterThanAverage, null).Fit(data).Transform(data);
                 data = mlContext.Transforms.DropColumns("MedianHomeValue").Fit(data).Transform(data);
             }
 

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

@@ -16,30 +16,35 @@ public static void Example()
             var trainData = mlContext.Data.LoadFromEnumerable(data);
 
             // Preview of the data.
-            //
-            // Age  Case  Education  Induced     Parity  PooledStratum  RowNum  ...
-            // 26   1       0-5yrs      1         6         3             1  ...
-            // 42   1       0-5yrs      1         1         1             2  ...
-            // 39   1       0-5yrs      2         6         4             3  ...
-            // 34   1       0-5yrs      2         4         2             4  ...
-            // 35   1       6-11yrs     1         3         32            5  ...
+            //  Age     RowNum  Education   ...
+            //  26       0       0-5yrs     ...
+            //  42       1       0-5yrs     ...
+            //  39       2       12+yrs     ...
+            //  34       3       0-5yrs     ...
+            //  35       4       6-11yrs    ...
 
             // We define the custom mapping between input and output rows that will be applied by the transformation.
-            Action<SamplesUtils.DatasetUtils.SampleInfertData, SampleInfertDataTransformed> mapping = 
+            Action<SamplesUtils.DatasetUtils.SampleInfertData, OutputRow> mapping =
                 (input, output) => output.IsUnderThirty = input.Age < 30;
 
             // Custom transformations can be used to transform data directly, or as part of a pipeline. Below we transform data directly.
-            var transformer = mlContext.Transforms.CustomMappingTransformer(mapping, null);
-            var transformedData = transformer.Transform(trainData);
+            var estimator = mlContext.Transforms.CustomMapping(mapping, null);
+            var transformedData = estimator.Fit(trainData).Transform(trainData);
+
+            // Preview 5 lines of the transformed data.
+            transformedData = mlContext.Data.TakeRows(transformedData, 5);
+            var dataEnumerable = mlContext.Data.CreateEnumerable<SampleInfertDataTransformed>(transformedData, reuseRowObject: true);
+            Console.WriteLine("IsUnderThirty\t Age\t RowNum\t Education\t ...");
+            foreach (var row in dataEnumerable)
+                Console.WriteLine($"{row.IsUnderThirty}\t {row.Age}\t {row.RowNum}\t {row.Education}\t ...");
+            // Expected output:
+            //  IsUnderThirty   Age     RowNum  Education       ...
+            //  True            26      0       0-5yrs   ...
+            //  False           42      1       0-5yrs   ...
+            //  False           39      2       12+yrs   ...
+            //  False           34      3       0-5yrs   ...
+            //  False           35      4       6-11yrs  ...
 
-            // Preview of the data.
-            //
-            // IsUnderThirty  Age   Case  Education  Induced     Parity  PooledStratum  RowNum  ...
-            // true            26    1       0-5yrs      1         6         3             1  ...
-            // false           42    1       0-5yrs      1         1         1             2  ...
-            // false           39    1       0-5yrs      2         6         4             3  ...
-            // false           34    1       0-5yrs      2         4         2             4  ...
-            // false           35    1       6-11yrs     1         3         32            5  ...
 
             // Here instead we use it as part of a pipeline of estimators.
             var pipeline = mlContext.Transforms.CustomMapping(mapping, null)
@@ -53,12 +58,19 @@ public static void Example()
             transformedData = pipeline.Fit(trainData).Transform(trainData);
         }
 
+        // This defines only the column to be generated by the transformation in addition to the columns already present.
+        public class OutputRow
+        {
+            public bool IsUnderThirty { get; set; }
+        }
+
         // Represents the transformed infertility dataset.
         public class SampleInfertDataTransformed
         {
+            public bool IsUnderThirty { get; set; }
+            public float Age { get; set; }
             public int RowNum { get; set; }
             public string Education { get; set; }
-            public bool IsUnderThirty { get; set; }
             public float Parity { get; set; }
             public float Induced { get; set; }
             public float Case { get; set; }

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

@@ -6,7 +6,7 @@ internal static class Program
     {
         static void Main(string[] args)
         {
-            TakeRows.Example();
+            CustomMapping.Example();
         }
     }
 }

src/Microsoft.ML.Transforms/CustomMappingCatalog.cs

@@ -34,29 +34,5 @@ public static CustomMappingEstimator<TSrc, TDst> CustomMapping<TSrc, TDst>(this
             where TSrc : class, new()
             where TDst : class, new()
             => new CustomMappingEstimator<TSrc, TDst>(catalog.GetEnvironment(), mapAction, contractName, inputSchemaDefinition, outputSchemaDefinition);
-
-        /// <summary>
-        /// Create a custom mapping of input columns to output columns. Most likely, you should call this method when you are loading the model:
-        /// use <see cref="CustomMapping{TSrc, TDst}(TransformsCatalog, Action{TSrc, TDst}, string, SchemaDefinition, SchemaDefinition)"/> when you are
-        /// training the model.
-        /// </summary>
-        /// <typeparam name="TSrc">The class defining which columns to take from the incoming data.</typeparam>
-        /// <typeparam name="TDst">The class defining which new columns are added to the data.</typeparam>
-        /// <param name="catalog">The transform catalog</param>
-        /// <param name="mapAction">The mapping action. This must be thread-safe and free from side effects.</param>
-        /// <param name="contractName">The contract name, used by ML.NET for loading the model. If <c>null</c> is specified, such a trained model would not be save-able.</param>
-        /// <param name="inputSchemaDefinition">Additional parameters for schema mapping between <typeparamref name="TSrc"/> and input data.</param>
-        /// <param name="outputSchemaDefinition">Additional parameters for schema mapping between <typeparamref name="TDst"/> and output data.</param>
-        /// <example>
-        /// <format type="text/markdown">
-        /// <![CDATA[
-        ///  [!code-csharp[FastTree](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/CustomMapping.cs)]
-        /// ]]></format>
-        /// </example>
-        public static CustomMappingTransformer<TSrc, TDst> CustomMappingTransformer<TSrc, TDst>(this TransformsCatalog catalog, Action<TSrc, TDst> mapAction, string contractName,
-                SchemaDefinition inputSchemaDefinition = null, SchemaDefinition outputSchemaDefinition = null)
-            where TSrc : class, new()
-            where TDst : class, new()
-            => new CustomMappingTransformer<TSrc, TDst>(catalog.GetEnvironment(), mapAction, contractName, inputSchemaDefinition, outputSchemaDefinition);
     }
 }

src/Microsoft.ML.Transforms/ExtensionsCatalog.cs

@@ -38,19 +38,19 @@ public static MissingValueIndicatorEstimator IndicateMissingValues(this Transfor
         /// Creates a new output column, or replaces the source with a new column
         /// (depending on whether the <paramref name="outputColumnName"/> is given a value, or left to null)
         /// identical to the input column for everything but the missing values. The missing values of the input column, in this new column are replaced with
-        /// one of the values specifid in the <paramref name="replacementKind"/>. The default for the <paramref name="replacementKind"/> is
+        /// one of the values specifid in the <paramref name="replacementMode"/>. The default for the <paramref name="replacementMode"/> is
         /// <see cref="MissingValueReplacingEstimator.ColumnOptions.ReplacementMode.DefaultValue"/>.
         /// </summary>
         /// <param name="catalog">The transform extensions' catalog.</param>
         /// <param name="outputColumnName">Name of the column resulting from the transformation of <paramref name="inputColumnName"/>.</param>
         /// <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.
         /// If not provided, the <paramref name="inputColumnName"/> will be replaced with the results of the transforms.</param>
-        /// <param name="replacementKind">The type of replacement to use as specified in <see cref="MissingValueReplacingEstimator.ColumnOptions.ReplacementMode"/></param>
+        /// <param name="replacementMode">The type of replacement to use as specified in <see cref="MissingValueReplacingEstimator.ColumnOptions.ReplacementMode"/></param>
         public static MissingValueReplacingEstimator ReplaceMissingValues(this TransformsCatalog catalog,
             string outputColumnName,
             string inputColumnName = null,
-            MissingValueReplacingEstimator.ColumnOptions.ReplacementMode replacementKind = MissingValueReplacingEstimator.Defaults.ReplacementMode)
-        => new MissingValueReplacingEstimator(CatalogUtils.GetEnvironment(catalog), outputColumnName, inputColumnName, replacementKind);
+            MissingValueReplacingEstimator.ColumnOptions.ReplacementMode replacementMode = MissingValueReplacingEstimator.Defaults.ReplacementMode)
+        => new MissingValueReplacingEstimator(CatalogUtils.GetEnvironment(catalog), outputColumnName, inputColumnName, replacementMode);
 
         /// <summary>
         /// Creates a new output column, identical to the input column for everything but the missing values.

src/Microsoft.ML.Transforms/MissingValueIndicatorTransformer.cs

@@ -80,7 +80,7 @@ private static VersionInfo GetVersionInfo()
         /// <summary>
         /// The names of the output and input column pairs for the transformation.
         /// </summary>
-        public IReadOnlyList<(string outputColumnName, string inputColumnName)> Columns => ColumnPairs.AsReadOnly();
+        internal IReadOnlyList<(string outputColumnName, string inputColumnName)> Columns => ColumnPairs.AsReadOnly();
 
         /// <summary>
         /// Initializes a new instance of <see cref="MissingValueIndicatorTransformer"/>

test/Microsoft.ML.Tests/Scenarios/Api/CookbookSamples/CookbookSamplesDynamicApi.cs

@@ -543,9 +543,9 @@ public static IDataView PrepareData(MLContext mlContext, IDataView data)
         {
             // Define the operation code.
             Action<InputRow, OutputRow> mapping = (input, output) => output.Label = input.Income > 50000;
-            // Make a custom transformer and transform the data.
-            var transformer = mlContext.Transforms.CustomMappingTransformer(mapping, null);
-            return transformer.Transform(data);
+            // Make a custom estimator and transform the data.
+            var estimator = mlContext.Transforms.CustomMapping(mapping, null);
+            return estimator.Fit(data).Transform(data);
         }
 
         public static ITransformer TrainModel(MLContext mlContext, IDataView trainData)