F9: add Accumulation/Distribution Line and Volume-Price Trend
Completes the F9 family (Cumulative volume) end to end: - Rust core: adl.rs (Accumulation/Distribution Line — cumulative range-weighted volume) and vpt.rs (Volume-Price Trend — cumulative volume scaled by percentage price change). Each with a full Indicator impl, runnable doctest and reference / cumulative-property / warmup / reset / batch==streaming tests. - Python: PyAdl / PyVolumePriceTrend PyO3 classes + module registration + .pyi stubs (no parameters, like OBV/VWAP). - Node: explicit AdlNode and VolumePriceTrendNode; index.d.ts and index.js updated. - WASM: WasmAdl and WasmVolumePriceTrend. - Wiki: Indicator-Adl.md and Indicator-VolumePriceTrend.md plus rows in Indicators-Overview.md and entries in Home.md. cargo fmt + clippy (core/wickra/data/wasm/node) clean; 373 core tests, 25 data tests and 53 doctests green.
This commit is contained in:
kingchenc
@@ -0,0 +1,161 @@
|
||||
# ADL
|
||||
|
||||
> Accumulation/Distribution Line — a cumulative volume-flow line that
|
||||
> weights each bar's volume by where its close fell within the range.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Family | Volume |
|
||||
| Sub-category | Cumulative |
|
||||
| Input type | `Candle` (uses `high`, `low`, `close`, `volume`) |
|
||||
| Output type | `f64` |
|
||||
| Output range | unbounded (drifts with cumulative volume) |
|
||||
| Default parameters | none (no parameters) |
|
||||
| Warmup period | `1` |
|
||||
| Interpretation | Running buying/selling pressure; slope and divergence matter. |
|
||||
|
||||
## Formula
|
||||
|
||||
```
|
||||
MFM_t = ((close − low) − (high − close)) / (high − low) (money-flow multiplier, −1..+1)
|
||||
MFV_t = MFM_t · volume_t (money-flow volume)
|
||||
ADL_t = ADL_{t−1} + MFV_t
|
||||
```
|
||||
|
||||
The money-flow multiplier asks *where in the bar's range did price
|
||||
close?* A close on the high gives `+1` (full accumulation), on the low
|
||||
`−1` (full distribution), in the middle `0`. Scaling by volume and
|
||||
running the cumulative total gives a line whose **slope** reflects
|
||||
sustained buying or selling pressure. A bar with `high == low` carries no
|
||||
positional information and contributes `0`.
|
||||
|
||||
## Parameters
|
||||
|
||||
`ADL` takes **no parameters** — `Adl::new()` in Rust, `wickra.ADL()` in
|
||||
Python, `new ta.ADL()` in Node.
|
||||
|
||||
## Inputs / Outputs
|
||||
|
||||
From `crates/wickra-core/src/indicators/adl.rs`:
|
||||
|
||||
```rust
|
||||
impl Indicator for Adl {
|
||||
type Input = Candle;
|
||||
type Output = f64;
|
||||
// update(&mut self, input: Candle) -> Option<f64>
|
||||
}
|
||||
```
|
||||
|
||||
`ADL` is a **candle-input** indicator: it reads `high`, `low`, `close` and
|
||||
`volume`. In Python the streaming `update` accepts a 6-tuple or a dict;
|
||||
the batch helper takes `high`, `low`, `close`, `volume` numpy arrays. Node
|
||||
and WASM expose `update(high, low, close, volume)` and the matching
|
||||
`batch`.
|
||||
|
||||
## Warmup
|
||||
|
||||
`Adl::new().warmup_period() == 1`. ADL is cumulative — it emits a value
|
||||
from the very first candle.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **Zero-range bar.** A bar with `high == low` contributes `0` to the line
|
||||
(`zero_range_bar_contributes_nothing` pins this).
|
||||
- **Close at the high.** Every bar closing on its high has `MFM = +1`, so
|
||||
ADL grows by exactly `volume` each bar
|
||||
(`close_at_high_accumulates_full_volume` pins this).
|
||||
- **Candle validation.** `Candle::new` rejects invalid bars upstream.
|
||||
- **Reset.** `adl.reset()` returns the running total to `0`.
|
||||
|
||||
## Examples
|
||||
|
||||
### Rust
|
||||
|
||||
```rust
|
||||
use wickra::{BatchExt, Candle, Indicator, Adl};
|
||||
|
||||
fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
let mut adl = Adl::new();
|
||||
let out = adl.batch(&[
|
||||
Candle::new(8.0, 10.0, 8.0, 10.0, 100.0, 0)?, // close at high
|
||||
Candle::new(10.0, 12.0, 8.0, 9.0, 200.0, 1)?,
|
||||
]);
|
||||
println!("{:?}", out);
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
[Some(100.0), Some(0.0)]
|
||||
```
|
||||
|
||||
Bar 1 closes at its high (`MFM = +1`), adding `+100`. Bar 2 has
|
||||
`MFM = ((9−8)−(12−9))/4 = −0.5`, adding `−100`, so the line returns to
|
||||
`0`. This matches the `reference_values` test in
|
||||
`crates/wickra-core/src/indicators/adl.rs`.
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
import wickra as ta
|
||||
|
||||
adl = ta.ADL()
|
||||
high = np.array([10.0, 12.0])
|
||||
low = np.array([8.0, 8.0])
|
||||
close = np.array([10.0, 9.0])
|
||||
volume = np.array([100.0, 200.0])
|
||||
print(adl.batch(high, low, close, volume))
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
[100. 0.]
|
||||
```
|
||||
|
||||
### Node
|
||||
|
||||
```javascript
|
||||
const ta = require('wickra');
|
||||
const adl = new ta.ADL();
|
||||
console.log(adl.batch([10, 12], [8, 8], [10, 9], [100, 200]));
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
[ 100, 0 ]
|
||||
```
|
||||
|
||||
## Interpretation
|
||||
|
||||
`Adl` is read by slope and by divergence, never by absolute level (the
|
||||
total drifts arbitrarily with cumulative volume). A rising ADL confirms
|
||||
that an up-move is backed by accumulation; a *falling* ADL while price
|
||||
rises is a bearish divergence — the rally is not being bought into.
|
||||
[`ChaikinOscillator`](Indicator-ChaikinOscillator.md) is the standard way
|
||||
to turn the ADL into a bounded, tradeable oscillator.
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- **Reading the absolute value.** Only the slope and divergences are
|
||||
meaningful; the level depends on where you started the stream.
|
||||
- **Feeding it scalar prices.** It needs the full OHLCV bar.
|
||||
|
||||
## References
|
||||
|
||||
Marc Chaikin's Accumulation/Distribution Line; the money-flow-multiplier
|
||||
formulation here matches the standard definition (StockCharts, TA-Lib's
|
||||
`AD`).
|
||||
|
||||
## See also
|
||||
|
||||
- [Indicator-Obv.md](Indicator-Obv.md) — cumulative *signed* volume.
|
||||
- [Indicator-ChaikinOscillator.md](Indicator-ChaikinOscillator.md) — an
|
||||
oscillator built on the ADL.
|
||||
- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
|
||||
@@ -0,0 +1,161 @@
|
||||
# VolumePriceTrend
|
||||
|
||||
> Volume-Price Trend (VPT) — a cumulative volume line where each bar's
|
||||
> contribution is scaled by its percentage price change.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Family | Volume |
|
||||
| Sub-category | Cumulative |
|
||||
| Input type | `Candle` (uses `close`, `volume`) |
|
||||
| Output type | `f64` |
|
||||
| Output range | unbounded (drifts with cumulative volume) |
|
||||
| Default parameters | none (no parameters) |
|
||||
| Warmup period | `1` |
|
||||
| Interpretation | Running volume flow; slope and divergence matter. |
|
||||
|
||||
## Formula
|
||||
|
||||
```
|
||||
VPT_t = VPT_{t−1} + volume_t · (close_t − close_{t−1}) / close_{t−1}
|
||||
```
|
||||
|
||||
VPT is a close relative of [`Obv`](Indicator-Obv.md). Where OBV adds the
|
||||
*entire* bar volume on any up-close, VPT adds volume scaled by the **size**
|
||||
of the move: a 2 % gain on a given volume moves the line twice as far as a
|
||||
1 % gain on the same volume. That makes VPT more sensitive to the
|
||||
conviction behind a move. The first bar establishes the baseline at `0`.
|
||||
|
||||
## Parameters
|
||||
|
||||
`VolumePriceTrend` takes **no parameters** — `VolumePriceTrend::new()` in
|
||||
Rust, `wickra.VolumePriceTrend()` in Python, `new ta.VolumePriceTrend()`
|
||||
in Node.
|
||||
|
||||
## Inputs / Outputs
|
||||
|
||||
From `crates/wickra-core/src/indicators/vpt.rs`:
|
||||
|
||||
```rust
|
||||
impl Indicator for VolumePriceTrend {
|
||||
type Input = Candle;
|
||||
type Output = f64;
|
||||
// update(&mut self, input: Candle) -> Option<f64>
|
||||
}
|
||||
```
|
||||
|
||||
`VolumePriceTrend` is a **candle-input** indicator: it reads `close` and
|
||||
`volume`. In Python the streaming `update` accepts a 6-tuple or a dict;
|
||||
the batch helper takes `close` and `volume` numpy arrays. Node and WASM
|
||||
expose `update(close, volume)` and `batch(close, volume)`.
|
||||
|
||||
## Warmup
|
||||
|
||||
`warmup_period() == 1`. VPT is cumulative — it emits the baseline `0` from
|
||||
the first candle, then accumulates from the second onward.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **Constant close.** With no price change every bar contributes `0`, so
|
||||
the line stays flat regardless of volume
|
||||
(`constant_close_keeps_line_flat` pins this).
|
||||
- **First bar.** The first candle has no previous close; VPT emits the
|
||||
baseline `0.0` (`emits_from_first_candle_at_zero` pins this).
|
||||
- **Zero previous close.** A percentage change against a `0.0` prior
|
||||
close is undefined and is treated as `0`.
|
||||
- **Candle validation.** `Candle::new` rejects invalid bars upstream.
|
||||
- **Reset.** `vpt.reset()` returns the running total to `0`.
|
||||
|
||||
## Examples
|
||||
|
||||
### Rust
|
||||
|
||||
```rust
|
||||
use wickra::{BatchExt, Candle, Indicator, VolumePriceTrend};
|
||||
|
||||
fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
let mut vpt = VolumePriceTrend::new();
|
||||
// closes 10 -> 11 -> 9, volumes 100, 200, 300.
|
||||
let out = vpt.batch(&[
|
||||
Candle::new(10.0, 10.0, 10.0, 10.0, 100.0, 0)?,
|
||||
Candle::new(11.0, 11.0, 11.0, 11.0, 200.0, 1)?,
|
||||
Candle::new(9.0, 9.0, 9.0, 9.0, 300.0, 2)?,
|
||||
]);
|
||||
println!("{:?}", out);
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
[Some(0.0), Some(20.0), Some(-34.54545454545455)]
|
||||
```
|
||||
|
||||
Bar 1 is the baseline `0`. Bar 2 adds `200 · (11−10)/10 = 20`. Bar 3 adds
|
||||
`300 · (9−11)/11 = −600/11`, leaving `20 − 600/11 ≈ −34.545`. This matches
|
||||
the `reference_values` test in `crates/wickra-core/src/indicators/vpt.rs`.
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
import wickra as ta
|
||||
|
||||
vpt = ta.VolumePriceTrend()
|
||||
close = np.array([10.0, 11.0, 9.0])
|
||||
volume = np.array([100.0, 200.0, 300.0])
|
||||
print(vpt.batch(close, volume))
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
[ 0. 20. -34.54545455]
|
||||
```
|
||||
|
||||
### Node
|
||||
|
||||
```javascript
|
||||
const ta = require('wickra');
|
||||
const vpt = new ta.VolumePriceTrend();
|
||||
console.log(vpt.batch([10, 11, 9], [100, 200, 300]));
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
[ 0, 20, -34.54545454545455 ]
|
||||
```
|
||||
|
||||
## Interpretation
|
||||
|
||||
`VolumePriceTrend` is read like OBV — by **slope** and by **divergence**,
|
||||
never by absolute level. A VPT rising in step with price confirms the
|
||||
trend is volume-supported; VPT flattening or falling while price climbs
|
||||
is a bearish divergence warning that the move lacks participation. Versus
|
||||
OBV, VPT gives proportionally more weight to large moves and less to a
|
||||
string of tiny up-closes, so it tracks the *magnitude* of conviction, not
|
||||
just its direction.
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- **Reading the absolute value.** Only slope and divergences carry
|
||||
meaning; the level depends on the stream's start point.
|
||||
- **Expecting OBV-identical behaviour.** VPT scales by percentage change,
|
||||
so the two lines diverge — especially across large single-bar moves.
|
||||
|
||||
## References
|
||||
|
||||
The Volume-Price Trend (also "Price-Volume Trend") is a standard
|
||||
cumulative volume study; the `volume · ROC` accumulation here matches the
|
||||
common definition.
|
||||
|
||||
## See also
|
||||
|
||||
- [Indicator-Obv.md](Indicator-Obv.md) — cumulative signed volume, the
|
||||
closest relative.
|
||||
- [Indicator-Adl.md](Indicator-Adl.md) — cumulative range-weighted volume.
|
||||
- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
|
||||
Reference in New Issue
Block a user