v2
This version release comes with the following changes:
• The `calcCumulativeSeries()` function now includes an optional `adjustRealtime` parameter. When enabled, the function estimates the potential closing value of the cumulative series on unclosed bars based on the data accumulated since the last anchor condition. Specifically, the function calculates a value-to-time ratio from the cumulative data and uses the result to project a possible closing value. The purpose of this estimation is to allow users to compare a hypothetical closing value to the historical average of closing values on realtime bars whose final values are not yet known.
• We've enhanced the `averageAtTime()` function to address calculation inaccuracies. Previously, the function used the first bar's time from the current period as a reference for offset calculations. While this approach is fine for symbols with consistent sessions, it can cause calculation errors on symbols with varied session open times. To remedy this issue, we've added an overload for the function that uses the input `timeframe` time as its reference, providing more consistency without relying on a specific session's opening time. The previous version (i.e., the first overload) remains available for users who wish to reset periods based on factors other than timeframe changes.
• We've refined the library's code comments and annotations for clarity and readability.
The enhanced `calcCumulativeSeries()` function:
calcCumulativeSeries(source, anchor, adjustRealtime)
Calculates the cumulative sum of the `source` since the last bar where `anchor` was `true`.
Parameters:
source (float): (series float) Source used for the calculation.
anchor (bool): (series bool) The condition that triggers the reset of the calculation. The calculation resets when `anchor` is `true`, and continues accumulating values since the previous reset when `anchor` is `false`.
adjustRealtime (simple bool): (simple bool) If `true`, estimates the cumulative value on unclosed bars based on the data since the last `anchor` condition. Optional. The default is `false`.
Returns: (float) The cumulative sum of the `source`.
The newly overloaded `averageAtTime()` function:
averageAtTime(source, length, timeframe, isCumulative)
Calculates the average `source` value over `length` periods, where the values in the average are from each bar whose time offset from the start of its respective period is closest to that of the current bar in the most recent period.
Parameters:
source (float): (series float) Source used for the calculation.
length (simple int): (simple int) The number of reset periods to consider for the average calculation of historical data.
timeframe (simple string): (series string) Specifies the size of each period in the average calculation. A new period begins when a new bar opens on the specified timeframe.
isCumulative (simple bool): (simple bool) If `true`, calculates the average of cumulative `source` values in each period at the current time offset. Optional. The default is `true`.
Returns: (float) The historical average of the `source` series at the current time offset.