Towards dotnet#1798 .

This PR addresses the estimators inside HalLearners:

Two public extension methods, one for simple arguments and the other for advanced options
Delete unecessary constructors
Pass Options objects as arguments instead of Action delegate
Rename Arguments to Options
Rename Options objects as options (instead of args or advancedSettings used so far)

Author: sfilipi

src/Microsoft.ML.HalLearners/HalLearnersCatalog.cs

@@ -4,6 +4,7 @@
 
 using System;
 using Microsoft.ML.Data;
+using Microsoft.ML.EntryPoints;
 using Microsoft.ML.Trainers.HalLearners;
 using Microsoft.ML.Trainers.SymSgd;
 using Microsoft.ML.Transforms.Projections;
@@ -22,16 +23,36 @@ public static class HalLearnersCatalog
         /// <param name="labelColumn">The labelColumn column.</param>
         /// <param name="featureColumn">The features column.</param>
         /// <param name="weights">The weights column.</param>
-        /// <param name="advancedSettings">Algorithm advanced settings.</param>
         public static OlsLinearRegressionTrainer OrdinaryLeastSquares(this RegressionContext.RegressionTrainers ctx,
             string labelColumn = DefaultColumnNames.Label,
             string featureColumn = DefaultColumnNames.Features,
-            string weights = null,
-            Action<OlsLinearRegressionTrainer.Arguments> advancedSettings = null)
+            string weights = null)
+        {
+            Contracts.CheckValue(ctx, nameof(ctx));
+            var env = CatalogUtils.GetEnvironment(ctx);
+            var options = new OlsLinearRegressionTrainer.Options
+            {
+                LabelColumn = labelColumn,
+                FeatureColumn = featureColumn,
+                WeightColumn = weights != null ? Optional<string>.Explicit(weights) : Optional<string>.Implicit(DefaultColumnNames.Weight)
+            };
+
+            return new OlsLinearRegressionTrainer(env, options);
+        }
+
+        /// <summary>
+        /// Predict a target using a linear regression model trained with the <see cref="OlsLinearRegressionTrainer"/>.
+        /// </summary>
+        /// <param name="ctx">The <see cref="RegressionContext"/>.</param>
+        /// <param name="options">Algorithm advanced options.</param>
+        public static OlsLinearRegressionTrainer OrdinaryLeastSquares(this RegressionContext.RegressionTrainers ctx,
+            OlsLinearRegressionTrainer.Options options)
         {
             Contracts.CheckValue(ctx, nameof(ctx));
+            Contracts.CheckValue(options, nameof(options));
+
             var env = CatalogUtils.GetEnvironment(ctx);
-            return new OlsLinearRegressionTrainer(env, labelColumn, featureColumn, weights, advancedSettings);
+            return new OlsLinearRegressionTrainer(env, options);
         }
 
         /// <summary>
@@ -44,11 +65,31 @@ public static OlsLinearRegressionTrainer OrdinaryLeastSquares(this RegressionCon
         public static SymSgdClassificationTrainer SymbolicStochasticGradientDescent(this BinaryClassificationContext.BinaryClassificationTrainers ctx,
             string labelColumn = DefaultColumnNames.Label,
             string featureColumn = DefaultColumnNames.Features,
-            Action<SymSgdClassificationTrainer.Arguments> advancedSettings = null)
+            Action<SymSgdClassificationTrainer.Options> advancedSettings = null)
+        {
+            Contracts.CheckValue(ctx, nameof(ctx));
+            var env = CatalogUtils.GetEnvironment(ctx);
+            var options = new SymSgdClassificationTrainer.Options
+            {
+                LabelColumn = labelColumn,
+                FeatureColumn = featureColumn,
+            };
+
+            return new SymSgdClassificationTrainer(env, options);
+        }
+
+        /// <summary>
+        ///  Predict a target using a linear binary classification model trained with the <see cref="SymSgdClassificationTrainer"/>.
+        /// </summary>
+        /// <param name="ctx">The <see cref="BinaryClassificationContext"/>.</param>
+        /// <param name="options">Algorithm advanced options.</param>
+        public static SymSgdClassificationTrainer SymbolicStochasticGradientDescent(this BinaryClassificationContext.BinaryClassificationTrainers ctx,
+            SymSgdClassificationTrainer.Options options)
         {
             Contracts.CheckValue(ctx, nameof(ctx));
+            Contracts.CheckValue(options, nameof(options));
             var env = CatalogUtils.GetEnvironment(ctx);
-            return new SymSgdClassificationTrainer(env, labelColumn, featureColumn, advancedSettings);
+            return new SymSgdClassificationTrainer(env, options);
         }
 
         /// <summary>

