KMeans and Implicit weight cleanup (#2158)

* KMeans and Implicit weight cleanup

Author: sfilipi

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

@@ -93,6 +93,9 @@ public abstract class LearnerInputBaseWithWeight : LearnerInputBaseWithLabel
     [TlcModule.EntryPointKind(typeof(CommonInputs.IUnsupervisedTrainerWithWeight))]
     public abstract class UnsupervisedLearnerInputBaseWithWeight : LearnerInputBase
     {
+        /// <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 Optional<string> WeightColumn = Optional<string>.Implicit(DefaultColumnNames.Weight);
     }

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

@@ -122,6 +122,13 @@ SchemaShape IEstimator<CalibratorTransformer<TICalibrator>>.GetOutputSchema(Sche
             return new SchemaShape(outColumns.Values);
         }
 
+        /// <summary>
+        /// Fits the scored <see cref="IDataView"/> creating a <see cref="CalibratorTransformer{TICalibrator}"/> that can transform the data by adding a
+        /// <see cref="DefaultColumnNames.Probability"/> column containing the calibrated <see cref="DefaultColumnNames.Score"/>.
+        /// </summary>
+        /// <param name="input"></param>
+        /// <returns>A trained <see cref="CalibratorTransformer{TICalibrator}"/> that will transform the data by adding the
+        /// <see cref="DefaultColumnNames.Probability"/> column.</returns>
         public CalibratorTransformer<TICalibrator> Fit(IDataView input)
         {
             TICalibrator calibrator = null;

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

@@ -6,6 +6,7 @@
 using System.Collections.Generic;
 using Microsoft.ML.Core.Data;
 using Microsoft.ML.Data;
+using Microsoft.ML.EntryPoints;
 using Microsoft.ML.Internal.Utilities;
 
 namespace Microsoft.ML.Training
@@ -385,10 +386,20 @@ public static SchemaShape.Column MakeR4VecFeature(string featureColumn)
         /// The <see cref="SchemaShape.Column"/> for the weight column.
         /// </summary>
         /// <param name="weightColumn">name of the weight column</param>
-        /// <param name="isExplicit">whether the column is implicitly, or explicitly defined</param>
-        public static SchemaShape.Column MakeR4ScalarWeightColumn(string weightColumn, bool isExplicit = true)
+        public static SchemaShape.Column MakeR4ScalarWeightColumn(string weightColumn)
         {
-            if (weightColumn == null || !isExplicit)
+            if (weightColumn == null)
+                return default;
+            return new SchemaShape.Column(weightColumn, SchemaShape.Column.VectorKind.Scalar, NumberType.R4, false);
+        }
+
+        /// <summary>
+        /// The <see cref="SchemaShape.Column"/> for the weight column.
+        /// </summary>
+        /// <param name="weightColumn">name of the weight column</param>
+        public static SchemaShape.Column MakeR4ScalarWeightColumn(Optional<string> weightColumn)
+        {
+            if (weightColumn == null || weightColumn.Value == null || !weightColumn.IsExplicit)
                 return default;
             return new SchemaShape.Column(weightColumn, SchemaShape.Column.VectorKind.Scalar, NumberType.R4, false);
         }

src/Microsoft.ML.FastTree/FastTree.cs

@@ -151,7 +151,7 @@ private protected FastTreeTrainerBase(IHostEnvironment env,
         /// Constructor that is used when invoking the classes deriving from this, through maml.
         /// </summary>
         private protected FastTreeTrainerBase(IHostEnvironment env, TArgs args, SchemaShape.Column label)
-            : base(Contracts.CheckRef(env, nameof(env)).Register(RegisterName), TrainerUtils.MakeR4VecFeature(args.FeatureColumn), label, TrainerUtils.MakeR4ScalarWeightColumn(args.WeightColumn, args.WeightColumn.IsExplicit))
+            : base(Contracts.CheckRef(env, nameof(env)).Register(RegisterName), TrainerUtils.MakeR4VecFeature(args.FeatureColumn), label, TrainerUtils.MakeR4ScalarWeightColumn(args.WeightColumn))
         {
             Host.CheckValue(args, nameof(args));
             Args = args;

src/Microsoft.ML.FastTree/GamTrainer.cs

@@ -192,7 +192,7 @@ private protected GamTrainerBase(IHostEnvironment env,
 
         private protected GamTrainerBase(IHostEnvironment env, TArgs args, string name, SchemaShape.Column label)
             : base(Contracts.CheckRef(env, nameof(env)).Register(name), TrainerUtils.MakeR4VecFeature(args.FeatureColumn),
-                  label, TrainerUtils.MakeR4ScalarWeightColumn(args.WeightColumn, args.WeightColumn.IsExplicit))
+                  label, TrainerUtils.MakeR4ScalarWeightColumn(args.WeightColumn))
         {
             Contracts.CheckValue(env, nameof(env));
             Host.CheckValue(args, nameof(args));

src/Microsoft.ML.HalLearners/OlsLinearRegression.cs

@@ -87,7 +87,7 @@ public OlsLinearRegressionTrainer(IHostEnvironment env,
         /// </summary>
         internal OlsLinearRegressionTrainer(IHostEnvironment env, Arguments args)
             : base(Contracts.CheckRef(env, nameof(env)).Register(LoadNameValue), TrainerUtils.MakeR4VecFeature(args.FeatureColumn),
-                  TrainerUtils.MakeR4ScalarColumn(args.LabelColumn), TrainerUtils.MakeR4ScalarWeightColumn(args.WeightColumn, args.WeightColumn.IsExplicit))
+                  TrainerUtils.MakeR4ScalarColumn(args.LabelColumn), TrainerUtils.MakeR4ScalarWeightColumn(args.WeightColumn))
         {
             Host.CheckValue(args, nameof(args));
             Host.CheckUserArg(args.L2Weight >= 0, nameof(args.L2Weight), "L2 regularization term cannot be negative");
@@ -106,7 +106,7 @@ private static Arguments ArgsInit(string featureColumn,
             advancedSettings?.Invoke(args);
             args.FeatureColumn = featureColumn;
             args.LabelColumn = labelColumn;
-            args.WeightColumn = weightColumn;
+            args.WeightColumn = weightColumn != null ? Optional<string>.Explicit(weightColumn) : Optional<string>.Implicit(DefaultColumnNames.Weight);
             return args;
         }
 

src/Microsoft.ML.KMeansClustering/KMeansCatalog.cs

@@ -4,6 +4,7 @@
 
 using System;
 using Microsoft.ML.Data;
+using Microsoft.ML.EntryPoints;
 using Microsoft.ML.Trainers.KMeans;
 
 namespace Microsoft.ML
@@ -16,20 +17,45 @@ public static class KMeansClusteringExtensions
         /// <summary>
         /// Train a KMeans++ clustering algorithm.
         /// </summary>
-        /// <param name="ctx">The regression context trainer object.</param>
-        /// <param name="features">The features, or independent variables.</param>
+        /// <param name="ctx">The clustering context trainer object.</param>
+        /// <param name="featureColumn">The features, or independent variables.</param>
         /// <param name="weights">The optional example weights.</param>
         /// <param name="clustersCount">The number of clusters to use for KMeans.</param>
-        /// <param name="advancedSettings">Algorithm advanced settings.</param>
+        /// <example>
+        /// <format type="text/markdown">
+        /// <![CDATA[
+        ///  [!code-csharp[KMeans](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/KMeans.cs)]
+        /// ]]></format>
+        /// </example>
         public static KMeansPlusPlusTrainer KMeans(this ClusteringContext.ClusteringTrainers ctx,
-           string features,
+           string featureColumn = DefaultColumnNames.Features,
            string weights = null,
-           int clustersCount = KMeansPlusPlusTrainer.Defaults.K,
-           Action<KMeansPlusPlusTrainer.Arguments> advancedSettings = null)
+           int clustersCount = KMeansPlusPlusTrainer.Defaults.ClustersCount)
         {
             Contracts.CheckValue(ctx, nameof(ctx));
             var env = CatalogUtils.GetEnvironment(ctx);
-            return new KMeansPlusPlusTrainer(env, features, clustersCount, weights, advancedSettings);
+
+            var options = new KMeansPlusPlusTrainer.Options
+            {
+                FeatureColumn = featureColumn,
+                WeightColumn = weights != null ? Optional<string>.Explicit(weights) : Optional<string>.Implicit(DefaultColumnNames.Weight),
+                ClustersCount = clustersCount
+            };
+            return new KMeansPlusPlusTrainer(env, options);
+        }
+
+        /// <summary>
+        /// Train a KMeans++ clustering algorithm.
+        /// </summary>
+        /// <param name="ctx">The clustering context trainer object.</param>
+        /// <param name="options">Algorithm advanced options.</param>
+        public static KMeansPlusPlusTrainer KMeans(this ClusteringContext.ClusteringTrainers ctx, KMeansPlusPlusTrainer.Options options)
+        {
+            Contracts.CheckValue(ctx, nameof(ctx));
+            Contracts.CheckValue(options, nameof(options));
+
+            var env = CatalogUtils.GetEnvironment(ctx);
+            return new KMeansPlusPlusTrainer(env, options);
         }
     }
 }

src/Microsoft.ML.KMeansClustering/KMeansPlusPlusTrainer.cs

@@ -17,7 +17,7 @@
 using Microsoft.ML.Trainers.KMeans;
 using Microsoft.ML.Training;
 
-[assembly: LoadableClass(KMeansPlusPlusTrainer.Summary, typeof(KMeansPlusPlusTrainer), typeof(KMeansPlusPlusTrainer.Arguments),
+[assembly: LoadableClass(KMeansPlusPlusTrainer.Summary, typeof(KMeansPlusPlusTrainer), typeof(KMeansPlusPlusTrainer.Options),
     new[] { typeof(SignatureClusteringTrainer), typeof(SignatureTrainer) },
     KMeansPlusPlusTrainer.UserNameValue,
     KMeansPlusPlusTrainer.LoadNameValue,
@@ -30,7 +30,7 @@ namespace Microsoft.ML.Trainers.KMeans
     /// <include file='./doc.xml' path='doc/members/member[@name="KMeans++"]/*' />
     public class KMeansPlusPlusTrainer : TrainerEstimatorBase<ClusteringPredictionTransformer<KMeansModelParameters>, KMeansModelParameters>
     {
-        public const string LoadNameValue = "KMeansPlusPlus";
+        internal const string LoadNameValue = "KMeansPlusPlus";
         internal const string UserNameValue = "KMeans++ Clustering";
         internal const string ShortName = "KM";
         internal const string Summary = "K-means is a popular clustering algorithm. With K-means, the data is clustered into a specified "
@@ -45,34 +45,54 @@ public enum InitAlgorithm
         }
 
         [BestFriend]
-        internal static class Defaults{
+        internal static class Defaults
+        {
             /// <value>The number of clusters.</value>
-            public const int K = 5;
+            public const int ClustersCount = 5;
         }
 
-        public class Arguments : UnsupervisedLearnerInputBaseWithWeight
+        public class Options : UnsupervisedLearnerInputBaseWithWeight
         {
-            [Argument(ArgumentType.AtMostOnce, HelpText = "The number of clusters", SortOrder = 50)]
+            /// <summary>
+            /// The number of clusters.
+            /// </summary>
+            [Argument(ArgumentType.AtMostOnce, HelpText = "The number of clusters", SortOrder = 50, Name = "K")]
             [TGUI(SuggestedSweeps = "5,10,20,40")]
             [TlcModule.SweepableDiscreteParam("K", new object[] { 5, 10, 20, 40 })]
-            public int K = Defaults.K;
+            public int ClustersCount = Defaults.ClustersCount;
 
+            /// <summary>
+            /// Cluster initialization algorithm.
+            /// </summary>
             [Argument(ArgumentType.AtMostOnce, HelpText = "Cluster initialization algorithm", ShortName = "init")]
             public InitAlgorithm InitAlgorithm = InitAlgorithm.KMeansParallel;
 
+            /// <summary>
+            /// Tolerance parameter for trainer convergence. Low = slower, more accurate.
+            /// </summary>
             [Argument(ArgumentType.AtMostOnce, HelpText = "Tolerance parameter for trainer convergence. Low = slower, more accurate",
-                ShortName = "ot")]
+                Name = "OptTol", ShortName = "ot")]
             [TGUI(Label = "Optimization Tolerance", Description = "Threshold for trainer convergence")]
-            public float OptTol = (float)1e-7;
+            public float OptimizationTolerance = (float)1e-7;
 
+            /// <summary>
+            /// Maximum number of iterations.
+            /// </summary>
             [Argument(ArgumentType.AtMostOnce, HelpText = "Maximum number of iterations.", ShortName = "maxiter")]
             [TGUI(Label = "Max Number of Iterations")]
             public int MaxIterations = 1000;
 
-            [Argument(ArgumentType.AtMostOnce, HelpText = "Memory budget (in MBs) to use for KMeans acceleration", ShortName = "accelMemBudgetMb")]
+            /// <summary>
+            /// Memory budget (in MBs) to use for KMeans acceleration.
+            /// </summary>
+            [Argument(ArgumentType.AtMostOnce, HelpText = "Memory budget (in MBs) to use for KMeans acceleration",
+                Name = "AccelMemBudgetMb", ShortName = "accelMemBudgetMb")]
             [TGUI(Label = "Memory Budget (in MBs) for KMeans Acceleration")]
-            public int AccelMemBudgetMb = 4 * 1024; // by default, use at most 4 GB
+            public int AccelerationMemoryBudgetMb = 4 * 1024; // by default, use at most 4 GB
 
+            /// <summary>
+            /// Degree of lock-free parallelism. Defaults to automatic. Determinism not guaranteed.
+            /// </summary>
             [Argument(ArgumentType.AtMostOnce, HelpText = "Degree of lock-free parallelism. Defaults to automatic. Determinism not guaranteed.", ShortName = "nt,t,threads", SortOrder = 50)]
             [TGUI(Label = "Number of threads")]
             public int? NumThreads;
@@ -95,58 +115,31 @@ public class Arguments : UnsupervisedLearnerInputBaseWithWeight
         /// Initializes a new instance of <see cref="KMeansPlusPlusTrainer"/>
         /// </summary>
         /// <param name="env">The <see cref="IHostEnvironment"/> to use.</param>
-        /// <param name="featureColumn">The name of the feature column.</param>
-        /// <param name="weights">The name for the optional column containing the example weights.</param>
-        /// <param name="advancedSettings">A delegate to apply all the advanced arguments to the algorithm.</param>
-        /// <param name="clustersCount">The number of clusters.</param>
-        public KMeansPlusPlusTrainer(IHostEnvironment env,
-            string featureColumn = DefaultColumnNames.Features,
-            int clustersCount = Defaults.K,
-            string weights = null,
-            Action<Arguments> advancedSettings = null)
-            : this(env, new Arguments
-            {
-                FeatureColumn = featureColumn,
-                WeightColumn = weights,
-                K = clustersCount
-            }, advancedSettings)
-        {
-        }
-
-        internal KMeansPlusPlusTrainer(IHostEnvironment env, Arguments args)
-            : this(env, args, null)
+        /// <param name="options">The advanced options of the algorithm.</param>
+        internal KMeansPlusPlusTrainer(IHostEnvironment env, Options options)
+            : base(Contracts.CheckRef(env, nameof(env)).Register(LoadNameValue), TrainerUtils.MakeR4VecFeature(options.FeatureColumn), default, TrainerUtils.MakeR4ScalarWeightColumn(options.WeightColumn))
         {
+            Host.CheckValue(options, nameof(options));
+            Host.CheckUserArg(options.ClustersCount > 0, nameof(options.ClustersCount), "Must be positive");
 
-        }
-
-        private KMeansPlusPlusTrainer(IHostEnvironment env, Arguments args, Action<Arguments> advancedSettings = null)
-            : base(Contracts.CheckRef(env, nameof(env)).Register(LoadNameValue), TrainerUtils.MakeR4VecFeature(args.FeatureColumn), default, TrainerUtils.MakeR4ScalarWeightColumn(args.WeightColumn))
-        {
-            Host.CheckValue(args, nameof(args));
-
-            // override with the advanced settings.
-            advancedSettings?.Invoke(args);
-
-            Host.CheckUserArg(args.K > 0, nameof(args.K), "Must be positive");
-
-            _featureColumn = args.FeatureColumn;
+            _featureColumn = options.FeatureColumn;
 
-            _k = args.K;
+            _k = options.ClustersCount;
 
-            Host.CheckUserArg(args.MaxIterations > 0, nameof(args.MaxIterations), "Must be positive");
-            _maxIterations = args.MaxIterations;
+            Host.CheckUserArg(options.MaxIterations > 0, nameof(options.MaxIterations), "Must be positive");
+            _maxIterations = options.MaxIterations;
 
-            Host.CheckUserArg(args.OptTol > 0, nameof(args.OptTol), "Tolerance must be positive");
-            _convergenceThreshold = args.OptTol;
+            Host.CheckUserArg(options.OptimizationTolerance > 0, nameof(options.OptimizationTolerance), "Tolerance must be positive");
+            _convergenceThreshold = options.OptimizationTolerance;
 
-            Host.CheckUserArg(args.AccelMemBudgetMb > 0, nameof(args.AccelMemBudgetMb), "Must be positive");
-            _accelMemBudgetMb = args.AccelMemBudgetMb;
+            Host.CheckUserArg(options.AccelerationMemoryBudgetMb > 0, nameof(options.AccelerationMemoryBudgetMb), "Must be positive");
+            _accelMemBudgetMb = options.AccelerationMemoryBudgetMb;
 
-            _initAlgorithm = args.InitAlgorithm;
+            _initAlgorithm = options.InitAlgorithm;
 
-            Host.CheckUserArg(!args.NumThreads.HasValue || args.NumThreads > 0, nameof(args.NumThreads),
+            Host.CheckUserArg(!options.NumThreads.HasValue || options.NumThreads > 0, nameof(options.NumThreads),
                 "Must be either null or a positive integer.");
-            _numThreads = ComputeNumThreads(Host, args.NumThreads);
+            _numThreads = ComputeNumThreads(Host, options.NumThreads);
             Info = new TrainerInfo();
         }
 
@@ -247,14 +240,14 @@ private static int ComputeNumThreads(IHost host, int? argNumThreads)
             ShortName = ShortName,
             XmlInclude = new[] { @"<include file='../Microsoft.ML.KMeansClustering/doc.xml' path='doc/members/member[@name=""KMeans++""]/*' />",
                                  @"<include file='../Microsoft.ML.KMeansClustering/doc.xml' path='doc/members/example[@name=""KMeans++""]/*' />"})]
-        public static CommonOutputs.ClusteringOutput TrainKMeans(IHostEnvironment env, Arguments input)
+        public static CommonOutputs.ClusteringOutput TrainKMeans(IHostEnvironment env, Options input)
         {
             Contracts.CheckValue(env, nameof(env));
             var host = env.Register("TrainKMeans");
             host.CheckValue(input, nameof(input));
             EntryPointUtils.CheckInputArgs(host, input);
 
-            return LearnerEntryPointsUtils.Train<Arguments, CommonOutputs.ClusteringOutput>(host, input,
+            return LearnerEntryPointsUtils.Train<Options, CommonOutputs.ClusteringOutput>(host, input,
                 () => new KMeansPlusPlusTrainer(host, input),
                 getWeight: () => LearnerEntryPointsUtils.FindColumn(host, input.TrainingData.Schema, input.WeightColumn));
         }
@@ -749,10 +742,10 @@ public static void Initialize(IHost host, int numThreads, IChannel ch, FeatureFl
             host.CheckValue(ch, nameof(ch));
             ch.CheckValue(cursorFactory, nameof(cursorFactory));
             ch.CheckValue(centroids, nameof(centroids));
-            ch.CheckUserArg(numThreads > 0, nameof(KMeansPlusPlusTrainer.Arguments.NumThreads), "Must be positive");
-            ch.CheckUserArg(k > 0, nameof(KMeansPlusPlusTrainer.Arguments.K), "Must be positive");
+            ch.CheckUserArg(numThreads > 0, nameof(KMeansPlusPlusTrainer.Options.NumThreads), "Must be positive");
+            ch.CheckUserArg(k > 0, nameof(KMeansPlusPlusTrainer.Options.ClustersCount), "Must be positive");
             ch.CheckParam(dimensionality > 0, nameof(dimensionality), "Must be positive");
-            ch.CheckUserArg(accelMemBudgetMb >= 0, nameof(KMeansPlusPlusTrainer.Arguments.AccelMemBudgetMb), "Must be non-negative");
+            ch.CheckUserArg(accelMemBudgetMb >= 0, nameof(KMeansPlusPlusTrainer.Options.AccelerationMemoryBudgetMb), "Must be non-negative");
 
             int numRounds;
             int numSamplesPerRound;