Modify API for advanced settings (RandomizedPcaTrainer)

src/Microsoft.ML.Data/Evaluators/AnomalyDetectionEvaluator.cs

@@ -10,6 +10,7 @@
 using Microsoft.ML;
 using Microsoft.ML.CommandLine;
 using Microsoft.ML.Data;
+using Microsoft.ML.Data.Evaluators.Metrics;
 using Microsoft.ML.EntryPoints;
 using Microsoft.ML.Internal.Utilities;
 using Microsoft.ML.Transforms;
@@ -576,6 +577,44 @@ public void Finish()
                 FinishOtherMetrics();
             }
         }
+
+        /// <summary>
+        /// Evaluates scored anomaly detection data.
+        /// </summary>
+        /// <param name="data">The scored data.</param>
+        /// <param name="label">The name of the label column in <paramref name="data"/>.</param>
+        /// <param name="score">The name of the score column in <paramref name="data"/>.</param>
+        /// <param name="predictedLabel">The name of the predicted label column in <paramref name="data"/>.</param>
+        /// <returns>The evaluation results for these outputs.</returns>
+        internal AnomalyDetectionMetrics Evaluate(IDataView data, string label = DefaultColumnNames.Label, string score = DefaultColumnNames.Score,
+            string predictedLabel = DefaultColumnNames.PredictedLabel)
+        {
+            Host.CheckValue(data, nameof(data));
+            Host.CheckNonEmpty(label, nameof(label));
+            Host.CheckNonEmpty(score, nameof(score));
+            Host.CheckNonEmpty(predictedLabel, nameof(predictedLabel));
+
+            var roles = new RoleMappedData(data, opt: false,
+                RoleMappedSchema.ColumnRole.Label.Bind(label),
+                RoleMappedSchema.CreatePair(MetadataUtils.Const.ScoreValueKind.Score, score),
+                RoleMappedSchema.CreatePair(MetadataUtils.Const.ScoreValueKind.PredictedLabel, predictedLabel));
+
+            var resultDict = ((IEvaluator)this).Evaluate(roles);
+            Host.Assert(resultDict.ContainsKey(MetricKinds.OverallMetrics));
+            var overall = resultDict[MetricKinds.OverallMetrics];
+
+            AnomalyDetectionMetrics result;
+            using (var cursor = overall.GetRowCursorForAllColumns())
+            {
+                var moved = cursor.MoveNext();
+                Host.Assert(moved);
+                result = new AnomalyDetectionMetrics(Host, cursor);
+                moved = cursor.MoveNext();
+                Host.Assert(!moved);
+            }
+            return result;
+        }
+
     }
 
     [BestFriend]

src/Microsoft.ML.Data/Evaluators/Metrics/AnomalyDetectionMetrics.cs

@@ -0,0 +1,46 @@
+// 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 System;
+using Microsoft.Data.DataView;
+
+namespace Microsoft.ML.Data.Evaluators.Metrics
+{
+    /// <summary>
+    /// Evaluation results for anomaly detection.
+    /// </summary>
+    public sealed class AnomalyDetectionMetrics
+    {
+        /// <summary>
+        /// Gets the area under the ROC curve.
+        /// </summary>
+        /// <remarks>
+        /// The area under the ROC curve is equal to the probability that the algorithm ranks
+        /// a randomly chosen positive instance higher than a randomly chosen negative one
+        /// (assuming 'positive' ranks higher than 'negative').
+        /// </remarks>
+        public double Auc { get; }
+
+        /// <summary>
+        /// Detection rate at K false positives.
+        /// </summary>
+        /// <remarks>
+        /// This is computed as follows:
+        /// 1.Sort the test examples by the output of the anomaly detector in descending order of scores.
+        /// 2.Among the top K False Positives,  compute ratio :  (True Positive @ K)  / (Total anomalies in test data)
+        /// Example confusion matrix for anomaly detection:
+        ///                            Anomalies (in test data)  | Non-Anomalies (in test data)
+        ///  Predicted Anomalies     :         TP                |           FP
+        ///  Predicted Non-Anomalies :         FN                |           TN
+        ///  </remarks>
+        public double DrAtK { get; }
+
+        internal AnomalyDetectionMetrics(IExceptionContext ectx, Row overallResult)
+        {
+            double FetchDouble(string name) => RowCursorUtils.Fetch<double>(ectx, overallResult, name);
+            Auc = FetchDouble(BinaryClassifierEvaluator.Auc);
+            DrAtK = FetchDouble(AnomalyDetectionEvaluator.OverallMetrics.DrAtK);
+        }
+    }
+}

