# Volume Indicators

Volume indicators analyze buying and selling pressure by incorporating trading volume data. Volume confirms price movements and can signal trend reversals.

---

## OBV - On Balance Volume

The On Balance Volume is a cumulative volume indicator that adds volume on up days and subtracts volume on down days. It measures buying and selling pressure.

### Formula

$$OBV_t = \begin{cases}
OBV_{t-1} + volume_t & \text{if } close_t > close_{t-1} \\
OBV_{t-1} - volume_t & \text{if } close_t < close_{t-1} \\
OBV_{t-1} & \text{if } close_t = close_{t-1}
\end{cases}$$

### Characteristics

| Property | Value |
|----------|-------|
| Input | OHLCV (close, volume) |
| Output | Single value (cumulative OBV) |
| Lookback | 0 (valid from first bar) |
| Memory | O(1) |

### API Usage

::::{tab-set}

:::{tab-item} Python
```python
from techkit import OBV

# Object-oriented
obv = OBV()
result = obv.update_ohlcv(open, high, low, close, volume)
if result.valid:
    print(f"OBV: {result.value:.0f}")

# Batch
from techkit import talib_compat as ta
obv_values = ta.OBV(close, volume)
```
:::

:::{tab-item} Node.js
```javascript
const tk = require('techkit');

// Streaming
const obv = tk.obv();
const result = obv.updateOHLCV({open, high, low, close, volume});

// Batch
const values = tk.OBV(close, volume);
```
:::

:::{tab-item} C++
```cpp
#include <techkit/techkit.hpp>

techkit::OBV obv;
techkit::OHLCV bar{open, high, low, close, volume};
auto result = obv.update(bar);
```
:::

:::{tab-item} C
```c
tk_indicator obv = tk_obv_new();
tk_ohlcv bar = {open, high, low, close, volume};
tk_result r = tk_update_ohlcv(obv, &bar);
tk_free(obv);
```
:::

::::

### Trading Usage

- **Trend Confirmation**: OBV rising with price = uptrend confirmed
- **Divergence**: Price makes new high but OBV doesn't = bearish divergence
- **Breakouts**: OBV breakout often precedes price breakout
- **Volume Analysis**: 
  - Rising OBV + Rising Price = Strong uptrend
  - Falling OBV + Falling Price = Strong downtrend
  - Rising OBV + Falling Price = Potential reversal up
  - Falling OBV + Rising Price = Potential reversal down

### Limitations

- OBV can accumulate errors over long periods
- Doesn't account for volume intensity (only direction)
- Use in conjunction with price action

---

## AD - Accumulation/Distribution Line

The Accumulation/Distribution Line measures money flow by considering where price closes within the period's range. It's more sophisticated than OBV.

### Formula

$$CLV = \frac{(close - low) - (high - close)}{high - low}$$

$$AD_t = AD_{t-1} + CLV_t \times volume_t$$

If $high = low$, then $CLV = 0$.

### Characteristics

| Property | Value |
|----------|-------|
| Input | OHLCV (open, high, low, close, volume) |
| Output | Single value (cumulative AD) |
| Lookback | 0 (valid from first bar) |
| Memory | O(1) |

### API Usage

::::{tab-set}

:::{tab-item} Python
```python
from techkit import AD

ad = AD()
result = ad.update_ohlcv(open, high, low, close, volume)
if result.valid:
    print(f"A/D: {result.value:.0f}")
```
:::

:::{tab-item} Node.js
```javascript
const ad = tk.ad();
const result = ad.updateOHLCV({open, high, low, close, volume});
```
:::

:::{tab-item} C++
```cpp
techkit::AD ad;
auto result = ad.update(bar);
```
:::

:::{tab-item} C
```c
tk_indicator ad = tk_ad_new();
tk_result r = tk_update_ohlcv(ad, &bar);
```
:::

::::

### Trading Usage

- **Money Flow**: Rising AD = accumulation (buying pressure)
- **Divergence**: Price down but AD up = potential reversal
- **Trend Confirmation**: AD should follow price trend
- **CLV Interpretation**:
  - CLV > 0: Price closes in upper half (accumulation)
  - CLV < 0: Price closes in lower half (distribution)
  - CLV = 0: Price closes at midpoint

### Comparison: OBV vs AD

| Aspect | OBV | AD |
|--------|-----|-----|
| Calculation | Simple (up/down) | Weighted by position in range |
| Sensitivity | Less sensitive | More sensitive |
| Use Case | Basic volume trend | Detailed money flow |

---

## ADOSC - Chaikin A/D Oscillator

The Chaikin A/D Oscillator is the difference between fast and slow EMAs of the Accumulation/Distribution Line. It provides momentum signals for the A/D line.

### Formula

$$ADOSC = EMA(AD, fast) - EMA(AD, slow)$$

where:
- $fast$ = fast EMA period (default: 3)
- $slow$ = slow EMA period (default: 10)