src/Microsoft.ML.HalLearners/OlsLinearRegression.cs

@@ -19,7 +19,7 @@
 using Microsoft.ML.Trainers.HalLearners;
 using Microsoft.ML.Training;
 
-[assembly: LoadableClass(OlsLinearRegressionTrainer.Summary, typeof(OlsLinearRegressionTrainer), typeof(OlsLinearRegressionTrainer.Arguments),
+[assembly: LoadableClass(OlsLinearRegressionTrainer.Summary, typeof(OlsLinearRegressionTrainer), typeof(OlsLinearRegressionTrainer.Options),
     new[] { typeof(SignatureRegressorTrainer), typeof(SignatureTrainer), typeof(SignatureFeatureScorerTrainer) },
     OlsLinearRegressionTrainer.UserNameValue,
     OlsLinearRegressionTrainer.LoadNameValue,
@@ -34,9 +34,10 @@
 namespace Microsoft.ML.Trainers.HalLearners
 {
     /// <include file='doc.xml' path='doc/members/member[@name="OLS"]/*' />
+    [BestFriend]
     public sealed class OlsLinearRegressionTrainer : TrainerEstimatorBase<RegressionPredictionTransformer<OlsLinearRegressionModelParameters>, OlsLinearRegressionModelParameters>
     {
-        public sealed class Arguments : LearnerInputBaseWithWeight
+        public sealed class Options : LearnerInputBaseWithWeight
         {
             // Adding L2 regularization turns this into a form of ridge regression,
             // rather than, strictly speaking, ordinary least squares. But it is an
@@ -46,13 +47,16 @@ public sealed class Arguments : LearnerInputBaseWithWeight
             [TlcModule.SweepableDiscreteParamAttribute("L2Weight", new object[] { 1e-6f, 0.1f, 1f })]
             public float L2Weight = 1e-6f;
 
+            /// <summary>
+            /// Whether to calculate per parameter significance statistics.
+            /// </summary>
             [Argument(ArgumentType.LastOccurenceWins, HelpText = "Whether to calculate per parameter significance statistics", ShortName = "sig")]
             public bool PerParameterSignificance = true;
         }
 
-        public const string LoadNameValue = "OLSLinearRegression";
-        public const string UserNameValue = "Ordinary Least Squares (Regression)";
-        public const string ShortName = "ols";
+        internal const string LoadNameValue = "OLSLinearRegression";
+        internal const string UserNameValue = "Ordinary Least Squares (Regression)";
+        internal const string ShortName = "ols";
         internal const string Summary = "The ordinary least square regression fits the target function as a linear function of the numerical features "
             + "that minimizes the square loss function.";
 
@@ -68,24 +72,7 @@ public sealed class Arguments : LearnerInputBaseWithWeight
         /// <summary>
         /// Initializes a new instance of <see cref="OlsLinearRegressionTrainer"/>
         /// </summary>
-        /// <param name="env">The environment to use.</param>
-        /// <param name="labelColumn">The name of the labelColumn column.</param>
-        /// <param name="featureColumn">The name of the feature column.</param>
-        /// <param name="weights">The name for the optional example weight column.</param>
-        /// <param name="advancedSettings">A delegate to apply all the advanced arguments to the algorithm.</param>
-        public OlsLinearRegressionTrainer(IHostEnvironment env,
-            string labelColumn = DefaultColumnNames.Label,
-            string featureColumn = DefaultColumnNames.Features,
-            string weights = null,
-            Action<Arguments> advancedSettings = null)
-            : this(env, ArgsInit(featureColumn, labelColumn, weights, advancedSettings))
-        {
-        }
-
-        /// <summary>
-        /// Initializes a new instance of <see cref="OlsLinearRegressionTrainer"/>
-        /// </summary>
-        internal OlsLinearRegressionTrainer(IHostEnvironment env, Arguments args)
+        internal OlsLinearRegressionTrainer(IHostEnvironment env, Options args)
             : base(Contracts.CheckRef(env, nameof(env)).Register(LoadNameValue), TrainerUtils.MakeR4VecFeature(args.FeatureColumn),
                   TrainerUtils.MakeR4ScalarColumn(args.LabelColumn), TrainerUtils.MakeR4ScalarWeightColumn(args.WeightColumn))
         {
@@ -95,21 +82,6 @@ internal OlsLinearRegressionTrainer(IHostEnvironment env, Arguments args)
             _perParameterSignificance = args.PerParameterSignificance;
         }
 
-        private static Arguments ArgsInit(string featureColumn,
-            string labelColumn,
-            string weightColumn,
-            Action<Arguments> advancedSettings)
-        {
-            var args = new Arguments();
-
-            // Apply the advanced args, if the user supplied any.
-            advancedSettings?.Invoke(args);
-            args.FeatureColumn = featureColumn;
-            args.LabelColumn = labelColumn;
-            args.WeightColumn = weightColumn != null ? Optional<string>.Explicit(weightColumn) : Optional<string>.Implicit(DefaultColumnNames.Weight);
-            return args;
-        }
-
         protected override RegressionPredictionTransformer<OlsLinearRegressionModelParameters> MakeTransformer(OlsLinearRegressionModelParameters model, Schema trainSchema)
              => new RegressionPredictionTransformer<OlsLinearRegressionModelParameters>(Host, model, trainSchema, FeatureColumn.Name);
 
@@ -518,14 +490,14 @@ public static void Pptri(Layout layout, UpLo uplo, int n, Double[] ap)
             UserName = UserNameValue,
             ShortName = ShortName,
             XmlInclude = new[] { @"<include file='../Microsoft.ML.HalLearners/doc.xml' path='doc/members/member[@name=""OLS""]/*' />" })]
-        public static CommonOutputs.RegressionOutput TrainRegression(IHostEnvironment env, Arguments input)
+        public static CommonOutputs.RegressionOutput TrainRegression(IHostEnvironment env, Options input)
         {
             Contracts.CheckValue(env, nameof(env));
             var host = env.Register("TrainOLS");
             host.CheckValue(input, nameof(input));
             EntryPointUtils.CheckInputArgs(host, input);
 
-            return LearnerEntryPointsUtils.Train<Arguments, CommonOutputs.RegressionOutput>(host, input,
+            return LearnerEntryPointsUtils.Train<Options, CommonOutputs.RegressionOutput>(host, input,
                 () => new OlsLinearRegressionTrainer(host, input),
                 () => LearnerEntryPointsUtils.FindColumn(host, input.TrainingData.Schema, input.LabelColumn),
                 () => LearnerEntryPointsUtils.FindColumn(host, input.TrainingData.Schema, input.WeightColumn));
@@ -579,7 +551,7 @@ private static VersionInfo GetVersionInfo()
         /// are all null. A model may not have per parameter statistics because either
         /// there were not more examples than parameters in the model, or because they
         /// were explicitly suppressed in training by setting
-        /// <see cref="OlsLinearRegressionTrainer.Arguments.PerParameterSignificance"/>
+        /// <see cref="OlsLinearRegressionTrainer.Options.PerParameterSignificance"/>
         /// to false.
         /// </summary>
         public bool HasStatistics => _standardErrors != null;

src/Microsoft.ML.HalLearners/Properties/AssemblyInfo.cs

@@ -5,6 +5,8 @@
 using System.Runtime.CompilerServices;
 using Microsoft.ML;
 
+[assembly: InternalsVisibleTo(assemblyName: "Microsoft.ML.Tests" + PublicKey.TestValue)]
+
 [assembly: InternalsVisibleTo(assemblyName: "Microsoft.ML.HalLearners.StaticPipe" + PublicKey.Value)]
 
 [assembly: InternalsVisibleTo(assemblyName: "RunTests" + InternalPublicKey.Value)]

src/Microsoft.ML.HalLearners/SymSgdClassificationTrainer.cs

@@ -20,7 +20,7 @@
 using Microsoft.ML.Training;
 using Microsoft.ML.Transforms;
 
-[assembly: LoadableClass(typeof(SymSgdClassificationTrainer), typeof(SymSgdClassificationTrainer.Arguments),
+[assembly: LoadableClass(typeof(SymSgdClassificationTrainer), typeof(SymSgdClassificationTrainer.Options),
     new[] { typeof(SignatureBinaryClassifierTrainer), typeof(SignatureTrainer), typeof(SignatureFeatureScorerTrainer) },
     SymSgdClassificationTrainer.UserNameValue,
     SymSgdClassificationTrainer.LoadNameValue,
@@ -33,48 +33,78 @@ namespace Microsoft.ML.Trainers.SymSgd
     using TPredictor = IPredictorWithFeatureWeights<float>;
 
     /// <include file='doc.xml' path='doc/members/member[@name="SymSGD"]/*' />
+    [BestFriend]
     public sealed class SymSgdClassificationTrainer : TrainerEstimatorBase<BinaryPredictionTransformer<TPredictor>, TPredictor>
     {
         internal const string LoadNameValue = "SymbolicSGD";
         internal const string UserNameValue = "Symbolic SGD (binary)";
         internal const string ShortName = "SymSGD";
 
-        public sealed class Arguments : LearnerInputBaseWithLabel
+        public sealed class Options : LearnerInputBaseWithLabel
         {
+            /// <summary>
+            /// Degree of lock-free parallelism. Determinism not guaranteed.
+            /// Multi-threading is not supported currently.
+            /// </summary>
             [Argument(ArgumentType.AtMostOnce, HelpText = "Degree of lock-free parallelism. Determinism not guaranteed. " +
                 "Multi-threading is not supported currently.", ShortName = "nt")]
             public int? NumberOfThreads;
 
+            /// <summary>
+            /// Number of passes over the data.
+            /// </summary>
             [Argument(ArgumentType.AtMostOnce, HelpText = "Number of passes over the data.", ShortName = "iter", SortOrder = 50)]
             [TGUI(SuggestedSweeps = "1,5,10,20,30,40,50")]
             [TlcModule.SweepableDiscreteParam("NumberOfIterations", new object[] { 1, 5, 10, 20, 30, 40, 50 })]
             public int NumberOfIterations = 50;
 
+            /// <summary>
+            /// Tolerance for difference in average loss in consecutive passes.
+            /// </summary>
             [Argument(ArgumentType.AtMostOnce, HelpText = "Tolerance for difference in average loss in consecutive passes.", ShortName = "tol")]
             public float Tolerance = 1e-4f;
 
+            /// <summary>
+            /// Learning rate.
+            /// </summary>
             [Argument(ArgumentType.AtMostOnce, HelpText = "Learning rate", ShortName = "lr", NullName = "<Auto>", SortOrder = 51)]
             [TGUI(SuggestedSweeps = "<Auto>,1e1,1e0,1e-1,1e-2,1e-3")]
             [TlcModule.SweepableDiscreteParam("LearningRate", new object[] { "<Auto>", 1e1f, 1e0f, 1e-1f, 1e-2f, 1e-3f })]
             public float? LearningRate;
 
+            /// <summary>
+            /// L2 regularization.
+            /// </summary>
             [Argument(ArgumentType.AtMostOnce, HelpText = "L2 regularization", ShortName = "l2", SortOrder = 52)]
             [TGUI(SuggestedSweeps = "0.0,1e-5,1e-5,1e-6,1e-7")]
             [TlcModule.SweepableDiscreteParam("L2Regularization", new object[] { 0.0f, 1e-5f, 1e-5f, 1e-6f, 1e-7f })]
             public float L2Regularization;
 
+            /// <summary>
+            /// The number of iterations each thread learns a local model until combining it with the
+            /// global model. Low value means more updated global model and high value means less cache traffic.
+            /// </summary>
             [Argument(ArgumentType.AtMostOnce, HelpText = "The number of iterations each thread learns a local model until combining it with the " +
                 "global model. Low value means more updated global model and high value means less cache traffic.", ShortName = "freq", NullName = "<Auto>")]
             [TGUI(SuggestedSweeps = "<Auto>,5,20")]
             [TlcModule.SweepableDiscreteParam("UpdateFrequency", new object[] { "<Auto>", 5, 20 })]
             public int? UpdateFrequency;
 
+            /// <summary>
+            /// The acceleration memory budget in MB.
+            /// </summary>
             [Argument(ArgumentType.AtMostOnce, HelpText = "The acceleration memory budget in MB", ShortName = "accelMemBudget")]
             public long MemorySize = 1024;
 
+            /// <summary>
+            /// Set to <see langword="true" /> causes the data to shuffle.
+            /// </summary>
             [Argument(ArgumentType.AtMostOnce, HelpText = "Shuffle data?", ShortName = "shuf")]
             public bool Shuffle = true;
 
+            /// <summary>
+            /// Apply weight to the positive class, for imbalanced data.
+            /// </summary>
             [Argument(ArgumentType.AtMostOnce, HelpText = "Apply weight to the positive class, for imbalanced data", ShortName = "piw")]
             public float PositiveInstanceWeight = 1;
 
@@ -88,7 +118,7 @@ public void Check(IExceptionContext ectx)
         }
 
         public override TrainerInfo Info { get; }
-        private readonly Arguments _args;
+        private readonly Options _args;
 
         /// <summary>
         /// This method ensures that the data meets the requirements of this trainer and its
@@ -152,32 +182,7 @@ private protected override TPredictor TrainModelCore(TrainContext context)
         /// <summary>
         /// Initializes a new instance of <see cref="SymSgdClassificationTrainer"/>
         /// </summary>
-        /// <param name="env">The private instance of <see cref="IHostEnvironment"/>.</param>
-        /// <param name="labelColumn">The name of the label column.</param>
-        /// <param name="featureColumn">The name of the feature column.</param>
-        /// <param name="advancedSettings">A delegate to apply all the advanced arguments to the algorithm.</param>
-        public SymSgdClassificationTrainer(IHostEnvironment env,
-            string labelColumn = DefaultColumnNames.Label,
-            string featureColumn = DefaultColumnNames.Features,
-            Action<Arguments> advancedSettings = null)
-            : base(Contracts.CheckRef(env, nameof(env)).Register(LoadNameValue), TrainerUtils.MakeR4VecFeature(featureColumn),
-                  TrainerUtils.MakeBoolScalarLabel(labelColumn))
-        {
-            _args = new Arguments();
-
-            // Apply the advanced args, if the user supplied any.
-            _args.Check(Host);
-            advancedSettings?.Invoke(_args);
-            _args.FeatureColumn = featureColumn;
-            _args.LabelColumn = labelColumn;
-
-            Info = new TrainerInfo(supportIncrementalTrain: true);
-        }
-
-        /// <summary>
-        /// Initializes a new instance of <see cref="SymSgdClassificationTrainer"/>
-        /// </summary>
-        internal SymSgdClassificationTrainer(IHostEnvironment env, Arguments args)
+        internal SymSgdClassificationTrainer(IHostEnvironment env, Options args)
             : base(Contracts.CheckRef(env, nameof(env)).Register(LoadNameValue), TrainerUtils.MakeR4VecFeature(args.FeatureColumn),
                   TrainerUtils.MakeBoolScalarLabel(args.LabelColumn))
         {
@@ -218,14 +223,14 @@ protected override SchemaShape.Column[] GetOutputColumnsCore(SchemaShape inputSc
             UserName = SymSgdClassificationTrainer.UserNameValue,
             ShortName = SymSgdClassificationTrainer.ShortName,
             XmlInclude = new[] { @"<include file='../Microsoft.ML.HalLearners/doc.xml' path='doc/members/member[@name=""SymSGD""]/*' />" })]
-        public static CommonOutputs.BinaryClassificationOutput TrainSymSgd(IHostEnvironment env, Arguments input)
+        public static CommonOutputs.BinaryClassificationOutput TrainSymSgd(IHostEnvironment env, Options input)
         {
             Contracts.CheckValue(env, nameof(env));
             var host = env.Register("TrainSymSGD");
             host.CheckValue(input, nameof(input));
             EntryPointUtils.CheckInputArgs(host, input);
 
-            return LearnerEntryPointsUtils.Train<Arguments, CommonOutputs.BinaryClassificationOutput>(host, input,
+            return LearnerEntryPointsUtils.Train<Options, CommonOutputs.BinaryClassificationOutput>(host, input,
                 () => new SymSgdClassificationTrainer(host, input),
                 () => LearnerEntryPointsUtils.FindColumn(host, input.TrainingData.Schema, input.LabelColumn));
         }