Home » Symbol Information Functions » Understanding barstate.ishistory Function in Pine Script

Understanding barstate.ishistory Function in Pine Script

Photo of author
Published on

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:

  1. True for Historical Bars: barstate.ishistory is set to true for all historical bars in a chart.
  2. 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.
  3. Remains False on Realtime Bar’s Closing Update: It does not become true when a real-time bar closes and barstate.isconfirmed becomes true.
  4. 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:

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.

Leave a Comment