### Parameters

| Parameter | Type | Default | Range | Description |
|-----------|------|---------|-------|-------------|
| fast_period | int | 3 | 1-100000 | Fast EMA period |
| slow_period | int | 10 | 1-100000 | Slow EMA period (must be > fast) |

### Characteristics

| Property | Value |
|----------|-------|
| Input | OHLCV (open, high, low, close, volume) |
| Output | Single value (oscillator) |
| Lookback | slow_period - 1 |
| Memory | O(1) |

### API Usage

::::{tab-set}

:::{tab-item} Python
```python
from techkit import ADOSC

adosc = ADOSC(fast_period=3, slow_period=10)
result = adosc.update_ohlcv(open, high, low, close, volume)
if result.valid:
    print(f"A/D Oscillator: {result.value:.0f}")
```
:::

:::{tab-item} Node.js
```javascript
const adosc = tk.adosc(3, 10);
const result = adosc.updateOHLCV({open, high, low, close, volume});
```
:::

:::{tab-item} C++
```cpp
techkit::ADOSC adosc(3, 10);
auto result = adosc.update(bar);
```
:::

:::{tab-item} C
```c
tk_indicator adosc = tk_adosc_new(3, 10);
tk_result r = tk_update_ohlcv(adosc, &bar);
```
:::

::::

### Trading Usage

- **Momentum**: Positive ADOSC = increasing accumulation
- **Crossovers**: ADOSC crossing zero = momentum shift
- **Divergence**: ADOSC divergence from price = reversal signal
- **Signal Interpretation**:
  - ADOSC > 0: Accumulation momentum
  - ADOSC < 0: Distribution momentum
  - ADOSC rising: Increasing buying pressure
  - ADOSC falling: Increasing selling pressure

### Common Periods

| Fast | Slow | Use Case |
|------|------|----------|
| 3 | 10 | Standard (most common) |
| 5 | 15 | Slower, less sensitive |
| 2 | 8 | Faster, more sensitive |

---

## MFI - Money Flow Index

The Money Flow Index is a volume-weighted RSI that measures buying and selling pressure. It ranges from 0 to 100.

### Formula

$$TP = \frac{high + low + close}{3}$$

$$MF = TP \times volume$$

$$+MF = \sum MF \text{ where } TP > TP_{prev}$$

$$-MF = \sum MF \text{ where } TP < TP_{prev}$$

$$MFI = 100 - \frac{100}{1 + \frac{+MF}{-MF}}$$

### Parameters

| Parameter | Type | Default | Range | Description |
|-----------|------|---------|-------|-------------|
| period | int | 14 | 1-100000 | Number of periods for averaging |

### Characteristics

| Property | Value |
|----------|-------|
| Input | OHLCV (open, high, low, close, volume) |
| Output | Single value (0-100) |
| Lookback | period |
| Memory | O(period) |

### API Usage

::::{tab-set}

:::{tab-item} Python
```python
from techkit import MFI

mfi = MFI(period=14)
result = mfi.update_ohlcv(open, high, low, close, volume)
if result.valid:
    if result.value > 80:
        print("Overbought")
    elif result.value < 20:
        print("Oversold")
```
:::

:::{tab-item} Node.js
```javascript
const mfi = tk.mfi(14);
const result = mfi.updateOHLCV({open, high, low, close, volume});
```
:::

:::{tab-item} C++
```cpp
techkit::MFI mfi(14);
auto result = mfi.update(bar);
```
:::

:::{tab-item} C
```c
tk_indicator mfi = tk_mfi_new(14);
tk_result r = tk_update_ohlcv(mfi, &bar);
```
:::

::::

### Trading Usage

- **Overbought/Oversold**: 
  - MFI > 80: Overbought (potential sell)
  - MFI < 20: Oversold (potential buy)
- **Divergence**: MFI divergence from price = reversal signal
- **Volume Confirmation**: MFI confirms RSI with volume weighting
- **Comparison with RSI**:
  - RSI: Price-based momentum
  - MFI: Volume-weighted momentum
  - Use together for stronger signals

### Common Periods

| Period | Use Case |
|--------|----------|
| 14 | Standard (most common) |
| 21 | Longer-term |
| 9 | Shorter-term, more sensitive |

---

## Volume Indicator Comparison

| Indicator | Calculation | Range | Best For |
|-----------|-------------|-------|----------|
| OBV | Cumulative volume | Unbounded | Basic volume trend |
| AD | Weighted cumulative | Unbounded | Money flow analysis |
| ADOSC | A/D momentum | Unbounded | Momentum signals |
| MFI | Volume-weighted RSI | 0-100 | Overbought/oversold |

---

## Related Indicators

- **Volume Price Trend (VPT)**: Similar to OBV but uses percentage change
- **Volume Rate of Change**: Measures volume momentum
- **Price-Volume Trend**: Combines price and volume changes