█ OVERVIEW
This library is a Pine programmer’s tool containing functions that return values calculated from the range of visible bars on the chart.
This is now possible in Pine Script™ thanks to the recently-released chart.left_visible_bar_time and chart.right_visible_bar_time built-ins, which return the opening time of the leftmost and rightmost bars on the chart. These values update as traders scroll or zoom their charts, which gives way to a class of indicators that can dynamically recalculate and draw visuals on visible bars only, as users scroll or zoom their charts. We hope this library's functions help you make the most of the world of possibilities these new built-ins provide for Pine scripts.
For an example of a script using this library, have a look at the Chart VWAP indicator.
█ CONCEPTS
Chart properties
The new chart.left_visible_bar_time and chart.right_visible_bar_time variables return the opening time of the leftmost and rightmost bars on the chart. They are only two of many new built-ins in the `chart.*` namespace. See this blog post for more information, or look them up by typing "chart." in the Pine Script™ Reference Manual.
Dynamic recalculation of scripts on visible bars
Any script using chart.left_visible_bar_time or chart.right_visible_bar_time acquires a unique property, which triggers its recalculation when traders scroll or zoom their charts in such a way that the range of visible bars on the chart changes. This library's functions use the two recent built-ins to derive various values from the range of visible bars.
Designing your scripts for dynamic recalculation
For the library's functions to work correctly, they must be called on every bar. For reliable results, assign their results to global variables and then use the variables locally where needed — not the raw function calls.
Some functions like `barIsVisible()` or `open()` will return a value starting on the leftmost visible bar. Others such as `high()` or `low()` will also return a value starting on the leftmost visible bar, but their correct value can only be known on the rightmost visible bar, after all visible bars have been analyzed by the script.
You can plot values as the script executes on visible bars, but efficient code will, when possible, create resource-intensive labels, lines or tables only once in the global scope using var, and then use the setter functions to modify their properties on the last bar only. The example code included in this library uses this method.
Keep in mind that when your script uses chart.left_visible_bar_time or chart.right_visible_bar_time, your script will recalculate on all bars each time the user scrolls or zooms their chart. To provide script users with the best experience you should strive to keep calculations to a minimum and use efficient code so that traders are not always waiting for your script to recalculate every time they scroll or zoom their chart.
Another aspect to consider is the fact that the rightmost visible bar will not always be the last bar in the dataset. When script users scroll back in time, a large portion of the time series the script calculates on may be situated after the rightmost visible bar. We can never assume the rightmost visible bar is also the last bar of the time series. Use `barIsVisible()` to restrict calculations to visible bars, but also consider that your script can continue to execute past them.
Look first. Then leap.
█ FUNCTIONS
The library contains the following functions:
barIsVisible()
Condition to determine if a given bar is within the users visible time range.
Returns: (bool) True if the the calling bar is between the `chart.left_visible_bar_time` and the `chart.right_visible_bar_time`.
high()
Determines the value of the highest `high` in visible bars.
Returns: (float) The maximum high value of visible chart bars.
highBarIndex()
Determines the `bar_index` of the highest `high` in visible bars.
Returns: (int) The `bar_index` of the `high()`.
highBarTime()
Determines the bar time of the highest `high` in visible bars.
Returns: (int) The `time` of the `high()`.
low()
Determines the value of the lowest `low` in visible bars.
Returns: (float) The minimum low value of visible chart bars.
lowBarIndex()
Determines the `bar_index` of the lowest `low` in visible bars.
Returns: (int) The `bar_index` of the `low()`.
lowBarTime()
Determines the bar time of the lowest `low` in visible bars.
Returns: (int) The `time` of the `low()`.
open()
Determines the value of the opening price in the visible chart time range.
Returns: (float) The `open` of the leftmost visible chart bar.
close()
Determines the value of the closing price in the visible chart time range.
Returns: (float) The `close` of the rightmost visible chart bar.
leftBarIndex()
Determines the `bar_index` of the leftmost visible chart bar.
Returns: (int) A `bar_index`.
rightBarIndex()
Determines the `bar_index` of the rightmost visible chart bar.
Returns: (int) A `bar_index`
bars()
Determines the number of visible chart bars.
Returns: (int) The number of bars.
volume()
Determines the sum of volume of all visible chart bars.
Returns: (float) The cumulative sum of volume.
ohlcv()
Determines the open, high, low, close, and volume sum of the visible bar time range.
Returns: () A tuple of the OHLCV values for the visible chart bars. Example: open is chart left, high is the highest visible high, etc.
chartYPct(pct)
Determines a price level as a percentage of the visible bar price range, which depends on the chart's top/bottom margins in "Settings/Appearance".
Parameters:
pct: (series float) Percentage of the visible price range (50 is 50%). Negative values are allowed.
Returns: (float) A price level equal to the `pct` of the price range between the high and low of visible chart bars. Example: 50 is halfway between the visible high and low.
chartXTimePct(pct)
Determines a time as a percentage of the visible bar time range.
Parameters:
pct: (series float) Percentage of the visible time range (50 is 50%). Negative values are allowed.
Returns: (float) A time in UNIX format equal to the `pct` of the time range from the `chart.left_visible_bar_time` to the `chart.right_visible_bar_time`. Example: 50 is halfway from the leftmost visible bar to the rightmost.
chartXIndexPct(pct)
Determines a `bar_index` as a percentage of the visible bar time range.
Parameters:
pct: (series float) Percentage of the visible time range (50 is 50%). Negative values are allowed.
Returns: (float) A time in UNIX format equal to the `pct` of the time range from the `chart.left_visible_bar_time` to the `chart.right_visible_bar_time`. Example: 50 is halfway from the leftmost visible bar to the rightmost.
whenVisible(src, whenCond, length)
Creates an array containing the `length` last `src` values where `whenCond` is true for visible chart bars.
Parameters:
src: (series int/float) The source of the values to be included.
whenCond: (series bool) The condition determining which values are included. Optional. The default is `true`.
length: (simple int) The number of last values to return. Optional. The default is all values.
Returns: (float) The array ID of the accumulated `src` values.
avg(src)
Gathers values of the source over visible chart bars and averages them.
Parameters:
src: (series int/float) The source of the values to be averaged. Optional. Default is `close`.
Returns: (float) A cumulative average of values for the visible time range.
median(src)
Calculates the median of a source over visible chart bars.
Parameters:
src: (series int/float) The source of the values. Optional. Default is `close`.
Returns: (float) The median of the `src` for the visible time range.
vVwap(src)
Calculates a volume-weighted average for visible chart bars.
Parameters:
src: (series int/float) Source used for the VWAP calculation. Optional. Default is `hlc3`.
Returns: (float) The VWAP for the visible time range.
This library is a Pine programmer’s tool containing functions that return values calculated from the range of visible bars on the chart.
This is now possible in Pine Script™ thanks to the recently-released chart.left_visible_bar_time and chart.right_visible_bar_time built-ins, which return the opening time of the leftmost and rightmost bars on the chart. These values update as traders scroll or zoom their charts, which gives way to a class of indicators that can dynamically recalculate and draw visuals on visible bars only, as users scroll or zoom their charts. We hope this library's functions help you make the most of the world of possibilities these new built-ins provide for Pine scripts.
For an example of a script using this library, have a look at the Chart VWAP indicator.
█ CONCEPTS
Chart properties
The new chart.left_visible_bar_time and chart.right_visible_bar_time variables return the opening time of the leftmost and rightmost bars on the chart. They are only two of many new built-ins in the `chart.*` namespace. See this blog post for more information, or look them up by typing "chart." in the Pine Script™ Reference Manual.
Dynamic recalculation of scripts on visible bars
Any script using chart.left_visible_bar_time or chart.right_visible_bar_time acquires a unique property, which triggers its recalculation when traders scroll or zoom their charts in such a way that the range of visible bars on the chart changes. This library's functions use the two recent built-ins to derive various values from the range of visible bars.
Designing your scripts for dynamic recalculation
For the library's functions to work correctly, they must be called on every bar. For reliable results, assign their results to global variables and then use the variables locally where needed — not the raw function calls.
Some functions like `barIsVisible()` or `open()` will return a value starting on the leftmost visible bar. Others such as `high()` or `low()` will also return a value starting on the leftmost visible bar, but their correct value can only be known on the rightmost visible bar, after all visible bars have been analyzed by the script.
You can plot values as the script executes on visible bars, but efficient code will, when possible, create resource-intensive labels, lines or tables only once in the global scope using var, and then use the setter functions to modify their properties on the last bar only. The example code included in this library uses this method.
Keep in mind that when your script uses chart.left_visible_bar_time or chart.right_visible_bar_time, your script will recalculate on all bars each time the user scrolls or zooms their chart. To provide script users with the best experience you should strive to keep calculations to a minimum and use efficient code so that traders are not always waiting for your script to recalculate every time they scroll or zoom their chart.
Another aspect to consider is the fact that the rightmost visible bar will not always be the last bar in the dataset. When script users scroll back in time, a large portion of the time series the script calculates on may be situated after the rightmost visible bar. We can never assume the rightmost visible bar is also the last bar of the time series. Use `barIsVisible()` to restrict calculations to visible bars, but also consider that your script can continue to execute past them.
Look first. Then leap.
█ FUNCTIONS
The library contains the following functions:
barIsVisible()
Condition to determine if a given bar is within the users visible time range.
Returns: (bool) True if the the calling bar is between the `chart.left_visible_bar_time` and the `chart.right_visible_bar_time`.
high()
Determines the value of the highest `high` in visible bars.
Returns: (float) The maximum high value of visible chart bars.
highBarIndex()
Determines the `bar_index` of the highest `high` in visible bars.
Returns: (int) The `bar_index` of the `high()`.
highBarTime()
Determines the bar time of the highest `high` in visible bars.
Returns: (int) The `time` of the `high()`.
low()
Determines the value of the lowest `low` in visible bars.
Returns: (float) The minimum low value of visible chart bars.
lowBarIndex()
Determines the `bar_index` of the lowest `low` in visible bars.
Returns: (int) The `bar_index` of the `low()`.
lowBarTime()
Determines the bar time of the lowest `low` in visible bars.
Returns: (int) The `time` of the `low()`.
open()
Determines the value of the opening price in the visible chart time range.
Returns: (float) The `open` of the leftmost visible chart bar.
close()
Determines the value of the closing price in the visible chart time range.
Returns: (float) The `close` of the rightmost visible chart bar.
leftBarIndex()
Determines the `bar_index` of the leftmost visible chart bar.
Returns: (int) A `bar_index`.
rightBarIndex()
Determines the `bar_index` of the rightmost visible chart bar.
Returns: (int) A `bar_index`
bars()
Determines the number of visible chart bars.
Returns: (int) The number of bars.
volume()
Determines the sum of volume of all visible chart bars.
Returns: (float) The cumulative sum of volume.
ohlcv()
Determines the open, high, low, close, and volume sum of the visible bar time range.
Returns: () A tuple of the OHLCV values for the visible chart bars. Example: open is chart left, high is the highest visible high, etc.
chartYPct(pct)
Determines a price level as a percentage of the visible bar price range, which depends on the chart's top/bottom margins in "Settings/Appearance".
Parameters:
pct: (series float) Percentage of the visible price range (50 is 50%). Negative values are allowed.
Returns: (float) A price level equal to the `pct` of the price range between the high and low of visible chart bars. Example: 50 is halfway between the visible high and low.
chartXTimePct(pct)
Determines a time as a percentage of the visible bar time range.
Parameters:
pct: (series float) Percentage of the visible time range (50 is 50%). Negative values are allowed.
Returns: (float) A time in UNIX format equal to the `pct` of the time range from the `chart.left_visible_bar_time` to the `chart.right_visible_bar_time`. Example: 50 is halfway from the leftmost visible bar to the rightmost.
chartXIndexPct(pct)
Determines a `bar_index` as a percentage of the visible bar time range.
Parameters:
pct: (series float) Percentage of the visible time range (50 is 50%). Negative values are allowed.
Returns: (float) A time in UNIX format equal to the `pct` of the time range from the `chart.left_visible_bar_time` to the `chart.right_visible_bar_time`. Example: 50 is halfway from the leftmost visible bar to the rightmost.
whenVisible(src, whenCond, length)
Creates an array containing the `length` last `src` values where `whenCond` is true for visible chart bars.
Parameters:
src: (series int/float) The source of the values to be included.
whenCond: (series bool) The condition determining which values are included. Optional. The default is `true`.
length: (simple int) The number of last values to return. Optional. The default is all values.
Returns: (float) The array ID of the accumulated `src` values.
avg(src)
Gathers values of the source over visible chart bars and averages them.
Parameters:
src: (series int/float) The source of the values to be averaged. Optional. Default is `close`.
Returns: (float) A cumulative average of values for the visible time range.
median(src)
Calculates the median of a source over visible chart bars.
Parameters:
src: (series int/float) The source of the values. Optional. Default is `close`.
Returns: (float) The median of the `src` for the visible time range.
vVwap(src)
Calculates a volume-weighted average for visible chart bars.
Parameters:
src: (series int/float) Source used for the VWAP calculation. Optional. Default is `hlc3`.
Returns: (float) The VWAP for the visible time range.
ملاحظات الأخبار:
v2
• Fixed a bug in `highBarIndex()`. Thx to @EulerMethod for the report!
• Fixed a bug in `highBarIndex()`. Thx to @EulerMethod for the report!
ملاحظات الأخبار:
v3
• Fixed example code by pre-evaluating `bars()` and `volume()` outside the `if barstate.islast` block.
• Fixed example code by pre-evaluating `bars()` and `volume()` outside the `if barstate.islast` block.
ملاحظات الأخبار:
v4
Added `isFirstVisibleBar()` and `isLastVisibleBar()` functions to determine the first and last visible bar.
The functions are:
isFirstVisibleBar()
Condition to determine if a bar is the first visible bar.
Returns: (bool) True if the current bar is the first visible bar.
isLastVisibleBar()
Condition to determine if a bar is the last visible bar.
Returns: (bool) True if the current bar is the last visible bar.
Added `isFirstVisibleBar()` and `isLastVisibleBar()` functions to determine the first and last visible bar.
The functions are:
isFirstVisibleBar()
Condition to determine if a bar is the first visible bar.
Returns: (bool) True if the current bar is the first visible bar.
isLastVisibleBar()
Condition to determine if a bar is the last visible bar.
Returns: (bool) True if the current bar is the last visible bar.
Tools and ideas for all Pine coders: www.pinecoders.com
Our Pine FAQ & Code: www.pinecoders.com/faq_and_code/
Pine news broadcasts: t.me/PineCodersSquawkBox or twitter.com/PineCoders
Our Pine FAQ & Code: www.pinecoders.com/faq_and_code/
Pine news broadcasts: t.me/PineCodersSquawkBox or twitter.com/PineCoders