File: Training\TrainerInputBase.cs
Web Access
Project: ..\..\..\src\Microsoft.ML.Data\Microsoft.ML.Data.csproj (Microsoft.ML.Data)
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.
 
using Microsoft.ML.CommandLine;
using Microsoft.ML.Data;
using Microsoft.ML.EntryPoints;
using Microsoft.ML.Runtime;
 
namespace Microsoft.ML.Trainers
{
    /// <summary>
    /// The base class for all trainer inputs.
    /// </summary>
    [TlcModule.EntryPointKind(typeof(CommonInputs.ITrainerInput))]
    public abstract class TrainerInputBase
    {
        private protected TrainerInputBase() { }
 
        /// <summary>
        /// The data to be used for training. Used only in entry-points, since in the API the expected mechanism is
        /// that the user will use the <see cref="IEstimator{TTransformer}.Fit(IDataView)"/> or some other train
        /// method.
        /// </summary>
        [BestFriend]
        [Argument(ArgumentType.Required, ShortName = "data", HelpText = "The data to be used for training", SortOrder = 1, Visibility = ArgumentAttribute.VisibilityType.EntryPointsOnly)]
        internal IDataView TrainingData;
 
        /// <summary>
        /// Column to use for features.
        /// </summary>
        [Argument(ArgumentType.AtMostOnce, HelpText = "Column to use for features", ShortName = "feat", SortOrder = 2, Visibility = ArgumentAttribute.VisibilityType.EntryPointsOnly)]
        public string FeatureColumnName = DefaultColumnNames.Features;
 
        /// <summary>
        /// Normalize option for the feature column. Used only in entry-points, since in the API the user is expected to do this themselves.
        /// </summary>
        [BestFriend]
        [Argument(ArgumentType.AtMostOnce, HelpText = "Normalize option for the feature column", ShortName = "norm", SortOrder = 5, Visibility = ArgumentAttribute.VisibilityType.EntryPointsOnly)]
        internal NormalizeOption NormalizeFeatures = NormalizeOption.Auto;
 
        /// <summary>
        /// Whether trainer should cache input training data. Used only in entry-points, since the intended API mechanism
        /// is that the user will use the <see cref="DataOperationsCatalog.Cache(IDataView, string[])"/> or other method
        /// like <see cref="EstimatorChain{TLastTransformer}.AppendCacheCheckpoint(IHostEnvironment)"/>.
        /// </summary>
        [BestFriend]
        [Argument(ArgumentType.LastOccurrenceWins, HelpText = "Whether trainer should cache input training data", ShortName = "cache", SortOrder = 6, Visibility = ArgumentAttribute.VisibilityType.EntryPointsOnly)]
        internal CachingOptions Caching = CachingOptions.Auto;
    }
 
    /// <summary>
    /// The base class for all trainer inputs that support a Label column.
    /// </summary>
    [TlcModule.EntryPointKind(typeof(CommonInputs.ITrainerInputWithLabel))]
    public abstract class TrainerInputBaseWithLabel : TrainerInputBase
    {
        private protected TrainerInputBaseWithLabel() { }
 
        /// <summary>
        /// Column to use for labels.
        /// </summary>
        [Argument(ArgumentType.AtMostOnce, HelpText = "Column to use for labels", ShortName = "lab", SortOrder = 3, Visibility = ArgumentAttribute.VisibilityType.EntryPointsOnly)]
        public string LabelColumnName = DefaultColumnNames.Label;
    }
 
    // REVIEW: This is a known antipattern, but the solution involves the decorator pattern which can't be used in this case.
    /// <summary>
    /// The base class for all trainer inputs that support a weight column.
    /// </summary>
    [TlcModule.EntryPointKind(typeof(CommonInputs.ITrainerInputWithWeight))]
    public abstract class TrainerInputBaseWithWeight : TrainerInputBaseWithLabel
    {
        private protected TrainerInputBaseWithWeight() { }
 
        /// <summary>
        /// Column to use for example weight.
        /// </summary>
        [Argument(ArgumentType.AtMostOnce, HelpText = "Column to use for example weight", ShortName = "weight", SortOrder = 4, Visibility = ArgumentAttribute.VisibilityType.EntryPointsOnly)]
        public string ExampleWeightColumnName = null;
    }
 
    /// <summary>
    /// The base class for all unsupervised trainer inputs that support a weight column.
    /// </summary>
    [TlcModule.EntryPointKind(typeof(CommonInputs.IUnsupervisedTrainerWithWeight))]
    public abstract class UnsupervisedTrainerInputBaseWithWeight : TrainerInputBase
    {
        private protected UnsupervisedTrainerInputBaseWithWeight() { }
 
        /// <summary>
        /// The name of the column containing a weight for each training example, or <see langword="null"/>
        /// to give all examples equal weight.
        /// </summary>
        /// <remarks>
        /// <para>
        /// The column must contain a single <see cref="System.Single"/> value per row.
        /// Weights control the relative influence of training examples, not individual features.
        /// How weights affect training depends on the trainer.
        /// If no weight column is specified, each example has a weight of 1.
        /// </para>
        /// <para>
        /// Only one column name can be specified. To calculate weights from multiple input columns,
        /// first combine their values into a single weight column before training. For example, a row
        /// with a quantity of 3 and a confidence of 0.5 could be assigned a weight of 1.5 by multiplying
        /// those values.
        /// </para>
        /// </remarks>
        /// <example>
        /// The following options configure K-means to use a column named "Weight" containing the
        /// per-example weights. The training data must contain that column in addition to "Features".
        /// <code>
        /// var options = new KMeansTrainer.Options
        /// {
        ///     FeatureColumnName = "Features",
        ///     ExampleWeightColumnName = "Weight",
        ///     NumberOfClusters = 2
        /// };
        /// var trainer = mlContext.Clustering.Trainers.KMeans(options);
        /// var model = trainer.Fit(trainingData);
        /// </code>
        /// </example>
        [Argument(ArgumentType.AtMostOnce, HelpText = "Column to use for example weight", ShortName = "weight", SortOrder = 4, Visibility = ArgumentAttribute.VisibilityType.EntryPointsOnly)]
        public string ExampleWeightColumnName = null;
    }
 
    /// <summary>
    /// The base class for all trainer inputs that support a group column.
    /// </summary>
    [TlcModule.EntryPointKind(typeof(CommonInputs.ITrainerInputWithGroupId))]
    public abstract class TrainerInputBaseWithGroupId : TrainerInputBaseWithWeight
    {
        private protected TrainerInputBaseWithGroupId() { }
 
        /// <summary>
        /// Column to use for example groupId.
        /// </summary>
        [Argument(ArgumentType.AtMostOnce, HelpText = "Column to use for example groupId", ShortName = "groupId", SortOrder = 5, Visibility = ArgumentAttribute.VisibilityType.EntryPointsOnly)]
        public string RowGroupColumnName = null;
    }
}