src/Microsoft.ML.Data/MLContext.cs

@@ -40,6 +40,11 @@ public sealed class MLContext : IHostEnvironment
         /// </summary>
         public RankingCatalog Ranking { get; }
 
+        /// <summary>
+        /// Trainers and tasks specific to anomaly detection problems.
+        /// </summary>
+        public AnomalyDetectionCatalog AnomalyDetection { get; }
+
         /// <summary>
         /// Data processing operations.
         /// </summary>
@@ -83,6 +88,7 @@ public MLContext(int? seed = null, int conc = 0)
             Regression = new RegressionCatalog(_env);
             Clustering = new ClusteringCatalog(_env);
             Ranking = new RankingCatalog(_env);
+            AnomalyDetection = new AnomalyDetectionCatalog(_env);
             Transforms = new TransformsCatalog(_env);
             Model = new ModelOperationsCatalog(_env);
             Data = new DataOperationsCatalog(_env);

src/Microsoft.ML.Data/TrainCatalog.cs

@@ -6,6 +6,7 @@
 using System.Linq;
 using Microsoft.Data.DataView;
 using Microsoft.ML.Data;
+using Microsoft.ML.Data.Evaluators.Metrics;
 using Microsoft.ML.Transforms;
 using Microsoft.ML.Transforms.Conversions;
 
@@ -646,4 +647,53 @@ public RankerMetrics Evaluate(IDataView data, string label, string groupId, stri
             return eval.Evaluate(data, label, groupId, score);
         }
     }
+
+    /// <summary>
+    /// The central catalog for anomaly detection tasks and trainers.
+    /// </summary>
+    public sealed class AnomalyDetectionCatalog : TrainCatalogBase
+    {
+        /// <summary>
+        /// The list of trainers for anomaly detection.
+        /// </summary>
+        public AnomalyDetectionTrainers Trainers { get; }
+
+        internal AnomalyDetectionCatalog(IHostEnvironment env)
+            : base(env, nameof(AnomalyDetectionCatalog))
+        {
+            Trainers = new AnomalyDetectionTrainers(this);
+        }
+
+        public sealed class AnomalyDetectionTrainers : CatalogInstantiatorBase
+        {
+            internal AnomalyDetectionTrainers(AnomalyDetectionCatalog catalog)
+                : base(catalog)
+            {
+            }
+        }
+
+        /// <summary>
+        /// Evaluates scored anomaly detection data.
+        /// </summary>
+        /// <param name="data">The scored data.</param>
+        /// <param name="label">The name of the label column in <paramref name="data"/>.</param>
+        /// <param name="score">The name of the score column in <paramref name="data"/>.</param>
+        /// <param name="predictedLabel">The name of the predicted label column in <paramref name="data"/>.</param>
+        /// <param name="k">The number of false positives to compute the <see cref="AnomalyDetectionMetrics.DrAtK"/> metric. </param>
+        /// <returns>Evaluation results.</returns>
+        public AnomalyDetectionMetrics Evaluate(IDataView data, string label = DefaultColumnNames.Label, string score = DefaultColumnNames.Score,
+            string predictedLabel = DefaultColumnNames.PredictedLabel, int k = 10)
+        {
+            Environment.CheckValue(data, nameof(data));
+            Environment.CheckNonEmpty(label, nameof(label));
+            Environment.CheckNonEmpty(score, nameof(score));
+            Environment.CheckNonEmpty(predictedLabel, nameof(predictedLabel));
+
+            var args = new AnomalyDetectionEvaluator.Arguments();
+            args.K = k;
+
+            var eval = new AnomalyDetectionEvaluator(Environment, args);
+            return eval.Evaluate(data, label, score, predictedLabel);
+        }
+    }
 }

src/Microsoft.ML.PCA/PCACatalog.cs

@@ -3,13 +3,14 @@
 // See the LICENSE file in the project root for more information.
 
 using Microsoft.ML.Data;
