Holiday
Library "Holiday"
- Full Control over Holidays and Daylight Savings Time (DLS)
The Holiday Library is an essential tool for traders and analysts who engage in backtesting and live trading. This comprehensive library enables the incorporation of crucial calendar elements - specifically Daylight Savings Time (DLS) adjustments and public holidays - into trading strategies and backtesting environments.
Key Features:
- DLS Adjustments: The library takes into account the shifts in time due to Daylight Savings. This feature is particularly vital for backtesting strategies, as DLS can impact trading hours, which in turn affects the volatility and liquidity in the market. Accurate DLS adjustments ensure that backtesting scenarios are as close to real-life conditions as possible.
- Comprehensive Holiday Metadata: The library includes a rich set of holiday metadata, allowing for the detailed scheduling of trading activities around public holidays. This feature is crucial for avoiding skewed results in backtesting, where holiday trading sessions might differ significantly in terms of volume and price movement.
- Customizable Holiday Schedules: Users can add or remove specific holidays, tailoring the library to fit various regional market schedules or specific trading requirements.
- Visualization Aids: The library supports on-chart labels, making it visually intuitive to identify holidays and DLS shifts directly on trading charts.
Use Cases:
1. Strategy Development: When developing trading strategies, it’s important to account for non-trading days and altered trading hours due to holidays and DLS. This library enables a realistic and accurate representation of these factors.
2. Risk Management: Trading around holidays can be riskier due to thinner liquidity and greater volatility. By integrating holiday data, traders can better manage their risk exposure.
3. Backtesting Accuracy: For backtesting to be effective, it must simulate the actual market conditions as closely as possible. Incorporating holidays and DLS adjustments contributes to more reliable and realistic backtesting results.
4. Global Trading: For traders active in multiple global markets, this library provides an easy way to handle different holiday schedules and DLS shifts across regions.
The Holiday Library is a versatile tool that enhances the precision and realism of trading simulations and strategy development. Its integration into the trading workflow is straightforward and beneficial for both novice and experienced traders.
EasterAlgo(_year)
Calculates the date of Easter Sunday for a given year using the Anonymous Gregorian algorithm.
`Gauss Algorithm for Easter Sunday` was developed by the mathematician Carl Friedrich Gauss
This algorithm is based on the cycles of the moon and the fact that Easter always falls on the first Sunday after the first ecclesiastical full moon that occurs on or after March 21.
While it's not considered to be 100% accurate due to rare exceptions, it does give the correct date in most cases.
It's important to note that Gauss's formula has been found to be inaccurate for some 21st-century years in the Gregorian calendar. Specifically, the next suggested failure years are 2038, 2051.
This function can be used for Good Friday (Friday before Easter), Easter Sunday, and Easter Monday (following Monday).
en.wikipedia.org/wiki/Date_of_Easter
Parameters:
_year (int): `int` - The year for which to calculate the date of Easter Sunday. This should be a four-digit year (YYYY).
Returns: tuple - The month (1-12) and day (1-31) of Easter Sunday for the given year.
easterInit()
Inits the date of Easter Sunday and Good Friday for a given year.
Returns: tuple - The month (1-12) and day (1-31) of Easter Sunday and Good Friday for the given year.
isLeapYear(_year)
Determine if a year is a leap year.
Parameters:
_year (int): `int` - 4 digit year to check => YYYY
Returns: `bool` - true if input year is a leap year
method timezoneHelper(utc)
Helper function to convert UTC time.
Namespace types: series int, simple int, input int, const int
Parameters:
utc (int): `int` - UTC time shift in hours.
Returns: `string`- UTC time string with shift applied.
weekofmonth()
Function to find the week of the month of a given Unix Time.
Returns: number - The week of the month of the specified UTC time.
dayLightSavingsAdjustedUTC(utc, adjustForDLS)
dayLightSavingsAdjustedUTC
Parameters:
utc (int): `int` - The normal UTC timestamp to be used for reference.
adjustForDLS (bool): `bool` - Flag indicating whether to adjust for daylight savings time (DLS).
Returns: `int` - The adjusted UTC timestamp for the given normal UTC timestamp.
getDayOfYear(monthOfYear, dayOfMonth, weekOfMonth, dayOfWeek, lastOccurrenceInMonth, holiday)
Function gets the day of the year of a given holiday (1-366)
Parameters:
monthOfYear (int)
dayOfMonth (int)
weekOfMonth (int)
dayOfWeek (int)
lastOccurrenceInMonth (bool)
holiday (string)
Returns: `int` - The day of the year of the holiday 1-366.
method buildMap(holidayMap, holiday, monthOfYear, weekOfMonth, dayOfWeek, dayOfMonth, lastOccurrenceInMonth, closingTime)
Function to build the `holidaysMap`.
Namespace types: map<string, HolidayMetaData>
Parameters:
holidayMap (map<string, HolidayMetaData>): `map<string, HolidayMetaData>` - The map of holidays.
holiday (string): `string` - The name of the holiday.
monthOfYear (int): `int` - The month of the year of the holiday.
weekOfMonth (int): `int` - The week of the month of the holiday.
dayOfWeek (int): `int` - The day of the week of the holiday.
dayOfMonth (int): `int` - The day of the month of the holiday.
lastOccurrenceInMonth (bool): `bool` - Flag indicating whether the holiday is the last occurrence of the day in the month.
closingTime (int): `int` - The closing time of the holiday.
Returns: `map<string, HolidayMetaData>` - The updated map of holidays
holidayInit(addHolidaysArray, removeHolidaysArray, defaultHolidays)
Initializes a HolidayStorage object with predefined US holidays.
Parameters:
addHolidaysArray (array<HolidayMetaData>): `array<HolidayMetaData>` - The array of additional holidays to be added.
removeHolidaysArray (array<string>): `array<string>` - The array of holidays to be removed.
defaultHolidays (bool): `bool` - Flag indicating whether to include the default holidays.
Returns: `map<string, HolidayMetaData>` - The map of holidays.
Holidays(utc, addHolidaysArray, removeHolidaysArray, adjustForDLS, displayLabel, defaultHolidays)
Main function to build the holidays object, this is the only function from this library that should be needed. \
all functionality should be available through this function. \
With the exception of initializing a `HolidayMetaData` object to add a holiday or early close. \
\
**Default Holidays:** \
`DLS begin`, `DLS end`, `New Year's Day`, `MLK Jr. Day`, \
`Washington Day`, `Memorial Day`, `Independence Day`, `Labor Day`, \
`Columbus Day`, `Veterans Day`, `Thanksgiving Day`, `Christmas Day` \
\
**Example**
```
HolidayMetaData valentinesDay = HolidayMetaData.new(holiday="Valentine's Day", monthOfYear=2, dayOfMonth=14)
HolidayMetaData stPatricksDay = HolidayMetaData.new(holiday="St. Patrick's Day", monthOfYear=3, dayOfMonth=17)
HolidayMetaData addHolidaysArray = array.from(valentinesDay, stPatricksDay)
string removeHolidaysArray = array.from("DLS begin", "DLS end")
܂Holidays = Holidays(
܂ utc=-6,
܂ addHolidaysArray=addHolidaysArray,
܂ removeHolidaysArray=removeHolidaysArray,
܂ adjustForDLS=true,
܂ displayLabel=true,
܂ defaultHolidays=true,
܂ )
plot(Holidays.newHoliday ? open : na, title="newHoliday", color=color.red, linewidth=4, style=plot.style_circles)
```
Parameters:
utc (int): `int` - The UTC time shift in hours
addHolidaysArray (array<HolidayMetaData>): `array<HolidayMetaData>` - The array of additional holidays to be added
removeHolidaysArray (array<string>): `array<string>` - The array of holidays to be removed
adjustForDLS (bool): `bool` - Flag indicating whether to adjust for daylight savings time (DLS)
displayLabel (bool): `bool` - Flag indicating whether to display a label on the chart
defaultHolidays (bool): `bool` - Flag indicating whether to include the default holidays
Returns: `HolidayObject` - The holidays object | Holidays = (holidaysMap: map<string, HolidayMetaData>, newHoliday: bool, holiday: string, dayString: string)
HolidayMetaData
HolidayMetaData
Fields:
holiday (series string): `string` - The name of the holiday.
dayOfYear (series int): `int` - The day of the year of the holiday.
monthOfYear (series int): `int` - The month of the year of the holiday.
dayOfMonth (series int): `int` - The day of the month of the holiday.
weekOfMonth (series int): `int` - The week of the month of the holiday.
dayOfWeek (series int): `int` - The day of the week of the holiday.
lastOccurrenceInMonth (series bool)
closingTime (series int): `int` - The closing time of the holiday.
utc (series int): `int` - The UTC time shift in hours.
HolidayObject
HolidayObject
Fields:
holidaysMap (map<string, HolidayMetaData>): `map<string, HolidayMetaData>` - The map of holidays.
newHoliday (series bool): `bool` - Flag indicating whether today is a new holiday.
activeHoliday (series bool): `bool` - Flag indicating whether today is an active holiday.
holiday (series string): `string` - The name of the holiday.
dayString (series string): `string` - The day of the week of the holiday.
- Full Control over Holidays and Daylight Savings Time (DLS)
The Holiday Library is an essential tool for traders and analysts who engage in backtesting and live trading. This comprehensive library enables the incorporation of crucial calendar elements - specifically Daylight Savings Time (DLS) adjustments and public holidays - into trading strategies and backtesting environments.
Key Features:
- DLS Adjustments: The library takes into account the shifts in time due to Daylight Savings. This feature is particularly vital for backtesting strategies, as DLS can impact trading hours, which in turn affects the volatility and liquidity in the market. Accurate DLS adjustments ensure that backtesting scenarios are as close to real-life conditions as possible.
- Comprehensive Holiday Metadata: The library includes a rich set of holiday metadata, allowing for the detailed scheduling of trading activities around public holidays. This feature is crucial for avoiding skewed results in backtesting, where holiday trading sessions might differ significantly in terms of volume and price movement.
- Customizable Holiday Schedules: Users can add or remove specific holidays, tailoring the library to fit various regional market schedules or specific trading requirements.
- Visualization Aids: The library supports on-chart labels, making it visually intuitive to identify holidays and DLS shifts directly on trading charts.
Use Cases:
1. Strategy Development: When developing trading strategies, it’s important to account for non-trading days and altered trading hours due to holidays and DLS. This library enables a realistic and accurate representation of these factors.
2. Risk Management: Trading around holidays can be riskier due to thinner liquidity and greater volatility. By integrating holiday data, traders can better manage their risk exposure.
3. Backtesting Accuracy: For backtesting to be effective, it must simulate the actual market conditions as closely as possible. Incorporating holidays and DLS adjustments contributes to more reliable and realistic backtesting results.
4. Global Trading: For traders active in multiple global markets, this library provides an easy way to handle different holiday schedules and DLS shifts across regions.
The Holiday Library is a versatile tool that enhances the precision and realism of trading simulations and strategy development. Its integration into the trading workflow is straightforward and beneficial for both novice and experienced traders.
EasterAlgo(_year)
Calculates the date of Easter Sunday for a given year using the Anonymous Gregorian algorithm.
`Gauss Algorithm for Easter Sunday` was developed by the mathematician Carl Friedrich Gauss
This algorithm is based on the cycles of the moon and the fact that Easter always falls on the first Sunday after the first ecclesiastical full moon that occurs on or after March 21.
While it's not considered to be 100% accurate due to rare exceptions, it does give the correct date in most cases.
It's important to note that Gauss's formula has been found to be inaccurate for some 21st-century years in the Gregorian calendar. Specifically, the next suggested failure years are 2038, 2051.
This function can be used for Good Friday (Friday before Easter), Easter Sunday, and Easter Monday (following Monday).
en.wikipedia.org/wiki/Date_of_Easter
Parameters:
_year (int): `int` - The year for which to calculate the date of Easter Sunday. This should be a four-digit year (YYYY).
Returns: tuple - The month (1-12) and day (1-31) of Easter Sunday for the given year.
easterInit()
Inits the date of Easter Sunday and Good Friday for a given year.
Returns: tuple - The month (1-12) and day (1-31) of Easter Sunday and Good Friday for the given year.
isLeapYear(_year)
Determine if a year is a leap year.
Parameters:
_year (int): `int` - 4 digit year to check => YYYY
Returns: `bool` - true if input year is a leap year
method timezoneHelper(utc)
Helper function to convert UTC time.
Namespace types: series int, simple int, input int, const int
Parameters:
utc (int): `int` - UTC time shift in hours.
Returns: `string`- UTC time string with shift applied.
weekofmonth()
Function to find the week of the month of a given Unix Time.
Returns: number - The week of the month of the specified UTC time.
dayLightSavingsAdjustedUTC(utc, adjustForDLS)
dayLightSavingsAdjustedUTC
Parameters:
utc (int): `int` - The normal UTC timestamp to be used for reference.
adjustForDLS (bool): `bool` - Flag indicating whether to adjust for daylight savings time (DLS).
Returns: `int` - The adjusted UTC timestamp for the given normal UTC timestamp.
getDayOfYear(monthOfYear, dayOfMonth, weekOfMonth, dayOfWeek, lastOccurrenceInMonth, holiday)
Function gets the day of the year of a given holiday (1-366)
Parameters:
monthOfYear (int)
dayOfMonth (int)
weekOfMonth (int)
dayOfWeek (int)
lastOccurrenceInMonth (bool)
holiday (string)
Returns: `int` - The day of the year of the holiday 1-366.
method buildMap(holidayMap, holiday, monthOfYear, weekOfMonth, dayOfWeek, dayOfMonth, lastOccurrenceInMonth, closingTime)
Function to build the `holidaysMap`.
Namespace types: map<string, HolidayMetaData>
Parameters:
holidayMap (map<string, HolidayMetaData>): `map<string, HolidayMetaData>` - The map of holidays.
holiday (string): `string` - The name of the holiday.
monthOfYear (int): `int` - The month of the year of the holiday.
weekOfMonth (int): `int` - The week of the month of the holiday.
dayOfWeek (int): `int` - The day of the week of the holiday.
dayOfMonth (int): `int` - The day of the month of the holiday.
lastOccurrenceInMonth (bool): `bool` - Flag indicating whether the holiday is the last occurrence of the day in the month.
closingTime (int): `int` - The closing time of the holiday.
Returns: `map<string, HolidayMetaData>` - The updated map of holidays
holidayInit(addHolidaysArray, removeHolidaysArray, defaultHolidays)
Initializes a HolidayStorage object with predefined US holidays.
Parameters:
addHolidaysArray (array<HolidayMetaData>): `array<HolidayMetaData>` - The array of additional holidays to be added.
removeHolidaysArray (array<string>): `array<string>` - The array of holidays to be removed.
defaultHolidays (bool): `bool` - Flag indicating whether to include the default holidays.
Returns: `map<string, HolidayMetaData>` - The map of holidays.
Holidays(utc, addHolidaysArray, removeHolidaysArray, adjustForDLS, displayLabel, defaultHolidays)
Main function to build the holidays object, this is the only function from this library that should be needed. \
all functionality should be available through this function. \
With the exception of initializing a `HolidayMetaData` object to add a holiday or early close. \
\
**Default Holidays:** \
`DLS begin`, `DLS end`, `New Year's Day`, `MLK Jr. Day`, \
`Washington Day`, `Memorial Day`, `Independence Day`, `Labor Day`, \
`Columbus Day`, `Veterans Day`, `Thanksgiving Day`, `Christmas Day` \
\
**Example**
```
HolidayMetaData valentinesDay = HolidayMetaData.new(holiday="Valentine's Day", monthOfYear=2, dayOfMonth=14)
HolidayMetaData stPatricksDay = HolidayMetaData.new(holiday="St. Patrick's Day", monthOfYear=3, dayOfMonth=17)
HolidayMetaData addHolidaysArray = array.from(valentinesDay, stPatricksDay)
string removeHolidaysArray = array.from("DLS begin", "DLS end")
܂Holidays = Holidays(
܂ utc=-6,
܂ addHolidaysArray=addHolidaysArray,
܂ removeHolidaysArray=removeHolidaysArray,
܂ adjustForDLS=true,
܂ displayLabel=true,
܂ defaultHolidays=true,
܂ )
plot(Holidays.newHoliday ? open : na, title="newHoliday", color=color.red, linewidth=4, style=plot.style_circles)
```
Parameters:
utc (int): `int` - The UTC time shift in hours
addHolidaysArray (array<HolidayMetaData>): `array<HolidayMetaData>` - The array of additional holidays to be added
removeHolidaysArray (array<string>): `array<string>` - The array of holidays to be removed
adjustForDLS (bool): `bool` - Flag indicating whether to adjust for daylight savings time (DLS)
displayLabel (bool): `bool` - Flag indicating whether to display a label on the chart
defaultHolidays (bool): `bool` - Flag indicating whether to include the default holidays
Returns: `HolidayObject` - The holidays object | Holidays = (holidaysMap: map<string, HolidayMetaData>, newHoliday: bool, holiday: string, dayString: string)
HolidayMetaData
HolidayMetaData
Fields:
holiday (series string): `string` - The name of the holiday.
dayOfYear (series int): `int` - The day of the year of the holiday.
monthOfYear (series int): `int` - The month of the year of the holiday.
dayOfMonth (series int): `int` - The day of the month of the holiday.
weekOfMonth (series int): `int` - The week of the month of the holiday.
dayOfWeek (series int): `int` - The day of the week of the holiday.
lastOccurrenceInMonth (series bool)
closingTime (series int): `int` - The closing time of the holiday.
utc (series int): `int` - The UTC time shift in hours.
HolidayObject
HolidayObject
Fields:
holidaysMap (map<string, HolidayMetaData>): `map<string, HolidayMetaData>` - The map of holidays.
newHoliday (series bool): `bool` - Flag indicating whether today is a new holiday.
activeHoliday (series bool): `bool` - Flag indicating whether today is an active holiday.
holiday (series string): `string` - The name of the holiday.
dayString (series string): `string` - The day of the week of the holiday.
Release Notes:
v2
Changed the getDayOfYear function to exit early if not adjusting for DLS
Fixed a couple of the docstrings
Removed a couple unneeded properties and parameters
Changed a couple functions to methods
Users should still only need to use the Holidays function or Init a HolidayMetaData object if adding holidays.
Updated:
getDayOfYear(monthOfYear, dayOfMonth, weekOfMonth, dayOfWeek, lastOccurrenceInMonth, holiday)
Function gets the day of the year of a given holiday (1-366)
Parameters:
monthOfYear (int): `int` - The month of the year of the holiday.
dayOfMonth (int): `int` - The day of the month of the holiday.
weekOfMonth (int): `int` - The week of the month of the holiday.
dayOfWeek (int): `int` - The day of the week of the holiday.
lastOccurrenceInMonth (bool): `bool` - Flag indicating whether the holiday is the last occurrence of the day in the month.
holiday (string): `string` - The name of the holiday.
Returns: `int` - The day of the year of the holiday 1-366.
method buildMap(holidayMap, holiday, monthOfYear, weekOfMonth, dayOfWeek, dayOfMonth, lastOccurrenceInMonth)
Function to build the `holidaysMap`.
Namespace types: map
Parameters:
holidayMap (map): `map` - The map of holidays.
holiday (string): `string` - The name of the holiday.
monthOfYear (int): `int` - The month of the year of the holiday.
weekOfMonth (int): `int` - The week of the month of the holiday.
dayOfWeek (int): `int` - The day of the week of the holiday.
dayOfMonth (int): `int` - The day of the month of the holiday.
lastOccurrenceInMonth (bool): `bool` - Flag indicating whether the holiday is the last occurrence of the day in the month.
Returns: `map` - The updated map of holidays
HolidayMetaData
HolidayMetaData
Fields:
holiday (series string): `string` - The name of the holiday.
dayOfYear (series int): `int` - The day of the year of the holiday.
monthOfYear (series int): `int` - The month of the year of the holiday.
dayOfMonth (series int): `int` - The day of the month of the holiday.
weekOfMonth (series int): `int` - The week of the month of the holiday.
dayOfWeek (series int): `int` - The day of the week of the holiday.
lastOccurrenceInMonth (series bool)
Changed the getDayOfYear function to exit early if not adjusting for DLS
Fixed a couple of the docstrings
Removed a couple unneeded properties and parameters
Changed a couple functions to methods
Users should still only need to use the Holidays function or Init a HolidayMetaData object if adding holidays.
Updated:
getDayOfYear(monthOfYear, dayOfMonth, weekOfMonth, dayOfWeek, lastOccurrenceInMonth, holiday)
Function gets the day of the year of a given holiday (1-366)
Parameters:
monthOfYear (int): `int` - The month of the year of the holiday.
dayOfMonth (int): `int` - The day of the month of the holiday.
weekOfMonth (int): `int` - The week of the month of the holiday.
dayOfWeek (int): `int` - The day of the week of the holiday.
lastOccurrenceInMonth (bool): `bool` - Flag indicating whether the holiday is the last occurrence of the day in the month.
holiday (string): `string` - The name of the holiday.
Returns: `int` - The day of the year of the holiday 1-366.
method buildMap(holidayMap, holiday, monthOfYear, weekOfMonth, dayOfWeek, dayOfMonth, lastOccurrenceInMonth)
Function to build the `holidaysMap`.
Namespace types: map
Parameters:
holidayMap (map): `map` - The map of holidays.
holiday (string): `string` - The name of the holiday.
monthOfYear (int): `int` - The month of the year of the holiday.
weekOfMonth (int): `int` - The week of the month of the holiday.
dayOfWeek (int): `int` - The day of the week of the holiday.
dayOfMonth (int): `int` - The day of the month of the holiday.
lastOccurrenceInMonth (bool): `bool` - Flag indicating whether the holiday is the last occurrence of the day in the month.
Returns: `map` - The updated map of holidays
HolidayMetaData
HolidayMetaData
Fields:
holiday (series string): `string` - The name of the holiday.
dayOfYear (series int): `int` - The day of the year of the holiday.
monthOfYear (series int): `int` - The month of the year of the holiday.
dayOfMonth (series int): `int` - The day of the month of the holiday.
weekOfMonth (series int): `int` - The week of the month of the holiday.
dayOfWeek (series int): `int` - The day of the week of the holiday.
lastOccurrenceInMonth (series bool)