lower_tf

█  OVERVIEW


This library is a Pine programmer’s tool containing functions to help those who use the request.security_lower_tf() function. Its `ltf()` function helps translate user inputs into a lower timeframe string usable with request.security_lower_tf() . Another function, `ltfStats()`, accumulates statistics on processed chart bars and intrabars.



█  CONCEPTS


Chart bars
Chart bars, as referred to in our publications, are bars that occur at the current chart timeframe, as opposed to those that occur at a timeframe that is higher or lower than that of the chart view.

Intrabars
Intrabars are chart bars at a lower timeframe than the chart's. Each 1H chart bar of a 24x7 market will, for example, usually contain 60 intrabars at the ​LTF of 1min, provided there was market activity during each minute of the hour. Mining information from intrabars can be useful in that it offers traders visibility on the activity inside a chart bar.

Lower timeframes (LTFs)
A lower timeframe is a timeframe that is smaller than the chart's timeframe. This framework exemplifies how authors can determine which ​LTF to use by examining the chart's timeframe. The ​LTF determines how many intrabars are examined for each chart bar; the lower the timeframe, the more intrabars are analyzed.

Intrabar precision
The precision of calculations increases with the number of intrabars analyzed for each chart bar. As there is a 100K limit to the number of intrabars that can be analyzed by a script, a trade-off occurs between the number of intrabars analyzed per chart bar and the chart bars for which calculations are possible.



█  `ltf()`


This function returns a timeframe string usable with request.security_lower_tf(). It calculates the returned timeframe by taking into account a user selection between eight different calculation modes and the chart's timeframe. You send it the user's selection, along with the text corresponding to the eight choices from which the user has chosen, and the function returns a corresponding ​LTF string.

Because the function processes strings and doesn't require recalculation on each bar, using var to declare the variable to which its result is assigned will execute the function only once on bar zero and speed up your script:

var string ltfString = ​ltf(ltfModeInput, LTF1, LTF2, LTF3, LTF4, LTF5, LTF6, LTF7, LTF8)

The eight choices users can select from are of two types: the first four allow a selection from the desired amount of chart bars to be covered, the last four are choices of a fixed number of intrabars to be analyzed per chart bar. Our example code shows how to structure your input call and then make the call to `ltf()`. By changing the text associated with the `LTF1` to `LTF8` constants, you can tailor it to your preferences while preserving the functionality of `ltf()` because you will be sending those string constants as the function's arguments so it can determine the user's selection. The association between each `LTFx` constant and its calculation mode is fixed, so the order of the arguments is important when you call `ltf()`.

These are the first four modes and the `LTFx` constants corresponding to each:

Covering most chart bars (least precise) — LTF1
Covers all chart bars. This is accomplished by dividing the current timeframe in seconds by 4 and converting that number back to a string in timeframe.period format using secondsToTfString(). Due to the fact that, on premium subscriptions, the typical historical bar count is between 20-25k bars, dividing the timeframe by 4 ensures the highest level of intrabar precision possible while achieving complete coverage for the entire dataset with the maximum allowed 100K intrabars.

Covering some chart bars (less precise) — LTF2
Covering less chart bars (more precise) — LTF3
These levels offer a stepped ​LTF in relation to the chart timeframe with slightly more, or slightly less precision. The stepped lower timeframe tiers are calculated from the chart timeframe as follows:

Chart Timeframe            Lower Timeframe

                    Less Precise     More Precise
                                   
    < 1hr               1min            1min
    < 1D                15min           1min
    < 1W                ​2hr​             30min
    > 1W                1D              60min

Covering the least chart bars (most precise) — LTF4
Analyzes the maximum quantity of intrabars possible by using the 1min ​LTF, which also allows the least amount of chart bars to be covered.

The last four modes allow the user to specify a fixed number of intrabars to analyze per chart bar. Users can choose from 12, 24, 50 or 100 intrabars, respectively corresponding to the `LTF5`, `LTF6`, `LTF7` and `LTF8` constants. The value is a target; the function will do its best to come up with a ​LTF producing the required number of intrabars. Because of considerations such as the length of a ticker's session, rounding of the ​LTF to the closest allowable timeframe, or the lowest allowable timeframe of 1min intrabars, it is often impossible for the function to find a ​​LTF producing the exact number of intrabars. Requesting 100 intrabars on a 60min chart, for example, can only produce 60 1min intrabars. Higher chart timeframes, tickers with high liquidity or 24x7 markets will produce optimal results.



█  `ltfStats()`


`ltfStats()` returns statistics that will be useful to programmers using intrabar inspection. By analyzing the arrays returned by request.security_lower_tf() in can determine:
 • intrabarsInChartBar: The number of intrabars analyzed for each chart bar.
 • chartBarsCovered: The number of chart bars where intrabar information is available.
 • avgIntrabars: The average number of intrabars analyzed per chart bar. Events like holidays, market activity, or reduced hours sessions can cause the number of intrabars to vary, bar to bar.

The function must be called on each bar to produce reliable results.



█  DEMONSTRATION CODE


Our example code shows how to provide users with an input from which they can select a ​LTF calculation mode. If you use this library's functions, feel free to reuse our input setup code, including the tooltip providing users with explanations on how it works for them.

We make a simple call to request.security_lower_tf() to fetch the close values of intrabars, but we do not use those values. We simply send the returned array to `ltfStats()` and then plot in the indicator's pane the number of intrabars examined on each bar and its average. We also display an information box showing the user's selection of the ​LTF calculation mode, the resulting ​LTF calculated by `ltf()` and some statistics.



