Conversion of ITrainer.Train returns predictor, accepts +TrainContext

* `ITrainer.Train` returns a predictor. There is no `CreatePredictor` method
  on the interface.

* `ITrainer.Train` always accepts a `TrainContext`. Dataset type is no longer
  a generic parameter. This context object replaces the functionality
  previously offered by the combination of `ITrainer`, `IValidatingTrainer`,
  `IIncrementalTrainer`, and `IIncrementalValidatingTrainer`, which is now
  captured in one `ITrainer.Train` method with differently configured
  contexts.

* All trainers updated to these two new idioms. Many trainers correspondingly
  improved to no longer be stateful objects. (The exceptions are those that
  are just too far gone to be done with than herculean effort at refactoring
  them to no longer use instance fields for their computation, most notably,
  LBFGS and FastTree based trainers.)

* Utility code meant to deal with the complexity of the aforementioned
  `IT/IVT/IIT/IIVT` idiom reduced considerably.

* Opportunistic improvements to `ITrainer` implementors where observed.

Author: Tom Finley

src/Microsoft.ML.Core/Prediction/ITrainer.cs

@@ -2,9 +2,8 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 // See the LICENSE file in the project root for more information.
 
-using System;
 using System.Collections.Generic;
-using System.IO;
+using Microsoft.ML.Runtime.Data;
 
 namespace Microsoft.ML.Runtime
 {
@@ -56,15 +55,9 @@ public interface ITrainerEx : ITrainer
         /// Whether this trainer could benefit from a cached view of the data.
         /// </summary>
         bool WantCaching { get; }
-    }
-
-    public interface ITrainerHost
-    {
-        Random Rand { get; }
-        int Verbosity { get; }
 
-        TextWriter StdOut { get; }
-        TextWriter StdErr { get; }
+        bool SupportsValidation { get; }
+        bool SupportsIncrementalTraining { get; }
     }
 
     // The Trainer (of Factory) can optionally implement this.
@@ -77,7 +70,8 @@ public interface IModelCombiner<TModel, TPredictor>
     public delegate void SignatureModelCombiner(PredictionKind kind);
 
     /// <summary>
-    /// Weakly typed interface for a trainer "session" that produces a predictor.
+    /// The base interface for a trainers. Implementors should not implement this interface directly,
+    /// but rather implement the more specific <see cref="ITrainer{TPredictor}"/>.
     /// </summary>
     public interface ITrainer
     {
@@ -87,91 +81,60 @@ public interface ITrainer
         PredictionKind PredictionKind { get; }
 
         /// <summary>
-        ///  Returns the trained predictor.
-        ///  REVIEW: Consider removing this.
-        /// </summary>
-        IPredictor CreatePredictor();
-    }
-
-    /// <summary>
-    /// Interface implemented by the MetalinearLearners base class.
-    /// Used to distinguish the MetaLinear Learners from the other learners
-    /// </summary>
-    public interface IMetaLinearTrainer
-    {
-
-    }
-
-    public interface ITrainer<in TDataSet> : ITrainer
-    {
-        /// <summary>
-        /// Trains a predictor using the specified dataset.
+        ///  Trains a predictor.
         /// </summary>
-        /// <param name="data"> Training dataset </param>
-        void Train(TDataSet data);
+        /// <param name="context">A context containing at least the training data</param>
+        /// <returns>The trained predictor</returns>
+        /// <seealso cref="ITrainer{TPredictor}.Train(TrainContext)"/>
+        IPredictor Train(TrainContext context);
     }
 
     /// <summary>
-    /// Strongly typed generic interface for a trainer. A trainer object takes
-    /// supervision data and produces a predictor.
+    /// Strongly typed generic interface for a trainer. A trainer object takes training data
+    /// and produces a predictor.
     /// </summary>
-    /// <typeparam name="TDataSet"> Type of the training dataset</typeparam>
     /// <typeparam name="TPredictor"> Type of predictor produced</typeparam>
-    public interface ITrainer<in TDataSet, out TPredictor> : ITrainer<TDataSet>
+    public interface ITrainer<out TPredictor> : ITrainer
         where TPredictor : IPredictor
     {
         /// <summary>
-        ///  Returns the trained predictor.
+        ///  Trains a predictor.
         /// </summary>
-        /// <returns>Trained predictor ready to make predictions</returns>
-        new TPredictor CreatePredictor();
+        /// <param name="context">A context containing at least the training data</param>
+        /// <returns>The trained predictor</returns>
+        new TPredictor Train(TrainContext context);
     }
 
