lower_tf

Library "lower_tf"

█ OVERVIEW

This library is an enhanced (opinionated) version of the library originally developed by PineCoders contained in lower_tf.
It is a Pine Script® programming tool for advanced lower-timeframe selection and intra-bar analysis.

█ CONCEPTS

Lower Timeframe Analysis

Lower timeframe analysis refers to the analysis of price action and market microstructure using data from timeframes shorter than the current chart period. This technique allows traders and analysts to gain deeper insights into market dynamics, volume distribution, and the price movements occurring within each bar on the chart. In Pine Script®, the request.security_lower_tf() function allows this analysis by accessing intrabar data.

The library provides a comprehensive set of functions for accurate mapping of lower timeframes, dynamic precision control, and optimized historical coverage using request.security_lower_tf().

█ IMPROVEMENTS

The original library implemented ten precision levels. This enhanced version extends that to twelve levels, adding two ultra-high-precision options:

Coverage-Based Precision (Original 5 levels):
1. "Covering most chart bars (least precise)"
2. "Covering some chart bars (less precise)"
3. "Covering fewer chart bars (more precise)"
4. "Covering few chart bars (very precise)"
5. "Covering the least chart bars (most precise)"

Intrabar-Count-Based Precision (Expanded from 5 to 7 levels):
6. "~12 intrabars per chart bar"
7. "~24 intrabars per chart bar"
8. "~50 intrabars per chart bar"
9. "~100 intrabars per chart bar"
10. "~250 intrabars per chart bar"
11. "~500 intrabars per chart bar" ← NEW
12. "~1000 intrabars per chart bar" ← NEW

The key enhancements in this version include:

1. Extended Precision Range: Adds two ultra-high-precision levels (~500 and ~1000 intrabars) for advanced microstructure analysis requiring maximum granularity.

2. Market-Agnostic Implementation: Eliminates the distinction between crypto/forex and traditional markets, removing the mktFactor variable in favor of a unified, predictable approach across all asset classes.

3. Explicit Precision Mapping: Completely refactors the timeframe selection logic using native Pine Script® timeframe properties (timeframe.isseconds, timeframe.isminutes, timeframe.isdaily, timeframe.isweekly, timeframe.ismonthly) and explicit multiplier-based lookup tables. The original library used minute-based calculations with market-dependent conditionals that produced inconsistent results. This version provides deterministic, predictable mappings for every chart timeframe, ensuring consistent precision behavior regardless of asset type or market hours.

An example of the differences can be seen side-by-side in the chart below, where the original library is on the left and the enhanced version is on the right:


█ USAGE EXAMPLE

// This Pine Script® code is subject to the terms of the Mozilla Public License 2.0 at https://mozilla.org/MPL/2.0/
// © andre_007

//@version=6
indicator("lower_tf Example")

import andre_007/lower_tf/1 as LTF
import PineCoders/Time/5 as PCtime

//#region ———————————————————— Example code

// ————— Constants

color WHITE   = color.white
color GRAY    = color.gray

string LTF1   = "Covering most chart bars (least precise)"
string LTF2   = "Covering some chart bars (less precise)"
string LTF3   = "Covering less chart bars (more precise)"
string LTF4   = "Covering few chart bars (very precise)"
string LTF5   = "Covering the least chart bars (most precise)"
string LTF6   = "~12 intrabars per chart bar"
string LTF7   = "~24 intrabars per chart bar"
string LTF8   = "~50 intrabars per chart bar"
string LTF9   = "~100 intrabars per chart bar"
string LTF10  = "~250 intrabars per chart bar"
string LTF11  = "~500 intrabars per chart bar"
string LTF12  = "~1000 intrabars per chart bar"

string TT_LTF = "This selection determines the approximate number of intrabars analyzed per chart bar. Higher numbers of
     intrabars produce more granular data at the cost of less historical bar coverage, because the maximum number of
     available intrabars is 200K.
     \n\nThe first five options set the lower timeframe based on a specified relative level of chart bar coverage.
     The last five options set the lower timeframe based on an approximate number of intrabars per chart bar."

