getSeries

23 jun 2022

█  OVERVIEW


This library is a Pine programmer’s tool containing functions that build an array of values meeting specific conditions. Its functions use concepts from our ConditionalAverages library, but instead of returning a single value, they return an array containing all the values meeting the conditions, which can then be processed as needed. This provides more flexibility to the programmer than a single value.

The "getSeries" name of the library stems from the fact that is uses arrays to build the equivalent of custom series which can then be operated on using array-specific functions in the `array.*` namespace, looped through using a for...in structure to implement custom logic, or sent to functions designed to process arrays such as those in these libraries: ArrayStatistics, ArrayOperations, arrayutils or Averages.

The eight examples illustrated in the library's code showcase the diversity of scenarios where the functions can be used.


Look first. Then leap.



█  FUNCTIONS


The library contains the following functions:


whenSince(​src, whenCond, sinceCond, length)
  Creates an array containing the `length` last `src` values where `whenCond` is true, since the last occurence of `sinceCond`.
  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`.
    sinceCond: (series bool) The condition determining when the accumulated series resets. Optional. The default is false, which will not reset.
    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.

rollOnTimeWhen(​src, timeWindow, cond, minBars)
  Creates an array of `src` values where `cond` is true, over a moving window of length `timeWindow` milliseconds.
  Parameters:
    src: (series int/float) The source of the values to be included.
    timeWindow: (simple int) The time duration in milliseconds defining the size of the moving window.
    cond: (series bool) The condition determining which values are included. Optional. The default is `true`.
    minBars: (simple int) The minimum number of values to maintain in the moving window. Optional. The default is 1.
  Returns: (float[]) The array ID of the accumulated `src` values.


Note that the functions must be called on each bar to work correctly. They must thus be pre-evaluated before using their results in conditional branches.