-    /// <summary>
-    /// Trainers that want data to do their own validation implement this interface.
-    /// </summary>
-    public interface IValidatingTrainer<in TDataSet> : ITrainer<TDataSet>
+    public static class TrainerExtensions
     {
         /// <summary>
-        /// Trains a predictor using the specified dataset.
+        /// Convenience train extension for the case where one has only a training set with no auxiliary information.
+        /// Equivalent to calling <see cref="ITrainer.Train(TrainContext)"/>
+        /// on a <see cref="TrainContext"/> constructed with <paramref name="trainData"/>.
         /// </summary>
-        /// <param name="data">Training dataset</param>
-        /// <param name="validData">Validation dataset</param>
-        void Train(TDataSet data, TDataSet validData);
-    }
+        /// <param name="trainer">The trainer</param>
+        /// <param name="trainData">The training data.</param>
+        /// <returns>The trained predictor</returns>
+        public static IPredictor Train(this ITrainer trainer, RoleMappedData trainData)
+            => trainer.Train(new TrainContext(trainData));
 
-    public interface IIncrementalTrainer<in TDataSet, in TPredictor> : ITrainer<TDataSet>
-    {
-        /// <summary>
-        /// Trains a predictor using the specified dataset and a trained predictor.
-        /// </summary>
-        /// <param name="data">Training dataset</param>
-        /// <param name="predictor">A trained predictor</param>
-        void Train(TDataSet data, TPredictor predictor);
-    }
-
-    public interface IIncrementalValidatingTrainer<in TDataSet, in TPredictor> : ITrainer<TDataSet>
-    {
         /// <summary>
-        /// Trains a predictor using the specified dataset and a trained predictor.
+        /// Convenience train extension for the case where one has only a training set with no auxiliary information.
+        /// Equivalent to calling <see cref="ITrainer{TPredictor}.Train(TrainContext)"/>
+        /// on a <see cref="TrainContext"/> constructed with <paramref name="trainData"/>.
         /// </summary>
-        /// <param name="data">Training dataset</param>
-        /// <param name="validData">Validation dataset</param>
-        /// <param name="predictor">A trained predictor</param>
-        void Train(TDataSet data, TDataSet validData, TPredictor predictor);
+        /// <param name="trainer">The trainer</param>
+        /// <param name="trainData">The training data.</param>
+        /// <returns>The trained predictor</returns>
+        public static TPredictor Train<TPredictor>(this ITrainer<TPredictor> trainer, RoleMappedData trainData) where TPredictor : IPredictor
+            => trainer.Train(new TrainContext(trainData));
     }
 
-#if FUTURE
-    public interface IMultiTrainer<in TDataSet, in TFeatures, out TResult> :
-        IMultiTrainer<TDataSet, TDataSet, TFeatures, TResult>
-    {
-    }
-
-    public interface IMultiTrainer<in TDataSet, in TDataBatch, in TFeatures, out TResult> :
-        ITrainer<TDataSet, TFeatures, TResult>
+    /// <summary>
+    /// Interface implemented by the MetalinearLearners base class.
+    /// Used to distinguish the MetaLinear Learners from the other learners
+    /// </summary>
+    public interface IMetaLinearTrainer
     {
-        void UpdatePredictor(TDataBatch trainInstance);
-        IPredictor<TFeatures, TResult> GetCurrentPredictor();
     }
-#endif
 }

src/Microsoft.ML.Core/Prediction/TrainContext.cs

@@ -0,0 +1,50 @@
+// 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.Runtime.Data;
+
+namespace Microsoft.ML.Runtime
+{
+    /// <summary>
+    /// Instances of this class are meant to be constructed and passed to trainers.
+    /// </summary>
+    public sealed class TrainContext
+    {
+        /// <summary>
+        /// The training set. Cannot be <c>null</c>.
+        /// </summary>
+        public RoleMappedData Train { get; }
+
+        /// <summary>
+        /// The validation set. Can be <c>null</c>.
+        /// </summary>
+        public RoleMappedData Validation { get; }
+
+        /// <summary>
+        /// The initial 
+        /// </summary>
+        public IPredictor InitialPredictor { get; }
+
+
+        /// <summary>
+        /// Constructor, given a training set and optional other arguments.
+        /// </summary>
+        /// <param name="train">Will be set to <see cref="Train"/>, must be specified</param>
+        /// <param name="valid">Will be set to <see cref="Validation"/> if specified</param>
+        /// <param name="initPredictor">Will be set to <see cref="InitialPredictor"/> if specified</param>
+        public TrainContext(RoleMappedData train, RoleMappedData valid = null, IPredictor initPredictor = null)
+        {
+            Contracts.CheckValue(train, nameof(train));
+            Contracts.CheckValueOrNull(valid);
+            Contracts.CheckValueOrNull(initPredictor);
+
+            // REVIEW: Should there be code here to ensure that the role mappings between the two are compatible?
+            // That is, all the role mappings are the same and the columns between them have identical types?
+
+            Train = train;
+            Validation = valid;
+            InitialPredictor = initPredictor;
+        }
+    }
+}

