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

feat(derivatives): leverage, OI/volume, perpetual premium, funding APR, OI momentum (B16) (#214)

Browse Source 
## B16 Derivatives — five new indicators (488 → 493)

All consume a `DerivativesTick` and emit `f64`:

| Indicator | Reads | Formula |
|-----------|-------|---------|
| `EstimatedLeverageRatio` | open_interest, long_size, short_size | `OI / (long + short)` |
| `OiToVolumeRatio` | open_interest, taker_buy_volume, taker_sell_volume | `OI / (buy + sell)` |
| `PerpetualPremiumIndex` | mark_price, index_price | `(mark − index) / index` |
| `FundingImpliedApr` | funding_rate | `rate × intervals_per_year` |
| `OpenInterestMomentum` | open_interest | `100 · (OI_t − OI_{t−period}) / OI_{t−period}` |

### Wiring
- Core structs + full unit tests (incl. zero-denominator branches).
- Hand-written Python/Node/WASM tick bindings; two new tick helpers (`deriv_oi_long_short`, `deriv_oi_taker`).
- Fuzz drives in `indicator_update_derivatives.rs`; dedicated reference + streaming-vs-batch tests (Python + Node).
- README counter + `docs/README.md` + `FAMILIES` assert bumped to 493.

### Verify (local, all green)
- `cargo test -p wickra-core --lib`: 4028 · `--doc`: 443
- clippy workspace: clean
- node: 563 · pytest: 928
This commit is contained in:
kingchenc
2026-06-08 03:33:59 +02:00
committed by GitHub
parent dc415a77fd
commit ff5a047078
19 changed files with 1973 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files
bindings/python/python/wickra/__init__.py
+10
View File
@@ -480,6 +480,11 @@ from ._wickra import (
# Microstructure: footprint
Footprint,
# Derivatives
OpenInterestMomentum,
FundingImpliedApr,
PerpetualPremiumIndex,
OiToVolumeRatio,
EstimatedLeverageRatio,
FundingRate,
FundingRateMean,
FundingRateZScore,
@@ -998,6 +1003,11 @@ __all__ = [
# Microstructure: footprint
"Footprint",
# Derivatives
"OpenInterestMomentum",
"FundingImpliedApr",
"PerpetualPremiumIndex",
"OiToVolumeRatio",
"EstimatedLeverageRatio",
"FundingRate",
"FundingRateMean",
"FundingRateZScore",
bindings/python/src/lib.rs
+345
View File
@@ -19420,6 +19420,50 @@ fn deriv_taker(taker_buy_volume: f64, taker_sell_volume: f64) -> PyResult<wc::De
.map_err(map_err)
}
fn deriv_oi_long_short(
open_interest: f64,
long_size: f64,
short_size: f64,
) -> PyResult<wc::DerivativesTick> {
wc::DerivativesTick::new(
0.0,
1.0,
1.0,
1.0,
open_interest,
long_size,
short_size,
0.0,
0.0,
0.0,
0.0,
0,
)
.map_err(map_err)
}
fn deriv_oi_taker(
open_interest: f64,
taker_buy_volume: f64,
taker_sell_volume: f64,
) -> PyResult<wc::DerivativesTick> {
wc::DerivativesTick::new(
0.0,
1.0,
1.0,
1.0,
open_interest,
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,
@@ -20140,6 +20184,302 @@ impl PyCalendarSpread {
}
}
// Estimated leverage ratio: open interest over aggregate long+short size.
#[pyclass(
name = "EstimatedLeverageRatio",
module = "wickra._wickra",
skip_from_py_object
)]
#[derive(Clone)]
struct PyEstimatedLeverageRatio {
inner: wc::EstimatedLeverageRatio,
}
#[pymethods]
impl PyEstimatedLeverageRatio {
#[new]
fn new() -> Self {
Self {
inner: wc::EstimatedLeverageRatio::new(),
}
}
fn update(
&mut self,
open_interest: f64,
long_size: f64,
short_size: f64,
) -> PyResult<Option<f64>> {
Ok(self
.inner
.update(deriv_oi_long_short(open_interest, long_size, short_size)?))
}
fn batch<'py>(
&mut self,
py: Python<'py>,
open_interest: Vec<f64>,
long_size: Vec<f64>,
short_size: Vec<f64>,
) -> PyResult<Bound<'py, PyArray1<f64>>> {
if open_interest.len() != long_size.len() || long_size.len() != short_size.len() {
return Err(PyValueError::new_err(
"open_interest, long_size, short_size 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_long_short(
open_interest[i],
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 {
"EstimatedLeverageRatio()".to_string()
}
}
// OI-to-volume ratio: open interest over taker buy+sell volume.
#[pyclass(
name = "OiToVolumeRatio",
module = "wickra._wickra",
skip_from_py_object
)]
#[derive(Clone)]
struct PyOiToVolumeRatio {
inner: wc::OiToVolumeRatio,
}
#[pymethods]
impl PyOiToVolumeRatio {
#[new]
fn new() -> Self {
Self {
inner: wc::OiToVolumeRatio::new(),
}
}
fn update(
&mut self,
open_interest: f64,
taker_buy_volume: f64,
taker_sell_volume: f64,
) -> PyResult<Option<f64>> {
Ok(self.inner.update(deriv_oi_taker(
open_interest,
taker_buy_volume,
taker_sell_volume,
)?))
}
fn batch<'py>(
&mut self,
py: Python<'py>,
open_interest: Vec<f64>,
taker_buy_volume: Vec<f64>,
taker_sell_volume: Vec<f64>,
) -> PyResult<Bound<'py, PyArray1<f64>>> {
if open_interest.len() != taker_buy_volume.len()
|| taker_buy_volume.len() != taker_sell_volume.len()
{
return Err(PyValueError::new_err(
"open_interest, taker_buy_volume, taker_sell_volume 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_taker(
open_interest[i],
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 {
"OiToVolumeRatio()".to_string()
}
}
// Perpetual premium index: relative premium of mark over index price.
#[pyclass(
name = "PerpetualPremiumIndex",
module = "wickra._wickra",
skip_from_py_object
)]
#[derive(Clone)]
struct PyPerpetualPremiumIndex {
inner: wc::PerpetualPremiumIndex,
}
#[pymethods]
impl PyPerpetualPremiumIndex {
#[new]
fn new() -> Self {
Self {
inner: wc::PerpetualPremiumIndex::new(),
}
}
fn update(&mut self, mark_price: f64, index_price: f64) -> PyResult<Option<f64>> {
Ok(self.inner.update(deriv_basis(mark_price, index_price)?))
}
fn batch<'py>(
&mut self,
py: Python<'py>,
mark_price: Vec<f64>,
index_price: Vec<f64>,
) -> PyResult<Bound<'py, PyArray1<f64>>> {
if mark_price.len() != index_price.len() {
return Err(PyValueError::new_err(
"mark_price and index_price 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_basis(mark_price[i], index_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 {
"PerpetualPremiumIndex()".to_string()
}
}
// Funding-implied APR: per-interval funding annualised.
#[pyclass(
name = "FundingImpliedApr",
module = "wickra._wickra",
skip_from_py_object
)]
#[derive(Clone)]
struct PyFundingImpliedApr {
inner: wc::FundingImpliedApr,
}
#[pymethods]
impl PyFundingImpliedApr {
#[new]
fn new(intervals_per_year: f64) -> PyResult<Self> {
Ok(Self {
inner: wc::FundingImpliedApr::new(intervals_per_year).map_err(map_err)?,
})
}
fn update(&mut self, funding_rate: f64) -> PyResult<Option<f64>> {
Ok(self.inner.update(deriv_funding(funding_rate)?))
}
fn batch<'py>(
&mut self,
py: Python<'py>,
funding_rate: Vec<f64>,
) -> PyResult<Bound<'py, PyArray1<f64>>> {
let mut out = Vec::with_capacity(funding_rate.len());
for r in funding_rate {
out.push(self.inner.update(deriv_funding(r)?).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!(
"FundingImpliedApr(intervals_per_year={})",
self.inner.intervals_per_year()
)
}
}
// Open-interest momentum: rate-of-change of open interest over a window.
#[pyclass(
name = "OpenInterestMomentum",
module = "wickra._wickra",
skip_from_py_object
)]
#[derive(Clone)]
struct PyOpenInterestMomentum {
inner: wc::OpenInterestMomentum,
}
#[pymethods]
impl PyOpenInterestMomentum {
#[new]
fn new(period: usize) -> PyResult<Self> {
Ok(Self {
inner: wc::OpenInterestMomentum::new(period).map_err(map_err)?,
})
}
fn update(&mut self, open_interest: f64) -> PyResult<Option<f64>> {
Ok(self.inner.update(deriv_oi(open_interest)?))
}
fn batch<'py>(
&mut self,
py: Python<'py>,
open_interest: Vec<f64>,
) -> PyResult<Bound<'py, PyArray1<f64>>> {
let mut out = Vec::with_capacity(open_interest.len());
for oi in open_interest {
out.push(self.inner.update(deriv_oi(oi)?).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!("OpenInterestMomentum(period={})", self.inner.period())
}
}
// ============================== Market Breadth ==============================
//
// Market-breadth indicators consume a `CrossSection`: one tick carrying the
@@ -25029,6 +25369,11 @@ fn _wickra(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
m.add_class::<PyLiquidationFeatures>()?;
m.add_class::<PyTermStructureBasis>()?;
m.add_class::<PyCalendarSpread>()?;
m.add_class::<PyEstimatedLeverageRatio>()?;
m.add_class::<PyOiToVolumeRatio>()?;
m.add_class::<PyPerpetualPremiumIndex>()?;
m.add_class::<PyFundingImpliedApr>()?;
m.add_class::<PyOpenInterestMomentum>()?;
m.add_class::<PyAdvanceDecline>()?;
m.add_class::<PyAdvanceDeclineRatio>()?;
m.add_class::<PyAdVolumeLine>()?;
bindings/python/tests/test_new_indicators.py
+65
View File
@@ -4082,6 +4082,71 @@ def test_basis_indicators_streaming_equals_batch():
assert _eq_nan(batch, streamed)
def test_b16_derivatives_reference():
# Estimated leverage: oi / (long + short) = 200 / 100 = 2.
assert ta.EstimatedLeverageRatio().update(200.0, 60.0, 40.0) == pytest.approx(2.0)
# OI-to-volume: oi / (buy + sell) = 100 / 50 = 2.
assert ta.OiToVolumeRatio().update(100.0, 30.0, 20.0) == pytest.approx(2.0)
# Perpetual premium: (mark - index) / index = 0.5 / 100 = 0.005.
assert ta.PerpetualPremiumIndex().update(100.5, 100.0) == pytest.approx(0.005)
# Funding-implied APR: rate * intervals = 0.0001 * 1095 = 0.1095.
assert ta.FundingImpliedApr(1095.0).update(0.0001) == pytest.approx(0.1095)
# Open-interest momentum (period 2): warmup then ROC% = 100*(120-100)/100 = 20.
oim = ta.OpenInterestMomentum(2)
assert oim.update(100.0) is None
assert oim.update(110.0) is None
assert oim.update(120.0) == pytest.approx(20.0)
def test_b16_derivatives_streaming_equals_batch():
n = 40
oi = np.array([1000.0 + 50.0 * math.sin(i * 0.3) for i in range(n)], dtype=np.float64)
long_sz = np.array([600.0 + 20.0 * math.cos(i * 0.2) for i in range(n)], dtype=np.float64)
short_sz = np.array([400.0 + 15.0 * math.sin(i * 0.4) for i in range(n)], dtype=np.float64)
buy = np.array([300.0 + 10.0 * math.sin(i * 0.5) for i in range(n)], dtype=np.float64)
sell = np.array([250.0 + 12.0 * math.cos(i * 0.35) for i in range(n)], dtype=np.float64)
index = np.array([100.0 + math.sin(i * 0.2) for i in range(n)], dtype=np.float64)
mark = np.array([index[i] + 0.05 * math.cos(i * 0.3) for i in range(n)], dtype=np.float64)
rate = np.array([0.0001 * math.sin(i * 0.3) for i in range(n)], dtype=np.float64)
# EstimatedLeverageRatio; update(open_interest, long_size, short_size).
batch = ta.EstimatedLeverageRatio().batch(oi, long_sz, short_sz)
streamer = ta.EstimatedLeverageRatio()
streamed = np.array(
[streamer.update(oi[i], long_sz[i], short_sz[i]) for i in range(n)], dtype=np.float64
)
assert batch.shape == (n,)
assert _eq_nan(batch, streamed)
# OiToVolumeRatio; update(open_interest, taker_buy_volume, taker_sell_volume).
batch = ta.OiToVolumeRatio().batch(oi, buy, sell)
streamer = ta.OiToVolumeRatio()
streamed = np.array(
[streamer.update(oi[i], buy[i], sell[i]) for i in range(n)], dtype=np.float64
)
assert _eq_nan(batch, streamed)
# PerpetualPremiumIndex; update(mark_price, index_price).
batch = ta.PerpetualPremiumIndex().batch(mark, index)
streamer = ta.PerpetualPremiumIndex()
streamed = np.array(
[streamer.update(mark[i], index[i]) for i in range(n)], dtype=np.float64
)
assert _eq_nan(batch, streamed)
# FundingImpliedApr; update(funding_rate).
batch = ta.FundingImpliedApr(1095.0).batch(rate)
streamer = ta.FundingImpliedApr(1095.0)
streamed = np.array([streamer.update(rate[i]) for i in range(n)], dtype=np.float64)
assert _eq_nan(batch, streamed)
# OpenInterestMomentum; update(open_interest).
batch = ta.OpenInterestMomentum(10).batch(oi)
streamer = ta.OpenInterestMomentum(10)
streamed = np.array([streamer.update(oi[i]) for i in range(n)], dtype=np.float64)
assert _eq_nan(batch, streamed)
# --- Alt-Chart Bars ------------------------------------------------------