string TAB_TXT = "Uses intrabars at the {0} timeframe.\nAvg intrabars per chart bar:
     {1,number,#.#}\nChart bars covered: {2} of {3} ({4,number,#.##}%)"
string ERR_TXT = "No intrabar information exists at the {1}{0}{1} timeframe."

// ————— Inputs

string  ltfModeInput            = input.string(LTF3,     "Intrabar precision",         options = [LTF1, LTF2, LTF3, LTF4, LTF5, LTF6, LTF7, LTF8, LTF9, LTF10, LTF11, LTF12], tooltip = TT_LTF)
bool    showInfoBoxInput        = input.bool(true,       "Show information box ")
string  infoBoxSizeInput        = input.string("normal", "Size ",                      inline = "01", options = ["tiny", "small", "normal", "large", "huge", "auto"])
string  infoBoxYPosInput        = input.string("bottom", "↕",                          inline = "01", options = ["top", "middle", "bottom"])
string  infoBoxXPosInput        = input.string("right",  "↔",                          inline = "01", options = ["left", "center", "right"])
color   infoBoxColorInput       = input.color(GRAY,      "",                           inline = "01")
color   infoBoxTxtColorInput    = input.color(WHITE,     "T",                          inline = "01")

// ————— Calculations

// @variable A "string" representing the lower timeframe for the data request.
// NOTE:
//      This line is a good example where using `var` in the declaration can improve a script's performance.
//      By using `var` here, the script calls `ltf()` only once, on the dataset's first bar, instead of redundantly 
//      evaluating unchanging strings on every bar. We only need one evaluation of this function because the selected 
//      timeframe does not change across bars in this script. 
var string ltfString = LTF.ltf(ltfModeInput, LTF1, LTF2, LTF3, LTF4, LTF5, LTF6, LTF7, LTF8, LTF9, LTF10, LTF11, LTF12)

// @variable An array containing all intrabar `close` prices from the `ltfString` timeframe for the current chart bar. 
array<float> intrabarCloses = request.security_lower_tf(syminfo.tickerid, ltfString, close)

// Calculate the intrabar stats. 
[intrabars, chartBarsCovered, avgIntrabars] = LTF.ltfStats(intrabarCloses)
int chartBars = bar_index + 1

// ————— Visuals 

// Plot the `avgIntrabars` and `intrabars` series in all display locations.
plot(avgIntrabars, "Average intrabars", color.silver, 6)
plot(intrabars,    "Intrabars",         color.blue,   2)

// Plot the `chartBarsCovered` and `chartBars` values in the Data Window and the script's status line. 
plot(chartBarsCovered,  "Chart bars covered", display = display.data_window + display.status_line)
plot(chartBars,         "Chart bars total",   display = display.data_window + display.status_line)

// Information box logic.
if showInfoBoxInput
    // @variable A single-cell table that displays intrabar information. 
    var table infoBox = table.new(infoBoxYPosInput + "_" + infoBoxXPosInput, 1, 1)
    // @variable The span of the `ltfString` timeframe formatted as a number of automatically selected time units. 
    string formattedLtf = PCtime.formattedNoOfPeriods(timeframe.in_seconds(ltfString) * 1000)
    // @variable A "string" containing the formatted text to display in the `infoBox`.
    string txt = str.format(
         TAB_TXT, formattedLtf, avgIntrabars,  chartBarsCovered, chartBars, chartBarsCovered / chartBars * 100, "'"
     )
    // Initialize the `infoBox` cell on the first bar. 
    if barstate.isfirst
        table.cell(
             infoBox, 0, 0, txt, text_color = infoBoxTxtColorInput, text_size = infoBoxSizeInput, 
             bgcolor = infoBoxColorInput
         )
    // Update the cell's text on the latest bar. 
    else if barstate.islast
        table.cell_set_text(infoBox, 0, 0, txt)        

// Raise a runtime error if no intrabar data is available.
if ta.cum(intrabars) == 0 and barstate.islast
    runtime.error(str.format(ERR_TXT, ltfString, "'"))
//#endregion

█ EXPORTED FUNCTIONS

ltf(userSelection, choice1, choice2, ...)
Returns the optimal lower timeframe string based on user selection and current chart timeframe. Dynamically calculates precision to balance granularity with historical coverage within the 200K intrabar limit.

ltfStats(intrabarValues)
Analyzes an intrabar array returned by request.security_lower_tf() and returns statistics: number of intrabars in current bar, total chart bars covered, and average intrabars per bar.

█ CREDITS AND LICENSING

Original Concept: PineCoders Team
Original Lower TF Library:

License: Mozilla Public License 2.0