Add contract filters to futures chains and universes

Algorithm.CSharp/BasicTemplateFuturesAlgorithm.cs

@@ -88,11 +88,7 @@ public override void OnData(Slice slice)
                 foreach(var chain in slice.FutureChains)
                 {
                     // find the front contract expiring no earlier than in 90 days
-                    var contract = (
-                        from futuresContract in chain.Value.OrderBy(x => x.Expiry)
-                        where futuresContract.Expiry > Time.Date.AddDays(90)
-                        select futuresContract
-                    ).FirstOrDefault();
+                    var contract = chain.Value.ExpiringAfter(Time.Date.AddDays(90)).FrontMonth().FirstOrDefault();
 
                     // if found, trade it
                     if (contract != null)

Algorithm.CSharp/FuturesChainFiltersRegressionAlgorithm.cs

@@ -0,0 +1,209 @@
+/*
+ * 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;
+using System.Collections.Generic;
+using System.Linq;
+using QuantConnect.Data;
+using QuantConnect.Data.Market;
+using QuantConnect.Interfaces;
+using QuantConnect.Securities;
+
+namespace QuantConnect.Algorithm.CSharp
+{
+    /// <summary>
+    /// Regression algorithm using the futures chain filters, the same ones the futures universe selection offers,
+    /// on <see cref="QCAlgorithm.FuturesChain(Symbol, bool)"/> and on the chains of the <see cref="Slice"/>
+    /// </summary>
+    public class FuturesChainFiltersRegressionAlgorithm : QCAlgorithm, IRegressionAlgorithmDefinition
+    {
+        private static readonly DateTime EndOf2013 = new(2013, 12, 31);
+
+        private Symbol _es;
+        private Symbol _gc;
+        private bool _esChainSeen;
+        private bool _gcChainSeen;
+        private bool _traded;
+
+        public override void Initialize()
+        {
+            SetStartDate(2013, 10, 7);
+            SetEndDate(2013, 10, 9);
+            SetCash(1000000);
+
+            // The contracts expiring within a year
+            var es = AddFuture(Futures.Indices.SP500EMini, Resolution.Minute, Market.CME);
+            es.SetFilter(universe => universe.Expiration(0, 365));
+            _es = es.Symbol;
+
+            // The liquid contracts, by open interest
+            var gc = AddFuture(Futures.Metals.Gold, Resolution.Minute, Market.COMEX);
+            gc.SetFilter(universe => universe.OpenInterest(100000, long.MaxValue));
+            _gc = gc.Symbol;
+
+            // The full chain from the universe data: December 2013 and March, June, September and December 2014
+            var chain = FuturesChain(_es);
+            if (chain.Count != 5)
+            {
+                throw new RegressionTestException($"Expected 5 ES contracts but got {chain.Count}");
+            }
+            AssertExpiries(chain.FrontMonth(), "FrontMonth()", (2013, 12));
+            AssertExpiries(chain.BackMonth(), "BackMonth()", (2014, 3));
+            AssertExpiries(chain.BackMonths(), "BackMonths()", (2014, 3), (2014, 6), (2014, 9), (2014, 12));
+            AssertExpiries(chain.FarthestExpiration(), "FarthestExpiration()", (2014, 12));
+            AssertExpiries(chain.ExpirationCycle([3, 9]), "ExpirationCycle([3, 9])", (2014, 3), (2014, 9));
+            // ES contracts are named after their expiration month, so the contract month filters agree with the expiration ones
+            AssertExpiries(chain.ContractMonths([3, 9]), "ContractMonths([3, 9])", (2014, 3), (2014, 9));
+            AssertExpiries(chain.ExpiringBefore(EndOf2013), "ExpiringBefore(2013-12-31)", (2013, 12));
+            AssertExpiries(chain.ExpiringAfter(EndOf2013).ExpiringBefore(new DateTime(2014, 7, 1)), "ExpiringAfter(2013-12-31).ExpiringBefore(2014-07-01)", (2014, 3), (2014, 6));
+            AssertExpiries(chain.Expiration([chain.FrontMonth().First().Expiry]), "Expiration([front month expiry])", (2013, 12));
+            if (chain.ZeroDte().Count != 0 || chain.StandardsOnly().Count != chain.Count || chain.WeeklysOnly().Count != 0)
+            {
+                throw new RegressionTestException("Expected no contract expiring today and only standard contracts");
+            }
+
+            // The liquidity filters read the universe data: only the front month has more than a million contracts open
+            AssertExpiries(chain.OpenInterest(1000000, long.MaxValue), "OpenInterest(1000000, max)", (2013, 12));
+            if (chain.OI(0, 1000000).Count != chain.Count - 1 || chain.Volume(1, long.MaxValue).Count != chain.Count(x => x.Volume >= 1))
+            {
+                throw new RegressionTestException("Open interest or volume filter mismatch");
+            }
+        }
+
+        public override void OnData(Slice slice)
+        {
+            if (slice.FuturesChains.TryGetValue(_es, out var esChain))
+            {
+                _esChainSeen = true;
+                // The universe selected the contracts expiring within a year, so the chain filters agree with it
+                if (esChain.Count == 0 || esChain.Count > 4 || esChain.Expiration(0, 365).Count != esChain.Count || esChain.ExpiringAfter(Time).Count != esChain.Count
+                    || esChain.ZeroDte().Count != 0 || esChain.ExpirationCycle([3, 6, 9, 12]).Count != esChain.Count || esChain.ExpirationCycle([1, 2]).Count != 0
+                    || esChain.StandardsOnly().Count != esChain.Count || esChain.WeeklysOnly().Count != 0)
+                {
+                    throw new RegressionTestException("The ES slice chain disagrees with the universe filter");
+                }
+                var frontMonth = esChain.FrontMonth();
+                var farthest = esChain.FarthestExpiration();
+                if (frontMonth.Count == 0 || frontMonth.Any(x => x.Expiry != esChain.Min(c => c.Expiry)) || farthest.Any(x => x.Expiry != esChain.Max(c => c.Expiry))
+                    || esChain.BackMonths().Count != esChain.Count - frontMonth.Count)
+                {
+                    throw new RegressionTestException("Front month, back months or farthest expiration mismatch on the ES slice chain");
+                }
+                if (esChain.OpenInterest(1, long.MaxValue).Count != esChain.Count(x => x.OpenInterest >= 1) || esChain.Volume(1, long.MaxValue).Count != esChain.Count(x => x.Volume >= 1))
+                {
+                    throw new RegressionTestException("Open interest or volume filter mismatch on the ES slice chain");
+                }
+
+                // Buy the front contract expiring at least 90 days out
+                if (!_traded)
+                {
+                    var contract = esChain.ExpiringAfter(Time.Date.AddDays(90)).FrontMonth().FirstOrDefault();
+                    if (contract != null)
+                    {
+                        MarketOrder(contract.Symbol, 1);
+                        _traded = true;
+                    }
+                }
+            }
+
+            if (slice.FuturesChains.TryGetValue(_gc, out var gcChain))
+            {
+                _gcChainSeen = true;
+                // Only the December 2013 contract had more than a hundred thousand contracts open
+                if (gcChain.Count == 0 || gcChain.Any(x => x.Expiry.Year != 2013 || x.Expiry.Month != 12) || gcChain.FrontMonth().Count != gcChain.Count)
+                {
+                    throw new RegressionTestException($"The GC slice chain disagrees with the universe filter: {string.Join(", ", gcChain.Select(x => x.Expiry))}");
+                }
+            }
+        }
+
+        public override void OnEndOfAlgorithm()
+        {
+            if (!_esChainSeen || !_gcChainSeen || !_traded)
+            {
+                throw new RegressionTestException($"Expected the ES chain ({_esChainSeen}), the GC chain ({_gcChainSeen}) and a trade ({_traded})");
+            }
+        }
+
+        private static void AssertExpiries(FuturesChain chain, string filter, params (int year, int month)[] expected)
+        {
+            var actual = chain.Select(x => (x.Expiry.Year, x.Expiry.Month)).OrderBy(x => x).ToList();
+            if (!actual.SequenceEqual(expected.OrderBy(x => x)))
+            {
+                throw new RegressionTestException($"{filter}: expected {string.Join(", ", expected)} but got {string.Join(", ", actual)}");
+            }
+        }
+
+        /// <summary>
+        /// This is used by the regression test system to indicate if the open source Lean repository has the required data to run this algorithm.
+        /// </summary>
+        public bool CanRunLocally { get; } = true;
+
+        /// <summary>
+        /// This is used by the regression test system to indicate which languages this algorithm is written in.
+        /// </summary>
+        public virtual List<Language> Languages { get; } = new() { Language.CSharp, Language.Python };
+
+        /// <summary>
+        /// Data Points count of all timeslices of algorithm
+        /// </summary>
+        public long DataPoints => 34838;
+
+        /// <summary>
+        /// Data Points count of the algorithm history
+        /// </summary>
+        public int AlgorithmHistoryDataPoints => 1;
+
+        /// <summary>
+        /// Final status of the algorithm
+        /// </summary>
+        public AlgorithmStatus AlgorithmStatus => AlgorithmStatus.Completed;
+
+        /// <summary>
+        /// This is used by the regression test system to indicate what the expected statistics are from running the algorithm
+        /// </summary>
+        public Dictionary<string, string> ExpectedStatistics => new Dictionary<string, string>
+        {
+            {"Total Orders", "1"},
+            {"Average Win", "0%"},
+            {"Average Loss", "0%"},
+            {"Compounding Annual Return", "-11.911%"},
+            {"Drawdown", "0.200%"},
+            {"Expectancy", "0"},
+            {"Start Equity", "1000000"},
+            {"End Equity", "998958.2"},
+            {"Net Profit", "-0.104%"},
+            {"Sharpe Ratio", "-9.32"},
+            {"Sortino Ratio", "0"},
+            {"Probabilistic Sharpe Ratio", "0%"},
+            {"Loss Rate", "0%"},
+            {"Win Rate", "0%"},
+            {"Profit-Loss Ratio", "0"},
+            {"Alpha", "-0.048"},
+            {"Beta", "0.095"},
+            {"Annual Standard Deviation", "0.013"},
+            {"Annual Variance", "0"},
+            {"Information Ratio", "5.187"},
+            {"Tracking Error", "0.123"},
+            {"Treynor Ratio", "-1.269"},
+            {"Total Fees", "$2.15"},
+            {"Estimated Strategy Capacity", "$940000000.00"},
+            {"Lowest Capacity Asset", "ES VP274HSU1AF5"},
+            {"Portfolio Turnover", "2.77%"},
+            {"Drawdown Recovery", "0"},
+            {"OrderListHash", "3b6b723d50c0d435d763aa456af197a6"}
+        };
+    }
+}

Algorithm.Python/BasicTemplateFuturesAlgorithm.py

@@ -49,12 +49,9 @@ def initialize(self):
     def on_data(self,slice):
         if not self.portfolio.invested:
             for chain in slice.future_chains:
-                 # Get contracts expiring no earlier than in 90 days
-                contracts = list(filter(lambda x: x.expiry > self.time + timedelta(90), chain.value))
-
-                # if there is any contract, trade the front contract
-                if len(contracts) == 0: continue
-                front = sorted(contracts, key = lambda x: x.expiry, reverse=True)[0]
+                # Get the front contract expiring no earlier than in 90 days, if any, and trade it
+                front = next(iter(chain.value.expiring_after(self.time + timedelta(90)).front_month()), None)
+                if front is None: continue
 
                 self.contract_symbol = front.symbol
                 self.market_order(front.symbol , 1)

Algorithm.Python/FuturesChainFiltersRegressionAlgorithm.py

@@ -0,0 +1,106 @@
+# 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.
+
+from AlgorithmImports import *
+
+### <summary>
+### Regression algorithm using the futures chain filters, the same ones the futures universe selection offers,
+### on futures_chain() and on the chains of the slice
+### </summary>
+class FuturesChainFiltersRegressionAlgorithm(QCAlgorithm):
+    END_OF_2013 = datetime(2013, 12, 31)
+    MAX_LONG = 2**62
+
+    def initialize(self):
+        self.set_start_date(2013, 10, 7)
+        self.set_end_date(2013, 10, 9)
+        self.set_cash(1000000)
+
+        # The contracts expiring within a year
+        es = self.add_future(Futures.Indices.SP_500_E_MINI, Resolution.MINUTE, Market.CME)
+        es.set_filter(lambda universe: universe.expiration(0, 365))
+        self._es = es.symbol
+
+        # The liquid contracts, by open interest
+        gc = self.add_future(Futures.Metals.GOLD, Resolution.MINUTE, Market.COMEX)
+        gc.set_filter(lambda universe: universe.open_interest(100000, self.MAX_LONG))
+        self._gc = gc.symbol
+
+        self._es_chain_seen = False
+        self._gc_chain_seen = False
+        self._traded = False
+
+        # The full chain from the universe data: December 2013 and March, June, September and December 2014
+        chain = self.futures_chain(self._es)
+        if chain.count != 5:
+            raise AssertionError(f"Expected 5 ES contracts but got {chain.count}")
+        self._assert_expiries(chain.front_month(), "front_month()", [(2013, 12)])
+        self._assert_expiries(chain.back_month(), "back_month()", [(2014, 3)])
+        self._assert_expiries(chain.back_months(), "back_months()", [(2014, 3), (2014, 6), (2014, 9), (2014, 12)])
+        self._assert_expiries(chain.farthest_expiration(), "farthest_expiration()", [(2014, 12)])
+        self._assert_expiries(chain.expiration_cycle([3, 9]), "expiration_cycle([3, 9])", [(2014, 3), (2014, 9)])
+        # ES contracts are named after their expiration month, so the contract month filters agree with the expiration ones
+        self._assert_expiries(chain.contract_months([3, 9]), "contract_months([3, 9])", [(2014, 3), (2014, 9)])
+        self._assert_expiries(chain.expiring_before(self.END_OF_2013), "expiring_before(2013-12-31)", [(2013, 12)])
+        self._assert_expiries(chain.expiring_after(self.END_OF_2013).expiring_before(datetime(2014, 7, 1)), "expiring_after(2013-12-31).expiring_before(2014-07-01)", [(2014, 3), (2014, 6)])
+        self._assert_expiries(chain.expiration([next(iter(chain.front_month())).expiry]), "expiration([front month expiry])", [(2013, 12)])
+        if chain.zero_dte().count != 0 or chain.standards_only().count != chain.count or chain.weeklys_only().count != 0:
+            raise AssertionError("Expected no contract expiring today and only standard contracts")
+
+        # The liquidity filters read the universe data: only the front month has more than a million contracts open
+        self._assert_expiries(chain.open_interest(1000000, self.MAX_LONG), "open_interest(1000000, max)", [(2013, 12)])
+        if chain.oi(0, 1000000).count != chain.count - 1 or chain.volume(1, self.MAX_LONG).count != sum(1 for x in chain if x.volume >= 1):
+            raise AssertionError("Open interest or volume filter mismatch")
+
+    def on_data(self, slice):
+        es_chain = slice.futures_chains.get(self._es)
+        if es_chain:
+            self._es_chain_seen = True
+            # The universe selected the contracts expiring within a year, so the chain filters agree with it
+            if (es_chain.count == 0 or es_chain.count > 4 or es_chain.expiration(0, 365).count != es_chain.count or es_chain.expiring_after(self.time).count != es_chain.count
+                    or es_chain.zero_dte().count != 0 or es_chain.expiration_cycle([3, 6, 9, 12]).count != es_chain.count or es_chain.expiration_cycle([1, 2]).count != 0
+                    or es_chain.standards_only().count != es_chain.count or es_chain.weeklys_only().count != 0):
+                raise AssertionError("The ES slice chain disagrees with the universe filter")
+            front_month = es_chain.front_month()
+            farthest = es_chain.farthest_expiration()
+            min_expiry = min(x.expiry for x in es_chain)
+            max_expiry = max(x.expiry for x in es_chain)
+            if (front_month.count == 0 or any(x.expiry != min_expiry for x in front_month) or any(x.expiry != max_expiry for x in farthest)
+                    or es_chain.back_months().count != es_chain.count - front_month.count):
+                raise AssertionError("Front month, back months or farthest expiration mismatch on the ES slice chain")
+            if (es_chain.open_interest(1, self.MAX_LONG).count != sum(1 for x in es_chain if x.open_interest >= 1)
+                    or es_chain.volume(1, self.MAX_LONG).count != sum(1 for x in es_chain if x.volume >= 1)):
+                raise AssertionError("Open interest or volume filter mismatch on the ES slice chain")
+
+            # Buy the front contract expiring at least 90 days out
+            if not self._traded:
+                contract = next(iter(es_chain.expiring_after(self.time + timedelta(days=90)).front_month()), None)
+                if contract is not None:
+                    self.market_order(contract.symbol, 1)
+                    self._traded = True
+
+        gc_chain = slice.futures_chains.get(self._gc)
+        if gc_chain:
+            self._gc_chain_seen = True
+            # Only the December 2013 contract had more than a hundred thousand contracts open
+            if gc_chain.count == 0 or any(x.expiry.year != 2013 or x.expiry.month != 12 for x in gc_chain) or gc_chain.front_month().count != gc_chain.count:
+                raise AssertionError(f"The GC slice chain disagrees with the universe filter: {[x.expiry for x in gc_chain]}")
+
+    def on_end_of_algorithm(self):
+        if not self._es_chain_seen or not self._gc_chain_seen or not self._traded:
+            raise AssertionError(f"Expected the ES chain ({self._es_chain_seen}), the GC chain ({self._gc_chain_seen}) and a trade ({self._traded})")
+
+    def _assert_expiries(self, chain, filter_name, expected):
+        actual = sorted((x.expiry.year, x.expiry.month) for x in chain)
+        if actual != sorted(expected):
+            raise AssertionError(f"{filter_name}: expected {expected} but got {actual}")