Understanding Series in Pine Script

Introduction to Series

In Pine Script, a series represents a sequence of data points that can change over time or across the bars on a chart. This capability is fundamental for analyzing financial markets since asset prices and trading volumes fluctuate continuously.

Variables and parameters declared with the series keyword can hold values that change from one bar to the next. This characteristic makes series the most versatile data type in Pine Script, essential for creating responsive and adaptive trading scripts.

Built-in Series Variables

Pine Script includes several built-in variables qualified as “series,” such as open, high, low, close, volume, time, and bar_index. These variables inherently carry the series qualifier because their values vary with each chart bar. Additionally, any expression or function that operates on these variables or returns dynamic values is considered a series. This includes accessing historical values through the history-referencing operator [].

Series Flexibility in Scripts

The series qualifier’s flexibility is showcased when scripts need to handle data that changes over time. For example, calculating moving averages, tracking highest and lowest prices, or implementing custom trading rules that adapt to price action.

Practical Example: Tracking High and Low Values

To illustrate the concept of series, let’s examine a script that identifies the highest and lowest values of a given input over a specified number of bars.

//@version=5
indicator("Flexible Series Demo", overlay = true)

// Declare the source value as a "series float"
series float priceSource = input.source(close, "Source")
// Declare the calculation length as an "input int"
lengthPeriod = input.int(20, "Length")

// Calculate the highest value over the specified period
series float peakValue = ta.highest(priceSource, lengthPeriod)
// Calculate the lowest value over the specified period
valleyValue = ta.lowest(priceSource, lengthPeriod)

plot(peakValue, "Peak Price", color.green)
plot(valleyValue, "Valley Price", color.red)

Walkthrough

• Indicator Declaration: The script starts by declaring a custom indicator with overlay = true, allowing it to be plotted directly on the price chart.
• Input Declarations:
  • priceSource: A series float variable set to track the closing price (close), though users can select another price component if desired.
  • lengthPeriod: An integer input that determines the number of bars over which the highest and lowest values are calculated.
• Series Calculations:
  • peakValue: Utilizes the built-in function ta.highest to find the highest value of priceSource over lengthPeriod bars.
  • valleyValue: Similarly, ta.lowest finds the lowest value within the same period.
• Plotting: The script plots both peakValue and valleyValue on the chart, using green and red colors, respectively, to distinguish between the two.

Key Takeaways

• Series Flexibility: The series qualifier allows variables to adapt dynamically to new data, crucial for real-time analysis.
• Built-in Functions: Pine Script provides functions like ta.highest and ta.lowest specifically designed to work with series data, simplifying the process of extracting meaningful statistics from price action.
• Customizability: By using inputs, the script allows users to adjust parameters like the source price and calculation length, demonstrating the adaptability of series variables in trading strategies.