Lean  $LEAN_TAG$
UniverseDefinitions.cs
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 
17 using System;
18 using System.Linq;
19 using Python.Runtime;
20 using System.Collections.Generic;
23 
24 namespace QuantConnect.Algorithm
25 {
26  /// <summary>
27  /// Provides helpers for defining universes in algorithms
28  /// </summary>
29  public class UniverseDefinitions
30  {
31  private readonly QCAlgorithm _algorithm;
32 
33  /// <summary>
34  /// Gets a helper that provides methods for creating universes based on daily dollar volumes
35  /// </summary>
37 
38  /// <summary>
39  /// Specifies that universe selection should not make changes on this iteration
40  /// </summary>
42 
43  /// <summary>
44  /// Initializes a new instance of the <see cref="UniverseDefinitions"/> class
45  /// </summary>
46  /// <param name="algorithm">The algorithm instance, used for obtaining the default <see cref="UniverseSettings"/></param>
47  public UniverseDefinitions(QCAlgorithm algorithm)
48  {
49  _algorithm = algorithm;
51  }
52 
53  /// <summary>
54  /// Creates a universe for the constituents of the provided <paramref name="etfTicker"/>
55  /// </summary>
56  /// <param name="etfTicker">Ticker of the ETF to get constituents for</param>
57  /// <param name="market">Market of the ETF</param>
58  /// <param name="universeSettings">Universe settings</param>
59  /// <param name="universeFilterFunc">Function to filter universe results</param>
60  /// <returns>New ETF constituents Universe</returns>
61  public Universe ETF(
62  string etfTicker,
63  string market,
64  UniverseSettings universeSettings,
65  Func<IEnumerable<ETFConstituentUniverse>, IEnumerable<Symbol>> universeFilterFunc)
66  {
67  market ??= _algorithm.BrokerageModel.DefaultMarkets.TryGetValue(SecurityType.Equity, out var defaultMarket)
68  ? defaultMarket
69  : throw new Exception("No default market set for security type: Equity");
70 
71  var etfSymbol = new Symbol(
73  etfTicker,
74  market,
75  true,
76  mappingResolveDate: _algorithm.Time.Date),
77  etfTicker);
78 
79  return ETF(etfSymbol, universeSettings, universeFilterFunc);
80  }
81 
82  /// <summary>
83  /// Creates a universe for the constituents of the provided <paramref name="etfTicker"/>
84  /// </summary>
85  /// <param name="etfTicker">Ticker of the ETF to get constituents for</param>
86  /// <param name="market">Market of the ETF</param>
87  /// <param name="universeFilterFunc">Function to filter universe results</param>
88  /// <returns>New ETF constituents Universe</returns>
89  public Universe ETF(string etfTicker, string market, Func<IEnumerable<ETFConstituentUniverse>, IEnumerable<Symbol>> universeFilterFunc)
90  {
91  return ETF(etfTicker, market, null, universeFilterFunc);
92  }
93 
94  /// <summary>
95  /// Creates a universe for the constituents of the provided <paramref name="etfTicker"/>
96  /// </summary>
97  /// <param name="etfTicker">Ticker of the ETF to get constituents for</param>
98  /// <param name="universeFilterFunc">Function to filter universe results</param>
99  /// <returns>New ETF constituents Universe</returns>
100  public Universe ETF(string etfTicker, Func<IEnumerable<ETFConstituentUniverse>, IEnumerable<Symbol>> universeFilterFunc)
101  {
102  return ETF(etfTicker, null, null, universeFilterFunc);
103  }
104 
105  /// <summary>
106  /// Creates a universe for the constituents of the provided <paramref name="etfTicker"/>
107  /// </summary>
108  /// <param name="etfTicker">Ticker of the ETF to get constituents for</param>
109  /// <param name="universeSettings">Universe settings</param>
110  /// <param name="universeFilterFunc">Function to filter universe results</param>
111  /// <returns>New ETF constituents Universe</returns>
112  public Universe ETF(
113  string etfTicker,
114  UniverseSettings universeSettings,
115  Func<IEnumerable<ETFConstituentUniverse>, IEnumerable<Symbol>> universeFilterFunc)
116  {
117  return ETF(etfTicker, null, universeSettings, universeFilterFunc);
118  }
119 
120  /// <summary>
121  /// Creates a universe for the constituents of the provided <paramref name="etfTicker"/>
122  /// </summary>
123  /// <param name="etfTicker">Ticker of the ETF to get constituents for</param>
124  /// <param name="market">Market of the ETF</param>
125  /// <param name="universeSettings">Universe settings</param>
126  /// <param name="universeFilterFunc">Function to filter universe results</param>
127  /// <returns>New ETF constituents Universe</returns>
128  public Universe ETF(
129  string etfTicker,
130  string market = null,
131  UniverseSettings universeSettings = null,
132  PyObject universeFilterFunc = null)
133  {
134  return ETF(etfTicker, market, universeSettings, universeFilterFunc?.ConvertPythonUniverseFilterFunction<ETFConstituentUniverse>());
135  }
136 
137  /// <summary>
138  /// Creates a universe for the constituents of the provided <paramref name="etfTicker"/>
139  /// </summary>
140  /// <param name="etfTicker">Ticker of the ETF to get constituents for</param>
141  /// <param name="universeSettings">Universe settings</param>
142  /// <param name="universeFilterFunc">Function to filter universe results</param>
143  /// <returns>New ETF constituents Universe</returns>
144  public Universe ETF(
145  string etfTicker,
146  UniverseSettings universeSettings,
147  PyObject universeFilterFunc)
148  {
149  return ETF(etfTicker, null, universeSettings, universeFilterFunc);
150  }
151 
152  /// <summary>
153  /// Creates a universe for the constituents of the provided ETF <paramref name="symbol"/>
154  /// </summary>
155  /// <param name="symbol">ETF Symbol to get constituents for</param>
156  /// <param name="universeSettings">Universe settings</param>
157  /// <param name="universeFilterFunc">Function to filter universe results</param>
158  /// <returns>New ETF constituents Universe</returns>
159  public Universe ETF(Symbol symbol, UniverseSettings universeSettings,
160  Func<IEnumerable<ETFConstituentUniverse>, IEnumerable<Symbol>> universeFilterFunc)
161  {
162  return new ETFConstituentsUniverseFactory(symbol, universeSettings ?? _algorithm.UniverseSettings, universeFilterFunc);
163  }
164 
165  /// <summary>
166  /// Creates a universe for the constituents of the provided ETF <paramref name="symbol"/>
167  /// </summary>
168  /// <param name="symbol">ETF Symbol to get constituents for</param>
169  /// <param name="universeFilterFunc">Function to filter universe results</param>
170  /// <returns>New ETF constituents Universe</returns>
171  public Universe ETF(Symbol symbol, Func<IEnumerable<ETFConstituentUniverse>, IEnumerable<Symbol>> universeFilterFunc)
172  {
173  return ETF(symbol, null, universeFilterFunc);
174  }
175 
176  /// <summary>
177  /// Creates a universe for the constituents of the provided ETF <paramref name="symbol"/>
178  /// </summary>
179  /// <param name="symbol">ETF Symbol to get constituents for</param>
180  /// <param name="universeSettings">Universe settings</param>
181  /// <param name="universeFilterFunc">Function to filter universe results</param>
182  /// <returns>New ETF constituents Universe</returns>
183  public Universe ETF(Symbol symbol, UniverseSettings universeSettings = null, PyObject universeFilterFunc = null)
184  {
185  return ETF(symbol, universeSettings ?? _algorithm.UniverseSettings,
186  universeFilterFunc?.ConvertPythonUniverseFilterFunction<ETFConstituentUniverse>());
187  }
188 
189  /// <summary>
190  /// Creates a universe for the constituents of the provided <paramref name="indexTicker"/>
191  /// </summary>
192  /// <param name="indexTicker">Ticker of the index to get constituents for</param>
193  /// <param name="market">Market of the index</param>
194  /// <param name="universeSettings">Universe settings</param>
195  /// <param name="universeFilterFunc">Function to filter universe results</param>
196  /// <returns>New index constituents Universe</returns>
197  public Universe Index(string indexTicker, string market, UniverseSettings universeSettings,
198  Func<IEnumerable<ETFConstituentUniverse>, IEnumerable<Symbol>> universeFilterFunc)
199  {
200  market ??= _algorithm.BrokerageModel.DefaultMarkets.TryGetValue(SecurityType.Index, out var defaultMarket)
201  ? defaultMarket
202  : throw new Exception("No default market set for security type: Index");
203 
204  return Index(
205  Symbol.Create(indexTicker, SecurityType.Index, market),
206  universeSettings,
207  universeFilterFunc);
208  }
209 
210  /// <summary>
211  /// Creates a universe for the constituents of the provided <paramref name="indexTicker"/>
212  /// </summary>
213  /// <param name="indexTicker">Ticker of the index to get constituents for</param>
214  /// <param name="market">Market of the index</param>
215  /// <param name="universeFilterFunc">Function to filter universe results</param>
216  /// <returns>New index constituents Universe</returns>
217  public Universe Index(string indexTicker, string market, Func<IEnumerable<ETFConstituentUniverse>, IEnumerable<Symbol>> universeFilterFunc)
218  {
219  return Index(indexTicker, market, null, universeFilterFunc);
220  }
221 
222  /// <summary>
223  /// Creates a universe for the constituents of the provided <paramref name="indexTicker"/>
224  /// </summary>
225  /// <param name="indexTicker">Ticker of the index to get constituents for</param>
226  /// <param name="universeFilterFunc">Function to filter universe results</param>
227  /// <returns>New index constituents Universe</returns>
228  public Universe Index(string indexTicker, Func<IEnumerable<ETFConstituentUniverse>, IEnumerable<Symbol>> universeFilterFunc)
229  {
230  return Index(indexTicker, null, null, universeFilterFunc);
231  }
232 
233  /// <summary>
234  /// Creates a universe for the constituents of the provided <paramref name="indexTicker"/>
235  /// </summary>
236  /// <param name="indexTicker">Ticker of the index to get constituents for</param>
237  /// <param name="universeSettings">Universe settings</param>
238  /// <param name="universeFilterFunc">Function to filter universe results</param>
239  /// <returns>New index constituents Universe</returns>
240  public Universe Index(string indexTicker, UniverseSettings universeSettings,
241  Func<IEnumerable<ETFConstituentUniverse>, IEnumerable<Symbol>> universeFilterFunc)
242  {
243  return Index(indexTicker, null, universeSettings, universeFilterFunc);
244  }
245 
246  /// <summary>
247  /// Creates a universe for the constituents of the provided <paramref name="indexTicker"/>
248  /// </summary>
249  /// <param name="indexTicker">Ticker of the index to get constituents for</param>
250  /// <param name="market">Market of the index</param>
251  /// <param name="universeSettings">Universe settings</param>
252  /// <param name="universeFilterFunc">Function to filter universe results</param>
253  /// <returns>New index constituents Universe</returns>
254  public Universe Index(
255  string indexTicker,
256  string market = null,
257  UniverseSettings universeSettings = null,
258  PyObject universeFilterFunc = null)
259  {
260  return Index(indexTicker, market, universeSettings, universeFilterFunc?.ConvertPythonUniverseFilterFunction<ETFConstituentUniverse>());
261  }
262 
263  /// <summary>
264  /// Creates a universe for the constituents of the provided <paramref name="indexTicker"/>
265  /// </summary>
266  /// <param name="indexTicker">Ticker of the index to get constituents for</param>
267  /// <param name="universeSettings">Universe settings</param>
268  /// <param name="universeFilterFunc">Function to filter universe results</param>
269  /// <returns>New index constituents Universe</returns>
270  public Universe Index(
271  string indexTicker,
272  UniverseSettings universeSettings,
273  PyObject universeFilterFunc)
274  {
275  return Index(indexTicker, null, universeSettings, universeFilterFunc);
276  }
277 
278  /// <summary>
279  /// Creates a universe for the constituents of the provided <paramref name="indexSymbol"/>
280  /// </summary>
281  /// <param name="indexSymbol">Index Symbol to get constituents for</param>
282  /// <param name="universeSettings">Universe settings</param>
283  /// <param name="universeFilterFunc">Function to filter universe results</param>
284  /// <returns>New index constituents Universe</returns>
285  public Universe Index(Symbol indexSymbol, UniverseSettings universeSettings,
286  Func<IEnumerable<ETFConstituentUniverse>, IEnumerable<Symbol>> universeFilterFunc)
287  {
288  return new ETFConstituentsUniverseFactory(indexSymbol, universeSettings, universeFilterFunc);
289  }
290 
291  /// <summary>
292  /// Creates a universe for the constituents of the provided <paramref name="indexSymbol"/>
293  /// </summary>
294  /// <param name="indexSymbol">Index Symbol to get constituents for</param>
295  /// <param name="universeFilterFunc">Function to filter universe results</param>
296  /// <returns>New index constituents Universe</returns>
297  public Universe Index(Symbol indexSymbol, Func<IEnumerable<ETFConstituentUniverse>, IEnumerable<Symbol>> universeFilterFunc)
298  {
299  return Index(indexSymbol, null, universeFilterFunc);
300  }
301 
302  /// <summary>
303  /// Creates a universe for the constituents of the provided <paramref name="indexSymbol"/>
304  /// </summary>
305  /// <param name="indexSymbol">Index Symbol to get constituents for</param>
306  /// <param name="universeSettings">Universe settings</param>
307  /// <param name="universeFilterFunc">Function to filter universe results</param>
308  /// <returns>New index constituents Universe</returns>
309  public Universe Index(
310  Symbol indexSymbol,
311  UniverseSettings universeSettings = null,
312  PyObject universeFilterFunc = null)
313  {
314  return Index(indexSymbol, universeSettings ?? _algorithm.UniverseSettings,
315  universeFilterFunc?.ConvertPythonUniverseFilterFunction<ETFConstituentUniverse>());
316  }
317 
318  /// <summary>
319  /// Creates a new fine universe that contains the constituents of QC500 index based onthe company fundamentals
320  /// The algorithm creates a default tradable and liquid universe containing 500 US equities
321  /// which are chosen at the first trading day of each month.
322  /// </summary>
323  /// <returns>A new coarse universe for the top count of stocks by dollar volume</returns>
324  public Universe QC500
325  {
326  get
327  {
328  return ETF(Symbol.Create("SPY", SecurityType.Equity, Market.USA));
329  }
330  }
331 
332  /// <summary>
333  /// Creates a new coarse universe that contains the top count of stocks
334  /// by daily dollar volume
335  /// </summary>
336  /// <param name="count">The number of stock to select</param>
337  /// <param name="universeSettings">The settings for stocks added by this universe.
338  /// Defaults to <see cref="QCAlgorithm.UniverseSettings"/></param>
339  /// <returns>A new coarse universe for the top count of stocks by dollar volume</returns>
340  public Universe Top(int count, UniverseSettings universeSettings = null)
341  {
342  universeSettings ??= _algorithm.UniverseSettings;
343 
344  var symbol = Symbol.Create("us-equity-dollar-volume-top-" + count, SecurityType.Equity, Market.USA);
345  return FundamentalUniverse.USA(selectionData => (
346  from c in selectionData
347  orderby c.DollarVolume descending
348  select c.Symbol).Take(count),
349  universeSettings);
350  }
351  }
352 }