█  NOTES


 • As in several of our recent publications, this script uses secondsToTfString() to produce a timeframe string in timeframe.period format from a timeframe expressed in seconds.
 • The script utilizes display.data_window and display.status_line to restrict the display of certain plots.
  These new built-ins allow coders to fine-tune where a script’s plot values are displayed.
 • We implement a new recommended best practice for tables which works faster and reduces memory consumption.
  Using this new method, tables are declared only once with var, as usual. Then, on bar zero only, we use table.cell() calls to populate the table.
  Finally, table.set_*() functions are used to update attributes of table cells on the last bar of the dataset.
  This greatly reduces the resources required to render tables. We encourage all Pine Script™ programmers to do the same.


Look first. Then leap.



█  FUNCTIONS


The library contains the following functions:


ltf(userSelection, choice1, choice2, choice3, choice4, choice5, choice6, choice7, choice8)
  Selects a ​LTF from the chart's TF, depending on the `userSelection` input string.
  Parameters:
    userSelection: (simple string) User-selected input string which must be one of the `choicex` arguments.
    choice1: (simple string) Input selection corresponding to "Least precise, covering most chart bars".
    choice2: (simple string) Input selection corresponding to "Less precise, covering some chart bars".
    choice3: (simple string) Input selection corresponding to "More precise, covering less chart bars".
    choice4: (simple string) Input selection corresponding to "Most precise, 1min intrabars".
    choice5: (simple string) Input selection corresponding to "~12 intrabars per chart bar".
    choice6: (simple string) Input selection corresponding to "~24 intrabars per chart bar".
    choice7: (simple string) Input selection corresponding to "~50 intrabars per chart bar".
    choice8: (simple string) Input selection corresponding to "~100 intrabars per chart bar".
  Returns: (simple string) A timeframe string to be used with `request.security_lower_tf()`.

ltfStats()
  Returns statistics about analyzed intrabars and chart bars covered by calls to `request.security_lower_tf()`.
  Parameters:
    intrabarValues: (float[]) The ID of a float array containing values fetched by a call to `request.security_lower_tf()`.
  Returns: A 3-element tuple: [(series int) intrabarsInChartBar, (series int) chartBarsCovered, (series float) avgIntrabars].

版本注释:

v2

Minor changes to `ltf()` calculation to ensure timeframes returned are at least 1min bars.

版本注释:

v3

Updated to include 2 more LTF options including a 2min LTF, and another for approximately 250 intrabars.

Updated Function:

ltf(userSelection, choice1, choice2, choice3, choice4, choice5, choice6, choice7, choice8, choice9, choice10)
  Selects a LTF from the chart's TF, depending on the `userSelection` input string.
  Parameters:
    userSelection: (simple string) User-selected input string which must be one of the `choicex` arguments.
    choice1: (simple string) Input selection corresponding to "Covering most chart bars (least precise)".
    choice2: (simple string) Input selection corresponding to "Covering some chart bars (less precise)".
    choice3: (simple string) Input selection corresponding to "Covering less chart bars (more precise)".
    choice4: (simple string) Input selection corresponding to "Very precise (2min intrabars)".
    choice5: (simple string) Input selection corresponding to "Most precise (1min intrabars)".
    choice6: (simple string) Input selection corresponding to "~12 intrabars per chart bar".
    choice7: (simple string) Input selection corresponding to "~24 intrabars per chart bar".
    choice8: (simple string) Input selection corresponding to "~50 intrabars per chart bar".
    choice9: (simple string) Input selection corresponding to "~100 intrabars per chart bar".
    choice10: (simple string) Input selection corresponding to "~250 intrabars per chart bar".
  Returns: (simple string) A timeframe string to be used with `request.security_lower_tf()`.

版本注释:

v4

We've updated the `ltf()` function to support seconds-based timeframes, following the recent update to request.security_lower_tf().

We've adjusted the stepped LTF calculation for "Less/More Precise" intrabar precision options according to the following table:

Chart Timeframe            Lower Timeframe

                    (24hr markets/non-24hr markets)

                     Less Precise     More Precise

    <= 1min              5S               1S
    <= 2min              10S              5S
    <= 3min              15S              10S     
    <= 5min              30S              15S
    <= 15min             1min             30S
    <= 1hr               3min             1min
    <  ​2hr               5min             2min
    <  4hr               15min            3min
    <  6hr               30min            5min
    <  12hr           (1hr/30min)     (10min/5min)
    <  1D             (​​2hr/30min)     (15min/5min)
    <  1W             (​12hr/​2hr)​      (​2hr/30min)
    >  1W                1D              ​ 12hr

The "Very/Most Precise" options now use a stepped LTF to request the highest precision possible while covering enough historical chart bars for usefulness.
The script calculates the LTF for these options as follows:

Chart Timeframe            Lower Timeframe

                    (24hr markets/non-24hr markets)

                     Very Precise     Most Precise

    <= 1hr               5S               1S
    <= ​2hr               15S              5S
    <= 4hr               30S              15S
    <= 12hr          (1min/30S)        (30S/15S)
    <  1D            (​​2min/1min)       (1min/30S)
    <  1W            (​15min/​5min)​      (​10min/3min)
    >  1W            (1hr/30min)       (30min/15min)