QuanTAlib/lib/volume/tvi/Tvi.md

TVI: Trade Volume Index

Property	Value
Category	Volume
Inputs	OHLCV bar (TBar)
Parameters	minTick (default 0.125)
Outputs	Single series (Tvi)
Output range	Unbounded
Warmup	> 2 bars

TL;DR

• Trade Volume Index refines the relationship between price and volume by introducing a threshold filter.
• Parameterized by mintick (default 0.125).
• Output range: Unbounded.
• Requires > 2 bars of warmup before first valid output (IsHot = true).
• Validated against TA-Lib, Skender, and Tulip reference implementations where available.

"The direction of money flow matters more than the magnitude of price change." — William Blau

Trade Volume Index refines the relationship between price and volume by introducing a threshold filter. Unlike OBV which responds to any price change, TVI only changes direction when price movement exceeds a minimum tick threshold. This "sticky direction" behavior filters out noise from insignificant price fluctuations, allowing the indicator to better capture genuine accumulation and distribution.

The insight behind TVI is that small price movements within the bid-ask spread or normal market noise shouldn't flip the volume attribution. Only when buyers or sellers demonstrate enough conviction to move price beyond a meaningful threshold should the volume be credited to that side.

Historical Context

Trade Volume Index was developed by William Blau and described in his work on technical analysis. Blau was known for developing indicators that filter market noise while preserving meaningful signals. TVI emerged from the recognition that OBV's sensitivity to any price change—even a single tick—could create false signals in choppy or range-bound markets.

The indicator gained popularity among futures and forex traders where minimum tick sizes are well-defined and market noise within the spread is common. By requiring price to exceed the minimum tick before changing direction, TVI:

• Filters out bid-ask bounce noise
• Reduces whipsaws in ranging markets
• Maintains direction during consolidation phases
• Provides cleaner divergence signals than OBV

The "sticky direction" concept means that once TVI establishes a direction (up or down), it maintains that bias until price convincingly moves the other way—exceeding the minimum tick threshold in the opposite direction.

Architecture & Physics

TVI operates as a directional accumulator with hysteresis. The direction state is "sticky"—it persists through small price movements and only flips when price change exceeds the minimum tick threshold.

This creates a filtered money flow indicator that ignores noise and only responds to meaningful price movements.

Component Breakdown

1. Price Change Calculation: Current close minus previous close
2. Threshold Comparison: Is |price_change| > minTick?
3. Direction Update: Flip direction only if threshold exceeded
4. Volume Accumulation: Add or subtract based on current direction

State Requirements

Component	Type	Purpose
TviValue	double	Current cumulative TVI
PrevPrice	double	Previous bar's close for comparison
Direction	int	Current direction: +1 (up) or -1 (down)
LastValidPrice	double	Fallback for NaN/Infinity handling
LastValidVolume	double	Fallback for NaN/Infinity handling

Mathematical Foundation

Direction Logic

\Delta P_t = Close_t - Close_{t-1}

Direction_t = \begin{cases}
+1 & \text{if } \Delta P_t > minTick \\
-1 & \text{if } \Delta P_t < -minTick \\
Direction_{t-1} & \text{otherwise (sticky)}
\end{cases}

TVI Formula

TVI_t = TVI_{t-1} + Direction_t \times Volume_t

where:

• TVI_0 = 0 (starts at zero)
• Direction_0 = +1 (default up)
• minTick \geq 0 (threshold parameter)

Key Difference from OBV

Aspect	OBV	TVI
Direction change	Any price difference	Only if |Δprice| > minTick
Unchanged price	Volume ignored (0)	Volume added with current direction
Small movements	Flip-flop possible	Direction is sticky
Parameter	None	minTick threshold

Why Sticky Direction?

The sticky direction behavior creates hysteresis—a form of memory that resists rapid direction changes. This is analogous to a Schmitt trigger in electronics, which prevents oscillation by requiring the input to cross a threshold before changing state.

Benefits:

• Filters bid-ask bounce in tick data
• Reduces noise in ranging markets
• Maintains trend bias during minor retracements
• Produces smoother divergence signals

Performance Profile

Operation Count (Streaming Mode)

Operation	Count	Notes
SUB	1	price_change = close - prevClose
CMP	2	price_change > minTick, < -minTick
MUL	1	direction × volume
ADD	1	Cumulative TVI update
Total	5	Per bar, O(1)

TVI has slightly more operations than OBV due to threshold comparisons, but remains extremely lightweight.

Batch Mode (SIMD)

