PINE LIBRARY
Updated RollingWindow
█ OVERVIEW
This a Pine Script™ library to create rolling windows with arrays and matrices.
A rolling window is a first-in-first-out algorithm that stores values over chart updates, removing the oldest element as new values are added. Many programmers implement a form of this algorithm into their scripts currently like this:
Pine Script®
With the RollingWindow library, you can simply call `roll()` to do the same thing like so:
Pine Script®
█ USAGE
Rolling Window Arrays
Import the RollingWindow library into your script.
Pine Script®
Create a rolling window array by calling `roll()` on an array declared with `var` bar persistence.
Pine Script®
Using an array with `varip` intrabar persistence lets `roll()` execute on and update elements intrabar.
Pine Script®
Ensure arrays are declared with `var` or `varip` keywords to store updated elements. Otherwise, applying `roll()` will not store rolled values.
Pine Script®
New elements can be added dynamically to empty arrays with the limit set by the `roll(size)` parameter. Once the array is full, every sequential chart update rolls out, removes, the oldest element.
Pine Script®
Arrays with initialized values and sizes can be used as a rolling window array.
Pine Script®
The `roll(size)` parameter becomes optional for arrays with an initialized size, because `roll()` will by default use the initialized size of the array provided if `roll(size)` is not set.
Pine Script®
An array with initialized values can still grow dynamically if `roll(size)` parameter is greater than the array's initial size.
Pine Script®
The `roll(size)` parameter must always be equal to or greater than the initial size of the array, or else `roll()` will generate a runtime error.
Pine Script®
When the array size and `roll(size)` parameter are both unspecified, `roll()` will dynamically size the array up to the element limit before rolling new elements.
Pine Script®
From within a conditional local scope, `roll()` can operate on arrays in a higher scope.
Pine Script®
`roll()` returns the element removed from the array, allowing scripts to capture values as they are rolled out.
Pine Script®
Reverse Rolling Window Arrays
The roll operation can be done in reverse order using the `rollReverse()` library function; new elements are inserted at the beginning of the array instead, and old elements are removed at the end of the array.
Pine Script®
`rollReverse()` returns the element removed from the array, just like `roll()`.
Pine Script®
Sorted Rolling Window Arrays
Rolling window arrays created with `roll()` are unsorted. To create ascending sorted rolling window arrays for `float` or `int` types, use the `rollAscendingVar()` or `rollAscendingVarip()` functions for `var` and `varip` keyword arrays respectively.
Pine Script®
To create descending sorted rolling window arrays for `float` or `int` types, use the `rollDescendingVar()` or `rollDescendingVarip()` functions for `var` and `varip` keyword arrays respectively.
Pine Script®
Just like with the `array.sort()` built-in function, the ascending and descending rolling window functions do not sort `na` values.
Pine Script®
The arrays with unsorted values should be sorted in ascending or descending order before calling the respective sorted rolling window library functions.
Pine Script®
The sorted rolling window functions can return the latest element removed from the array.
Pine Script®
Rolling Window Matrices
The `roll()` matrix methods store a rolling window of arrays in row-major order. Rows are "rolled" by adding a new row at index `0`, and removing the oldest row at the end of the matrix.
Pine Script®
A matrix with `varip` intrabar persistence lets `roll()` execute and update matrix rows intrabar.
Pine Script®
The matrix methods of `roll()` will dynamically create the necessary columns to fit all elements of `roll(array_id)` as long as the array size is greater than the number of matrix columns.
Pine Script®
The size of `array_id` can possibly be too large when dynamically adding columns to a rolling window matrix, generating a runtime error when the new column would exceed the 100,000 matrix size limit.
Pine Script®
A matrix with initialized rows and columns can also be used with `roll()`. This requires that the array's size used in `roll(array_id)` must be less than or equal to the number of matrix columns.
Pine Script®
The `roll(rows)` parameter is also optional: `roll()` will use the number of rows in the initialized matrix when `roll(rows)` is not set. Plus the number of initialized matrix columns does not have to be the same size as `roll(array_id)`.
Pine Script®
Managing Drawings
An array or matrix of `line`, `linefill`, `label`, `box`, `polyline`, or `table` types can be used with `roll()` to manage the number of drawing on a chart.
Pine Script®
When drawings are rolled out of an array or matrix, they are deleted with the `.delete()` method of the respective type used. The library functions return `void` for drawing types, so no value is returned when an element is removed.
This a Pine Script™ library to create rolling windows with arrays and matrices.
A rolling window is a first-in-first-out algorithm that stores values over chart updates, removing the oldest element as new values are added. Many programmers implement a form of this algorithm into their scripts currently like this:
With the RollingWindow library, you can simply call `roll()` to do the same thing like so:
█ USAGE
Rolling Window Arrays
Import the RollingWindow library into your script.
Create a rolling window array by calling `roll()` on an array declared with `var` bar persistence.
Using an array with `varip` intrabar persistence lets `roll()` execute on and update elements intrabar.
Ensure arrays are declared with `var` or `varip` keywords to store updated elements. Otherwise, applying `roll()` will not store rolled values.
New elements can be added dynamically to empty arrays with the limit set by the `roll(size)` parameter. Once the array is full, every sequential chart update rolls out, removes, the oldest element.
Arrays with initialized values and sizes can be used as a rolling window array.
The `roll(size)` parameter becomes optional for arrays with an initialized size, because `roll()` will by default use the initialized size of the array provided if `roll(size)` is not set.
An array with initialized values can still grow dynamically if `roll(size)` parameter is greater than the array's initial size.
The `roll(size)` parameter must always be equal to or greater than the initial size of the array, or else `roll()` will generate a runtime error.
When the array size and `roll(size)` parameter are both unspecified, `roll()` will dynamically size the array up to the element limit before rolling new elements.
From within a conditional local scope, `roll()` can operate on arrays in a higher scope.
`roll()` returns the element removed from the array, allowing scripts to capture values as they are rolled out.
Reverse Rolling Window Arrays
The roll operation can be done in reverse order using the `rollReverse()` library function; new elements are inserted at the beginning of the array instead, and old elements are removed at the end of the array.
`rollReverse()` returns the element removed from the array, just like `roll()`.
Sorted Rolling Window Arrays
Rolling window arrays created with `roll()` are unsorted. To create ascending sorted rolling window arrays for `float` or `int` types, use the `rollAscendingVar()` or `rollAscendingVarip()` functions for `var` and `varip` keyword arrays respectively.
To create descending sorted rolling window arrays for `float` or `int` types, use the `rollDescendingVar()` or `rollDescendingVarip()` functions for `var` and `varip` keyword arrays respectively.
Just like with the `array.sort()` built-in function, the ascending and descending rolling window functions do not sort `na` values.
The arrays with unsorted values should be sorted in ascending or descending order before calling the respective sorted rolling window library functions.
The sorted rolling window functions can return the latest element removed from the array.
Rolling Window Matrices
The `roll()` matrix methods store a rolling window of arrays in row-major order. Rows are "rolled" by adding a new row at index `0`, and removing the oldest row at the end of the matrix.
A matrix with `varip` intrabar persistence lets `roll()` execute and update matrix rows intrabar.
The matrix methods of `roll()` will dynamically create the necessary columns to fit all elements of `roll(array_id)` as long as the array size is greater than the number of matrix columns.
The size of `array_id` can possibly be too large when dynamically adding columns to a rolling window matrix, generating a runtime error when the new column would exceed the 100,000 matrix size limit.
A matrix with initialized rows and columns can also be used with `roll()`. This requires that the array's size used in `roll(array_id)` must be less than or equal to the number of matrix columns.
The `roll(rows)` parameter is also optional: `roll()` will use the number of rows in the initialized matrix when `roll(rows)` is not set. Plus the number of initialized matrix columns does not have to be the same size as `roll(array_id)`.
Managing Drawings
An array or matrix of `line`, `linefill`, `label`, `box`, `polyline`, or `table` types can be used with `roll()` to manage the number of drawing on a chart.
When drawings are rolled out of an array or matrix, they are deleted with the `.delete()` method of the respective type used. The library functions return `void` for drawing types, so no value is returned when an element is removed.
Release Notes
v2Added Reverse Rolling Window Matrices
The `rollReverse()` matrix methods append new rows at the last index and remove the oldest row at index `0`, producing a matrix with rows in reverse order compared to `roll()`.
Release Notes
v3Update chart preview with a `rollReverse()` matrix example.
Pine library
In true TradingView spirit, the author has published this Pine code as an open-source library so that other Pine programmers from our community can reuse it. Cheers to the author! You may use this library privately or in other open-source publications, but reuse of this code in publications is governed by House Rules.
Joe Baus, whop.com/baustrading
Disclaimer
The information and publications are not meant to be, and do not constitute, financial, investment, trading, or other types of advice or recommendations supplied or endorsed by TradingView. Read more in the Terms of Use.
Pine library
In true TradingView spirit, the author has published this Pine code as an open-source library so that other Pine programmers from our community can reuse it. Cheers to the author! You may use this library privately or in other open-source publications, but reuse of this code in publications is governed by House Rules.
Joe Baus, whop.com/baustrading
Disclaimer
The information and publications are not meant to be, and do not constitute, financial, investment, trading, or other types of advice or recommendations supplied or endorsed by TradingView. Read more in the Terms of Use.