Results analyzer

Common/Analysis.cs

@@ -0,0 +1,57 @@
+/*
+ * QUANTCONNECT.COM - Democratizing Finance, Empowering Individuals.
+ * Lean Algorithmic Trading Engine v2.0. Copyright 2014 QuantConnect Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+*/
+
+using Newtonsoft.Json;
+using System.Collections.Generic;
+
+namespace QuantConnect
+{
+    /// <summary>
+    /// Represents the outcome of a single backtest diagnostic analysis,
+    /// containing the analysis name, diagnostic context, and a list of solutions.
+    /// </summary>
+    public class Analysis(string name, string issue, object sample, int? count, IReadOnlyList<string> solutions)
+    {
+        /// <summary>
+        /// Gets or sets the name of the analysis that produced this result.
+        /// </summary>
+        public string Name { get; set; } = name;
+
+        /// <summary>
+        /// Gets or sets a short description of why the analysis was triggered.
+        /// </summary>
+        public string Issue { get; set; } = issue;
+
+        /// <summary>
+        /// Gets or sets a representative sample value of the issue detected by the analysis.
+        /// It can be something like a log message, an order or an order event.
+        /// </summary>
+        public object Sample { get; set; } = sample;
+
+        /// <summary>
+        /// Gets or sets the total number of matching occurrences found by the analysis.
+        /// If null, the analysis is reporting a single issue with the provided sample;
+        /// if not null, the sample represents one of multiple occurrences of the same issue.
+        /// </summary>
+        [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
+        public int? Count { get; set; } = count;
+
+        /// <summary>
+        /// Gets or sets human-readable suggestions for resolving the detected issue.
+        /// </summary>
+        public IReadOnlyList<string> Solutions { get; set; } = solutions;
+    }
+}

Common/Extensions.cs

@@ -4558,6 +4558,19 @@ public static int GreatestCommonDivisor(this IEnumerable<int> values)
             return result.Value;
         }
 
+        /// <summary>
+        /// Returns a new sorted list of (v[i] / v[i-1] - 1) values. The first key is dropped.
+        /// </summary>
+        public static SortedList<DateTime, decimal> PercentChange(this SortedList<DateTime, decimal> values)
+        {
+            var result = new SortedList<DateTime, decimal>();
+            foreach (var (current, previous) in values.Skip(1).Zip(values, (current, previous) => (current, previous)))
+            {
+                result.Add(current.Key, current.Value / previous.Value - 1);
+            }
+            return result;
+        }
+
         /// <summary>
         /// Gets the greatest common divisor of two numbers
         /// </summary>

Common/Packets/BacktestResultParameters.cs

@@ -14,9 +14,9 @@
  *
 */
 
-using System;
 using QuantConnect.Orders;
 using QuantConnect.Statistics;
+using System;
 using System.Collections.Generic;
 
 namespace QuantConnect.Packets
@@ -43,8 +43,9 @@ public BacktestResultParameters(IDictionary<string, Chart> charts,
             List<OrderEvent> orderEvents,
             AlgorithmPerformance totalPerformance = null,
             AlgorithmConfiguration algorithmConfiguration = null,
-            IDictionary<string, string> state = null)
-            : base(charts, orders, profitLoss, statistics, runtimeStatistics, orderEvents, totalPerformance, algorithmConfiguration, state)
+            IDictionary<string, string> state = null,
+            IReadOnlyList<Analysis> analysisResult = null)
+            : base(charts, orders, profitLoss, statistics, runtimeStatistics, orderEvents, totalPerformance, algorithmConfiguration, state, analysisResult)
         {
             RollingWindow = rollingWindow;
         }

Common/Packets/BaseResultParameters.cs

@@ -71,6 +71,11 @@ public class BaseResultParameters
         /// </summary>
         public AlgorithmPerformance TotalPerformance { get; set; }
 
+        /// <summary>
+        /// Backtest analysis results.
+        /// </summary>
+        public IReadOnlyList<Analysis> Analysis { get; set; }
+
         /// <summary>
         /// Creates a new instance
         /// </summary>
@@ -82,7 +87,8 @@ public BaseResultParameters(IDictionary<string, Chart> charts,
             List<OrderEvent> orderEvents,
             AlgorithmPerformance totalPerformance = null,
             AlgorithmConfiguration algorithmConfiguration = null,
-            IDictionary<string, string> state = null)
+            IDictionary<string, string> state = null,
+            IReadOnlyList<Analysis> analysisResult = null)
         {
             Charts = charts;
             Orders = orders;
@@ -93,6 +99,7 @@ public BaseResultParameters(IDictionary<string, Chart> charts,
             AlgorithmConfiguration = algorithmConfiguration;
             State = state;
             TotalPerformance = totalPerformance;
+            Analysis = analysisResult;
         }
     }
 }

