chrono_utils

19. Nov. 2023

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:

Pine Script®

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:

Pine Script®

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:

Pine Script®

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

Pine Script®

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:

Pine Script®

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:

Pine Script®

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

Pine Script®

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

Pine Script®

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

Pine Script®

🏋️‍♂️ 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!

8. Mai

Versionshinweise

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

8. Sept.

Versionshinweise

v4

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

14. Sept.

Versionshinweise

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

17. Sept.

Versionshinweise

v6

• Minor adjustment in the settings menu indentation