Skip to content

Commit 02e491c

Browse files
jhonabreuljhonabreul
authored
Add contract filters to futures chains and universes (#9791)
* Add contract filters to futures chains and universes Split the contract filters shared by every derivative into IContractFilters, with IFutureContractFilters and IOptionContractFilters on top, and move the open interest and volume filters into ContractSecurityFilterUniverse so the futures universe gets them. Add BaseFutureFilterUniverse over the universe rows and the chain contracts, FuturesChainFilterUniverse, and FuturesChain filters that forward to it. The chain wrappers shared by OptionChain and FuturesChain live once in a BaseChain layer with the chain type and its filter universe as parameters. New futures filters: ContractMonth(year, month) and ContractMonths(months), by the contract month rather than the expiration month. FutureSymbol.IsStandard and FutureOptionSymbol.IsStandard back the standard and weekly filters. Tests: FuturesChainTests (parity with the universe, every universe filter declared on the interface, Python), FutureFilterTests, OptionChainTests, and the FuturesChainFiltersRegressionAlgorithm in C# and Python. The futures templates pick the front contract with the new filters. * Drop the single contract month filter and take any months sequence in ExpirationCycle
1 parent 5b0c997 commit 02e491c

20 files changed

Lines changed: 1371 additions & 313 deletions

‎Algorithm.CSharp/BasicTemplateFuturesAlgorithm.cs‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -88,11 +88,7 @@ public override void OnData(Slice slice)
8888
foreach(var chain in slice.FutureChains)
8989
{
9090
// find the front contract expiring no earlier than in 90 days
91-
var contract = (
92-
from futuresContract in chain.Value.OrderBy(x => x.Expiry)
93-
where futuresContract.Expiry > Time.Date.AddDays(90)
94-
select futuresContract
95-
).FirstOrDefault();
91+
var contract = chain.Value.ExpiringAfter(Time.Date.AddDays(90)).FrontMonth().FirstOrDefault();
9692

9793
// if found, trade it
9894
if (contract != null)

‎Algorithm.CSharp/FuturesChainFiltersRegressionAlgorithm.cs‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
/*
2+
* QUANTCONNECT.COM - Democratizing Finance, Empowering Individuals.
3+
* Lean Algorithmic Trading Engine v2.0. Copyright 2014 QuantConnect Corporation.
4+
*
5+
* Licensed under the Apache License, Version 2.0 (the "License");
6+
* you may not use this file except in compliance with the License.
7+
* You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
8+
*
9+
* Unless required by applicable law or agreed to in writing, software
10+
* distributed under the License is distributed on an "AS IS" BASIS,
11+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
* See the License for the specific language governing permissions and
13+
* limitations under the License.
14+
*/
15+
16+
using System;
17+
using System.Collections.Generic;
18+
using System.Linq;
19+
using QuantConnect.Data;
20+
using QuantConnect.Data.Market;
21+
using QuantConnect.Interfaces;
22+
using QuantConnect.Securities;
23+
24+
namespace QuantConnect.Algorithm.CSharp
25+
{
26+
/// <summary>
27+
/// Regression algorithm using the futures chain filters, the same ones the futures universe selection offers,
28+
/// on <see cref="QCAlgorithm.FuturesChain(Symbol, bool)"/> and on the chains of the <see cref="Slice"/>
29+
/// </summary>
30+
public class FuturesChainFiltersRegressionAlgorithm : QCAlgorithm, IRegressionAlgorithmDefinition
31+
{
32+
private static readonly DateTime EndOf2013 = new(2013, 12, 31);
33+
34+
private Symbol _es;
35+
private Symbol _gc;
36+
private bool _esChainSeen;
37+
private bool _gcChainSeen;
38+
private bool _traded;
39+
40+
public override void Initialize()
41+
{
42+
SetStartDate(2013, 10, 7);
43+
SetEndDate(2013, 10, 9);
44+
SetCash(1000000);
45+
46+
// The contracts expiring within a year
47+
var es = AddFuture(Futures.Indices.SP500EMini, Resolution.Minute, Market.CME);
48+
es.SetFilter(universe => universe.Expiration(0, 365));
49+
_es = es.Symbol;
50+
51+
// The liquid contracts, by open interest
52+
var gc = AddFuture(Futures.Metals.Gold, Resolution.Minute, Market.COMEX);
53+
gc.SetFilter(universe => universe.OpenInterest(100000, long.MaxValue));
54+
_gc = gc.Symbol;
55+
56+
// The full chain from the universe data: December 2013 and March, June, September and December 2014
57+
var chain = FuturesChain(_es);
58+
if (chain.Count != 5)
59+
{
60+
throw new RegressionTestException($"Expected 5 ES contracts but got {chain.Count}");
61+
}
62+
AssertExpiries(chain.FrontMonth(), "FrontMonth()", (2013, 12));
63+
AssertExpiries(chain.BackMonth(), "BackMonth()", (2014, 3));
64+
AssertExpiries(chain.BackMonths(), "BackMonths()", (2014, 3), (2014, 6), (2014, 9), (2014, 12));
65+
AssertExpiries(chain.FarthestExpiration(), "FarthestExpiration()", (2014, 12));
66+
AssertExpiries(chain.ExpirationCycle([3, 9]), "ExpirationCycle([3, 9])", (2014, 3), (2014, 9));
67+
// ES contracts are named after their expiration month, so the contract month filters agree with the expiration ones
68+
AssertExpiries(chain.ContractMonths([3, 9]), "ContractMonths([3, 9])", (2014, 3), (2014, 9));
69+
AssertExpiries(chain.ExpiringBefore(EndOf2013), "ExpiringBefore(2013-12-31)", (2013, 12));
70+
AssertExpiries(chain.ExpiringAfter(EndOf2013).ExpiringBefore(new DateTime(2014, 7, 1)), "ExpiringAfter(2013-12-31).ExpiringBefore(2014-07-01)", (2014, 3), (2014, 6));
71+
AssertExpiries(chain.Expiration([chain.FrontMonth().First().Expiry]), "Expiration([front month expiry])", (2013, 12));
72+
if (chain.ZeroDte().Count != 0 || chain.StandardsOnly().Count != chain.Count || chain.WeeklysOnly().Count != 0)
73+
{
74+
throw new RegressionTestException("Expected no contract expiring today and only standard contracts");
75+
}
76+
77+
// The liquidity filters read the universe data: only the front month has more than a million contracts open
78+
AssertExpiries(chain.OpenInterest(1000000, long.MaxValue), "OpenInterest(1000000, max)", (2013, 12));
79+
if (chain.OI(0, 1000000).Count != chain.Count - 1 || chain.Volume(1, long.MaxValue).Count != chain.Count(x => x.Volume >= 1))
80+
{
81+
throw new RegressionTestException("Open interest or volume filter mismatch");
82+
}
83+
}
84+
85+
public override void OnData(Slice slice)
86+
{
87+
if (slice.FuturesChains.TryGetValue(_es, out var esChain))
88+
{
89+
_esChainSeen = true;
90+
// The universe selected the contracts expiring within a year, so the chain filters agree with it
91+
if (esChain.Count == 0 || esChain.Count > 4 || esChain.Expiration(0, 365).Count != esChain.Count || esChain.ExpiringAfter(Time).Count != esChain.Count
92+
|| esChain.ZeroDte().Count != 0 || esChain.ExpirationCycle([3, 6, 9, 12]).Count != esChain.Count || esChain.ExpirationCycle([1, 2]).Count != 0
93+
|| esChain.StandardsOnly().Count != esChain.Count || esChain.WeeklysOnly().Count != 0)
94+
{
95+
throw new RegressionTestException("The ES slice chain disagrees with the universe filter");
96+
}
97+
var frontMonth = esChain.FrontMonth();
98+
var farthest = esChain.FarthestExpiration();
99+
if (frontMonth.Count == 0 || frontMonth.Any(x => x.Expiry != esChain.Min(c => c.Expiry)) || farthest.Any(x => x.Expiry != esChain.Max(c => c.Expiry))
100+
|| esChain.BackMonths().Count != esChain.Count - frontMonth.Count)
101+
{
102+
throw new RegressionTestException("Front month, back months or farthest expiration mismatch on the ES slice chain");
103+
}
104+
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))
105+
{
106+
throw new RegressionTestException("Open interest or volume filter mismatch on the ES slice chain");
107+
}
108+
109+
// Buy the front contract expiring at least 90 days out
110+
if (!_traded)
111+
{
112+
var contract = esChain.ExpiringAfter(Time.Date.AddDays(90)).FrontMonth().FirstOrDefault();
113+
if (contract != null)
114+
{
115+
MarketOrder(contract.Symbol, 1);
116+
_traded = true;
117+
}
118+
}
119+
}
120+
121+
if (slice.FuturesChains.TryGetValue(_gc, out var gcChain))
122+
{
123+
_gcChainSeen = true;
124+
// Only the December 2013 contract had more than a hundred thousand contracts open
125+
if (gcChain.Count == 0 || gcChain.Any(x => x.Expiry.Year != 2013 || x.Expiry.Month != 12) || gcChain.FrontMonth().Count != gcChain.Count)
126+
{
127+
throw new RegressionTestException($"The GC slice chain disagrees with the universe filter: {string.Join(", ", gcChain.Select(x => x.Expiry))}");
128+
}
129+
}
130+
}
131+
132+
public override void OnEndOfAlgorithm()
133+
{
134+
if (!_esChainSeen || !_gcChainSeen || !_traded)
135+
{
136+
throw new RegressionTestException($"Expected the ES chain ({_esChainSeen}), the GC chain ({_gcChainSeen}) and a trade ({_traded})");
137+
}
138+
}
139+
140+
private static void AssertExpiries(FuturesChain chain, string filter, params (int year, int month)[] expected)
141+
{
142+
var actual = chain.Select(x => (x.Expiry.Year, x.Expiry.Month)).OrderBy(x => x).ToList();
143+
if (!actual.SequenceEqual(expected.OrderBy(x => x)))
144+
{
145+
throw new RegressionTestException($"{filter}: expected {string.Join(", ", expected)} but got {string.Join(", ", actual)}");
146+
}
147+
}
148+
149+
/// <summary>
150+
/// This is used by the regression test system to indicate if the open source Lean repository has the required data to run this algorithm.
151+
/// </summary>
152+
public bool CanRunLocally { get; } = true;
153+
154+
/// <summary>
155+
/// This is used by the regression test system to indicate which languages this algorithm is written in.
156+
/// </summary>
157+
public virtual List<Language> Languages { get; } = new() { Language.CSharp, Language.Python };
158+
159+
/// <summary>
160+
/// Data Points count of all timeslices of algorithm
161+
/// </summary>
162+
public long DataPoints => 34838;
163+
164+
/// <summary>
165+
/// Data Points count of the algorithm history
166+
/// </summary>
167+
public int AlgorithmHistoryDataPoints => 1;
168+
169+
/// <summary>
170+
/// Final status of the algorithm
171+
/// </summary>
172+
public AlgorithmStatus AlgorithmStatus => AlgorithmStatus.Completed;
173+
174+
/// <summary>
175+
/// This is used by the regression test system to indicate what the expected statistics are from running the algorithm
176+
/// </summary>
177+
public Dictionary<string, string> ExpectedStatistics => new Dictionary<string, string>
178+
{
179+
{"Total Orders", "1"},
180+
{"Average Win", "0%"},
181+
{"Average Loss", "0%"},
182+
{"Compounding Annual Return", "-11.911%"},
183+
{"Drawdown", "0.200%"},
184+
{"Expectancy", "0"},
185+
{"Start Equity", "1000000"},
186+
{"End Equity", "998958.2"},
187+
{"Net Profit", "-0.104%"},
188+
{"Sharpe Ratio", "-9.32"},
189+
{"Sortino Ratio", "0"},
190+
{"Probabilistic Sharpe Ratio", "0%"},
191+
{"Loss Rate", "0%"},
192+
{"Win Rate", "0%"},
193+
{"Profit-Loss Ratio", "0"},
194+
{"Alpha", "-0.048"},
195+
{"Beta", "0.095"},
196+
{"Annual Standard Deviation", "0.013"},
197+
{"Annual Variance", "0"},
198+
{"Information Ratio", "5.187"},
199+
{"Tracking Error", "0.123"},
200+
{"Treynor Ratio", "-1.269"},
201+
{"Total Fees", "$2.15"},
202+
{"Estimated Strategy Capacity", "$940000000.00"},
203+
{"Lowest Capacity Asset", "ES VP274HSU1AF5"},
204+
{"Portfolio Turnover", "2.77%"},
205+
{"Drawdown Recovery", "0"},
206+
{"OrderListHash", "3b6b723d50c0d435d763aa456af197a6"}
207+
};
208+
}
209+
}

