Understanding ta.percentile_nearest_rank() Function in Pine Script

Let’s dive into the syntax, application, and key features of ta.percentile_nearest_rank() function.

Syntax

The syntax for ta.percentile_nearest_rank() is straightforward:

ta.percentile_nearest_rank(source, length, percentage) → series float

Here’s a breakdown of its arguments:

• source (series int/float): The series of values to process. This is the data from which the percentile will be calculated.
• length (series int): This specifies the number of bars back to consider for the calculation. It defines the window size of the dataset.
• percentage (simple int/float): This is the target percentile to find, specified as a number in the range of 0 to 100.

Returns

This function returns the P-th percentile of the source series for the specified length of bars back as a floating-point number. The result is a value that represents the specified percentile within the window of data considered.

Example

Let’s look at a practical example to see how ta.percentile_nearest_rank() can be applied in Pine Script:

//@version=5
indicator("Percentile Nearest Rank Example", overlay=true)
priceData = close
lookbackPeriod = 14
targetPercentile = 90

percentileValue = ta.percentile_nearest_rank(priceData, lookbackPeriod, targetPercentile)
plot(percentileValue, color=color.red, title="90th Percentile")

In this example, we calculate the 90th percentile of the closing prices over the last 14 bars. Then, we plot this value on the chart, allowing traders to visually compare the current price to the calculated percentile.

Code Walkthrough

1. Indicator Declaration:
   • //@version=5: Specifies the version of Pine Script being used, in this case, version 5, which is the latest at the time of writing.
   • indicator("Percentile Nearest Rank Example", overlay=true): Declares a new indicator with the title “Percentile Nearest Rank Example”. The overlay=true parameter means this indicator will be plotted directly on the price chart, overlaying the price data.
2. Variable Initialization:
   • priceData = close: Assigns the closing price of each bar to the variable priceData. This variable will serve as the source data for the percentile calculation.
   • lookbackPeriod = 14: Sets the lookback period to 14 bars. This defines the window size of the dataset to be considered for the percentile calculation.
   • targetPercentile = 90: Specifies that the target percentile to calculate is the 90th percentile. This value indicates the desired threshold percentile.
3. Percentile Calculation:
   • percentileValue = ta.percentile_nearest_rank(priceData, lookbackPeriod, targetPercentile): This line is where the percentile calculation happens. The function ta.percentile_nearest_rank() is called with three arguments: the source data (priceData), the length of the lookback period (lookbackPeriod), and the target percentile (targetPercentile). The result of this function, which is the 90th percentile value of the closing prices over the specified lookback period, is stored in the variable percentileValue.
4. Plotting the Percentile Value:
   • plot(percentileValue, color=color.red, title="90th Percentile"): This line plots the calculated 90th percentile value on the chart. The plot will be colored red (specified by color=color.red), and it will have the title “90th Percentile” to make it easily identifiable on the chart.

Key Features and Takeaways

• Function Usability: The ta.percentile_nearest_rank() function is invaluable for statistical analysis over a series of values, offering insights into the distribution of data points.
• Syntax and Application: It accepts three parameters (source, length, percentage) to provide a versatile tool for analyzing market conditions across different time frames and percentile targets.
• Practical Utility: By identifying where the current price stands relative to historical data, traders can make more informed decisions based on the relative strength or weakness of the market.

Understanding and applying the ta.percentile_nearest_rank() function can significantly enhance your market analysis, enabling a deeper dive into the data’s statistical properties.