Understanding the year() Function in Pine Script

In this article, we delve into the syntax, overloads, and practical applications of the year() function in Pine Script. The year() function is a crucial component for extracting the year from a given UNIX timestamp. This function enables traders and analysts to manipulate and analyze time-series data concerning years, allowing for the creation of custom indicators and strategies tailored to specific timeframes.

Syntax and Overloads

The year() function in Pine Script is designed to return the year from a specified UNIX time. UNIX time, also known as Epoch time, counts the milliseconds since 00:00:00 UTC on 1 January 1970. The function can be utilized in two forms:

1. Basic Syntax: year(time) → series int

• Arguments:
  • time (series int): The UNIX time in milliseconds.
• Returns: The year (in exchange timezone) corresponding to the provided UNIX time.

1. With Timezone: year(time, timezone) → series int

• Arguments:
  • time (series int): The UNIX time in milliseconds.
  • timezone: The timezone to consider for extracting the year.
• Returns: Similar to the basic syntax, it returns the year but adjusted for the specified timezone.

Understanding the Arguments

• UNIX Time: It’s essential to grasp the concept of UNIX time to effectively use the year() function. UNIX time denotes the elapsed milliseconds since the start of the UNIX epoch at midnight on January 1, 1970, UTC. This time format is crucial for handling date and time operations in programming, including Pine Script.
• Timezone: When specifying a timezone in the year() function, it adjusts the returned year based on the timezone’s offset from UTC. This is particularly useful for financial markets analysis, where the trading session’s timezone can influence the date and time calculations.

Example

//@version=5
indicator("Highlight Year Bars", overlay=true)

// Target year for highlighting
targetYear = input.int(2022, title="Target Year")

// Current bar's year calculation with timezone consideration
currentYear = year(time, "UTC")

// Condition to check if the current bar's year matches the target year
isTargetYear = currentYear == targetYear

// Plotting logic to highlight bars belonging to the target year
bgcolor(isTargetYear ? color.new(color.green, 90) : na)

// Displaying the current year as a label on the chart for verification
label.new(bar_index, high, text=str.tostring(currentYear), style=label.style_label_down, color=color.red, textcolor=color.white, size=size.small)

Walkthrough of Code

1. Indicator Declaration: We start by declaring a custom indicator using indicator() the function, enabling it to overlay on the price chart.
2. Input for Target Year: We use input.int() to allow the user to specify the target year they want to highlight on the chart.
3. Calculating the Current Year: The year(time, "UTC") function calculates the year of each bar’s opening time in UTC timezone.
4. Matching Current Year with Target Year: We compare the calculated year with the user-specified target year using a conditional expression. This results in a boolean series where true indicates the bar’s year matches the target year.
5. Highlighting Bars: The bgcolor() function changes the background color of bars that match the target year, making them easily identifiable. We use color.new() to adjust the opacity of the green color for better visibility.
6. Displaying Year Labels: Finally, we use label.new() to create labels on the chart that display the year of each bar. This aids in verifying the correct application of the year function and the effectiveness of our highlighting logic.

 

Key Features and Takeaways

• Function Usability: The year() function is straightforward, requiring the UNIX time as input and optionally a timezone for more precise control over the year extraction.
• Syntax and Application: Pine Script users can choose between a basic syntax without timezone consideration or an overload with timezone, depending on their analysis needs.
• Handling Overnight Sessions: It’s important to be aware of the nuances related to overnight trading sessions and timezone differences, which can affect year calculations.
• Essential for Time-Series Analysis: This function is a fundamental tool for any Pine Script developer working with time-series data, offering a simple way to extract and work with yearly data segments.

By integrating the year() function into your Pine Script strategies and indicators, you can enhance your financial market analyses, ensuring accurate and timezone-aware year-based computations. Whether you’re filtering data, comparing different periods, or adjusting for specific market sessions, the year() function offers the flexibility and precision needed for effective date and time manipulation in Pine Script.