Understanding barstate.ishistory Function in Pine Script

In this article, we’ll delve into the barstate.ishistory property in Pine Script version 5, its characteristics, and its practical use in a script. We’ll also provide a working example to demonstrate its application.

What is barstate.ishistory?

barstate.ishistory is a built-in boolean property in Pine Script that helps in identifying historical bars in a chart. Understanding this property is crucial for script developers to differentiate between real-time and historical data.

Characteristics of barstate.ishistory:

True for Historical Bars: barstate.ishistory is set to true for all historical bars in a chart.
Mutually Exclusive with barstate.isrealtime: This property cannot be true when barstate.isrealtime is also true. This means it exclusively identifies historical bars, not real-time bars.
Remains False on Realtime Bar’s Closing Update: It does not become true when a real-time bar closes and barstate.isconfirmed becomes true.
Special Case in Closed Markets: In the case of closed markets, barstate.ishistory can be true for the same bar where barstate.islast is true.

Example: Using barstate.ishistory in Pine Script

Let’s create an example script in Pine Script v5 that utilizes barstate.ishistory to demonstrate its functionality.

Script Overview:

Objective: To highlight historical bars on the chart.
Functionality: The script will change the color of the bars to distinguish historical bars from real-time bars.

Code Example:

//@version=5
indicator("Historical Bar Highlighter", overlay=true)

// Define a unique color variable for historical bars
histBarColor = color.new(color.green, 90)

// Condition to check if the bar is historical
isHistBar = barstate.ishistory

// Apply color to historical bars
barcolor(isHistBar ? histBarColor : na)

// Displaying a label for demonstration
if barstate.islast
    label.new(bar_index, high, "End of Historical Data", color=color.red)

Code Walkthrough:

1. Declaring the Script and Overlay Settings

Script Declaration: We begin with //@version=5 to specify the use of Pine Script version 5.
Indicator Function: The indicator function names the script “Historical Bar Highlighter” and sets overlay=true, allowing the script to overlay on the main price chart.

2. Defining Color for Historical Bars

Color Variable: histBarColor is initialized with color.new(color.green, 90), creating a semi-transparent green color to distinguish historical bars.

3. Checking for Historical Bars

Historical Bar Condition: The boolean variable isHistBar is assigned the value of barstate.ishistory. This boolean will be true for historical bars and false otherwise.

4. Applying Color to Historical Bars

Color Application: Using barcolor(isHistBar ? histBarColor : na), the script colors the historical bars green. Bars not meeting the condition remain unchanged.

5. Adding a Label for Clarity

Label Creation: A label is created on the last bar of historical data using label.new(bar_index, high, "End of Historical Data", color=color.red), providing a clear demarcation between historical and real-time data.

Key Features and Takeaways

Function Usability: barstate.ishistory is ideal for scripts that need to distinguish between historical and real-time data.
Syntax and Application: This property is straightforward to implement and requires no additional parameters.
Practical Usage: Commonly used in scripts where the behavior for historical and real-time data needs to be different, such as in backtesting scenarios.

The provided example offers a basic but practical implementation of barstate.ishistory, demonstrating its ability to distinguish historical bars, which is vital in many trading strategies and indicators.