Time Series

Much of the power of Lipi Script stems from its design, which efficiently processes time series data. Time series are not a qualified type; instead, they serve as the foundational structure that Lipi Script uses to store a variable’s sequential values over time, with each value linked to a specific point in time. Given that charts consist of bars, each representing a particular moment, time series provide an ideal structure for managing values that vary over time.

The concept of time series is closely related to Lipi Script’s execution model and type system. Understanding these concepts is crucial for harnessing the full power of Lipi Script.

Consider the built-in open variable, which holds the “open” price for each bar in the dataset—this dataset includes all the bars on a given chart. If your script runs on a 5-minute chart, each value in the open time series reflects the open price of consecutive 5-minute chart bars. Referring to open in your script accesses the open price of the specific bar on which the script executes. To reference historical values within a time series, use the [] history-referencing operator. For instance, when a script executes on a given bar, open[1] denotes the open value from the previous bar.

Time series in Lipi Script, combined with its unique runtime engine and built-in functions, allow for straightforward cumulative calculations, such as talib.cum(close) for the cumulative total of close values. This works without a for loop because, although talib.cum(close) appears static in a script, it actually executes on each bar, increasing cumulatively as each new bar’s close value is added. Upon reaching the last bar, talib.cum(close) returns the sum of close values from all bars on the chart.

Likewise, calculating the mean difference between the last 14 high and low values is as simple as talib.sma(high - low, 14), and determining the bar count since five consecutive higher highs were reached can be achieved with barssince(rising(high, 5)).

Additionally, the output of function calls on successive bars produces a trace of values in a time series, which can be accessed using the [] history-referencing operator. This can be helpful, for instance, to test if the close of the current bar exceeds the highest high of the last 10 bars (excluding the current bar), which can be written as breach = close > highest(close, 10)[1]. Alternatively, this could also be written as breach = close > highest(close[1], 10).

This same logic of looping through all bars applies to functions such as plot(open), which will plot the open value for each bar sequentially on the chart.

It’s important to distinguish between a “time series” and the “series” qualifier. Time series define how Lipi Script stores consecutive values, while the “series” qualifier designates variables whose values can change from bar to bar. Take timeframe.period, for instance—a built-in variable of the “simple string” type. Since it is qualified as “simple”, its value is established on bar zero (the first bar the script executes on) and does not change throughout the chart’s bars. The value reflects the chart’s timeframe as a string, like "D" for a 1-day chart. While timeframe.period’s value remains constant, you could still reference it 10 bars back as timeframe.period[10], thanks to Lipi Script’s storage of consecutive values within a time series. However, using the [] operator to access a past value yields a “series” qualified output, even if the original variable is qualified differently, such as “simple” in timeframe.period.

Mastering how Lipi Script handles time series efficiently through its syntax and execution model allows for defining complex calculations with minimal code.