chrono_utils

2023年11月19日

Library "chrono_utils"
📝 Description
Collection of objects and common functions that are related to datetime windows session days and time ranges. The main purpose of this library is to handle time-related functionality and make it easy to reason about a future bar checking if it will be part of a predefined session and/or inside a datetime window. All existing session functionality I found in the documentation e.g. "not na(time(timeframe, session, timezone))" are not suitable for strategy scripts, since the execution of the orders is delayed by one bar, due to the script execution happening at the bar close. Moreover, a history operator with a negative value that looks forward is not allowed in any pinescript expression. So, a prediction for the next bar using the bars_back argument of "time()"" and "time_close()" was necessary. Thus, I created this library to overcome this small but very important limitation. In the meantime, I added useful functionality to handle session-based behavior. An interesting utility that emerged from this development is data anomaly detection where a comparison between the prediction and the actual value is happening. If those two values are different then a data inconsistency happens between the prediction bar and the actual bar (probably due to a holiday, half session day, a timezone change etc..)

🤔 How to Guide
To use the functionality this library provides in your script you have to import it first!
Copy the import statement of the latest release by pressing the copy button below and then paste it into your script. Give a short name to this library so you can refer to it later on. The import statement should look like this:

import jason5480/chrono_utils/2 as chr

To check if a future bar will be inside a window first of all you have to initialize a DateTimeWindow object.
A code example is the following:

var dateTimeWindow = chr.DateTimeWindow.new().init(fromDateTime = timestamp('01 Jan 2023 00:00'), toDateTime = timestamp('01 Jan 2024 00:00'))

Then you have to "ask" the dateTimeWindow if the future bar defined by an offset (default is 1 that corresponds th the next bar), will be inside that window:

// Filter bars outside of the datetime window
bool dateFilterApproval = dateTimeWindow.is_bar_included()

You can visualize the result by drawing the background of the bars that are outside the given window:

bgcolor(color = dateFilterApproval ? na : color.new(color.fuchsia, 90), offset = 1, title = 'Datetime Window Filter')

In the same way, you can "ask" the Session if the future bar defined by an offset it will be inside that session.
First of all, you should initialize a Session object.
A code example is the following:

var sess = chr.Session.new().from_sess_string(sess = '0800-1700:23456', refTimezone = 'UTC')

Then check if the given bar defined by the offset (default is 1 that corresponds th the next bar), will be inside the session like that:

// Filter bars outside the sessions
bool sessionFilterApproval = view.sess.is_bar_included()

You can visualize the result by drawing the background of the bars that are outside the given session:

bgcolor(color = sessionFilterApproval ? na : color.new(color.red, 90), offset = 1, title = 'Session Filter')

In case you want to visualize multiple session ranges you can create a SessionView object like that:

var view = SessionView.new().init(SessionDays.new().from_sess_string('2345'), array.from(SessionTimeRange.new().from_sess_string('0800-1600'), SessionTimeRange.new().from_sess_string('1300-2200')), array.from('London', 'New York'), array.from(color.blue, color.orange))

and then call the draw method of the SessionView object like that:

view.draw()

🏋️‍♂️ Please refer to the "EXAMPLE DATETIME WINDOW FILTER" and "EXAMPLE SESSION FILTER" regions of the script for more advanced code examples of how to utilize the full potential of this library, including user input settings and advanced visualization!

⚠️ Caveats
As I mentioned in the description there are some cases that the prediction of the next bar is not accurate. A wrong prediction will affect the outcome of the filtering. The main reasons this could happen are the following:
Public holidays when the market is closed
Half trading days usually before public holidays
Change in the daylight saving time (DST)
A data anomaly of the chart, where there are missing and/or inconsistent data.
A bug in this library (Please report by PM sending the symbol, timeframe, and settings)


Special thanks to robbatt and skinra for the constructive feedback 🏆. Without them, the exposed API of this library would be very lengthy and complicated to use. Thanks to them, now the user of this library will be able to get the most, with only a few lines of code!

2024年5月8日

發行說明

v3

• I exported the drawing functionality of the library, after a request from ranalog, which means you can use the draw() method of the `SessionView` UDT in your script! However, my drawing implementation should not limit your imagination on how you can visualize the sessions. Please remember that this implementation adds computational cost since it has to compute (internally) the highest high and lowest low of the session range to draw the boxes.
  
• I circumvent a limitation (bug) in the build-in time() function that returns wrong results when you are passing sessions whose sum exceeds 24 hours, by checking each time range separately. This affected only the data anomaly detection functionality, not the filtering functionality itself.
  

Added:
method to_sess_strings(this)
  to_sess_strings - Formats the session into an array of session strings
  Namespace types: Session
  Parameters:
    this (Session): - The session object with the day and the time range selection
  Returns: - The array of strings of the sessions

method draw(this)
  draw - Draw the sessions into the chart using boxes
  Namespace types: SessionView
  Parameters:
    this (SessionView): - The session view object with the day and the time range selection

2024年9月8日

發行說明

v4

• Update documentation
  
• Use force_overlay for the drawings in the example
  

2024年9月14日

發行說明

v5

Use enum for timezones for easier input

Updated:
exTimezone(timezone)
  Convert extended timezone to timezone string
  Parameters:
    timezone (simple Timezone): The timezone or a special string
  Returns: string representing the timezone

2024年9月17日

發行說明

v6

• Minor adjustment in the settings menu indentation
  

1月3日

發行說明

v7

• Update to pinescript version 6
  
• Improve leap years calculations (thanks dyrtybit)
  

Added:
monthInDays(mon, yer, rolloverMonths)
  Calculate the days of each month of the year
  Parameters:
    mon (int): The month of reference to get the days
    yer (int): The year of reference to check if it is a leap year
    rolloverMonths (bool): Policy on how to handle months that are out of [1, 12] range
  Returns: The number of days of the month with leap year accuracy

Updated:
normalize(num, min, max)
  Check if number is in the range of [min, max]
  Parameters:
    num (int)
    min (int)
    max (int)
  Returns: The normalized number