Security List terms are often referred to as benchmark lists in RuleTrader to distinguish them from a Trading Strategy‘s trading lists, which are selected by its List Selectors. They are used to dynamically gather together lists of shares and other financial instruments that your Trading Spec may use to, for example, create a target buy or sell list, or to calculate benchmarks, statistics or rankings for e.g. all securities in a market sector. For example, in the Example Trading Spec they are used in the Value & Growth strategy terms ‘Growth Opportunities‘ and ‘Value & Growth Buy List‘ to first gather potential investment opportunities and then to reduce that to a list of the best opportunities to buy.

The options for a benchmark security list expression are as follows:

• Named security list term: returns the securities in a previously defined Security List term, whose selection expression is evaluated with respect to the current evaluated security (similar to Evaluated security)
• Another security’s named security list: returns the securities in a previously defined Security List term, whose selection expression is evaluated with respect to a specified security (similar to Other security’s named security term)
• Named strategy’s list: returns the securities in a specified Trading Strategy‘s trading list (i.e. the list that results from combining the lists generated by each of the strategy’s List Selectors and then de-duplicating that list, so each share appears only once). This list includes permanent and reinstated securities.
• Named list selector’s list: returns the securities generated by a specified List Selector in a trading strategy. Note that this list will exclude permanent and reinstated securities
• Ranked list of securities: extracts a rank (i.e. a set) of securities from a security list that has been sorted on some value expression. The size of the rank is specified as a number of securities, or a percentage of the securities in the list, or a decile (1/10), quintile (1/5) or quartile (1/4) of the list. The location of the rank in the list may be specified as being at the top, middle or bottom, or at some index in the sorted list. Unlike the use of this construct in List Selectors, the size of the rank is NOT automatically adjusted for any List Sampling.
• List of securities whose total value: picks the top rank of securities from a security list sorted on some value expression. Securities are picked from the top of the list until the total of a value associated with each of those securities is at or under, or is just over, some threshold value. You could use this, for example, to pick those securities with the most profitable open positions that account for 80% of all current, unrealised profits.
• List of securities with/without trades: creates a list of all those securities that have / have not got an open position, or have / have not been traded at some point in the past
• List with the same attribute as a reference share: selects a list of securities that have an attribute whose value matches the value of that attribute in a specified security. For example, this could be used to create a sector list by picking, from some list of shares, all those shares whose market sector is the same as e.g. the evaluated security
• List of securities that meet a condition: selects securities from some source list, that meet some criteria. The condition may test a value, characteristic or attribute of the securities in the source list. Multiple such conditions may be combined into a conditional expression that is applied against every security in the source list. The securities that pass are then returned in the security list
• List of securities from a choice of lists: selects a list of securities from two or more such lists based on the results of a series of selection conditions
• Trading universe list: selects the Trading Universe list, which was selected from a ShareScope list according to the filter criteria defined in the Trading Universe tab in the Shared level of the Trading Definition Dialog
• Trading list: returns your Trading Spec‘s trading list, which is the de-duplicated combination of all the strategy lists defined in the Spec. This list includes permanent and reinstated securities
• List of securities added today: generates a list of every security that was newly selected today (i.e. which was not previously in the overall trading list) by one of your Spec’s trading strategy List Selectors. This is useful if you want to apply special treatment for shares that your Spec has not encountered before. This list includes permanent and reinstated securities
• ShareScope list: returns the list of securities in one of ShareScope’s built-in security lists
• Portfolio list: returns the list of securities in one of ShareScope’s portfolio lists
• Empty list: creates an empty security list. This provides a useful starting point if you want to manually construct a list of one or more shares using the list operators discussed next

A list selection expression can be created by combining lists, generated using the options above, using list operators. Like all RuleTrader operators, these are evaluated from left to right in an expression (i.e. there is no precedence between operators):

• PLUS a list of securities: adds the securities in one security list to the securities in another list to create a combined list of securities. Duplicate securities are removed, so the final list contains only one instance of each security
• EXCLUDING a list of securities: removes (i.e. subtracts) securities from one security list if those securities are present in a second list and returns the reduced list
• PLUS a security: adds a single named security to a security list and returns the resulting list
• EXCLUDING a security: removes a single named security from  a security list, if it is present in that list, and returns the resulting list
• end list expression: ends the addition of sub-terms to the list expression

Please see Expressions And Sub-Expressions for information on handling the sub-expressions within larger list expressions.

List selection constructs, like ‘Ranked list of securities‘ and ‘List of securities whose total value‘, sort their lists to arrange them in order based on the value of some expression. For example, in the Example Trading System’s Value & Growth strategy’s Value & Growth Shares List Selector, the list is ranked based on each share’s trend growth, as shown below:

This definition refers to each listed security’s trend growth. So the definition gets each share in the High Liquidity list, calculates its trend growth and then uses that value to order each share in descending order in the final list. It then picks the top 80 shares (i.e. those shares with the highest trend growth). All is as you’d expect.

Now consider the ranking expression used in the same strategy’s Value & Growth Buy List security list term. This is defined as follows (detail omitted for clarity):

As you can see there is no mention of a listed security. Instead, the list is ordered by Rank Score, which in turn is dependent on the Turnover Growth Score term (amongst others), which is dependent on the evaluated security.

Elsewhere in this Help system (e.g. see Security Terms & Expressions) we’ve said that the ‘evaluated security’ is the security from your Trading Spec‘s trading list that is currently being evaluated against the Spec’s trading rules and that each share in that trading list becomes the ‘evaluated security’, for that purpose. So when a Named Term or Trading Rule definition refers to the ‘evaluated security’s data, it is referring to that share’s data, in that instance.

But the  Value & Growth Buy List definition suggests that we want to sort the securities in the Growth Opportunities list (i.e. the listed securities), using the Rank Score term’s value for each of those listed securities. But the Rank Score term is ultimately dependent on the evaluated security, so how is this going to work?

The simple answer is, don’t worry about it. RuleTrader is designed to ‘just work’ and that’s what the  definition will do; it will sort each share in the list according to each of those share’s Rank Score values.

The full answer is that it all depends on context. In this case the shares in the Value And Growth Buy List are being ordered by the value of the Rank Score term, which is evaluated in the context of that ordering expression i.e. with respect to each of those shares. So any reference to the ‘evaluated security’s data, in this specific context, is a reference to the data of each share in the list, as its sort order is determined. This applies to the Rank Score term definition and to any subsidiary terms it depends on, such as the Turnover Growth Score term.

Note that if you were to refer (somewhere else) to the value of any of these terms outside of a list ordering expression, then references to the ‘evaluated security’ in their definitions is, once again, a reference to the share in the Spec’s trading list that is currently being evaluated.

The best way to think about it is to replace the phrase ‘evaluated security‘, with ‘security being evaluated in the current context‘. This is another example of RuleTrader ‘just working’ in the way you’d expect. It’s a very powerful feature that means you can create complex security list definitions using Named Terms.