What is the exact behavior of CreateTextLoader<TInput> when dataSample is given?

[najeeb-kazmi]

We have this overload for CreateTextLoader<TInput>, where the schema is defined in TInput.

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

Lines 90 to 98 in c3d1592

	public static TextLoader CreateTextLoader<TInput>(this DataOperationsCatalog catalog,
	char separatorChar = TextLoader.Defaults.Separator,
	bool hasHeader = TextLoader.Defaults.HasHeader,
	IMultiStreamSource dataSample = null,
	bool allowQuoting = TextLoader.Defaults.AllowQuoting,
	bool trimWhitespace = TextLoader.Defaults.TrimWhitespace,
	bool allowSparse = TextLoader.Defaults.AllowSparse)
	=> TextLoader.CreateTextLoader<TInput>(CatalogUtils.GetEnvironment(catalog), hasHeader, separatorChar, allowQuoting,
	allowSparse, trimWhitespace, dataSample: dataSample);

The dataSample argument is meant to be used to infer schema. Since TInput must contain at least one field, there is always at least one column in the schema. Then, this condition is never hit, and consequently, dataSample is never used to infer the schema with the CreateTextLoader<TInput> overload.

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

Line 1118 in c3d1592

if (Utils.Size(cols) == 0 && !TryParseSchema(_host, headerFile ?? dataSample, ref options, out cols, out error))

Presence of the dataSample argument is confusing here as it implies that a sample can be provided. In other places, this sample is used to infer schema, so the user would expect this to be the case here as well, but dataSample is ignored here.

I will update the documentation to reflect this, but this should be removed. Since this will be an API breaking change, this should be revisited for 2.0.

[yaeldekel]

This is not a bug.

The data sample is also used here: https://github.com/dotnet/machinelearning/blob/master/src/Microsoft.ML.Data/DataLoadSave/Text/TextLoader.cs#L1191

_bindings = new Bindings(this, cols, headerFile, dataSample);

It is used to get slot names for the vector columns in case hasHeader is specified to be true.

[najeeb-kazmi]

@yaeldekel must the dataSample have the schema in the header for this to work? E.g.

#@ TextLoader{
#@ sep=tab
#@ col=Features:R4:0-5
#@ }

[yaeldekel]

No. The columns are taken either from the TInput class or from the Options if using the non-generic overload. The other arguments (such as the separator) are taken from the arguments to CreateTextLoader. The data sample is used for inferring the columns only if there are no columns specified, and I think even then it will work even when there is no schema in the header, by creating a default set of columns "Label" and "Features" (this is how it used to work, I'll have to look at the code to see if this is still what we do).

[najeeb-kazmi]

Yes, if no schema is present in the header, it will add col=Label:R4:0 col=Features:R4:1-*. If some features are text, they will be loaded as missing values.

For this particular overload, you are right, the columns are inferred from TInput, but for other overloads, if no columns are specified, either the schema is parsed from the header of the dataSample if present, or it defaults to first column label, and the rest all features.

Am I right that if any other schema is needed, and no columns are specified, the dataSample must have it in the header?

[yaeldekel]

If the dataSample has the columns defined in it, it also has the rest of the TextLoader options in it (such as the separator, and whether or not there is a header). Is this what you mean by "any other schema needed"?

[najeeb-kazmi]

I mean let's say that the schema is NOT col=Label:R4:0 col=Features:R4:1-* but something like col=Label:R4:0 col=Categories:TX:1-3 col=Features:R4:4-*. Then the dataSample MUST contain this information in the header. If not, the loaded data has missing values. This means that if the user provides a dataSample, that sample must be one that has previously been loaded with the right schema, and then saved to a text file with schema in the header. Otherwise, dataSample is of no use.

I say dataSample must be loaded with right schema and then saved because the user cannot be expected to know the old TLC format of specifying schema line col=<Name>:<Type>:<index> and so this information must come from having saved the file previously.