Understanding the array.percentrank() Function in Pine Script

The array.percentrank() function in Pine Script is a powerful tool for statistical analysis within your trading scripts. It helps you determine the relative position of a data point within a dataset. Let’s dive deeper into its syntax, usage, and practical application.

Syntax

The function comes in two main forms, accommodating both floating-point and integer arrays:

• For Floating-Point Arrays: array.percentrank(id, index) → series float
• For Integer Arrays: array.percentrank(id, index) → series int

Arguments

• id (array<int/float>): This is the array object containing your dataset. It can either be an array of integers or floating points.
• index (series int): This specifies the index of the element for which you want to calculate the percentile rank. It’s a dynamic value that can change with each bar on the chart.

Practical Example

Let’s look at a practical example to understand how array.percentrank() can be utilized in a Pine Script:

//@version=5
indicator("Percentile Rank Example", overlay=false)

// Sample array of closing prices
pricesArray = array.new_float(0)
for i = 0 to 99
    array.push(pricesArray, close[i])

// Calculate the percentile rank of the latest closing price
currentIndex = array.size(pricesArray) - 1
percentRank = array.percentrank(pricesArray, currentIndex)

plot(percentRank, "Percentile Rank", color=color.blue)

Walkthrough of Code 

1. Indicator Declaration: The code begins with //@version=5, specifying it uses Pine Script version 5. The indicator function is called with the title “Percentile Rank Example” and overlay=false, indicating that the indicator will be displayed in its own pane below the main chart.
2. Creating the Array of Prices:
   • pricesArray is initialized as an empty floating-point array using array.new_float(0). This array will store the closing prices.
   • A for loop (for i = 0 to 99) iterates 100 times, each time pushing the closing price from i bars ago into pricesArray with array.push(pricesArray, close[i]).
3. Calculating the Percentile Rank:
   • currentIndex is determined by array.size(pricesArray) - 1, which finds the last index of pricesArray. Since array indexing is zero-based, we subtract 1 to get the correct last index.
   • percentRank is then calculated using array.percentrank(pricesArray, currentIndex). This function call computes the percentile rank of the element at currentIndex within pricesArray, effectively assessing where the latest closing price stands in relation to the past 100 closing prices.
4. Plotting the Result:
   • The calculated percentRank is plotted on the chart using plot(percentRank, "Percentile Rank", color=color.blue). This visualizes the percentile rank of the latest closing price as a line graph, allowing for an easy assessment of its relative position over time.

Key Features and Takeaways

• Function Useability: array.percentrank() is versatile, supporting both integer and floating-point arrays. This makes it suitable for a wide range of data types in financial markets.
• Syntax: The function requires two arguments: the array id and the index of the element. This simplicity makes it easy to integrate into your scripts.
• Application: It’s invaluable for statistical analysis, especially when assessing the distribution of data points like prices, volumes, or custom indicators over a given period.

The array.percentrank() function is a testament to Pine Script’s flexibility in financial analysis, providing traders and developers with robust tools for dissecting market data.