‎Algorithm.Python/BasicTemplateFuturesAlgorithm.py‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -49,12 +49,9 @@ def initialize(self):
4949
def on_data(self,slice):
5050
if not self.portfolio.invested:
5151
for chain in slice.future_chains:
52-
# Get contracts expiring no earlier than in 90 days
53-
contracts = list(filter(lambda x: x.expiry > self.time + timedelta(90), chain.value))
54-
55-
# if there is any contract, trade the front contract
56-
if len(contracts) == 0: continue
57-
front = sorted(contracts, key = lambda x: x.expiry, reverse=True)[0]
52+
# Get the front contract expiring no earlier than in 90 days, if any, and trade it
53+
front = next(iter(chain.value.expiring_after(self.time + timedelta(90)).front_month()), None)
54+
if front is None: continue
5855

5956
self.contract_symbol = front.symbol
6057
self.market_order(front.symbol , 1)

‎Algorithm.Python/FuturesChainFiltersRegressionAlgorithm.py‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# QUANTCONNECT.COM - Democratizing Finance, Empowering Individuals.
2+
# Lean Algorithmic Trading Engine v2.0. Copyright 2014 QuantConnect Corporation.
3+
#
4+
# Licensed under the Apache License, Version 2.0 (the "License");
5+
# you may not use this file except in compliance with the License.
6+
# You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
7+
#
8+
# Unless required by applicable law or agreed to in writing, software
9+
# distributed under the License is distributed on an "AS IS" BASIS,
10+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11+
# See the License for the specific language governing permissions and
12+
# limitations under the License.
13+
14+
from AlgorithmImports import *
15+
16+
### <summary>
17+
### Regression algorithm using the futures chain filters, the same ones the futures universe selection offers,
18+
### on futures_chain() and on the chains of the slice
19+
### </summary>
20+
class FuturesChainFiltersRegressionAlgorithm(QCAlgorithm):
21+
END_OF_2013 = datetime(2013, 12, 31)
22+
MAX_LONG = 2**62
23+
24+
def initialize(self):
25+
self.set_start_date(2013, 10, 7)
26+
self.set_end_date(2013, 10, 9)
27+
self.set_cash(1000000)
28+
29+
# The contracts expiring within a year
30+
es = self.add_future(Futures.Indices.SP_500_E_MINI, Resolution.MINUTE, Market.CME)
31+
es.set_filter(lambda universe: universe.expiration(0, 365))
32+
self._es = es.symbol
33+
34+
# The liquid contracts, by open interest
35+
gc = self.add_future(Futures.Metals.GOLD, Resolution.MINUTE, Market.COMEX)
36+
gc.set_filter(lambda universe: universe.open_interest(100000, self.MAX_LONG))
37+
self._gc = gc.symbol
38+
39+
self._es_chain_seen = False
40+
self._gc_chain_seen = False
41+
self._traded = False
42+
43+
# The full chain from the universe data: December 2013 and March, June, September and December 2014
44+
chain = self.futures_chain(self._es)
45+
if chain.count != 5:
46+
raise AssertionError(f"Expected 5 ES contracts but got {chain.count}")
47+
self._assert_expiries(chain.front_month(), "front_month()", [(2013, 12)])
48+
self._assert_expiries(chain.back_month(), "back_month()", [(2014, 3)])
49+
self._assert_expiries(chain.back_months(), "back_months()", [(2014, 3), (2014, 6), (2014, 9), (2014, 12)])
50+
self._assert_expiries(chain.farthest_expiration(), "farthest_expiration()", [(2014, 12)])
51+
self._assert_expiries(chain.expiration_cycle([3, 9]), "expiration_cycle([3, 9])", [(2014, 3), (2014, 9)])
52+
# ES contracts are named after their expiration month, so the contract month filters agree with the expiration ones
53+
self._assert_expiries(chain.contract_months([3, 9]), "contract_months([3, 9])", [(2014, 3), (2014, 9)])
54+
self._assert_expiries(chain.expiring_before(self.END_OF_2013), "expiring_before(2013-12-31)", [(2013, 12)])
55+
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)])
56+
self._assert_expiries(chain.expiration([next(iter(chain.front_month())).expiry]), "expiration([front month expiry])", [(2013, 12)])
57+
if chain.zero_dte().count != 0 or chain.standards_only().count != chain.count or chain.weeklys_only().count != 0:
58+
raise AssertionError("Expected no contract expiring today and only standard contracts")
59+
60+
# The liquidity filters read the universe data: only the front month has more than a million contracts open
61+
self._assert_expiries(chain.open_interest(1000000, self.MAX_LONG), "open_interest(1000000, max)", [(2013, 12)])
62+
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):
63+
raise AssertionError("Open interest or volume filter mismatch")
64+
65+
def on_data(self, slice):
66+
es_chain = slice.futures_chains.get(self._es)
67+
if es_chain:
68+
self._es_chain_seen = True
69+
# The universe selected the contracts expiring within a year, so the chain filters agree with it
70+
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
71+
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
72+
or es_chain.standards_only().count != es_chain.count or es_chain.weeklys_only().count != 0):
73+
raise AssertionError("The ES slice chain disagrees with the universe filter")
74+
front_month = es_chain.front_month()
75+
farthest = es_chain.farthest_expiration()
76+
min_expiry = min(x.expiry for x in es_chain)
77+
max_expiry = max(x.expiry for x in es_chain)
78+
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)
79+
or es_chain.back_months().count != es_chain.count - front_month.count):
80+
raise AssertionError("Front month, back months or farthest expiration mismatch on the ES slice chain")
81+
if (es_chain.open_interest(1, self.MAX_LONG).count != sum(1 for x in es_chain if x.open_interest >= 1)
82+
or es_chain.volume(1, self.MAX_LONG).count != sum(1 for x in es_chain if x.volume >= 1)):
83+
raise AssertionError("Open interest or volume filter mismatch on the ES slice chain")
84+
85+
# Buy the front contract expiring at least 90 days out
86+
if not self._traded:
87+
contract = next(iter(es_chain.expiring_after(self.time + timedelta(days=90)).front_month()), None)
88+
if contract is not None:
89+
self.market_order(contract.symbol, 1)
90+
self._traded = True
91+
92+
gc_chain = slice.futures_chains.get(self._gc)
93+
if gc_chain:
94+
self._gc_chain_seen = True
95+
# Only the December 2013 contract had more than a hundred thousand contracts open
96+
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:
97+
raise AssertionError(f"The GC slice chain disagrees with the universe filter: {[x.expiry for x in gc_chain]}")
98+
99+
def on_end_of_algorithm(self):
100+
if not self._es_chain_seen or not self._gc_chain_seen or not self._traded:
101+
raise AssertionError(f"Expected the ES chain ({self._es_chain_seen}), the GC chain ({self._gc_chain_seen}) and a trade ({self._traded})")
102+
103+
def _assert_expiries(self, chain, filter_name, expected):
104+
actual = sorted((x.expiry.year, x.expiry.month) for x in chain)
105+
if actual != sorted(expected):
106+
raise AssertionError(f"{filter_name}: expected {expected} but got {actual}")

0 commit comments

Comments
 (0)