Operation	Vectorizable	Notes
Price differences	✅	Close[i] - Close[i-1]
Threshold comparisons	✅	ConditionalSelect
Direction update	❌	Sequential dependency (sticky)
Volume accumulation	❌	Sequential dependency

The sticky direction state creates a sequential dependency that prevents full SIMD vectorization. However, price difference calculations can be vectorized as a preprocessing step.

Quality Metrics

Metric	Score	Notes
Accuracy	10/10	Exact computation
Timeliness	7/10	Threshold delays response to small moves
Noise Filtering	9/10	Sticky direction filters noise well
Overshoot	N/A	No bounds; cumulative indicator
Memory	10/10	O(1) state: 3-5 scalar values

Validation

Library	Status	Notes
TA-Lib	N/A	Not implemented
Skender	N/A	Not implemented
Tulip	N/A	Not implemented
Ooples	N/A	Not implemented
PineScript	✅	Custom implementation available

TVI is not a standard indicator in most libraries. QuanTAlib implementation is based on Blau's original specification and validated against the PineScript reference implementation. Internal consistency between streaming, batch, and span modes is verified with tight tolerances (1e-9).

Common Pitfalls

1. MinTick Selection: Choosing an appropriate minTick value is critical. Too small reduces TVI to OBV behavior; too large makes direction changes rare. For stocks, 0.01–0.10 is typical. For futures, use the contract's minimum tick size.

2. Absolute Value Meaningless: Like OBV, TVI's numeric value has no intrinsic meaning—only direction and divergences matter. Don't compare TVI values across different securities.

3. Not Bounded: TVI can reach any value, positive or negative. It has no overbought/oversold levels. Use trend analysis, not absolute thresholds.

4. Default MinTick: The default minTick of 0.125 (1/8) was historical for stock trading in eighths. Modern decimalized markets may need adjustment.

5. Zero MinTick: Setting minTick = 0 makes TVI behave similarly to OBV, but not identically—TVI adds volume even on unchanged prices (using the sticky direction), while OBV adds zero.

6. Initial Direction: TVI starts with direction = +1 (up). The first bar's volume is always added positively. This matches standard implementations.

7. TValue Limitations: The Update(TValue) method exists for interface compatibility but cannot compute TVI properly without volume data. Use Update(TBar) for proper calculation.

8. isNew Parameter: When correcting bars (isNew=false), the implementation properly restores previous state including direction. Incorrect handling causes cumulative drift.

Interpretation Guide

Trend Confirmation

Price Trend	TVI Trend	Interpretation
Rising	Rising	Confirmed uptrend with filtered volume support
Falling	Falling	Confirmed downtrend with filtered volume support
Rising	Falling	Bearish divergence: weakness ahead
Falling	Rising	Bullish divergence: strength building

Sticky Direction Analysis

When TVI maintains its direction during price consolidation, it indicates:

• Persistent Up Direction: Buyers continue to dominate despite price pauses
• Persistent Down Direction: Sellers continue to dominate despite price bounces
• Direction Flip: A meaningful shift in control has occurred

TVI vs OBV Comparison

Use TVI when:

• Trading instruments with defined tick sizes (futures, forex)
• Markets are ranging or choppy
• OBV produces too many whipsaws
• You want to filter bid-ask bounce noise

Use OBV when:

• You want maximum sensitivity to price changes
• Trending markets where direction changes are meaningful
• Simplicity is preferred (no parameter to tune)

Divergence Trading

Signal	Setup	Action
Bullish	Price makes lower low, TVI makes higher low	Anticipate reversal up
Bearish	Price makes higher high, TVI makes lower high	Anticipate reversal down

TVI divergences are often cleaner than OBV divergences because noise is filtered.

Parameter Selection Guide

Market	Typical MinTick	Rationale
US Stocks (decimalized)	0.01–0.05	Penny stocks use lower; blue chips higher
E-mini S&P 500	0.25	Contract minimum tick
EUR/USD Forex	0.0001	One pip
Bitcoin	0.50–1.00	Depends on exchange precision
Bonds	1/32 ≈ 0.03125	Traditional bond tick

The minTick should generally match or exceed the instrument's minimum price increment to filter out normal bid-ask fluctuations.

References

• Blau, W. (1995). Momentum, Direction, and Divergence. Wiley.
• Blau, W. (1993). "The Trade Volume Index." Technical Analysis of Stocks & Commodities.
• Achelis, S. (2001). Technical Analysis from A to Z. McGraw-Hill.
• TradingView. "PineScript TVI Implementation." Community Scripts.