Returning multiple dimensions in RCA for anomaly detection

docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/TimeSeries/LocalizeRootCauseMultidimension.cs

@@ -0,0 +1,140 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using Microsoft.ML;
+using Microsoft.ML.TimeSeries;
+
+namespace Samples.Dynamic
+{
+    public static class LocalizeRootCauseMultipleDimensions
+    {
+        private static string AGG_SYMBOL = "##SUM##";
+
+        public static void Example()
+        {
+            // Create a new ML context, for ML.NET operations. It can be used for
+            // exception tracking and logging, as well as the source of randomness.
+            var mlContext = new MLContext();
+
+            // Create an root cause localization input instance.
+            DateTime timestamp = GetTimestamp();
+            var data = new RootCauseLocalizationInput(timestamp, GetAnomalyDimension(), new List<MetricSlice>() { new MetricSlice(timestamp, GetTimeSeriesPoints()) }, AggregateType.Sum, AGG_SYMBOL);
+
+            // Get the root cause localization result.
+            List<RootCause> prediction = mlContext.AnomalyDetection.LocalizeRootCauses(data);
+
+            // Print the localization results.
+            int count = 0;
+            foreach (RootCause cause in prediction)
+            {
+                count++;
+                foreach (RootCauseItem item in cause.Items)
+                {
+                    Console.WriteLine($"Prepared cause #{count} ...");
+                    Console.WriteLine($"Score: {item.Score}, Path: {String.Join(" ", item.Path)}, Direction: {item.Direction}, Dimension:{String.Join(" ", item.Dimension)}");
+                }
+            }
+
+            //Prepared cause #1 ...
+            //Score: 0.26670448876705927, Path: DataCenter, Direction: Up, Dimension:[Country, UK] [DeviceType, ##SUM##] [DataCenter, DC1]
+            //Prepared cause #2 ...
+            //Score: 0.254746585094852, Path: DeviceType, Direction: Up, Dimension:[Country, UK] [DeviceType, Laptop] [DataCenter, ##SUM##]        
+        }
+
+        private static List<TimeSeriesPoint> GetTimeSeriesPoints()
+        {
+            List<TimeSeriesPoint> TimeSeriesPoints = new List<TimeSeriesPoint>();
+
+            Dictionary<string, Object> dic1 = new Dictionary<string, Object>
+            {
+                { "Country", "UK" },
+                { "DeviceType", "Laptop" },
+                { "DataCenter", "DC1" }
+            };
+            TimeSeriesPoints.Add(new TimeSeriesPoint(200, 100, true, dic1));
+
+            Dictionary<string, Object> dic2 = new Dictionary<string, Object>();
+            dic2.Add("Country", "UK");
+            dic2.Add("DeviceType", "Mobile");
+            dic2.Add("DataCenter", "DC1");
+            TimeSeriesPoints.Add(new TimeSeriesPoint(1000, 100, true, dic2));
+
+            Dictionary<string, Object> dic3 = new Dictionary<string, Object>();
+            dic3.Add("Country", "UK");
+            dic3.Add("DeviceType", AGG_SYMBOL);
+            dic3.Add("DataCenter", "DC1");
+            TimeSeriesPoints.Add(new TimeSeriesPoint(1200, 200, true, dic3));
+
+            Dictionary<string, Object> dic4 = new Dictionary<string, Object>();
+            dic4.Add("Country", "UK");
+            dic4.Add("DeviceType", "Laptop");
+            dic4.Add("DataCenter", "DC2");
+            TimeSeriesPoints.Add(new TimeSeriesPoint(100, 100, false, dic4));
+
+            Dictionary<string, Object> dic5 = new Dictionary<string, Object>();
+            dic5.Add("Country", "UK");
+            dic5.Add("DeviceType", "Mobile");
+            dic5.Add("DataCenter", "DC2");
+            TimeSeriesPoints.Add(new TimeSeriesPoint(200, 200, false, dic5));
+
+            Dictionary<string, Object> dic6 = new Dictionary<string, Object>();
+            dic6.Add("Country", "UK");
+            dic6.Add("DeviceType", AGG_SYMBOL);
+            dic6.Add("DataCenter", "DC2");
+            TimeSeriesPoints.Add(new TimeSeriesPoint(300, 300, false, dic6));
+
+            Dictionary<string, Object> dic7 = new Dictionary<string, Object>();
+            dic7.Add("Country", "UK");
+            dic7.Add("DeviceType", AGG_SYMBOL);
+            dic7.Add("DataCenter", AGG_SYMBOL);
+            TimeSeriesPoints.Add(new TimeSeriesPoint(1800, 750, true, dic7));
+
+            Dictionary<string, Object> dic8 = new Dictionary<string, Object>();
+            dic8.Add("Country", "UK");
+            dic8.Add("DeviceType", "Laptop");
+            dic8.Add("DataCenter", AGG_SYMBOL);
+            TimeSeriesPoints.Add(new TimeSeriesPoint(1500, 450, true, dic8));
+
+            Dictionary<string, Object> dic9 = new Dictionary<string, Object>();
+            dic9.Add("Country", "UK");
+            dic9.Add("DeviceType", "Mobile");
+            dic9.Add("DataCenter", AGG_SYMBOL);
+            TimeSeriesPoints.Add(new TimeSeriesPoint(600, 550, false, dic9));
+
+            Dictionary<string, Object> dic10 = new Dictionary<string, Object>();
+            dic10.Add("Country", "UK");
+            dic10.Add("DeviceType", "Mobile");
+            dic10.Add("DataCenter", "DC3");
+            TimeSeriesPoints.Add(new TimeSeriesPoint(100, 100, false, dic10));
+
+            Dictionary<string, Object> dic11 = new Dictionary<string, Object>();
+            dic11.Add("Country", "UK");
+            dic11.Add("DeviceType", "Laptop");
+            dic11.Add("DataCenter", "DC3");
+            TimeSeriesPoints.Add(new TimeSeriesPoint(200, 250, false, dic11));
+
+            Dictionary<string, Object> dic12 = new Dictionary<string, Object>();
+            dic12.Add("Country", "UK");
+            dic12.Add("DeviceType", AGG_SYMBOL);
+            dic12.Add("DataCenter", "DC3");
+            TimeSeriesPoints.Add(new TimeSeriesPoint(300, 350, false, dic12));
+
+            return TimeSeriesPoints;
+        }
+
+        private static Dictionary<string, Object> GetAnomalyDimension()
+        {
+            Dictionary<string, Object> dim = new Dictionary<string, Object>();
+            dim.Add("Country", "UK");
+            dim.Add("DeviceType", AGG_SYMBOL);
+            dim.Add("DataCenter", AGG_SYMBOL);
+
+            return dim;
+        }
+
+        private static DateTime GetTimestamp()
+        {
+            return new DateTime(2020, 3, 23, 0, 0, 0);
+        }
+    }
+}