+using Microsoft.ML.Trainers.PCA;
 using Microsoft.ML.Transforms.Projections;
+using static Microsoft.ML.Trainers.PCA.RandomizedPcaTrainer;
 
 namespace Microsoft.ML
 {
     public static class PcaCatalog
     {
-
         /// <summary>Initializes a new instance of <see cref="PrincipalComponentAnalysisEstimator"/>.</summary>
         /// <param name="catalog">The transform's catalog.</param>
         /// <param name="outputColumnName">Name of the column resulting from the transformation of <paramref name="inputColumnName"/>.</param>
@@ -35,5 +36,40 @@ public static PrincipalComponentAnalysisEstimator ProjectToPrincipalComponents(t
         /// <param name="columns">Input columns to apply PrincipalComponentAnalysis on.</param>
         public static PrincipalComponentAnalysisEstimator ProjectToPrincipalComponents(this TransformsCatalog.ProjectionTransforms catalog, params PrincipalComponentAnalysisEstimator.ColumnInfo[] columns)
             => new PrincipalComponentAnalysisEstimator(CatalogUtils.GetEnvironment(catalog), columns);
+
+        /// <summary>
+        /// Trains an approximate PCA using Randomized SVD algorithm.
+        /// </summary>
+        /// <param name="catalog">The anomaly detection catalog trainer object.</param>
+        /// <param name="featureColumn">The features, or independent variables.</param>
+        /// <param name="weights">The optional example weights.</param>
+        /// <param name="rank">The number of components in the PCA.</param>
+        /// <param name="oversampling">Oversampling parameter for randomized PCA training.</param>
+        /// <param name="center">If enabled, data is centered to be zero mean.</param>
+        /// <param name="seed">The seed for random number generation.</param>
+        public static RandomizedPcaTrainer RandomizedPca(this AnomalyDetectionCatalog.AnomalyDetectionTrainers catalog,
+            string featureColumn = DefaultColumnNames.Features,
+            string weights = null,
+            int rank = Options.Defaults.NumComponents,
+            int oversampling = Options.Defaults.OversamplingParameters,
+            bool center = Options.Defaults.IsCenteredZeroMean,
+            int? seed = null)
+        {
+            Contracts.CheckValue(catalog, nameof(catalog));
+            var env = CatalogUtils.GetEnvironment(catalog);
+            return new RandomizedPcaTrainer(env, featureColumn, weights, rank, oversampling, center, seed);
+        }
+
+        /// <summary>
+        /// Trains an approximate PCA using Randomized SVD algorithm.
+        /// </summary>
+        /// <param name="catalog">The anomaly detection catalog trainer object.</param>
+        /// <param name="options">Advanced options to the algorithm.</param>
+        public static RandomizedPcaTrainer RandomizedPca(this AnomalyDetectionCatalog.AnomalyDetectionTrainers catalog, Options options)
+        {
+            Contracts.CheckValue(catalog, nameof(catalog));
+            var env = CatalogUtils.GetEnvironment(catalog);
+            return new RandomizedPcaTrainer(env, options);
+        }
     }
 }

src/Microsoft.ML.PCA/PcaTrainer.cs

@@ -18,7 +18,7 @@
 using Microsoft.ML.Trainers.PCA;
 using Microsoft.ML.Training;
 
-[assembly: LoadableClass(RandomizedPcaTrainer.Summary, typeof(RandomizedPcaTrainer), typeof(RandomizedPcaTrainer.Arguments),
+[assembly: LoadableClass(RandomizedPcaTrainer.Summary, typeof(RandomizedPcaTrainer), typeof(RandomizedPcaTrainer.Options),
     new[] { typeof(SignatureAnomalyDetectorTrainer), typeof(SignatureTrainer) },
     RandomizedPcaTrainer.UserNameValue,
     RandomizedPcaTrainer.LoadNameValue,
@@ -48,24 +48,31 @@ public sealed class RandomizedPcaTrainer : TrainerEstimatorBase<AnomalyPredictio
         internal const string Summary = "This algorithm trains an approximate PCA using Randomized SVD algorithm. "
             + "This PCA can be made into Kernel PCA by using Random Fourier Features transform.";
 
-        public class Arguments : UnsupervisedLearnerInputBaseWithWeight
+        public class Options : UnsupervisedLearnerInputBaseWithWeight
         {
             [Argument(ArgumentType.AtMostOnce, HelpText = "The number of components in the PCA", ShortName = "k", SortOrder = 50)]
             [TGUI(SuggestedSweeps = "10,20,40,80")]
             [TlcModule.SweepableDiscreteParam("Rank", new object[] { 10, 20, 40, 80 })]
-            public int Rank = 20;
+            public int Rank = Defaults.NumComponents;
 
             [Argument(ArgumentType.AtMostOnce, HelpText = "Oversampling parameter for randomized PCA training", SortOrder = 50)]
             [TGUI(SuggestedSweeps = "10,20,40")]
             [TlcModule.SweepableDiscreteParam("Oversampling", new object[] { 10, 20, 40 })]
-            public int Oversampling = 20;
+            public int Oversampling = Defaults.OversamplingParameters;
 
             [Argument(ArgumentType.AtMostOnce, HelpText = "If enabled, data is centered to be zero mean", ShortName = "center")]
             [TlcModule.SweepableDiscreteParam("Center", null, isBool: true)]
-            public bool Center = true;
+            public bool Center = Defaults.IsCenteredZeroMean;
 
             [Argument(ArgumentType.AtMostOnce, HelpText = "The seed for random number generation", ShortName = "seed")]
             public int? Seed;
+
+            internal static class Defaults
+            {
+                public const int NumComponents = 20;
+                public const int OversamplingParameters = 20;
+                public const bool IsCenteredZeroMean = true;
+            }
         }
 
         private readonly int _rank;
@@ -90,35 +97,35 @@ public class Arguments : UnsupervisedLearnerInputBaseWithWeight
         /// <param name="oversampling">Oversampling parameter for randomized PCA training.</param>
         /// <param name="center">If enabled, data is centered to be zero mean.</param>
         /// <param name="seed">The seed for random number generation.</param>
-        public RandomizedPcaTrainer(IHostEnvironment env,
+        internal RandomizedPcaTrainer(IHostEnvironment env,
             string features,
             string weights = null,
-            int rank = 20,
-            int oversampling = 20,
-            bool center = true,
+            int rank = Options.Defaults.NumComponents,
+            int oversampling = Options.Defaults.OversamplingParameters,
+            bool center = Options.Defaults.IsCenteredZeroMean,
             int? seed = null)
             : this(env, null, features, weights, rank, oversampling, center, seed)
         {
 
         }
 
-        internal RandomizedPcaTrainer(IHostEnvironment env, Arguments args)
-            :this(env, args, args.FeatureColumn, args.WeightColumn)
+        internal RandomizedPcaTrainer(IHostEnvironment env, Options options)
+            :this(env, options, options.FeatureColumn, options.WeightColumn)
         {
 
         }
 
-        private RandomizedPcaTrainer(IHostEnvironment env, Arguments args, string featureColumn, string weightColumn,
+        private RandomizedPcaTrainer(IHostEnvironment env, Options options, string featureColumn, string weightColumn,
             int rank = 20, int oversampling = 20, bool center = true, int? seed = null)
             : base(Contracts.CheckRef(env, nameof(env)).Register(LoadNameValue), TrainerUtils.MakeR4VecFeature(featureColumn), default, TrainerUtils.MakeR4ScalarWeightColumn(weightColumn))
         {
             // if the args are not null, we got here from maml, and the internal ctor.
-            if (args != null)
+            if (options != null)
             {
-                _rank = args.Rank;
-                _center = args.Center;
-                _oversampling = args.Oversampling;
-                _seed = args.Seed ?? Host.Rand.Next();
+                _rank = options.Rank;
+                _center = options.Center;
+                _oversampling = options.Oversampling;
+                _seed = options.Seed ?? Host.Rand.Next();
             }
             else
             {
@@ -346,14 +353,14 @@ protected override AnomalyPredictionTransformer<PcaModelParameters> MakeTransfor
             Desc = "Train an PCA Anomaly model.",
             UserName = UserNameValue,
             ShortName = ShortName)]
-        internal static CommonOutputs.AnomalyDetectionOutput TrainPcaAnomaly(IHostEnvironment env, Arguments input)
+        internal static CommonOutputs.AnomalyDetectionOutput TrainPcaAnomaly(IHostEnvironment env, Options input)
         {
             Contracts.CheckValue(env, nameof(env));
             var host = env.Register("TrainPCAAnomaly");
             host.CheckValue(input, nameof(input));
             EntryPointUtils.CheckInputArgs(host, input);
 
-            return LearnerEntryPointsUtils.Train<Arguments, CommonOutputs.AnomalyDetectionOutput>(host, input,
+            return LearnerEntryPointsUtils.Train<Options, CommonOutputs.AnomalyDetectionOutput>(host, input,
                 () => new RandomizedPcaTrainer(host, input),
                 getWeight: () => LearnerEntryPointsUtils.FindColumn(host, input.TrainingData.Schema, input.WeightColumn));
         }

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

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

test/BaselineOutput/Common/EntryPoints/core_ep-list.tsv

@@ -63,7 +63,7 @@ Trainers.LogisticRegressionClassifier	Logistic Regression is a method in statist
 Trainers.NaiveBayesClassifier	Train a MultiClassNaiveBayesTrainer.	Microsoft.ML.Trainers.MultiClassNaiveBayesTrainer	TrainMultiClassNaiveBayesTrainer	Microsoft.ML.Trainers.MultiClassNaiveBayesTrainer+Options	Microsoft.ML.EntryPoints.CommonOutputs+MulticlassClassificationOutput
 Trainers.OnlineGradientDescentRegressor	Train a Online gradient descent perceptron.	Microsoft.ML.Trainers.Online.OnlineGradientDescentTrainer	TrainRegression	Microsoft.ML.Trainers.Online.OnlineGradientDescentTrainer+Options	Microsoft.ML.EntryPoints.CommonOutputs+RegressionOutput
 Trainers.OrdinaryLeastSquaresRegressor	Train an OLS regression model.	Microsoft.ML.Trainers.HalLearners.OlsLinearRegressionTrainer	TrainRegression	Microsoft.ML.Trainers.HalLearners.OlsLinearRegressionTrainer+Options	Microsoft.ML.EntryPoints.CommonOutputs+RegressionOutput
-Trainers.PcaAnomalyDetector	Train an PCA Anomaly model.	Microsoft.ML.Trainers.PCA.RandomizedPcaTrainer	TrainPcaAnomaly	Microsoft.ML.Trainers.PCA.RandomizedPcaTrainer+Arguments	Microsoft.ML.EntryPoints.CommonOutputs+AnomalyDetectionOutput
+Trainers.PcaAnomalyDetector	Train an PCA Anomaly model.	Microsoft.ML.Trainers.PCA.RandomizedPcaTrainer	TrainPcaAnomaly	Microsoft.ML.Trainers.PCA.RandomizedPcaTrainer+Options	Microsoft.ML.EntryPoints.CommonOutputs+AnomalyDetectionOutput
 Trainers.PoissonRegressor	Train an Poisson regression model.	Microsoft.ML.Trainers.PoissonRegression	TrainRegression	Microsoft.ML.Trainers.PoissonRegression+Options	Microsoft.ML.EntryPoints.CommonOutputs+RegressionOutput
 Trainers.StochasticDualCoordinateAscentBinaryClassifier	Train an SDCA binary model.	Microsoft.ML.Trainers.Sdca	TrainBinary	Microsoft.ML.Trainers.SdcaBinaryTrainer+Options	Microsoft.ML.EntryPoints.CommonOutputs+BinaryClassificationOutput
 Trainers.StochasticDualCoordinateAscentClassifier	The SDCA linear multi-class classification trainer.	Microsoft.ML.Trainers.Sdca	TrainMultiClass	Microsoft.ML.Trainers.SdcaMultiClassTrainer+Options	Microsoft.ML.EntryPoints.CommonOutputs+MulticlassClassificationOutput

test/Microsoft.ML.Core.Tests/UnitTests/TestEntryPoints.cs

@@ -3414,7 +3414,7 @@ public void EntryPointPcaPredictorSummary()
                     InputFile = inputFile,
                 }).Data;
 
-                var pcaInput = new RandomizedPcaTrainer.Arguments
+                var pcaInput = new RandomizedPcaTrainer.Options
                 {
                     TrainingData = dataView,
                 };