Add optimization analysis (#9495)

* Add optimization analysis

* Address feedback

* Remove redundant CurveType

* Address feedback pt 2

* Address review pt 3

* Address review pt 4

* Removed redundant properties

* Add Interpretation member

Author: DerekMelchin

Common/Api/Optimization.cs

@@ -16,6 +16,7 @@
 using System;
 using System.Collections.Generic;
 using Newtonsoft.Json;
+using QuantConnect.Optimizer;
 using QuantConnect.Optimizer.Objectives;
 using QuantConnect.Util;
 
@@ -74,6 +75,12 @@ public class Optimization : BaseOptimization
         /// </summary>
         [JsonConverter(typeof(DateTimeJsonConverter), DateFormat.ISOShort, DateFormat.UI)]
         public DateTime Requested { get; set; }
+
+        /// <summary>
+        /// Aggregate diagnostic of the optimization; omitted when no analysis was produced.
+        /// </summary>
+        [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
+        public OptimizationAnalysis Analysis { get; set; }
     }
 
     /// <summary>

Common/Optimizer/Analysis/OptimizationAnalysisRunParameters.cs

@@ -0,0 +1,50 @@
+/*
+ * 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 QuantConnect.Optimizer.Parameters;
+using System.Collections.Generic;
+
+namespace QuantConnect.Optimizer.Analysis
+{
+    /// <summary>
+    /// Bundles the inputs to the optimization analyzer: per-backtest metrics and the parameter grid spec.
+    /// </summary>
+    public class OptimizationAnalysisRunParameters
+    {
+        /// <summary>
+        /// Completed backtests from the optimization, already reduced to the metrics the analyzer reads.
+        /// </summary>
+        public IReadOnlyList<OptimizationBacktestMetrics> CompletedBacktests { get; }
+
+        /// <summary>
+        /// The optimization parameter grid spec.
+        /// </summary>
+        public IReadOnlyCollection<OptimizationParameter> OptimizationParameters { get; }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="OptimizationAnalysisRunParameters"/> class.
+        /// </summary>
+        /// <param name="completedBacktests">The completed backtest metrics.</param>
+        /// <param name="optimizationParameters">The parameter grid spec.</param>
+        public OptimizationAnalysisRunParameters(
+            IReadOnlyList<OptimizationBacktestMetrics> completedBacktests,
+            IReadOnlyCollection<OptimizationParameter> optimizationParameters)
+        {
+            CompletedBacktests = completedBacktests;
+            OptimizationParameters = optimizationParameters;
+        }
+    }
+}

Common/Optimizer/BacktestSummary.cs

@@ -0,0 +1,43 @@
+/*
+ * 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.Optimizer
+{
+    /// <summary>
+    /// Per-backtest identity + Sharpe ratio shared by all optimization-analysis records that describe one backtest.
+    /// </summary>
+    public class BacktestSummary
+    {
+        /// <summary>
+        /// The backtest id; kept for programmatic access but not serialized into the analysis JSON.
+        /// </summary>
+        [JsonIgnore]
+        public string BacktestId { get; set; }
+
+        /// <summary>
+        /// Parameter values the backtest was run with.
+        /// </summary>
+        public IReadOnlyDictionary<string, decimal> Parameters { get; set; }
+
+        /// <summary>
+        /// The backtest's Sharpe ratio.
+        /// </summary>
+        public decimal SharpeRatio { get; set; }
+    }
+}

Common/Optimizer/Cluster.cs

@@ -0,0 +1,56 @@
+/*
+ * 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 System.Collections.Generic;
+
+namespace QuantConnect.Optimizer
+{
+    /// <summary>
+    /// One k-means cluster of backtests in standardized parameter space.
+    /// </summary>
+    public class Cluster
+    {
+        /// <summary>
+        /// Cluster centroid in original parameter units.
+        /// </summary>
+        public IReadOnlyDictionary<string, decimal> Centroid { get; set; }
+
+        /// <summary>
+        /// Number of backtests assigned to this cluster.
+        /// </summary>
+        public int MemberCount { get; set; }
+
+        /// <summary>
+        /// Mean Sharpe ratio across the cluster's members.
+        /// </summary>
+        public decimal SharpeMean { get; set; }
+
+        /// <summary>
+        /// Sample standard deviation of Sharpe ratios within this cluster.
+        /// </summary>
+        public decimal SharpeStdDev { get; set; }
+
+        /// <summary>
+        /// Minimum Sharpe ratio within this cluster.
+        /// </summary>
+        public decimal SharpeMin { get; set; }
+
+        /// <summary>
+        /// Maximum Sharpe ratio within this cluster.
+        /// </summary>
+        public decimal SharpeMax { get; set; }
+    }
+}

Common/Optimizer/FailedBacktestSummary.cs

@@ -0,0 +1,41 @@
+/*
+ * 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 System.Collections.Generic;
+
+namespace QuantConnect.Optimizer
+{
+    /// <summary>
+    /// Breakdown of backtests in an optimization that produced zero orders.
+    /// </summary>
+    public class FailedBacktestSummary
+    {
+        /// <summary>
+        /// Total number of backtests that produced zero orders.
+        /// </summary>
+        public int ZeroOrderCount { get; set; }
+
+        /// <summary>
+        /// Number of zero-order backtests inspected for analysis tags; may be smaller than <see cref="ZeroOrderCount"/>.
+        /// </summary>
+        public int InspectedCount { get; set; }
+
+        /// <summary>
+        /// Map of analysis-tag name to the number of inspected backtests carrying that tag.
+        /// </summary>
+        public IReadOnlyDictionary<string, int> AnalysisNameCounts { get; set; }
+    }
+}

Common/Optimizer/LinearSegment.cs

@@ -0,0 +1,44 @@
+/*
+ * 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.
+ *
+*/
+
+namespace QuantConnect.Optimizer
+{
+    /// <summary>
+    /// One linear piece of a piecewise interpolant on [<see cref="XLo"/>, <see cref="XHi"/>], evaluated as y(x) = A + B * (x - XLo).
+    /// </summary>
+    public class LinearSegment
+    {
+        /// <summary>
+        /// Lower bound of this segment.
+        /// </summary>
+        public decimal XLo { get; set; }
+
+        /// <summary>
+        /// Upper bound of this segment.
+        /// </summary>
+        public decimal XHi { get; set; }
+
+        /// <summary>
+        /// Sharpe ratio at <see cref="XLo"/>.
+        /// </summary>
+        public decimal A { get; set; }
+
+        /// <summary>
+        /// Slope through the segment.
+        /// </summary>
+        public decimal B { get; set; }
+    }
+}

Common/Optimizer/Mode.cs

@@ -0,0 +1,29 @@
+/*
+ * 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.
+ *
+*/
+
+namespace QuantConnect.Optimizer
+{
+    /// <summary>
+    /// A local maximum of the Sharpe surface on the parameter grid; strictly greater than every face-neighbor's Sharpe.
+    /// </summary>
+    public class Mode : BacktestSummary
+    {
+        /// <summary>
+        /// Number of face-neighbors this backtest was compared against.
+        /// </summary>
+        public int NeighborCount { get; set; }
+    }
+}

Common/Optimizer/OptimizationAnalysis.cs

@@ -0,0 +1,77 @@
+/*
+ * 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;
+using System.ComponentModel;
+
+namespace QuantConnect.Optimizer
+{
+    /// <summary>
+    /// Aggregate diagnostic produced by analyzing a completed optimization.
+    /// </summary>
+    public class OptimizationAnalysis
+    {
+        /// <summary>
+        /// Natural-language interpretation of the analysis produced by a downstream AI consumer; empty until populated.
+        /// </summary>
+        [DefaultValue("")]
+        [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)]
+        public string Interpretation { get; set; } = string.Empty;
+
+        /// <summary>
+        /// Total number of backtests observed, including failures.
+        /// </summary>
+        public int BacktestCountTotal { get; set; }
+
+        /// <summary>
+        /// Number of backtests used in the analysis after filtering failures.
+        /// </summary>
+        public int BacktestCountUsed { get; set; }
+
+        /// <summary>
+        /// Sharpe ratio statistics across all used backtests.
+        /// </summary>
+        public SharpeSummary OverallSharpe { get; set; }
+
+        /// <summary>
+        /// The best-performing backtest (argmax of Sharpe).
+        /// </summary>
+        [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
+        public BacktestSummary Best { get; set; }
+
+        /// <summary>
+        /// Per-parameter sensitivity report; one entry per optimized parameter.
+        /// </summary>
+        public IReadOnlyList<ParameterReport> Parameters { get; set; }
+
+        /// <summary>
+        /// K-means clusters in standardized parameter space, ordered by mean Sharpe descending.
+        /// </summary>
+        public IReadOnlyList<Cluster> Clusters { get; set; }
+
+        /// <summary>
+        /// Local maxima of the Sharpe surface on the parameter grid, ordered by Sharpe descending.
+        /// </summary>
+        public IReadOnlyList<Mode> Modes { get; set; }
+
+        /// <summary>
+        /// Breakdown of zero-order backtests; null when none exist.
+        /// </summary>
+        [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
+        public FailedBacktestSummary FailedBacktests { get; set; }
+    }
+}