Time Series

A significant strength of Pine Script lies in its ability to process time series data efficiently. Time series, although not a type or form, are a fundamental structure in Pine Script used to store variable values over time. Each of these values is associated with a specific point in time. As charts are comprised of bars each symbolizing a unique point in time, time series provide the optimal structure for managing values that may fluctuate over time.

The concept of time series is deeply intertwined with Pine Script’s execution model and type system. To fully harness the power of Pine Script, it is essential to understand these three concepts.

Consider the built-in open variable that holds the "open" price for each bar in a data set, which consists of all the bars on a given chart. When your script is operating on a 5-minute chart, each value in the open time series signifies the "open" price of the successive 5-minute chart bars. When you refer to open, you are addressing the "open" price of the bar on which the script is currently executing. The [] history-referencing operator is used to refer to past values in a time series.

It's important to note that time series, although they might remind you of arrays, are not the same. Pine Script does use an array data structure, but it's entirely separate from the concept of a time series.

Pine Script's time series functionality, in combination with its specific runtime engine and built-in functions, simplifies calculations like the cumulative total of close values without requiring a for loop. Instead, you can use ta.cum(close). This expression appears static in a script, but it actually executes on each bar, continuously accumulating as the close value of each new bar is added to it. By the time the script reaches the rightmost bar of the chart, ta.cum(close) returns the sum of the close value from all bars on the chart.

The number of bars since the last time the chart made five consecutive higher highs can be calculated using barssince(rising(high, 5)). Also, the outcome of function calls on successive bars leaves a trail of values in a time series, which can be accessed using the [] history-referencing operator.

A function call such as plot(open) applies the same looping logic to all bars, successively plotting the value of open for each bar on the chart.

It's crucial not to confuse "time series" with the "series" form. The time series concept elucidates how Pine Script stores consecutive variable values, whereas the "series" form refers to variables whose values can change from one bar to the next.

A prime example of this is the timeframe.period built-in variable, which is of the "simple" form and "string" type. The "simple" form indicates that the variable's value is fixed on bar zero (where the script first executes) and remains unchanged throughout the script's execution across all the chart's bars.

Once you understand how Pine Script's syntax and its execution model can effectively manage time series, you can define complex calculations with minimal code.