Common/Packets/LiveResultParameters.cs

@@ -56,8 +56,9 @@ public LiveResultParameters(IDictionary<string, Chart> charts,
             AlgorithmPerformance totalPerformance = null,
             IDictionary<string, string> serverStatistics = null,
             AlgorithmConfiguration algorithmConfiguration = null,
-            IDictionary<string, string> state = null)
-            : base(charts, orders, profitLoss, statistics, runtimeStatistics, orderEvents, totalPerformance, algorithmConfiguration, state)
+            IDictionary<string, string> state = null,
+            IReadOnlyList<Analysis> analysisResult = null)
+            : base(charts, orders, profitLoss, statistics, runtimeStatistics, orderEvents, totalPerformance, algorithmConfiguration, state, analysisResult)
         {
             Holdings = holdings;
             CashBook = cashBook;

Common/Result.cs

@@ -90,6 +90,12 @@ public class Result
         [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
         public AlgorithmPerformance TotalPerformance { get; set; }
 
+        /// <summary>
+        /// Backtest analysis results.
+        /// </summary>
+        [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
+        public IReadOnlyList<Analysis> Analysis { get; set; }
+
         /// <summary>
         /// Creates new empty instance
         /// </summary>
@@ -111,6 +117,7 @@ public Result(BaseResultParameters parameters)
             AlgorithmConfiguration = parameters.AlgorithmConfiguration;
             State = parameters.State;
             TotalPerformance = parameters.TotalPerformance;
+            Analysis = parameters.Analysis;
         }
     }
 }

Engine/Results/Analysis/Analyses/BaseResultsAnalysis.cs

@@ -0,0 +1,76 @@
+/*
+ * QUANTCONNECT.COM - Democratizing Finance, Empowering Individuals.
+ * Lean Algorithmic Trading Engine v2.0. Copyright 2014 QuantConnect Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+*/
+using Python.Runtime;
+using System.Collections.Generic;
+using System.Linq;
+
+namespace QuantConnect.Lean.Engine.Results.Analysis.Analyses
+{
+    /// <summary>
+    /// Abstract base class for all backtest diagnostic tests.
+    /// </summary>
+    public abstract class BaseResultsAnalysis
+    {
+        /// <summary>
+        /// Gets a short (3–8 word) description of why the analysis was triggered.
+        /// </summary>
+        public abstract string Issue { get; }
+
+        /// <summary>
+        /// Gets the severity/impact weight (0–100). Higher values run first and rank higher in results.
+        /// </summary>
+        public abstract int Weight { get; }
+
+        /// <summary>
+        /// Runs the analysis against all backtest data provided in <paramref name="parameters"/>.
+        /// </summary>
+        public abstract IReadOnlyList<QuantConnect.Analysis> Run(ResultsAnalysisRunParameters parameters);
+
+        /// <summary>
+        /// Wraps a single <see cref="QuantConnect.Analysis"/> in a one-element read-only list.
+        /// </summary>
+        protected IReadOnlyList<QuantConnect.Analysis> SingleResponse(object sample, IReadOnlyList<string> solutions = null)
+            => SingleResponse(sample, null, solutions);
+
+        /// <summary>
+        /// Wraps a single <see cref="QuantConnect.Analysis"/> in a one-element read-only list.
+        /// </summary>
+        protected IReadOnlyList<QuantConnect.Analysis> SingleResponse(object sample, int? count, IReadOnlyList<string> solutions = null)
+            => [new(GetType().Name, Issue, sample, count, solutions ?? [])];
+
+        /// <summary>
+        /// Filters <paramref name="responses"/> to those with solutions,
+        /// prefixes the class name, and returns a flat list.
+        /// </summary>
+        protected IReadOnlyList<QuantConnect.Analysis> CreateAggregatedResponse(IEnumerable<QuantConnect.Analysis> responses)
+            => responses
+                .Where(x => x.Solutions.Count > 0)
+                .Select(x => new QuantConnect.Analysis(GetType().Name + " / " + x.Name, x.Issue, x.Sample, x.Count, x.Solutions))
+                .ToList();
+
+        /// <summary>
+        /// Formats the specified code string according to the conventions of the given programming language.
+        /// </summary>
+        protected static string FormatCode(string code, Language language)
+        {
+            return language switch
+            {
+                Language.Python => code.ToSnakeCase(),
+                _ => code
+            };
+        }
+    }
+}