src/Microsoft.ML.Data/Commands/TrainCommand.cs

@@ -252,77 +252,27 @@ private static IPredictor TrainCore(IHostEnvironment env, IChannel ch, RoleMappe
             ch.CheckValueOrNull(validData);
             ch.CheckValueOrNull(inpPredictor);
 
-            var trainerRmd = trainer as ITrainer<RoleMappedData>;
-            if (trainerRmd == null)
-                throw ch.ExceptUserArg(nameof(TrainCommand.Arguments.Trainer), "Trainer '{0}' does not accept known training data type", name);
-
-            Action<IChannel, ITrainer, Action<object>, object, object, object> trainCoreAction = TrainCore;
-            IPredictor predictor;
             AddCacheIfWanted(env, ch, trainer, ref data, cacheData);
             ch.Trace("Training");
             if (validData != null)
                 AddCacheIfWanted(env, ch, trainer, ref validData, cacheData);
 
-            var genericExam = trainCoreAction.GetMethodInfo().GetGenericMethodDefinition().MakeGenericMethod(
-                typeof(RoleMappedData),
-                inpPredictor != null ? inpPredictor.GetType() : typeof(IPredictor));
-            Action<RoleMappedData> trainExam = trainerRmd.Train;
-            genericExam.Invoke(null, new object[] { ch, trainerRmd, trainExam, data, validData, inpPredictor });
-
-            ch.Trace("Constructing predictor");
-            predictor = trainerRmd.CreatePredictor();
+            var trainerEx = trainer as ITrainerEx;
+            if (inpPredictor != null && trainerEx?.SupportsIncrementalTraining != true)
+            {
+                ch.Warning("Ignoring " + nameof(TrainCommand.Arguments.InputModelFile) +
+                    ": Trainer does not support incremental training.");
+                inpPredictor = null;
+            }
+            ch.Assert(validData == null || CanUseValidationData(trainer));
+            var predictor = trainer.Train(new TrainContext(data, validData, inpPredictor));
             return CalibratorUtils.TrainCalibratorIfNeeded(env, ch, calibrator, maxCalibrationExamples, trainer, predictor, data);
         }
 
         public static bool CanUseValidationData(ITrainer trainer)
         {
             Contracts.CheckValue(trainer, nameof(trainer));
-
-            if (trainer is ITrainer<RoleMappedData>)
-                return trainer is IValidatingTrainer<RoleMappedData>;
-
-            return false;
-        }
-
-        private static void TrainCore<TDataSet, TPredictor>(IChannel ch, ITrainer trainer, Action<TDataSet> train, TDataSet data, TDataSet validData = null, TPredictor predictor = null)
-            where TDataSet : class
-            where TPredictor : class
-        {
-            const string inputModelArg = nameof(TrainCommand.Arguments.InputModelFile);
-            if (validData != null)
-            {
-                if (predictor != null)
-                {
-                    var incValidTrainer = trainer as IIncrementalValidatingTrainer<TDataSet, TPredictor>;
-                    if (incValidTrainer != null)
-                    {
-                        incValidTrainer.Train(data, validData, predictor);
-                        return;
-                    }
-
-                    ch.Warning("Ignoring " + inputModelArg + ": Trainer is not an incremental trainer.");
-                }
-
-                var validTrainer = trainer as IValidatingTrainer<TDataSet>;
-                ch.AssertValue(validTrainer);
-                validTrainer.Train(data, validData);
-            }
-            else
-            {
-                if (predictor != null)
-                {
-                    var incTrainer = trainer as IIncrementalTrainer<TDataSet, TPredictor>;
-                    if (incTrainer != null)
-                    {
-                        incTrainer.Train(data, predictor);
-                        return;
-                    }
-
-                    ch.Warning("Ignoring " + inputModelArg + ": Trainer is not an incremental trainer.");
-                }
-
-                train(data);
-            }
+            return (trainer as ITrainerEx)?.SupportsValidation ?? false;
         }
 
         public static bool TryLoadPredictor(IChannel ch, IHostEnvironment env, string inputModelFile, out IPredictor inputPredictor)

