Add public generic methods to TextLoader catalog that accept Options objects (#5134)

* Added new API for generic text loader catalog methods, with an Options parameter

* Added a couple of tests to directly test the new API

Author: antoniovs1029

src/Microsoft.ML.Data/DataLoadSave/Text/TextLoader.cs

@@ -1460,6 +1460,23 @@ internal static TextLoader CreateTextLoader<TInput>(IHostEnvironment host,
            bool trimWhitespace = Defaults.TrimWhitespace,
            IMultiStreamSource dataSample = null)
         {
+            Options options = new Options
+            {
+                HasHeader = hasHeader,
+                Separators = new[] { separator },
+                AllowQuoting = allowQuoting,
+                AllowSparse = supportSparse,
+                TrimWhitespace = trimWhitespace
+            };
+
+            return CreateTextLoader<TInput>(host, options, dataSample);
+        }
+
+        internal static TextLoader CreateTextLoader<TInput>(IHostEnvironment host,
+           Options options = null,
+           IMultiStreamSource dataSample = null)
+        {
+            options = options ?? new Options();
             var userType = typeof(TInput);
 
             var fieldInfos = userType.GetFields(BindingFlags.Public | BindingFlags.Instance);
@@ -1520,15 +1537,7 @@ internal static TextLoader CreateTextLoader<TInput>(IHostEnvironment host,
                 columns.Add(column);
             }
 
-            Options options = new Options
-            {
-                HasHeader = hasHeader,
-                Separators = new[] { separator },
-                AllowQuoting = allowQuoting,
-                AllowSparse = supportSparse,
-                TrimWhitespace = trimWhitespace,
-                Columns = columns.ToArray()
-            };
+            options.Columns = columns.ToArray();
 
             return new TextLoader(host, options, dataSample: dataSample);
         }

src/Microsoft.ML.Data/DataLoadSave/Text/TextLoaderSaverCatalog.cs

@@ -119,6 +119,19 @@ public static TextLoader CreateTextLoader<TInput>(this DataOperationsCatalog cat
             => TextLoader.CreateTextLoader<TInput>(CatalogUtils.GetEnvironment(catalog), hasHeader, separatorChar, allowQuoting,
                 allowSparse, trimWhitespace, dataSample: dataSample);
 
+        /// <summary>
+        /// Create a text loader <see cref="TextLoader"/> by inferencing the dataset schema from a data model type.
+        /// </summary>
+        /// <param name="catalog">The <see cref="DataOperationsCatalog"/> catalog.</param>
+        /// <param name="options">Defines the settings of the load operation. Defines the settings of the load operation. No need to specify a Columns field,
+        /// as columns will be infered by this method.</param>
+        /// <param name="dataSample">The optional location of a data sample. The sample can be used to infer information
+        /// about the columns, such as slot names.</param>
+        public static TextLoader CreateTextLoader<TInput>(this DataOperationsCatalog catalog,
+            TextLoader.Options options,
+            IMultiStreamSource dataSample = null)
+            => TextLoader.CreateTextLoader<TInput>(CatalogUtils.GetEnvironment(catalog), options, dataSample);
+
         /// <summary>
         /// Load a <see cref="IDataView"/> from a text file using <see cref="TextLoader"/>.
         /// Note that <see cref="IDataView"/>'s are lazy, so no actual loading happens here, just schema validation.
@@ -172,6 +185,35 @@ public static IDataView LoadFromTextFile(this DataOperationsCatalog catalog,
             return loader.Load(new MultiFileSource(path));
         }
 
+        /// <summary>
+        /// Load a <see cref="IDataView"/> from a text file using <see cref="TextLoader"/>.
+        /// Note that <see cref="IDataView"/>'s are lazy, so no actual loading happens here, just schema validation.
+        /// </summary>
+        /// <param name="catalog">The <see cref="DataOperationsCatalog"/> catalog.</param>
+        /// <param name="path">Specifies a file from which to load.</param>
+        /// <param name="options">Defines the settings of the load operation.</param>
+        /// <example>
+        /// <format type="text/markdown">
+        /// <![CDATA[
+        /// [!code-csharp[LoadFromTextFile](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/DataOperations/SaveAndLoadFromText.cs)]
+        /// ]]>
+        /// </format>
+        /// </example>
+        public static IDataView LoadFromTextFile(this DataOperationsCatalog catalog, string path,
+            TextLoader.Options options = null)
+        {
+            Contracts.CheckNonEmpty(path, nameof(path));
+            if (!File.Exists(path))
+            {
+                throw Contracts.ExceptParam(nameof(path), "File does not exist at path: {0}", path);
+            }
+
+            var env = catalog.GetEnvironment();
+            var source = new MultiFileSource(path);
+
+            return new TextLoader(env, options, dataSample: source).Load(source);
+        }
+
         /// <summary>
         /// Load a <see cref="IDataView"/> from a text file using <see cref="TextLoader"/>.
         /// Note that <see cref="IDataView"/>'s are lazy, so no actual loading happens here, just schema validation.
@@ -221,27 +263,20 @@ public static IDataView LoadFromTextFile<TInput>(this DataOperationsCatalog cata
         /// </summary>
         /// <param name="catalog">The <see cref="DataOperationsCatalog"/> catalog.</param>
         /// <param name="path">Specifies a file from which to load.</param>
-        /// <param name="options">Defines the settings of the load operation.</param>
-        /// <example>
-        /// <format type="text/markdown">
-        /// <![CDATA[
-        /// [!code-csharp[LoadFromTextFile](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/DataOperations/SaveAndLoadFromText.cs)]
-        /// ]]>
-        /// </format>
-        /// </example>
-        public static IDataView LoadFromTextFile(this DataOperationsCatalog catalog, string path,
-            TextLoader.Options options = null)
+        /// <param name="options">Defines the settings of the load operation. No need to specify a Columns field,
+        /// as columns will be infered by this method.</param>
+        /// <returns>The data view.</returns>
+        public static IDataView LoadFromTextFile<TInput>(this DataOperationsCatalog catalog, string path,
+            TextLoader.Options options)
         {
             Contracts.CheckNonEmpty(path, nameof(path));
             if (!File.Exists(path))
             {
                 throw Contracts.ExceptParam(nameof(path), "File does not exist at path: {0}", path);
             }
 
-            var env = catalog.GetEnvironment();
-            var source = new MultiFileSource(path);
-
-            return new TextLoader(env, options, dataSample: source).Load(source);
+            return TextLoader.CreateTextLoader<TInput>(CatalogUtils.GetEnvironment(catalog), options)
+                .Load(new MultiFileSource(path));
         }
 
         /// <summary>

test/Microsoft.ML.Functional.Tests/Prediction.cs

@@ -36,9 +36,14 @@ public void ReconfigurablePrediction()
         {
             var mlContext = new MLContext(seed: 1);
 
+            var options = new TextLoader.Options
+            {
+                HasHeader = TestDatasets.Sentiment.fileHasHeader,
+                Separators = new[] { TestDatasets.Sentiment.fileSeparator }
+            };
+
             var data = mlContext.Data.LoadFromTextFile<TweetSentiment>(TestCommon.GetDataPath(DataDir, TestDatasets.Sentiment.trainFilename),
-                hasHeader: TestDatasets.Sentiment.fileHasHeader,
-                separatorChar: TestDatasets.Sentiment.fileSeparator);
+                options);
 
             // Create a training pipeline.
             var pipeline = mlContext.Transforms.Text.FeaturizeText("Features", "SentimentText")

test/Microsoft.ML.Tests/TextLoaderTests.cs

@@ -704,8 +704,10 @@ public class IrisColumnIndices
             public string Type;
         }
 
-        [Fact]
-        public void LoaderColumnsFromIrisData()
+        [Theory]
+        [InlineData(true)]
+        [InlineData(false)]
+        public void LoaderColumnsFromIrisData(bool useOptionsObject)
         {
             var dataPath = GetDataPath(TestDatasets.irisData.trainFilename);
             var mlContext = new MLContext(1);
@@ -719,7 +721,12 @@ public void LoaderColumnsFromIrisData()
             var irisFirstRowValues = irisFirstRow.Values.GetEnumerator();
 
             // Simple load
-            var dataIris = mlContext.Data.CreateTextLoader<Iris>(separatorChar: ',').Load(dataPath);
+            IDataView dataIris;
+            if (useOptionsObject)
+                dataIris = mlContext.Data.CreateTextLoader<Iris>(new TextLoader.Options() { Separator = ",", AllowQuoting = false }).Load(dataPath);
+            else
+                dataIris = mlContext.Data.CreateTextLoader<Iris>(separatorChar: ',').Load(dataPath);
+
             var previewIris = dataIris.Preview(1);
 
             Assert.Equal(5, previewIris.ColumnView.Length);
@@ -735,7 +742,12 @@ public void LoaderColumnsFromIrisData()
             Assert.Equal("Iris-setosa", previewIris.RowView[0].Values[index].Value.ToString());
 
             // Load with start and end indexes
-            var dataIrisStartEnd = mlContext.Data.CreateTextLoader<IrisStartEnd>(separatorChar: ',').Load(dataPath);
+            IDataView dataIrisStartEnd;
+            if (useOptionsObject)
+                dataIrisStartEnd = mlContext.Data.CreateTextLoader<IrisStartEnd>(new TextLoader.Options() { Separator = ",", AllowQuoting = false }).Load(dataPath);
+            else
+                dataIrisStartEnd = mlContext.Data.CreateTextLoader<IrisStartEnd>(separatorChar: ',').Load(dataPath);
+
             var previewIrisStartEnd = dataIrisStartEnd.Preview(1);
 
             Assert.Equal(2, previewIrisStartEnd.ColumnView.Length);
@@ -752,7 +764,12 @@ public void LoaderColumnsFromIrisData()
             }
 
             // load setting the distinct columns. Loading column 0 and 2
-            var dataIrisColumnIndices = mlContext.Data.CreateTextLoader<IrisColumnIndices>(separatorChar: ',').Load(dataPath);
+            IDataView dataIrisColumnIndices;
+            if (useOptionsObject)
+                dataIrisColumnIndices = mlContext.Data.CreateTextLoader<IrisColumnIndices>(new TextLoader.Options() { Separator = ",", AllowQuoting = false }).Load(dataPath);
+            else
+                dataIrisColumnIndices = mlContext.Data.CreateTextLoader<IrisColumnIndices>(separatorChar: ',').Load(dataPath);
+
             var previewIrisColumnIndices = dataIrisColumnIndices.Preview(1);
 
             Assert.Equal(2, previewIrisColumnIndices.ColumnView.Length);