real_time_candles

16 mar

Introduction
The Real-Time Candles Library provides comprehensive tools for creating, manipulating, and visualizing custom timeframe candles in Pine Script. Unlike standard indicators that only update at bar close, this library enables real-time visualization of price action and indicators within the current bar, offering traders unprecedented insight into market dynamics as they unfold.

This library addresses a fundamental limitation in traditional technical analysis: the inability to see how indicators evolve between bar closes. By implementing sophisticated real-time data processing techniques, traders can now observe indicator movements, divergences, and trend changes as they develop, potentially identifying trading opportunities much earlier than with conventional approaches.

Key Features
The library supports two primary candle generation approaches:

1. Chart-Time Candles: Generate real-time OHLC data for any variable (like RSI, MACD, etc.) while maintaining synchronization with chart bars.
   
2. Custom Timeframe (CTF) Candles: Create candles with custom time intervals or tick counts completely independent of the chart's native timeframe.
   

Both approaches support traditional candlestick and Heikin-Ashi visualization styles, with options for moving average overlays to smooth the data.

Configuration Requirements
For optimal performance with this library:

• Set max_bars_back = 5000 in your script settings
  
• When using CTF drawing functions, set max_lines_count = 500, max_boxes_count = 500, and max_labels_count = 500
  

These settings ensure that you will be able to draw correctly and will avoid any runtime errors.

Usage Examples
Basic Chart-Time Candle Visualization

// Create real-time candles for RSI
float rsi = ta.rsi(close, 14)
Candle rsi_candle = candle_series(rsi, CandleType.candlestick)

// Plot the candles using Pine's built-in function
plotcandle(rsi_candle.Open, rsi_candle.High, rsi_candle.Low, rsi_candle.Close, 
          "RSI Candles", rsi_candle.candle_color, rsi_candle.candle_color)

Multiple Access Patterns
The library provides three ways to access candle data, accommodating different programming styles:

// 1. Array-based access for collection operations
Candle[] candles = candle_array(source)

// 2. Object-oriented access for single entity manipulation
Candle candle = candle_series(source)
float value = candle.source(Source.HLC3)

// 3. Tuple-based access for functional programming styles
[open, high, low, close] = candle_tuple(source)

Custom Timeframe Examples

// Create 20-second candles with EMA overlay
plot_ctf_candles(
    source = close,
    candle_type = CandleType.candlestick,
    sample_type = SampleType.Time,
    number_of_seconds = 20,
    timezone = -5,
    tied_open = true,
    ema_period = 9,
    enable_ema = true
)

// Create tick-based candles (new candle every 15 ticks)
plot_ctf_tick_candles(
    source = close,
    candle_type = CandleType.heikin_ashi,
    number_of_ticks = 15,
    timezone = -5,
    tied_open = true
)

Advanced Usage with Custom Visualization

// Get custom timeframe candles without automatic plotting
CandleCTF[] my_candles = ctf_candles_array(
    source = close,
    candle_type = CandleType.candlestick,
    sample_type = SampleType.Time,
    number_of_seconds = 30
)

// Apply custom logic to the candles
float[] ema_values = my_candles.ctf_ema(14)