src/Microsoft.ML.Data/Training/TrainerBase.cs

@@ -4,59 +4,33 @@
 
 namespace Microsoft.ML.Runtime.Training
 {
-    public abstract class TrainerBase : ITrainer, ITrainerEx
+    public abstract class TrainerBase<TPredictor> : ITrainer<TPredictor>, ITrainerEx
+        where TPredictor : IPredictor
     {
         public const string NoTrainingInstancesMessage = "No valid training instances found, all instances have missing features.";
 
-        protected readonly IHost Host;
+        protected IHost Host { get; }
 
         public string Name { get; }
         public abstract PredictionKind PredictionKind { get; }
         public abstract bool NeedNormalization { get; }
         public abstract bool NeedCalibration { get; }
         public abstract bool WantCaching { get; }
 
+        public virtual bool SupportsValidation => false;
+        public virtual bool SupportsIncrementalTraining => false;
+
         protected TrainerBase(IHostEnvironment env, string name)
         {
             Contracts.CheckValue(env, nameof(env));
-            Contracts.CheckNonEmpty(name, nameof(name));
+            env.CheckNonEmpty(name, nameof(name));
 
             Name = name;
             Host = env.Register(name);
         }
 
-        IPredictor ITrainer.CreatePredictor()
-        {
-            return CreatePredictorCore();
-        }
-
-        protected abstract IPredictor CreatePredictorCore();
-    }
-
-    public abstract class TrainerBase<TPredictor> : TrainerBase
-        where TPredictor : IPredictor
-    {
-        protected TrainerBase(IHostEnvironment env, string name)
-            : base(env, name)
-        {
-        }
-
-        public abstract TPredictor CreatePredictor();
-
-        protected sealed override IPredictor CreatePredictorCore()
-        {
-            return CreatePredictor();
-        }
-    }
-
-    public abstract class TrainerBase<TDataSet, TPredictor> : TrainerBase<TPredictor>, ITrainer<TDataSet, TPredictor>
-        where TPredictor : IPredictor
-    {
-        protected TrainerBase(IHostEnvironment env, string name)
-            : base(env, name)
-        {
-        }
+        IPredictor ITrainer.Train(TrainContext context) => Train(context);
 
-        public abstract void Train(TDataSet data);
+        public abstract TPredictor Train(TrainContext context);
     }
 }

src/Microsoft.ML.Ensemble/OutputCombiners/BaseStacking.cs

@@ -27,10 +27,10 @@ public abstract class ArgumentsBase
             [Argument(ArgumentType.Multiple, HelpText = "Base predictor for meta learning", ShortName = "bp", SortOrder = 50,
                 Visibility = ArgumentAttribute.VisibilityType.CmdLineOnly)]
             [TGUI(Label = "Base predictor")]
-            public SubComponent<ITrainer<RoleMappedData, IPredictorProducing<TOutput>>, TSigBase> BasePredictorType;
+            public SubComponent<ITrainer<IPredictorProducing<TOutput>>, TSigBase> BasePredictorType;
         }
 
-        protected readonly SubComponent<ITrainer<RoleMappedData, IPredictorProducing<TOutput>>, TSigBase> BasePredictorType;
+        protected readonly SubComponent<ITrainer<IPredictorProducing<TOutput>>, TSigBase> BasePredictorType;
         protected readonly IHost Host;
         protected IPredictorProducing<TOutput> Meta;
 
@@ -190,8 +190,7 @@ public void Train(List<FeatureSubsetModel<IPredictorProducing<TOutput>>> models,
                 var trainer = BasePredictorType.CreateInstance(host);
                 if (trainer is ITrainerEx ex && ex.NeedNormalization)
                     ch.Warning("The trainer specified for stacking wants normalization, but we do not currently allow this.");
-                trainer.Train(rmd);
-                Meta = trainer.CreatePredictor();
+                Meta = trainer.Train(rmd);
                 CheckMeta();
 
                 ch.Done();