TrainerInfo introduction, ITrainerEx destruction

Author: TomFinley

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

@@ -34,6 +34,12 @@ namespace Microsoft.ML.Runtime
     /// </summary>
     public interface ITrainer
     {
+        /// <summary>
+        /// Auxiliary information about the trainer in terms of its capabilities
+        /// and requirements.
+        /// </summary>
+        TrainerInfo Info { get; }
+
         /// <summary>
         /// Return the type of prediction task for the produced predictor.
         /// </summary>
@@ -89,51 +95,6 @@ public static TPredictor Train<TPredictor>(this ITrainer<TPredictor> trainer, Ro
             => trainer.Train(new TrainContext(trainData));
     }
 
-    /// <summary>
-    /// Interface to provide extra information about a trainer.
-    /// </summary>
-    public interface ITrainerEx : ITrainer
-    {
-        // REVIEW: Ideally trainers should be able to communicate
-        // something about the type of data they are capable of being trained
-        // on, e.g., what ColumnKinds they want, how many of each, of what type,
-        // etc. This interface seems like the most natural conduit for that sort
-        // of extra information.
-
-        // REVIEW: Can we please have consistent naming here?
-        // 'Need' vs. 'Want' looks arbitrary to me, and it's grammatically more correct to
-        // be 'Needs' / 'Wants' anyway.
-
-        /// <summary>
-        /// Whether the trainer needs to see data in normalized form.
-        /// </summary>
-        bool NeedNormalization { get; }
-
-        /// <summary>
-        /// Whether the trainer needs calibration to produce probabilities.
-        /// </summary>
-        bool NeedCalibration { get; }
-
-        /// <summary>
-        /// Whether this trainer could benefit from a cached view of the data.
-        /// </summary>
-        bool WantCaching { get; }
-
-        /// <summary>
-        /// Whether the trainer supports validation sets via <see cref="TrainContext.ValidationSet"/>.
-        /// Not implementing this interface and returning <c>true</c> from this property is an indication
-        /// the trainer does not support that.
-        /// </summary>
-        bool SupportsValidation { get; }
-
-        /// <summary>
-        /// Whether the trainer can support incremental trainers via <see cref="TrainContext.InitialPredictor"/>.
-        /// Not implementing this interface and returning <c>true</c> from this property is an indication
-        /// the trainer does not support that.
-        /// </summary>
-        bool SupportsIncrementalTraining { get; }
-    }
-
     // A trainer can optionally implement this to indicate it can combine multiple models into a single predictor.
     public interface IModelCombiner<TModel, TPredictor>
         where TPredictor : IPredictor

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

@@ -0,0 +1,75 @@
+// 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.
+
+namespace Microsoft.ML.Runtime
+{
+    /// <summary>
+    /// Instances of this class posses information about trainers, in terms of their requirements and capabilities.
+    /// The intended usage is as the value for <see cref="ITrainer.Info"/>.
+    /// </summary>
+    public sealed class TrainerInfo
+    {
+        // REVIEW: Ideally trainers should be able to communicate
+        // something about the type of data they are capable of being trained
+        // on, e.g., what ColumnKinds they want, how many of each, of what type,
+        // etc. This interface seems like the most natural conduit for that sort
+        // of extra information.
+
+        // REVIEW: Can we please have consistent naming here?
+        // 'Need' vs. 'Want' looks arbitrary to me, and it's grammatically more correct to
+        // be 'Needs' / 'Wants' anyway.
+
+        /// <summary>
+        /// Whether the trainer needs to see data in normalized form. Only non-parametric learners will tend to produce
+        /// normalization here.
+        /// </summary>
+        public bool NeedNormalization { get; }
+
+        /// <summary>
+        /// Whether the trainer needs calibration to produce probabilities. As a general rule only trainers that produce
+        /// binary classifier predictors that also do not have a natural probabilistic interpretation should have a
+        /// <c>true</c> value here.
+        /// </summary>
+        public bool NeedCalibration { get; }
+
+        /// <summary>
+        /// Whether this trainer could benefit from a cached view of the data. Trainers that have few passes over the
+        /// data, or that need to build their own custom data structure over the data, will have a <c>false</c> here.
+        /// </summary>
+        public bool WantCaching { get; }
+
+        /// <summary>
+        /// Whether the trainer supports validation sets via <see cref="TrainContext.ValidationSet"/>. Not implementing
+        /// this interface and returning <c>true</c> from this property is an indication the trainer does not support
+        /// that.
+        /// </summary>
+        public bool SupportsValidation { get; }
+
+        /// <summary>
+        /// Whether the trainer can support incremental trainers via <see cref="TrainContext.InitialPredictor"/>. Not
+        /// implementing this interface and returning <c>true</c> from this property is an indication the trainer does
+        /// not support that.
+        /// </summary>
+        public bool SupportsIncrementalTraining { get; }
+
+        /// <summary>
+        /// Initializes with the given parameters. The parameters have default values for the most typical values
+        /// for most classical trainers.
+        /// </summary>
+        /// <param name="normalization">The value for the property <see cref="NeedNormalization"/></param>
+        /// <param name="calibration">The value for the property <see cref="NeedCalibration"/></param>
+        /// <param name="caching">The value for the property <see cref="WantCaching"/></param>
+        /// <param name="supportValid">The value for the property <see cref="SupportsValidation"/></param>
+        /// <param name="supportIncrementalTrain">The value for the property <see cref="SupportsIncrementalTraining"/></param>
+        public TrainerInfo(bool normalization = true, bool calibration = false, bool caching = true,
+            bool supportValid = false, bool supportIncrementalTrain = false)
+        {
+            NeedNormalization = normalization;
+            NeedCalibration = calibration;
+            WantCaching = caching;
+            SupportsValidation = supportValid;
+            SupportsIncrementalTraining = supportIncrementalTrain;
+        }
+    }
+}

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

@@ -538,7 +538,7 @@ private FoldResult RunFold(int fold)
                     if (_getValidationDataView != null)
                     {
                         ch.Assert(_applyTransformsToValidationData != null);
-                        if (!TrainUtils.CanUseValidationData(trainer))
+                        if (!trainer.Info.SupportsValidation)
                             ch.Warning("Trainer does not accept validation dataset.");
                         else
                         {

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

@@ -163,7 +163,7 @@ private void RunCore(IChannel ch, string cmd)
             RoleMappedData validData = null;
             if (!string.IsNullOrWhiteSpace(Args.ValidationFile))
             {
-                if (!TrainUtils.CanUseValidationData(trainer))
+                if (!trainer.Info.SupportsValidation)
                 {
                     ch.Warning("Ignoring validationFile: Trainer does not accept validation dataset.");
                 }
@@ -242,39 +242,32 @@ public static IPredictor Train(IHostEnvironment env, IChannel ch, RoleMappedData
         }
 
         private static IPredictor TrainCore(IHostEnvironment env, IChannel ch, RoleMappedData data, ITrainer trainer, string name, RoleMappedData validData,
-            ICalibratorTrainer calibrator, int maxCalibrationExamples, bool? cacheData, IPredictor inpPredictor = null)
+            ICalibratorTrainer calibrator, int maxCalibrationExamples, bool? cacheData, IPredictor inputPredictor = null)
         {
             Contracts.CheckValue(env, nameof(env));
             env.CheckValue(ch, nameof(ch));
             ch.CheckValue(data, nameof(data));
             ch.CheckValue(trainer, nameof(trainer));
             ch.CheckNonEmpty(name, nameof(name));
             ch.CheckValueOrNull(validData);
-            ch.CheckValueOrNull(inpPredictor);
+            ch.CheckValueOrNull(inputPredictor);
 
             AddCacheIfWanted(env, ch, trainer, ref data, cacheData);
             ch.Trace("Training");
             if (validData != null)
                 AddCacheIfWanted(env, ch, trainer, ref validData, cacheData);
 
-            var trainerEx = trainer as ITrainerEx;
-            if (inpPredictor != null && trainerEx?.SupportsIncrementalTraining != true)
+            if (inputPredictor != null && !trainer.Info.SupportsIncrementalTraining)
             {
                 ch.Warning("Ignoring " + nameof(TrainCommand.Arguments.InputModelFile) +
                     ": Trainer does not support incremental training.");
-                inpPredictor = null;
+                inputPredictor = null;
             }
-            ch.Assert(validData == null || CanUseValidationData(trainer));
-            var predictor = trainer.Train(new TrainContext(data, validData, inpPredictor));
+            ch.Assert(validData == null || trainer.Info.SupportsValidation);
+            var predictor = trainer.Train(new TrainContext(data, validData, inputPredictor));
             return CalibratorUtils.TrainCalibratorIfNeeded(env, ch, calibrator, maxCalibrationExamples, trainer, predictor, data);
         }
 
-        public static bool CanUseValidationData(ITrainer trainer)
-        {
-            Contracts.CheckValue(trainer, nameof(trainer));
-            return (trainer as ITrainerEx)?.SupportsValidation ?? false;
-        }
-
         public static bool TryLoadPredictor(IChannel ch, IHostEnvironment env, string inputModelFile, out IPredictor inputPredictor)
         {
             Contracts.AssertValue(env);
@@ -388,9 +381,8 @@ public static void SaveDataPipe(IHostEnvironment env, RepositoryWriter repositor
             IDataView pipeStart;
             var xfs = BacktrackPipe(dataPipe, out pipeStart);
 
-            IDataLoader loader;
             Action<ModelSaveContext> saveAction;
-            if (!blankLoader && (loader = pipeStart as IDataLoader) != null)
+            if (!blankLoader && pipeStart is IDataLoader loader)
                 saveAction = loader.Save;
             else
             {
@@ -460,7 +452,7 @@ public static bool AddNormalizerIfNeeded(IHostEnvironment env, IChannel ch, ITra
                 if (autoNorm != NormalizeOption.Yes)
                 {
                     DvBool isNormalized = DvBool.False;
-                    if (trainer.NeedNormalization() != true || schema.IsNormalized(featCol))
+                    if (!trainer.Info.NeedNormalization || schema.IsNormalized(featCol))
                     {
                         ch.Info("Not adding a normalizer.");
                         return false;
@@ -491,8 +483,7 @@ private static bool AddCacheIfWanted(IHostEnvironment env, IChannel ch, ITrainer
             ch.AssertValue(trainer, nameof(trainer));
             ch.AssertValue(data, nameof(data));
 
-            ITrainerEx trainerEx = trainer as ITrainerEx;
-            bool shouldCache = cacheData ?? (!(data.Data is BinaryLoader) && (trainerEx == null || trainerEx.WantCaching));
+            bool shouldCache = cacheData ?? !(data.Data is BinaryLoader) && trainer.Info.WantCaching;
 
             if (shouldCache)
             {

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

@@ -152,7 +152,7 @@ private void RunCore(IChannel ch, string cmd)
             RoleMappedData validData = null;
             if (!string.IsNullOrWhiteSpace(Args.ValidationFile))
             {
-                if (!TrainUtils.CanUseValidationData(trainer))
+                if (!trainer.Info.SupportsValidation)
                 {
                     ch.Warning("Ignoring validationFile: Trainer does not accept validation dataset.");
                 }

src/Microsoft.ML.Data/EntryPoints/InputBase.cs

@@ -164,9 +164,8 @@ public static TOut Train<TArg, TOut>(IHost host, TArg input,
                         }
                     case CachingOptions.Auto:
                         {
-                            ITrainerEx trainerEx = trainer as ITrainerEx;
                             // REVIEW: we should switch to hybrid caching in future.
-                            if (!(input.TrainingData is BinaryLoader) && (trainerEx == null || trainerEx.WantCaching))
+                            if (!(input.TrainingData is BinaryLoader) && trainer.Info.WantCaching)
                                 // default to Memory so mml is on par with maml
                                 cachingType = Cache.CachingType.Memory;
                             break;

src/Microsoft.ML.Data/Prediction/Calibrator.cs

@@ -687,8 +687,7 @@ public static class CalibratorUtils
         private static bool NeedCalibration(IHostEnvironment env, IChannel ch, ICalibratorTrainer calibrator,
             ITrainer trainer, IPredictor predictor, RoleMappedSchema schema)
         {
-            var trainerEx = trainer as ITrainerEx;
-            if (trainerEx == null || !trainerEx.NeedCalibration)
+            if (!trainer.Info.NeedCalibration)
             {
                 ch.Info("Not training a calibrator because it is not needed.");
                 return false;

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

@@ -4,7 +4,7 @@
 
 namespace Microsoft.ML.Runtime.Training
 {
-    public abstract class TrainerBase<TPredictor> : ITrainer<TPredictor>, ITrainerEx
+    public abstract class TrainerBase<TPredictor> : ITrainer<TPredictor>
         where TPredictor : IPredictor
     {
         /// <summary>
@@ -17,12 +17,7 @@ public abstract class TrainerBase<TPredictor> : ITrainer<TPredictor>, ITrainerEx
 
         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;
+        public abstract TrainerInfo Info { get; }
 
         protected TrainerBase(IHostEnvironment env, string name)
         {

src/Microsoft.ML.Data/Transforms/NormalizeTransform.cs

@@ -205,24 +205,21 @@ private NormalizeTransform(IHost host, ArgumentsBase args, IDataView input,
         /// </summary>
         /// <param name="env">The host environment to use to potentially instantiate the transform</param>
         /// <param name="data">The role-mapped data that is potentially going to be modified by this method.</param>
-        /// <param name="trainer">The trainer to query with <see cref="NormalizeUtils.NeedNormalization(ITrainer)"/>.
-        /// This method will not modify <paramref name="data"/> if the return from that is <c>null</c> or
-        /// <c>false</c>.</param>
+        /// <param name="trainer">The trainer to query as to whether it wants normalization. If the
+        /// <see cref="ITrainer.Info"/>'s <see cref="TrainerInfo.NeedNormalization"/> is <c>true</c></param>
         /// <returns>True if the normalizer was applied and <paramref name="data"/> was modified</returns>
         public static bool CreateIfNeeded(IHostEnvironment env, ref RoleMappedData data, ITrainer trainer)
         {
             Contracts.CheckValue(env, nameof(env));
             env.CheckValue(data, nameof(data));
             env.CheckValue(trainer, nameof(trainer));
 
-            // If this is false or null, we do not want to normalize.
-            if (trainer.NeedNormalization() != true)
-                return false;
-            // If this is true or null, we do not want to normalize.
-            if (data.Schema.FeaturesAreNormalized() != false)
+            // If the trainer does not need normalization, or if the features either don't exist
+            // or are not normalized, return false.
+            if (!trainer.Info.NeedNormalization || data.Schema.FeaturesAreNormalized() != false)
                 return false;
             var featInfo = data.Schema.Feature;
-            env.AssertValue(featInfo); // Should be defined, if FEaturesAreNormalized returned a definite value.
+            env.AssertValue(featInfo); // Should be defined, if FeaturesAreNormalized returned a definite value.
 
             var view = CreateMinMaxNormalizer(env, data.Data, name: featInfo.Name);
             data = new RoleMappedData(view, data.Schema.GetColumnRoleNames());
@@ -363,20 +360,6 @@ protected override Delegate GetGetterCore(IChannel ch, IRow input, int iinfo, ou
 
     public static class NormalizeUtils
     {
-        /// <summary>
-        /// Tells whether the trainer wants normalization.
-        /// </summary>
-        /// <remarks>This method works via testing whether the trainer implements the optional interface
-        /// <see cref="ITrainerEx"/>, via the Boolean <see cref="ITrainerEx.NeedNormalization"/> property.
-        /// If <paramref name="trainer"/> does not implement that interface, then we return <c>null</c></remarks>
-        /// <param name="trainer">The trainer to query</param>
-        /// <returns>Whether the trainer wants normalization</returns>
-        public static bool? NeedNormalization(this ITrainer trainer)
-        {
-            Contracts.CheckValue(trainer, nameof(trainer));
-            return (trainer as ITrainerEx)?.NeedNormalization;
-        }
-
         /// <summary>
         /// Returns whether the feature column in the schema is indicated to be normalized. If the features column is not
         /// specified on the schema, then this will return <c>null</c>.

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

@@ -188,7 +188,7 @@ public void Train(List<FeatureSubsetModel<IPredictorProducing<TOutput>>> models,
                 var rmd = new RoleMappedData(view, DefaultColumnNames.Label, DefaultColumnNames.Features);
 
                 var trainer = BasePredictorType.CreateInstance(host);
-                if (trainer is ITrainerEx ex && ex.NeedNormalization)
+                if (trainer.Info.NeedNormalization)
                     ch.Warning("The trainer specified for stacking wants normalization, but we do not currently allow this.");
                 Meta = trainer.Train(rmd);
                 CheckMeta();