Struct RangeBarProcessor

Source

pub struct RangeBarProcessor { /* private fields */ }

Expand description

Range bar processor with non-lookahead bias guarantee

Implementations§

Source §

impl RangeBarProcessor

Source

pub fn new(threshold_decimal_bps: u32) -> Result<Self, ProcessingError>

Create new processor with given threshold

§Arguments

threshold_decimal_bps - Threshold in decimal basis points
- Example: 250 → 25bps = 0.25%
- Example: 10 → 1bps = 0.01%
- Minimum: 1 → 0.1bps = 0.001%

§Breaking Change (v3.0.0)

Prior to v3.0.0, threshold_decimal_bps was in 1bps units. Migration: Multiply all threshold values by 10.

Source

pub fn process_single_trade( &mut self, trade: AggTrade, ) -> Result<Option<RangeBar>, ProcessingError>

Process a single trade and return completed bar if any

Maintains internal state for streaming use case. State persists across calls until a bar completes (threshold breach), enabling get_incomplete_bar().

§Arguments

trade - Single aggregated trade to process

§Returns

Some(RangeBar) if a bar was completed, None otherwise

§State Management

First trade: Initializes new bar state
Subsequent trades: Updates existing bar or closes on breach
Breach: Returns completed bar, starts new bar with breaching trade

Source

pub fn get_incomplete_bar(&self) -> Option<RangeBar>

Get any incomplete bar currently being processed

Returns clone of current bar state for inspection without consuming it. Useful for final bar at stream end or progress monitoring.

§Returns

Some(RangeBar) if bar is in progress, None if no active bar

Source

pub fn process_agg_trade_records_with_incomplete( &mut self, agg_trade_records: &[AggTrade], ) -> Result<Vec<RangeBar>, ProcessingError>

Process AggTrade records into range bars including incomplete bars for analysis

§Arguments

agg_trade_records - Slice of AggTrade records sorted by (timestamp, agg_trade_id)

§Returns

Vector of range bars including incomplete bars at end of data

§Warning

This method is for analysis purposes only. Incomplete bars violate the fundamental range bar algorithm and should not be used for production trading.

Source

pub fn process_agg_trade_records( &mut self, agg_trade_records: &[AggTrade], ) -> Result<Vec<RangeBar>, ProcessingError>

Process Binance aggregated trade records into range bars

This is the primary method for converting AggTrade records (which aggregate multiple individual trades) into range bars based on price movement thresholds.

§Parameters

agg_trade_records - Slice of AggTrade records sorted by (timestamp, agg_trade_id) Each record represents multiple individual trades aggregated at same price

§Returns

Vector of completed range bars (ONLY bars that breached thresholds). Each bar tracks both individual trade count and AggTrade record count.

Source

pub fn process_agg_trade_records_with_options( &mut self, agg_trade_records: &[AggTrade], include_incomplete: bool, ) -> Result<Vec<RangeBar>, ProcessingError>

Process AggTrade records with options for including incomplete bars

Batch processing mode: Clears any existing state before processing. Use process_single_trade() for stateful streaming instead.

§Parameters

agg_trade_records - Slice of AggTrade records sorted by (timestamp, agg_trade_id)
include_incomplete - Whether to include incomplete bars at end of processing

§Returns

Vector of range bars (completed + incomplete if requested)

Source

pub fn create_checkpoint(&self, symbol: &str) -> Checkpoint

Create checkpoint for cross-file continuation

Captures current processing state for seamless continuation:

Incomplete bar (if any) with FIXED thresholds
Position tracking (timestamp, trade_id if available)
Price hash for verification

§Arguments

symbol - Symbol being processed (e.g., “BTCUSDT”, “EURUSD”)

§Example

let bars = processor.process_agg_trade_records(&trades)?;
let checkpoint = processor.create_checkpoint("BTCUSDT");
let json = serde_json::to_string(&checkpoint)?;
std::fs::write("checkpoint.json", json)?;

Source

pub fn from_checkpoint(checkpoint: Checkpoint) -> Result<Self, CheckpointError>

Resume processing from checkpoint

Restores incomplete bar state with IMMUTABLE thresholds. Next trade continues building the bar until threshold breach.

§Errors

CheckpointError::MissingThresholds - Checkpoint has bar but no thresholds

§Example

let json = std::fs::read_to_string("checkpoint.json")?;
let checkpoint: Checkpoint = serde_json::from_str(&json)?;
let mut processor = RangeBarProcessor::from_checkpoint(checkpoint)?;
let bars = processor.process_agg_trade_records(&next_file_trades)?;

Source

pub fn verify_position(&self, first_trade: &AggTrade) -> PositionVerification

Verify we’re at the right position in the data stream

Call with first trade of new file to verify continuity. Returns verification result indicating if there’s a gap or exact match.

§Arguments

first_trade - First trade of the new file/chunk

§Example

let processor = RangeBarProcessor::from_checkpoint(checkpoint)?;
let verification = processor.verify_position(&next_file_trades[0]);
match verification {
    PositionVerification::Exact => println!("Perfect continuation!"),
    PositionVerification::Gap { missing_count, .. } => {
        println!("Warning: {} trades missing", missing_count);
    }
    PositionVerification::TimestampOnly { gap_ms } => {
        println!("Exness data: {}ms gap", gap_ms);
    }
}