docs/samples/Microsoft.ML.Samples/Program.cs

@@ -6,20 +6,23 @@ namespace Microsoft.ML.Samples
 {
     public static class Program
     {
-        public static void Main(string[] args) => RunAll();
+        public static void Main(string[] args) => RunAll(args == null || args.Length == 0 ? null : args[0]);
 
-        internal static void RunAll()
+        internal static void RunAll(string name = null)
         {
             int samples = 0;
             foreach (var type in Assembly.GetExecutingAssembly().GetTypes())
             {
-                var sample = type.GetMethod("Example", BindingFlags.Public | BindingFlags.Static | BindingFlags.FlattenHierarchy);
-
-                if (sample != null)
+                if (name == null || name.Equals(type.Name))
                 {
-                    Console.WriteLine(type.Name);
-                    sample.Invoke(null, null);
-                    samples++;
+                    var sample = type.GetMethod("Example", BindingFlags.Public | BindingFlags.Static | BindingFlags.FlattenHierarchy);
+
+                    if (sample != null)
+                    {
+                        Console.WriteLine(type.Name);
+                        sample.Invoke(null, null);
+                        samples++;
+                    }
                 }
             }
 

src/Microsoft.ML.TimeSeries/ExtensionsCatalog.cs

@@ -2,6 +2,7 @@
 // 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.Collections.Generic;
 using Microsoft.ML.Data;
 using Microsoft.ML.Runtime;
 using Microsoft.ML.TimeSeries;
@@ -197,6 +198,35 @@ public static IDataView DetectEntireAnomalyBySrCnn(this AnomalyDetectionCatalog
         /// </format>
         /// </example>
         public static RootCause LocalizeRootCause(this AnomalyDetectionCatalog catalog, RootCauseLocalizationInput src, double beta = 0.3, double rootCauseThreshold = 0.95)
+        {
+            List<RootCause> causes = LocalizeRootCauses(catalog, src, beta, rootCauseThreshold);
+            if (causes?.Count > 0)
+            {
+                return causes[0];
+            }
+            else
+            {
+                return null;
+            }
+
+        }
+
+        /// <summary>
+        /// Outputs an ordered list of <see cref="RootCause"/>s. The order corresponds to which prepared cause is most likely to be the root cause.
+        /// </summary>
+        /// <param name="catalog">The anomaly detection catalog.</param>
+        /// <param name="src">Root cause's input. The data is an instance of <see cref="Microsoft.ML.TimeSeries.RootCauseLocalizationInput"/>.</param>
+        /// <param name="beta">Beta is a weight parameter for user to choose. It is used when score is calculated for each root cause item. The range of beta should be in [0,1]. For a larger beta, root cause point which has a large difference between value and expected value will get a high score. On the contrary, for a small beta, root cause items which has a high relative change will get a high score.</param>
+        /// <param name="rootCauseThreshold">A threshold to determine whether the point should be root cause. The range of this threshold should be in [0,1].
+        /// If the point's delta is equal to or larger than rootCauseThreshold multiplied by anomaly dimension point's delta, this point is treated as a root cause. Different threshold will turn out different results. Users can choose the delta according to their data and requirments.</param>
+        /// <example>
+        /// <format type="text/markdown">
+        /// <![CDATA[
+        /// [!code-csharp[LocalizeRootCauseMultipleDimensions](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/TimeSeries/LocalizeRootCauseMultipleDimensions.cs)]
+        /// ]]>
+        /// </format>
+        /// </example>
+        public static List<RootCause> LocalizeRootCauses(this AnomalyDetectionCatalog catalog, RootCauseLocalizationInput src, double beta = 0.5, double rootCauseThreshold = 0.95)
         {
             IHostEnvironment host = CatalogUtils.GetEnvironment(catalog);
 
@@ -205,12 +235,11 @@ public static RootCause LocalizeRootCause(this AnomalyDetectionCatalog catalog,
 
             //check parameters
             host.CheckUserArg(beta >= 0 && beta <= 1, nameof(beta), "Must be in [0,1]");
-            host.CheckUserArg(rootCauseThreshold >= 0 && rootCauseThreshold <= 1, nameof(beta), "Must be in [0,1]");
+            host.CheckUserArg(rootCauseThreshold >= 0 && rootCauseThreshold <= 1, nameof(rootCauseThreshold), "Must be in [0,1]");
 
-            //find out the root cause
+            //find out the possible causes
             RootCauseAnalyzer analyzer = new RootCauseAnalyzer(src, beta, rootCauseThreshold);
-            RootCause dst = analyzer.Analyze();
-            return dst;
+            return analyzer.AnalyzePossibleCauses();
         }
 
         /// <summary>