// Draw candles and EMA using time-based coordinates
my_candles.draw_ctf_candles_time()
ema_values.draw_ctf_line_time(line_color = #FF6D00)

Library Components

Data Types

• Candle: Structure representing chart-time candles with OHLC, polarity, and visualization properties
  
• CandleCTF: Extended candle structure with additional time metadata for custom timeframes
  
• TickData: Structure for individual price updates with time deltas
  

Enumerations

• CandleType: Specifies visualization style (candlestick or Heikin-Ashi)
  
• Source: Defines price components for calculations (Open, High, Low, Close, HL2, etc.)
  
• SampleType: Sets sampling method (Time-based or Tick-based)
  

Core Functions

• get_tick(): Captures current price as a tick data point
  
• candle_array(): Creates an array of candles from price updates
  
• candle_series(): Provides a single candle based on latest data
  
• candle_tuple(): Returns OHLC values as a tuple
  
• ctf_candles_array(): Creates custom timeframe candles without rendering
  

Visualization Functions

• source(): Extracts specific price components from candles
  
• candle_ctf_to_float(): Converts candle data to float arrays
  
• ctf_ema(): Calculates exponential moving averages for candle arrays
  
• draw_ctf_candles_time(): Renders candles using time coordinates
  
• draw_ctf_candles_index(): Renders candles using bar index coordinates
  
• draw_ctf_line_time(): Renders lines using time coordinates
  
• draw_ctf_line_index(): Renders lines using bar index coordinates
  

Technical Implementation Notes
This library leverages Pine Script's varip variables for state management, creating a sophisticated real-time data processing system. The implementation includes:

• Efficient tick capturing: Samples price at every execution, maintaining temporal tracking with time deltas
  
• Smart state management: Uses a hybrid approach with mutable updates at index 0 and historical preservation at index 1+
  
• Temporal synchronization: Manages two time domains (chart time and custom timeframe)
  

The tooltip implementation provides crucial temporal context for custom timeframe visualizations, allowing users to understand exactly when each candle formed regardless of chart timeframe.

Limitations

• Custom timeframe candles cannot be backtested due to Pine Script's limitations with historical tick data
  
• Real-time visualization is only available during live chart updates
  
• Maximum history is constrained by Pine Script's array size limits
  

Applications

1. Indicator visualization: See how RSI, MACD, or other indicators evolve in real-time
   
2. Volume analysis: Create custom volume profiles independent of chart timeframe
   
3. Scalping strategies: Identify short-term patterns with precisely defined time windows
   
4. Volatility measurement: Track price movement characteristics within bars
   
5. Custom signal generation: Create entry/exit signals based on custom timeframe patterns
   

Conclusion
The Real-Time Candles Library bridges the gap between traditional technical analysis (based on discrete OHLC bars) and the continuous nature of market movement. By making indicators more responsive to real-time price action, it gives traders a significant edge in timing and decision-making, particularly in fast-moving markets where waiting for bar close could mean missing important opportunities.

Whether you're building custom indicators, researching price patterns, or developing trading strategies, this library provides the foundation for sophisticated real-time analysis in Pine Script.

Implementation Details & Advanced Guide

Core Implementation Concepts
The Real-Time Candles Library implements a sophisticated event-driven architecture within Pine Script's constraints. At its heart, the library creates what's essentially a reactive programming framework handling continuous data streams.

Tick Processing System
The foundation of the library is the get_tick() function, which captures price updates as they occur:

export get_tick(series float source = close, series float na_replace = na)=>
    varip float price = na
    varip int series_index = -1
    varip int old_time = 0
    varip int new_time = na
    varip float time_delta = 0
    // ...

This function:

1. Samples the current price
   
2. Calculates time elapsed since last update
   
3. Maintains a sequential index to track updates
   

The resulting TickData structure serves as the fundamental building block for all candle generation.

State Management Architecture
The library employs a sophisticated state management system using varip variables, which persist across executions within the same bar. This creates a hybrid programming paradigm that's different from standard Pine Script's bar-by-bar model.

For chart-time candles, the core state transition logic is:

// Real-time update of current candle
candle_data := Candle.new(Open, High, Low, Close, polarity, series_index, candle_color)
candles.set(0, candle_data)

// When a new bar starts, preserve the previous candle
if clear_state
    candles.insert(1, candle_data)
    price.clear()
    // Reset state for new candle
    Open := Close
    price.push(Open)
    series_index += 1

This pattern of updating index 0 in real-time while inserting completed candles at index 1 creates an elegant solution for maintaining both current state and historical data.

Custom Timeframe Implementation

The custom timeframe system manages its own time boundaries independent of chart bars:

bool clear_state = switch settings.sample_type
    SampleType.Ticks => cumulative_series_idx >= settings.number_of_ticks
    SampleType.Time => cumulative_time_delta >= settings.number_of_seconds

This dual-clock system synchronizes two time domains:

1. Pine's execution clock (bar-by-bar processing)
   
2. The custom timeframe clock (tick or time-based)
   

The library carefully handles temporal discontinuities, ensuring candle formation remains accurate despite irregular tick arrival or market gaps.

Advanced Usage Techniques

1. Creating Custom Indicators with Real-Time Candles
To develop indicators that process real-time data within the current bar:

// Get real-time candles for your data
Candle[] rsi_candles = candle_array(ta.rsi(close, 14))

// Calculate indicator values based on candle properties
float signal = ta.ema(rsi_candles.first().source(Source.Close), 9)

// Detect patterns that occur within the bar
bool divergence = close > close[1] and rsi_candles.first().Close < rsi_candles.get(1).Close

2. Working with Custom Timeframes and Plotting
For maximum flexibility when visualizing custom timeframe data:

// Create custom timeframe candles
CandleCTF[] volume_candles = ctf_candles_array(
    source = volume, 
    candle_type = CandleType.candlestick,
    sample_type = SampleType.Time,
    number_of_seconds = 60
)

// Convert specific candle properties to float arrays
float[] volume_closes = volume_candles.candle_ctf_to_float(Source.Close)

// Calculate derived values
float[] volume_ema = volume_candles.ctf_ema(14)

// Create custom visualization
volume_candles.draw_ctf_candles_time()
volume_ema.draw_ctf_line_time(line_color = color.orange)

3. Creating Hybrid Timeframe Analysis
One powerful application is comparing indicators across multiple timeframes:

// Standard chart timeframe RSI
float chart_rsi = ta.rsi(close, 14)

// Custom 5-second timeframe RSI
CandleCTF[] ctf_candles = ctf_candles_array(
    source = close,
    candle_type = CandleType.candlestick,
    sample_type = SampleType.Time,
    number_of_seconds = 5
)
float[] fast_rsi_array = ctf_candles.candle_ctf_to_float(Source.Close)
float fast_rsi = fast_rsi_array.first()

// Generate signals based on divergence between timeframes
bool entry_signal = chart_rsi < 30 and fast_rsi > fast_rsi_array.get(1)

Final Notes
This library represents an advanced implementation of real-time data processing within Pine Script's constraints. By creating a reactive programming framework for handling continuous data streams, it enables sophisticated analysis typically only available in dedicated trading platforms.

The design principles employed—including state management, temporal processing, and object-oriented architecture—can serve as patterns for other advanced Pine Script development beyond this specific application.

------------------------

Library "real_time_candles"
A comprehensive library for creating real-time candles with customizable timeframes and sampling methods.
Supports both chart-time and custom-time candles with options for candlestick and Heikin-Ashi visualization.
Allows for tick-based or time-based sampling with moving average overlay capabilities.

get_tick(source, na_replace)
  Captures the current price as a tick data point
  Parameters:
    source (float): Optional - Price source to sample (defaults to close)
    na_replace (float): Optional - Value to use when source is na
  Returns: TickData structure containing price, time since last update, and sequential index

candle_array(source, candle_type, sync_start, bullish_color, bearish_color)
  Creates an array of candles based on price updates
  Parameters:
    source (float): Optional - Price source to sample (defaults to close)
    candle_type (simple CandleType): Optional - Type of candle chart to create (candlestick or Heikin-Ashi)
    sync_start (simple bool): Optional - Whether to synchronize with the start of a new bar
    bullish_color (color): Optional - Color for bullish candles
    bearish_color (color): Optional - Color for bearish candles
  Returns: Array of Candle objects ordered with most recent at index 0

candle_series(source, candle_type, wait_for_sync, bullish_color, bearish_color)
  Provides a single candle based on the latest price data
  Parameters:
    source (float): Optional - Price source to sample (defaults to close)
    candle_type (simple CandleType): Optional - Type of candle chart to create (candlestick or Heikin-Ashi)
    wait_for_sync (simple bool): Optional - Whether to wait for a new bar before starting
    bullish_color (color): Optional - Color for bullish candles
    bearish_color (color): Optional - Color for bearish candles
  Returns: A single Candle object representing the current state

candle_tuple(source, candle_type, wait_for_sync, bullish_color, bearish_color)
  Provides candle data as a tuple of OHLC values
  Parameters:
    source (float): Optional - Price source to sample (defaults to close)
    candle_type (simple CandleType): Optional - Type of candle chart to create (candlestick or Heikin-Ashi)
    wait_for_sync (simple bool): Optional - Whether to wait for a new bar before starting
    bullish_color (color): Optional - Color for bullish candles
    bearish_color (color): Optional - Color for bearish candles
  Returns: Tuple [Open, High, Low, Close] representing current candle values

method source(self, source, na_replace)
  Extracts a specific price component from a Candle
  Namespace types: Candle
  Parameters:
    self (Candle)
    source (series Source): Type of price data to extract (Open, High, Low, Close, or composite values)
    na_replace (float): Optional - Value to use when source value is na
  Returns: The requested price value from the candle

method source(self, source)
  Extracts a specific price component from a CandleCTF
  Namespace types: CandleCTF
  Parameters:
    self (CandleCTF)
    source (simple Source): Type of price data to extract (Open, High, Low, Close, or composite values)
  Returns: The requested price value from the candle as a varip

method candle_ctf_to_float(self, source)
  Converts a specific price component from each CandleCTF to a float array
  Namespace types: array<CandleCTF>
  Parameters:
    self (array<CandleCTF>)
    source (simple Source): Optional - Type of price data to extract (defaults to Close)
  Returns: Array of float values extracted from the candles, ordered with most recent at index 0

method ctf_ema(self, ema_period)
  Calculates an Exponential Moving Average for a CandleCTF array
  Namespace types: array<CandleCTF>
  Parameters:
    self (array<CandleCTF>)
    ema_period (simple float): Period for the EMA calculation
  Returns: Array of float values representing the EMA of the candle data, ordered with most recent at index 0

method draw_ctf_candles_time(self, sample_type, number_of_ticks, number_of_seconds, timezone)
  Renders custom timeframe candles using bar time coordinates
  Namespace types: array<CandleCTF>
  Parameters:
    self (array<CandleCTF>)
    sample_type (simple SampleType): Optional - Method for sampling data (Time or Ticks), used for tooltips
    number_of_ticks (simple int): Optional - Number of ticks per candle (used when sample_type is Ticks), used for tooltips
    number_of_seconds (simple float): Optional - Time duration per candle in seconds (used when sample_type is Time), used for tooltips
    timezone (simple int): Optional - Timezone offset from UTC (-12 to +12), used for tooltips
  Returns: void - Renders candles on the chart using time-based x-coordinates

method draw_ctf_candles_index(self, sample_type, number_of_ticks, number_of_seconds, timezone)
  Renders custom timeframe candles using bar index coordinates
  Namespace types: array<CandleCTF>
  Parameters:
    self (array<CandleCTF>)
    sample_type (simple SampleType): Optional - Method for sampling data (Time or Ticks), used for tooltips
    number_of_ticks (simple int): Optional - Number of ticks per candle (used when sample_type is Ticks), used for tooltips
    number_of_seconds (simple float): Optional - Time duration per candle in seconds (used when sample_type is Time), used for tooltips
    timezone (simple int): Optional - Timezone offset from UTC (-12 to +12), used for tooltips
  Returns: void - Renders candles on the chart using index-based x-coordinates

method draw_ctf_line_time(self, source, line_size, line_color)
  Renders a line representing a price component from the candles using time coordinates
  Namespace types: array<CandleCTF>
  Parameters:
    self (array<CandleCTF>)
    source (simple Source): Optional - Type of price data to extract (defaults to Close)
    line_size (simple int): Optional - Width of the line
    line_color (simple color): Optional - Color of the line
  Returns: void - Renders a connected line on the chart using time-based x-coordinates

method draw_ctf_line_time(self, line_size, line_color)
  Renders a line from a varip float array using time coordinates
  Namespace types: array<float>
  Parameters:
    self (array<float>)
    line_size (simple int): Optional - Width of the line, defaults to 2
    line_color (simple color): Optional - Color of the line
  Returns: void - Renders a connected line on the chart using time-based x-coordinates

method draw_ctf_line_index(self, source, line_size, line_color)
  Renders a line representing a price component from the candles using index coordinates
  Namespace types: array<CandleCTF>
  Parameters:
    self (array<CandleCTF>)
    source (simple Source): Optional - Type of price data to extract (defaults to Close)
    line_size (simple int): Optional - Width of the line
    line_color (simple color): Optional - Color of the line
  Returns: void - Renders a connected line on the chart using index-based x-coordinates

method draw_ctf_line_index(self, line_size, line_color)
  Renders a line from a varip float array using index coordinates
  Namespace types: array<float>
  Parameters:
    self (array<float>)
    line_size (simple int): Optional - Width of the line, defaults to 2
    line_color (simple color): Optional - Color of the line
  Returns: void - Renders a connected line on the chart using index-based x-coordinates

plot_ctf_tick_candles(source, candle_type, number_of_ticks, timezone, tied_open, ema_period, bullish_color, bearish_color, line_width, ema_color, use_time_indexing)
  Plots tick-based candles with moving average
  Parameters:
    source (float): Input price source to sample
    candle_type (simple CandleType): Type of candle chart to display
    number_of_ticks (simple int): Number of ticks per candle
    timezone (simple int): Timezone offset from UTC (-12 to +12)
    tied_open (simple bool): Whether to tie open price to close of previous candle
    ema_period (simple float): Period for the exponential moving average
    bullish_color (color): Optional - Color for bullish candles
    bearish_color (color): Optional - Color for bearish candles
    line_width (simple int): Optional - Width of the moving average line, defaults to 2
    ema_color (color): Optional - Color of the moving average line
    use_time_indexing (simple bool): Optional - When true the function will plot with xloc.time, when false it will plot using xloc.bar_index
  Returns: void - Creates visual candle chart with EMA overlay

plot_ctf_tick_candles(source, candle_type, number_of_ticks, timezone, tied_open, bullish_color, bearish_color, use_time_indexing)
  Plots tick-based candles without moving average
  Parameters:
    source (float): Input price source to sample
    candle_type (simple CandleType): Type of candle chart to display
    number_of_ticks (simple int): Number of ticks per candle
    timezone (simple int): Timezone offset from UTC (-12 to +12)
    tied_open (simple bool): Whether to tie open price to close of previous candle
    bullish_color (color): Optional - Color for bullish candles
    bearish_color (color): Optional - Color for bearish candles
    use_time_indexing (simple bool): Optional - When true the function will plot with xloc.time, when false it will plot using xloc.bar_index
  Returns: void - Creates visual candle chart without moving average

plot_ctf_time_candles(source, candle_type, number_of_seconds, timezone, tied_open, ema_period, bullish_color, bearish_color, line_width, ema_color, use_time_indexing)
  Plots time-based candles with moving average
  Parameters:
    source (float): Input price source to sample
    candle_type (simple CandleType): Type of candle chart to display
    number_of_seconds (simple float): Time duration per candle in seconds
    timezone (simple int): Timezone offset from UTC (-12 to +12)
    tied_open (simple bool): Whether to tie open price to close of previous candle
    ema_period (simple float): Period for the exponential moving average
    bullish_color (color): Optional - Color for bullish candles
    bearish_color (color): Optional - Color for bearish candles
    line_width (simple int): Optional - Width of the moving average line, defaults to 2
    ema_color (color): Optional - Color of the moving average line
    use_time_indexing (simple bool): Optional - When true the function will plot with xloc.time, when false it will plot using xloc.bar_index
  Returns: void - Creates visual candle chart with EMA overlay

plot_ctf_time_candles(source, candle_type, number_of_seconds, timezone, tied_open, bullish_color, bearish_color, use_time_indexing)
  Plots time-based candles without moving average
  Parameters:
    source (float): Input price source to sample
    candle_type (simple CandleType): Type of candle chart to display
    number_of_seconds (simple float): Time duration per candle in seconds
    timezone (simple int): Timezone offset from UTC (-12 to +12)
    tied_open (simple bool): Whether to tie open price to close of previous candle
    bullish_color (color): Optional - Color for bullish candles
    bearish_color (color): Optional - Color for bearish candles
    use_time_indexing (simple bool): Optional - When true the function will plot with xloc.time, when false it will plot using xloc.bar_index
  Returns: void - Creates visual candle chart without moving average

plot_ctf_candles(source, candle_type, sample_type, number_of_ticks, number_of_seconds, timezone, tied_open, ema_period, bullish_color, bearish_color, enable_ema, line_width, ema_color, use_time_indexing)
  Unified function for plotting candles with comprehensive options
  Parameters:
    source (float): Input price source to sample
    candle_type (simple CandleType): Optional - Type of candle chart to display
    sample_type (simple SampleType): Optional - Method for sampling data (Time or Ticks)
    number_of_ticks (simple int): Optional - Number of ticks per candle (used when sample_type is Ticks)
    number_of_seconds (simple float): Optional - Time duration per candle in seconds (used when sample_type is Time)
    timezone (simple int): Optional - Timezone offset from UTC (-12 to +12)
    tied_open (simple bool): Optional - Whether to tie open price to close of previous candle
    ema_period (simple float): Optional - Period for the exponential moving average
    bullish_color (color): Optional - Color for bullish candles
    bearish_color (color): Optional - Color for bearish candles
    enable_ema (bool): Optional - Whether to display the EMA overlay
    line_width (simple int): Optional - Width of the moving average line, defaults to 2
    ema_color (color): Optional - Color of the moving average line
    use_time_indexing (simple bool): Optional - When true the function will plot with xloc.time, when false it will plot using xloc.bar_index
  Returns: void - Creates visual candle chart with optional EMA overlay

ctf_candles_array(source, candle_type, sample_type, number_of_ticks, number_of_seconds, tied_open, bullish_color, bearish_color)
  Creates an array of custom timeframe candles without rendering them
  Parameters:
    source (float): Input price source to sample
    candle_type (simple CandleType): Type of candle chart to create (candlestick or Heikin-Ashi)
    sample_type (simple SampleType): Method for sampling data (Time or Ticks)
    number_of_ticks (simple int): Optional - Number of ticks per candle (used when sample_type is Ticks)
    number_of_seconds (simple float): Optional - Time duration per candle in seconds (used when sample_type is Time)
    tied_open (simple bool): Optional - Whether to tie open price to close of previous candle
    bullish_color (color): Optional - Color for bullish candles
    bearish_color (color): Optional - Color for bearish candles
  Returns: Array of CandleCTF objects ordered with most recent at index 0

Candle
  Structure representing a complete candle with price data and display properties
  Fields:
    Open (series float): Opening price of the candle
    High (series float): Highest price of the candle
    Low (series float): Lowest price of the candle
    Close (series float): Closing price of the candle
    polarity (series bool): Boolean indicating if candle is bullish (true) or bearish (false)
    series_index (series int): Sequential index identifying the candle in the series
    candle_color (series color): Color to use when rendering the candle
    ready (series bool): Boolean indicating if candle data is valid and ready for use

TickData
  Structure for storing individual price updates
  Fields:
    price (series float): The price value at this tick
    time_delta (series float): Time elapsed since the previous tick in milliseconds
    series_index (series int): Sequential index identifying this tick

CandleCTF
  Structure representing a custom timeframe candle with additional time metadata
  Fields:
    Open (series float): Opening price of the candle
    High (series float): Highest price of the candle
    Low (series float): Lowest price of the candle
    Close (series float): Closing price of the candle
    polarity (series bool): Boolean indicating if candle is bullish (true) or bearish (false)
    series_index (series int): Sequential index identifying the candle in the series
    open_time (series int): Timestamp marking when the candle was opened (in Unix time)
    time_delta (series float): Duration of the candle in milliseconds
    candle_color (series color): Color to use when rendering the candle

17 mar

Note di rilascio

v2
Bug fix in time candles ctf

17 mar

Note di rilascio

v3

Bug fix with ha candles where the historical candles had na valued color. Spelling fix with CandleType enum.

19 mar

Note di rilascio

Breaking Change: candle_tuple really didnt need the color input lol. I have removed that.

v4

Updated:
candle_tuple(source, candle_type, wait_for_sync)
  Provides candle data as a tuple of OHLC values
  Parameters:
    source (float): Optional - Price source to sample (defaults to close)
    candle_type (simple CandleType): Optional - Type of candle chart to create (candlestick or Heikin-Ashi)
    wait_for_sync (simple bool): Optional - Whether to wait for a new bar before starting
  Returns: Tuple [Open, High, Low, Close] representing current candle values