Qualifiers in Pine Script Functions

Introduction

Pine Script™ uses a robust type system to define how values interact with various functions and operations. Grasping the nuances of this system, including the concept of qualifiers, is essential for proficient scripting in Pine Script™.

Qualifiers in Pine Script™ determine the state of values – whether they are constant, established at the script’s first iteration, or dynamic. This article delves into the different types of qualifiers: const, input, simple, and series, explaining their usage and impact on script behavior.

Qualifiers Explained

const Qualifiers

Definition: Values qualified as const are determined at compile time. They are immutable during the script’s lifecycle.
Usage: const values are set using literal values or expressions exclusively containing literals or other const values.
Example:

  //@version=5
  const NUM_DAYS = 5
  plot(ta.sma(close, NUM_DAYS), "SMA over " + tostring(NUM_DAYS) + " days")

input Qualifiers

Definition: input qualifiers are set after initialization via input.*() functions, allowing user modifications in the script settings.
Example:

  //@version=5
  inputLength = input.int(14, "Input Length")
  plot(ta.rsi(close, inputLength), "RSI with Input Length")

simple Qualifiers

Definition: simple qualifiers become available at the script’s first execution bar and remain constant throughout.
Example:

  //@version=5
  simple isFirstBar = (bar_index == 0)
  bgcolor(isFirstBar ? color.red : na, title = "First Bar Highlight")

series Qualifiers

Definition: series qualifiers offer the most flexibility, changing across any bar during execution.
Example:

  //@version=5
  series float dynamicValue = close > open ? close - open : na
  plot(dynamicValue, "Dynamic Value")

Unique Use Case Example

Let’s create a unique example demonstrating these qualifiers. We’ll build a script that plots a moving average, highlighting bars where the close price is significantly different from the average.

Script Example

//@version=5
indicator("Unique Use Case: Qualifiers Demo", overlay = true)

// const qualifier for the number of days in the moving average
const int NUM_DAYS = 10
const float DIFF_THRESHOLD = 2.0

// input qualifier for user to adjust the sensitivity
inputSensitivity = input.float(1.5, "Sensitivity")

// simple qualifier for the initial moving average
simple float initialMA = na

// series qualifier for dynamic average calculation
series float dynamicMA = ta.sma(close, NUM_DAYS)

// Calculate the difference and apply the sensitivity
float diff = math.abs(close - dynamicMA) * inputSensitivity

// Determine if the difference exceeds the threshold
series bool isSignificant = diff > DIFF_THRESHOLD

// Plotting
plot(dynamicMA, "Moving Average", color.blue)
bgcolor(isSignificant ? color.new(color.orange, 90) : na, title = "Significant Difference Highlight")

Explanation

const Qualifiers: NUM_DAYS and DIFF_THRESHOLD are set at compile time, providing constants for the moving average calculation and the difference threshold.
input Qualifier: inputSensitivity allows the user to adjust the sensitivity of the difference calculation.
simple Qualifier: initialMA is defined but not used dynamically in this script. It serves to illustrate a simple qualifier.
series Qualifiers: dynamicMA calculates the moving average dynamically for each bar, and diff measures the difference between the close price and this moving average, adjusted by user sensitivity.
Conditional Highlighting: Bars where the difference is significant (exceeding DIFF_THRESHOLD) are highlighted, demonstrating the practical use of series qualifiers.

Key Takeaway

Understanding and correctly using qualifiers in Pine Script™ is pivotal for writing efficient and accurate scripts. Each qualifier (const, input, simple, series) serves a unique purpose, influencing how values are initialized, modified, and utilized throughout a script’s lifecycle.

Conclusion

Qualifiers in Pine Script™ play a crucial role in determining the behavior and efficiency of scripts. By grasping the nuances of these qualifiers, scriptwriters can create more dynamic, flexible, and powerful trading indicators and strategies. Remember, the choice of qualifier directly impacts the script’s functionality and performance, making it a fundamental aspect of Pine Script™ programming.