-
Notifications
You must be signed in to change notification settings - Fork 1
Bar Formatting and Timestamp Alignment
- Introduction
- TVBar Structure and Requirements
- Timestamp Alignment by Resolution
- Time Zone and Exchange Session Handling
- Best Practices for Bar Construction
- Edge Cases and Validation
- Conclusion
This document provides comprehensive guidance on constructing TVBar objects for historical market data responses in the PyTradingView framework. It details the required structure of the TVBar class, emphasizes the critical importance of timestamp alignment based on resolution, and outlines best practices for ensuring data integrity. The document covers proper handling of time zones, exchange sessions, and edge cases such as daylight saving time transitions. It also provides recommendations for validating OHLCV data and preventing common issues that can lead to chart rendering problems.
The TVBar class serves as the fundamental data structure for representing OHLCV (Open, High, Low, Close, Volume) market data points within the PyTradingView system. Each TVBar instance encapsulates price and volume information for a specific time period, with strict requirements for data formatting and timestamp precision.
The TVBar class is defined in the TVDataStructures module and includes the following required fields:
- time: UTC timestamp in milliseconds since Unix epoch
- open: Opening price for the period
- high: Highest price reached during the period
- low: Lowest price reached during the period
- close: Closing price for the period
- volume: Trading volume (optional, can be None)
The class provides a to_dict() method that converts the bar data into a dictionary format suitable for transmission to the TradingView charting library. This standardized structure ensures compatibility with the datafeed API and proper rendering on financial charts.
classDiagram
class TVBar {
+int time
+float open
+float high
+float low
+float close
+Optional[float] volume
+__init__(time, open, high, low, close, volume)
+to_dict() dict
}
Proper timestamp alignment is critical for accurate chart rendering and technical analysis calculations. The TradingView platform requires that bar timestamps be precisely aligned to specific time boundaries based on the resolution (timeframe) of the data.
For daily bars, the timestamp must fall exactly at 00:00 UTC of the trading day, not the session start time in the local exchange timezone. This ensures consistency across different markets and prevents misalignment when comparing instruments from different exchanges.
For hourly bars, timestamps must align to the top of each hour in UTC (e.g., 01:00, 02:00, 03:00 UTC). Similarly, minute bars must align to exact minute boundaries (e.g., 09:30, 09:31, 09:32 UTC). This alignment prevents fractional time offsets that can cause rendering artifacts and incorrect bar spacing on charts.
The alignment requirements are particularly important when converting from local exchange time to UTC. For example, a market that operates from 9:30 AM to 4:00 PM in New York time (EST/EDT) must have its bars properly converted to UTC timestamps that align with the UTC hour or minute boundaries, rather than preserving the local time offsets.
Failure to properly align timestamps can result in gaps or overlaps in the chart display, incorrect indicator calculations, and synchronization issues between different data series. The system expects monotonic time progression with consistent intervals between bars based on the specified resolution.
Proper handling of time zones and exchange sessions is essential for accurate market data representation. The TVLibrarySymbolInfo class contains comprehensive information about each trading symbol, including its exchange timezone in OlsonDB format, trading sessions, and holiday schedules.
When constructing TVBar objects, it's crucial to convert local exchange times to properly aligned UTC timestamps. This conversion must account for daylight saving time transitions and non-standard trading sessions. The symbol information provides the session string that defines the regular trading hours in the exchange's local timezone.
For exchanges that observe daylight saving time, the conversion process must dynamically adjust for the time shift. This ensures that bars are correctly aligned to UTC boundaries throughout the year, regardless of whether the exchange is in standard or daylight time.
The system supports extended trading sessions through the subsessions feature, allowing for pre-market and post-market data to be properly represented. Each subsession can have its own session definition and display properties, enabling accurate representation of complex trading schedules.
When processing historical data, the system must validate that bars fall within valid trading sessions for the specific symbol and date, accounting for exchange holidays and special trading days. This validation helps prevent the inclusion of erroneous data points that could distort technical analysis.
When constructing TVBar objects for historical data responses, several best practices should be followed to ensure data quality and compatibility with the TradingView platform.
First, always validate OHLCV integrity by ensuring that high >= low and that volume >= 0. Negative volume values or inverted price ranges indicate data errors that should be corrected before transmission. Additionally, verify that open, high, low, and close prices are within reasonable bounds for the specific instrument.
Ensure monotonic time progression by sorting bars in chronological order and verifying that each subsequent bar has a timestamp greater than the previous bar. This prevents chart rendering issues and ensures proper functioning of time-based indicators.
Handle missing or incomplete bars appropriately. For periods with no trading activity, consider whether to include empty bars (if supported by the symbol configuration) or to omit them entirely. The has_empty_bars flag in the symbol information indicates whether empty bars should be generated for periods with no trading.
When converting local exchange time to UTC, use robust time zone conversion libraries that properly handle daylight saving time transitions and historical time zone changes. Avoid simple fixed-offset calculations, as they can produce incorrect results during DST transitions.
Implement proper error handling for edge cases such as:
- Market holidays and special trading sessions
- Early market closures or delayed openings
- Data gaps due to connectivity issues
- Duplicate or overlapping bars
Use the TVPeriodParams class to properly handle requests for historical data, respecting the from_, to, and countBack parameters to deliver the requested data range efficiently.
Several edge cases require special attention when constructing TVBar objects to ensure data accuracy and prevent chart rendering issues.
Daylight saving time transitions can create ambiguous or non-existent time periods. When converting from local exchange time to UTC, ensure that timestamps during the "fall back" transition (when clocks move back) are properly disambiguated, and that timestamps during the "spring forward" transition (when clocks move ahead) do not create gaps in the data series.
Non-standard trading sessions, such as shortened holiday sessions or special event trading, require careful handling. Use the session_holidays and corrections fields in the symbol information to adjust for these special cases and ensure bars are properly aligned to the actual trading periods.
Validate that the first and last bars in a series properly align with the requested time range and resolution boundaries. Misaligned boundary bars can cause rendering artifacts at the edges of the chart viewport.
Implement comprehensive validation of OHLCV data:
- Ensure high >= low for all bars
- Verify that open, high, low, and close are within valid price ranges
- Confirm volume >= 0
- Check for extreme price movements that may indicate data errors
- Validate that timestamps are monotonically increasing
When handling real-time data subscriptions through the subscribeBars method, ensure that incoming tick data is properly aggregated into correctly aligned bars before transmission to the charting library. This aggregation process must maintain the same alignment rules as historical data to prevent discontinuities when switching between historical and real-time modes.
flowchart TD
Start([Start Bar Processing]) --> ValidateInput["Validate OHLCV Values<br/>High >= Low, Volume >= 0"]
ValidateInput --> InputValid{"Valid?"}
InputValid --> |No| HandleError["Log Error<br/>Discard Invalid Bar"]
InputValid --> |Yes| ConvertTime["Convert Local Time<br/>to Aligned UTC"]
ConvertTime --> CheckAlignment["Verify Timestamp Alignment<br/>to Resolution Boundaries"]
CheckAlignment --> AlignmentValid{"Aligned?"}
AlignmentValid --> |No| CorrectTime["Adjust to Proper<br/>UTC Boundary"]
AlignmentValid --> |Yes| Proceed
CorrectTime --> Proceed
Proceed --> ValidateSequence["Check Monotonic<br/>Time Progression"]
ValidateSequence --> SequenceValid{"Sequential?"}
SequenceValid --> |No| HandleGap["Process Gap<br/>or Duplicate"]
SequenceValid --> |Yes| FinalOutput["Transmit Validated Bar"]
HandleError --> End([End])
FinalOutput --> End
HandleGap --> FinalOutput
Proper construction of TVBar objects with correctly aligned timestamps is essential for accurate financial charting and technical analysis. By following the guidelines outlined in this document, developers can ensure their market data is properly formatted and synchronized with the TradingView platform's expectations. Key considerations include strict adherence to UTC timestamp alignment based on resolution, proper handling of time zone conversions and daylight saving time transitions, validation of OHLCV integrity, and careful management of edge cases such as holiday sessions and data gaps. Implementing these best practices will result in reliable, accurate, and visually correct chart displays that provide meaningful insights to users.