Understanding the time_close() Function in Pine Script

This article will delve into the time_close() function, explaining its syntax, possible overloads, and how to use it effectively in your scripts.

Syntax

The time_close() function is versatile, with several overloads allowing you to tailor its use to your specific needs. Here’s a breakdown of its syntax and overloads:

• Basic Syntax: time_close(timeframe) → series int
• With Session: time_close(timeframe, session) → series int
• With Session and Timezone: time_close(timeframe, session, timezone) → series int

Arguments

• timeframe (series string): This represents the resolution of the bars you are interested in. An empty string ("") indicates the current chart resolution.
• session (string, optional): Specifies the trading session time range (e.g., "1200-1300" for noon to 1 PM). This is useful for focusing on a particular trading session.
• timezone (string, optional): Allows you to specify the timezone for the session, such as "America/New_York".

Example

Let’s consider an example to see how time_close() can be used in a Pine Script:

//@version=5
indicator("Bar Close Time", overlay=true)
closeTime = time_close(timeframe.period, "1200-1300", "America/New_York")
bgcolor(closeTime ? color.new(color.green, 90) : na)

In this script, we’re creating an indicator that changes the background color of bars closing between 12:00 PM and 1:00 PM New York time to a semi-transparent green. Here’s what each line does:

• Pine Script Version Declaration:
  • //@version=5: This line specifies that the script uses version 5 of Pine Script, which is essential for compatibility and access to the latest features and syntax improvements.
• Indicator Declaration:
  • indicator("Bar Close Time", overlay=true): This line declares a new indicator with the name “Bar Close Time”. The overlay=true parameter indicates that this indicator should be drawn directly on top of the price chart, rather than in a separate panel below it.
• Variable Assignment for Close Time:
  • closeTime = time_close(timeframe.period, "1200-1300", "America/New_York"): This line calculates and assigns to closeTime the UNIX time for the close of bars that end between 12:00 PM and 1:00 PM in the “America/New_York” timezone. The function time_close() is used here with three arguments:
    • timeframe.period refers to the current chart’s resolution (timeframe).
    • "1200-1300" specifies the session time window of interest.
    • "America/New_York" sets the timezone for the session time window.
• Background Color Application:
  • bgcolor(closeTime ? color.new(color.green, 90) : na): This line uses a ternary operator to conditionally change the background color of the chart. Here’s the breakdown:
    • closeTime ?: Checks if closeTime is not na (meaning the bar’s close time falls within the specified session).
    • color.new(color.green, 90): If closeTime is valid, creates a new semi-transparent green color (90% transparency) to be used for the background color of the bar.
    • : na: If closeTime is na (the bar does not close within the specified timeframe or the function returns na for other reasons), no background color is applied (na stands for “not applicable” or “no value”).

Returns

The time_close() function returns the UNIX time of a bar’s close, which is the number of milliseconds that have elapsed since 00:00:00 UTC on 1 January 1970. If the specified time point is outside the session or if used on non-standard price-based chart types (like Renko, Line break, Kagi, Point & Figure, and Range) in real-time bars, the function returns na.

Key Features and Takeaways

• Versatility: The time_close() function supports different overloads, making it versatile for various use cases.
• Session and Timezone Specificity: It allows for precise targeting of bars within specific trading sessions and timezones, enhancing the analysis of trading patterns.
• Returns UNIX Time: The function provides the UNIX time of bar closures, aiding in time-based data analysis and operations.
• Limitation on Chart Types: On non-standard price-based chart types, the function’s utility is limited in real-time bars, returning na.

In conclusion, the time_close() function in Pine Script is a powerful tool for developers looking to perform time-based analyses or operations within their custom indicators or strategies. By understanding and utilizing this function’s capabilities, you can enhance your trading scripts to better meet your analytical needs.