Understanding the weekofyear() Function in Pine Script

This tutorial delves into the syntax, overloads, and practical applications of the weekOfYear() function, providing insights into how it can be leveraged within the Pine Script environment.

Syntax

The weekOfYear() function is available in two variants, accommodating different use cases:

1. Basic Usage

   weekOfYear(time) → series int

• Arguments:
  • time (series int): Represents UNIX time in milliseconds.
• Returns: The week of the year for the provided UNIX time, based on the exchange’s timezone.

1. With Timezone Specification

   weekOfYear(time, timezone) → series int

• Arguments:
  • time (series int): UNIX time in milliseconds.
  • timezone (string): The timezone to consider when calculating the week of the year.
• Returns: Similar to the basic usage, but allows for timezone specification, offering flexibility in analysis across different geographic locations.

Arguments

• time (series int): This is the UNIX time in milliseconds. UNIX time, also known as Epoch time, is the total number of milliseconds that have elapsed since 00:00:00 UTC on 1 January 1970.

Returns

• The function returns the week of the year for the given UNIX time. This calculation is done considering the exchange’s timezone, which is crucial for accurately analyzing time-sensitive data in financial markets.

Example: Basic Weekly Trend Indicator

Consider creating a simple indicator that highlights the first trading session of each week:

//@version=5
indicator("Weekly Trend Starter", overlay=true)
weekNum = weekofyear(time)
weekStart = ta.change(weekNum) != 0
if weekStart
    label.new(bar_index, high, "Week Start", color=color.green)

This script uses the weekOfYear() function to determine the week number for each bar. When the week number changes (ta.change(weekNum) != 0), it signifies the start of a new week, at which point a label is placed on the chart.

Walkthrough of Code 

1. Script Version Declaration
   • //@version=5: Specifies that this script uses version 5 of Pine Script. This is necessary for compatibility and to ensure that the script utilizes the latest features and syntax supported by Pine Script.
2. Indicator Declaration
   • indicator("Weekly Trend Starter", overlay=true): This line declares a new indicator with the name “Weekly Trend Starter.” The overlay=true parameter indicates that this indicator will be drawn directly on the price chart, overlaying the price data.
3. Week Number Calculation
   • weekNum = weekofyear(time): Calculates the week number of the year for each bar on the chart. It uses the weekofyear() function, which takes the time series (UNIX time in milliseconds for each bar) as an argument. The result is assigned to the variable weekNum.
4. Detecting the Start of a New Week
   • weekStart = ta.change(weekNum) != 0: This line determines if the current bar represents the start of a new week. It does so by using the ta.change() function on weekNum to detect changes in the week number from one bar to the next. If there’s a change (ta.change(weekNum) != 0), it means a new week has started, and weekStart is set to true. Otherwise, weekStart is false.
5. Label Placement for Week Start
   • The if weekStart conditional checks if the weekStart variable is true. If so, it executes the following block of code:
     • label.new(bar_index, high, "Week Start", color=color.green): This creates a new label at the beginning of a new week. The label is placed at the high price of the bar (to ensure visibility) and marked with the text “Week Start”. The label is colored green (color=color.green) to make it easily distinguishable. The bar_index is used to position the label on the x-axis (time axis), ensuring it aligns with the corresponding bar that marks the start of a new week.

Key Features and Takeaways

• Function Usability: The weekOfYear() function is versatile, supporting both basic and timezone-specific applications.
• Syntax and Application: Offers a straightforward approach to obtaining the week of the year, enhancing time-based data analysis in Pine Script.
• Practical Use Cases: Essential for creating time-aware trading strategies or indicators, especially for identifying seasonal trends or performing week-over-week comparisons.

In conclusion, the weekOfYear() function is a powerful tool within Pine Script, enabling developers to incorporate time-based logic into their custom trading solutions. By understanding and applying this function, users can unlock new dimensions of market analysis, catering to a wide range of trading strategies and research endeavors.