gavindiaz/wickra
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: derivatives open-interest, flow & liquidation indicators (part 2 of 3) (#127)

Browse Source 
* feat(derivatives): OIPriceDivergence indicator (core)

* feat(derivatives): OIWeighted indicator (core)

* feat(derivatives): LongShortRatio indicator (core)

* feat(derivatives): TakerBuySellRatio indicator (core)

* feat(derivatives): LiquidationFeatures multi-output indicator (core)

* feat(derivatives): Python, Node and WASM bindings for OI, flow & liquidation indicators

* test(derivatives): Python and Node tests for OI, flow & liquidation indicators

* fuzz(derivatives): drive OI, flow & liquidation indicators in derivatives target

* docs(derivatives): README row + counter 237->242, CHANGELOG part 2
This commit is contained in:
kingchenc
2026-06-01 21:50:35 +02:00
committed by GitHub
parent 5eb820a9c7
commit 8e5bfd07ce
20 changed files with 2078 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
bindings/python/python/wickra/__init__.py
+10
View File
@@ -263,6 +263,11 @@ from ._wickra import (
FundingRateZScore,
FundingBasis,
OpenInterestDelta,
OIPriceDivergence,
OIWeighted,
LongShortRatio,
TakerBuySellRatio,
LiquidationFeatures,
# Risk / Performance
SharpeRatio,
SortinoRatio,
@@ -523,6 +528,11 @@ __all__ = [
"FundingRateZScore",
"FundingBasis",
"OpenInterestDelta",
"OIPriceDivergence",
"OIWeighted",
"LongShortRatio",
"TakerBuySellRatio",
"LiquidationFeatures",
# Risk / Performance
"SharpeRatio",
"SortinoRatio",
bindings/python/src/lib.rs
+375
View File
@@ -12244,6 +12244,70 @@ fn deriv_oi(open_interest: f64) -> PyResult<wc::DerivativesTick> {
.map_err(map_err)
}
fn deriv_oi_mark(open_interest: f64, mark_price: f64) -> PyResult<wc::DerivativesTick> {
wc::DerivativesTick::new(
0.0,
mark_price,
1.0,
1.0,
open_interest,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0,
)
.map_err(map_err)
}
fn deriv_long_short(long_size: f64, short_size: f64) -> PyResult<wc::DerivativesTick> {
wc::DerivativesTick::new(
0.0, 1.0, 1.0, 1.0, 0.0, long_size, short_size, 0.0, 0.0, 0.0, 0.0, 0,
)
.map_err(map_err)
}
fn deriv_taker(taker_buy_volume: f64, taker_sell_volume: f64) -> PyResult<wc::DerivativesTick> {
wc::DerivativesTick::new(
0.0,
1.0,
1.0,
1.0,
0.0,
0.0,
0.0,
taker_buy_volume,
taker_sell_volume,
0.0,
0.0,
0,
)
.map_err(map_err)
}
fn deriv_liquidation(
long_liquidation: f64,
short_liquidation: f64,
) -> PyResult<wc::DerivativesTick> {
wc::DerivativesTick::new(
0.0,
1.0,
1.0,
1.0,
0.0,
0.0,
0.0,
0.0,
0.0,
long_liquidation,
short_liquidation,
0,
)
.map_err(map_err)
}
// FundingRate takes no parameters; streaming `update(funding_rate)`, `batch`
// over one funding-rate array.
#[pyclass(name = "FundingRate", module = "wickra._wickra", skip_from_py_object)]
@@ -12482,6 +12546,312 @@ impl PyOpenInterestDelta {
}
}
// OIPriceDivergence carries a `window` parameter; streaming
// `update(open_interest, mark_price)`.
#[pyclass(
name = "OIPriceDivergence",
module = "wickra._wickra",
skip_from_py_object
)]
#[derive(Clone)]
struct PyOIPriceDivergence {
inner: wc::OIPriceDivergence,
}
#[pymethods]
impl PyOIPriceDivergence {
#[new]
fn new(window: usize) -> PyResult<Self> {
Ok(Self {
inner: wc::OIPriceDivergence::new(window).map_err(map_err)?,
})
}
fn update(&mut self, open_interest: f64, mark_price: f64) -> PyResult<Option<f64>> {
Ok(self.inner.update(deriv_oi_mark(open_interest, mark_price)?))
}
fn batch<'py>(
&mut self,
py: Python<'py>,
open_interest: Vec<f64>,
mark_price: Vec<f64>,
) -> PyResult<Bound<'py, PyArray1<f64>>> {
if open_interest.len() != mark_price.len() {
return Err(PyValueError::new_err(
"open_interest and mark_price must be equal length",
));
}
let mut out = Vec::with_capacity(open_interest.len());
for i in 0..open_interest.len() {
out.push(
self.inner
.update(deriv_oi_mark(open_interest[i], mark_price[i])?)
.unwrap_or(f64::NAN),
);
}
Ok(out.into_pyarray(py))
}
fn reset(&mut self) {
self.inner.reset();
}
fn is_ready(&self) -> bool {
self.inner.is_ready()
}
fn warmup_period(&self) -> usize {
self.inner.warmup_period()
}
fn __repr__(&self) -> String {
format!("OIPriceDivergence(window={})", self.inner.window())
}
}
// OIWeighted takes no parameters; streaming `update(mark_price, open_interest)`.
#[pyclass(name = "OIWeighted", module = "wickra._wickra", skip_from_py_object)]
#[derive(Clone)]
struct PyOIWeighted {
inner: wc::OIWeighted,
}
#[pymethods]
impl PyOIWeighted {
#[new]
fn new() -> Self {
Self {
inner: wc::OIWeighted::new(),
}
}
fn update(&mut self, mark_price: f64, open_interest: f64) -> PyResult<Option<f64>> {
Ok(self.inner.update(deriv_oi_mark(open_interest, mark_price)?))
}
fn batch<'py>(
&mut self,
py: Python<'py>,
mark_price: Vec<f64>,
open_interest: Vec<f64>,
) -> PyResult<Bound<'py, PyArray1<f64>>> {
if mark_price.len() != open_interest.len() {
return Err(PyValueError::new_err(
"mark_price and open_interest must be equal length",
));
}
let mut out = Vec::with_capacity(mark_price.len());
for i in 0..mark_price.len() {
out.push(
self.inner
.update(deriv_oi_mark(open_interest[i], mark_price[i])?)
.unwrap_or(f64::NAN),
);
}
Ok(out.into_pyarray(py))
}
fn reset(&mut self) {
self.inner.reset();
}
fn is_ready(&self) -> bool {
self.inner.is_ready()
}
fn warmup_period(&self) -> usize {
self.inner.warmup_period()
}
fn __repr__(&self) -> String {
"OIWeighted()".to_string()
}
}
// LongShortRatio takes no parameters; streaming `update(long_size, short_size)`.
#[pyclass(
name = "LongShortRatio",
module = "wickra._wickra",
skip_from_py_object
)]
#[derive(Clone)]
struct PyLongShortRatio {
inner: wc::LongShortRatio,
}
#[pymethods]
impl PyLongShortRatio {
#[new]
fn new() -> Self {
Self {
inner: wc::LongShortRatio::new(),
}
}
fn update(&mut self, long_size: f64, short_size: f64) -> PyResult<Option<f64>> {
Ok(self.inner.update(deriv_long_short(long_size, short_size)?))
}
fn batch<'py>(
&mut self,
py: Python<'py>,
long_size: Vec<f64>,
short_size: Vec<f64>,
) -> PyResult<Bound<'py, PyArray1<f64>>> {
if long_size.len() != short_size.len() {
return Err(PyValueError::new_err(
"long_size and short_size must be equal length",
));
}
let mut out = Vec::with_capacity(long_size.len());
for i in 0..long_size.len() {
out.push(
self.inner
.update(deriv_long_short(long_size[i], short_size[i])?)
.unwrap_or(f64::NAN),
);
}
Ok(out.into_pyarray(py))
}
fn reset(&mut self) {
self.inner.reset();
}
fn is_ready(&self) -> bool {
self.inner.is_ready()
}
fn warmup_period(&self) -> usize {
self.inner.warmup_period()
}
fn __repr__(&self) -> String {
"LongShortRatio()".to_string()
}
}
// TakerBuySellRatio takes no parameters; streaming
// `update(taker_buy_volume, taker_sell_volume)`.
#[pyclass(
name = "TakerBuySellRatio",
module = "wickra._wickra",
skip_from_py_object
)]
#[derive(Clone)]
struct PyTakerBuySellRatio {
inner: wc::TakerBuySellRatio,
}
#[pymethods]
impl PyTakerBuySellRatio {
#[new]
fn new() -> Self {
Self {
inner: wc::TakerBuySellRatio::new(),
}
}
fn update(&mut self, taker_buy_volume: f64, taker_sell_volume: f64) -> PyResult<Option<f64>> {
Ok(self
.inner
.update(deriv_taker(taker_buy_volume, taker_sell_volume)?))
}
fn batch<'py>(
&mut self,
py: Python<'py>,
taker_buy_volume: Vec<f64>,
taker_sell_volume: Vec<f64>,
) -> PyResult<Bound<'py, PyArray1<f64>>> {
if taker_buy_volume.len() != taker_sell_volume.len() {
return Err(PyValueError::new_err(
"taker_buy_volume and taker_sell_volume must be equal length",
));
}
let mut out = Vec::with_capacity(taker_buy_volume.len());
for i in 0..taker_buy_volume.len() {
out.push(
self.inner
.update(deriv_taker(taker_buy_volume[i], taker_sell_volume[i])?)
.unwrap_or(f64::NAN),
);
}
Ok(out.into_pyarray(py))
}
fn reset(&mut self) {
self.inner.reset();
}
fn is_ready(&self) -> bool {
self.inner.is_ready()
}
fn warmup_period(&self) -> usize {
self.inner.warmup_period()
}
fn __repr__(&self) -> String {
"TakerBuySellRatio()".to_string()
}
}
// LiquidationFeatures is a multi-output indicator: streaming
// `update(long_liquidation, short_liquidation)` returns a 5-tuple
// `(long, short, net, total, imbalance)`; `batch` returns an `(n, 5)` array.
#[pyclass(
name = "LiquidationFeatures",
module = "wickra._wickra",
skip_from_py_object
)]
#[derive(Clone)]
struct PyLiquidationFeatures {
inner: wc::LiquidationFeatures,
}
#[pymethods]
impl PyLiquidationFeatures {
#[new]
fn new() -> Self {
Self {
inner: wc::LiquidationFeatures::new(),
}
}
/// Returns `(long, short, net, total, imbalance)` or None during warmup.
#[allow(clippy::type_complexity)]
fn update(
&mut self,
long_liquidation: f64,
short_liquidation: f64,
) -> PyResult<Option<(f64, f64, f64, f64, f64)>> {
Ok(self
.inner
.update(deriv_liquidation(long_liquidation, short_liquidation)?)
.map(|o| (o.long, o.short, o.net, o.total, o.imbalance)))
}
fn batch<'py>(
&mut self,
py: Python<'py>,
long_liquidation: Vec<f64>,
short_liquidation: Vec<f64>,
) -> PyResult<Bound<'py, PyArray2<f64>>> {
if long_liquidation.len() != short_liquidation.len() {
return Err(PyValueError::new_err(
"long_liquidation and short_liquidation must be equal length",
));
}
let rows = long_liquidation.len();
let mut data = Vec::with_capacity(rows * 5);
for i in 0..rows {
let out = self
.inner
.update(deriv_liquidation(
long_liquidation[i],
short_liquidation[i],
)?)
.expect("liquidation features emit on every tick");
data.push(out.long);
data.push(out.short);
data.push(out.net);
data.push(out.total);
data.push(out.imbalance);
}
Ok(numpy::ndarray::Array2::from_shape_vec((rows, 5), data)
.expect("shape consistent")
.into_pyarray(py))
}
fn reset(&mut self) {
self.inner.reset();
}
fn is_ready(&self) -> bool {
self.inner.is_ready()
}
fn warmup_period(&self) -> usize {
self.inner.warmup_period()
}
fn __repr__(&self) -> String {
"LiquidationFeatures()".to_string()
}
}
// ============================== Family 15: Risk / Performance ==============================
#[pyclass(name = "SharpeRatio", module = "wickra._wickra", skip_from_py_object)]
@@ -13610,6 +13980,11 @@ fn _wickra(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
m.add_class::<PyFundingRateZScore>()?;
m.add_class::<PyFundingBasis>()?;
m.add_class::<PyOpenInterestDelta>()?;
m.add_class::<PyOIPriceDivergence>()?;
m.add_class::<PyOIWeighted>()?;
m.add_class::<PyLongShortRatio>()?;
m.add_class::<PyTakerBuySellRatio>()?;
m.add_class::<PyLiquidationFeatures>()?;
// Family 15: Risk / Performance metrics.
m.add_class::<PySharpeRatio>()?;
m.add_class::<PySortinoRatio>()?;
bindings/python/tests/test_input_validation.py
+10
View File
@@ -258,3 +258,13 @@ def test_funding_basis_non_positive_index_raises():
def test_funding_rate_non_finite_raises():
with pytest.raises(ValueError):
ta.FundingRate().update(float("nan"))
def test_oi_price_divergence_zero_window_raises():
with pytest.raises(ValueError):
ta.OIPriceDivergence(0)
def test_oi_weighted_non_positive_mark_raises():
with pytest.raises(ValueError):
ta.OIWeighted().update(0.0, 100.0)
bindings/python/tests/test_known_values.py
+34
View File
@@ -979,3 +979,37 @@ def test_open_interest_delta_reference_value():
assert oid.update(1000.0) is None # seeds the previous OI
assert oid.update(1250.0) == pytest.approx(250.0)
assert oid.update(1100.0) == pytest.approx(-150.0)
def test_oi_price_divergence_reference_value():
div = ta.OIPriceDivergence(1)
assert div.update(1000.0, 100.0) is None # warming up
# OI +10% while price flat -> divergence +0.1.
assert div.update(1100.0, 100.0) == pytest.approx(0.1)
def test_oi_weighted_reference_value():
oiw = ta.OIWeighted()
assert oiw.update(100.0, 10.0) == pytest.approx(100.0)
# (100·10 + 110·30) / 40 = 107.5.
assert oiw.update(110.0, 30.0) == pytest.approx(107.5)
def test_long_short_ratio_reference_value():
# 600 longs vs 400 shorts -> 1.5.
assert ta.LongShortRatio().update(600.0, 400.0) == pytest.approx(1.5)
# No short side -> 0.0.
assert ta.LongShortRatio().update(600.0, 0.0) == pytest.approx(0.0)
def test_taker_buy_sell_ratio_reference_value():
# 60 taker buys vs 40 taker sells -> 1.5.
assert ta.TakerBuySellRatio().update(60.0, 40.0) == pytest.approx(1.5)
# No taker sell volume -> 0.0.
assert ta.TakerBuySellRatio().update(60.0, 0.0) == pytest.approx(0.0)
def test_liquidation_features_reference_value():
# 30 long vs 10 short: (long, short, net, total, imbalance).
out = ta.LiquidationFeatures().update(30.0, 10.0)
assert out == pytest.approx((30.0, 10.0, 20.0, 40.0, 0.5))
bindings/python/tests/test_new_indicators.py
+53
View File
@@ -1994,3 +1994,56 @@ def test_open_interest_delta_streaming_equals_batch():
streamed = np.array([streamer.update(oi[i]) for i in range(n)], dtype=np.float64)
assert batch.shape == (n,)
assert _eq_nan(batch, streamed)
def test_oi_flow_indicators_streaming_equals_batch():
n = 40
oi = np.array([1000.0 + 50.0 * math.sin(i * 0.2) for i in range(n)], dtype=np.float64)
mark = np.array([100.0 + math.cos(i * 0.3) for i in range(n)], dtype=np.float64)
long_sz = np.array([500.0 + 20.0 * math.sin(i * 0.25) for i in range(n)], dtype=np.float64)
short_sz = np.array([400.0 + 20.0 * math.cos(i * 0.25) for i in range(n)], dtype=np.float64)
# OIPriceDivergence carries a window; update(open_interest, mark_price).
batch = ta.OIPriceDivergence(5).batch(oi, mark)
streamer = ta.OIPriceDivergence(5)
streamed = np.array(
[streamer.update(oi[i], mark[i]) for i in range(n)], dtype=np.float64
)
assert batch.shape == (n,)
assert _eq_nan(batch, streamed)
# OIWeighted; update(mark_price, open_interest).
batch = ta.OIWeighted().batch(mark, oi)
streamer = ta.OIWeighted()
streamed = np.array(
[streamer.update(mark[i], oi[i]) for i in range(n)], dtype=np.float64
)
assert _eq_nan(batch, streamed)
# LongShortRatio; update(long_size, short_size).
batch = ta.LongShortRatio().batch(long_sz, short_sz)
streamer = ta.LongShortRatio()
streamed = np.array(
[streamer.update(long_sz[i], short_sz[i]) for i in range(n)], dtype=np.float64
)
assert _eq_nan(batch, streamed)
# TakerBuySellRatio; update(taker_buy_volume, taker_sell_volume).
batch = ta.TakerBuySellRatio().batch(long_sz, short_sz)
streamer = ta.TakerBuySellRatio()
streamed = np.array(
[streamer.update(long_sz[i], short_sz[i]) for i in range(n)], dtype=np.float64
)
assert _eq_nan(batch, streamed)
def test_liquidation_features_streaming_equals_batch():
n = 30
long_liq = np.array([abs(50.0 * math.sin(i * 0.4)) for i in range(n)], dtype=np.float64)
short_liq = np.array([abs(40.0 * math.cos(i * 0.3)) for i in range(n)], dtype=np.float64)
batch = ta.LiquidationFeatures().batch(long_liq, short_liq)
streamer = ta.LiquidationFeatures()
assert batch.shape == (n, 5)
for i in range(n):
row = streamer.update(long_liq[i], short_liq[i])
assert tuple(batch[i]) == pytest.approx(row)