kingchencandGitHub
d9d3ad18aa
* feat(apo): add Absolute Price Oscillator EMA(close, fast) - EMA(close, slow). Like MACD without the signal EMA. Defaults to (fast = 12, slow = 26); fast must be strictly less than slow. Touchpoints: apo.rs + mod.rs + lib.rs re-export, PyApo + __init__.py + test_new_indicators SCALAR + test_known_values flat reference, ApoNode + index.d.ts/index.js + indicators.test.js factory + reference, WasmApo via scalar macro, scalar-fuzz target, README + CHANGELOG. * fix(apo): add PyApo + ApoNode + WasmApo bindings missed fromec269d8The previous APO commit (ec269d8) only registered APO in the Python __init__.py / Node index.js / Node index.d.ts / fuzz / tests / docs. The actual PyApo pyclass, ApoNode napi class, and WasmApo wasm class edits silently no-op'd because the underlying lib.rs files had been touched by a branch switch between Read and Edit. The bindings were therefore advertising APO from the Python module / Node package / WASM module but not actually exposing it. Fix: insert PyApo block + add_class call in bindings/python/src/lib.rs, ApoNode block in bindings/node/src/lib.rs, WasmApo macro line in bindings/wasm/src/lib.rs. cargo test workspace stays at 615 (no new tests added; the existing test_known_values + indicators.test.js references would have failed at import once the bindings rebuilt without these classes). * feat(ao-histogram): add Awesome Oscillator Histogram AO - SMA(AO, sma_period). A configurable variant of the existing AcceleratorOscillator (which fixes fast=5, slow=34, sma=5). Three parameters; defaults match Bill Williams' Accelerator. Touchpoints: awesome_oscillator_histogram.rs + mod.rs + lib.rs re-export, PyAoHist + __init__.py + test_new_indicators CANDLE_SCALAR + test_known_values flat reference, AwesomeOscillatorHistogramNode + index.d.ts/index.js + indicators.test.js factory + reference, WasmAoHist, candle-fuzz target, README + CHANGELOG. * feat(cfo): add Chande Forecast Oscillator 100 * (close - LinReg(close, period)) / close. Positive when close overshoots the linear forecast, negative when it undershoots. Holds the previous value if the close is zero (percentage form undefined). Single param period (default 14). Touchpoints: cfo.rs + mod.rs + lib.rs re-export, PyCfo + __init__.py + test_new_indicators SCALAR + test_known_values linear reference, CfoNode + index.d.ts/index.js + indicators.test.js factory + reference, WasmCfo via scalar macro, scalar-fuzz target, README + CHANGELOG. * fix(cfo): add WasmCfo binding missed from733afd9* feat(zero-lag-macd): add Zero-Lag MACD Classic MACD topology with ZLEMA substituted for EMA everywhere: faster reaction to trend changes at the cost of slightly noisier readings. Multi-output ZeroLagMacdOutput { macd, signal, histogram }. Three parameters (fast = 12, slow = 26, signal = 9); fast must be strictly less than slow. Touchpoints: zero_lag_macd.rs + mod.rs + lib.rs re-export, PyZeroLagMacd + __init__.py + test_new_indicators MULTI + test_known_values flat reference, ZeroLagMacdNode + ZeroLagMacdValue + index.d.ts/index.js + indicators.test.js multi factory + reference, WasmZeroLagMacd, scalar fuzz with hand-rolled drive (multi-output bypasses the f64-only helper), README + CHANGELOG. * feat(elder-impulse): add Alexander Elder Impulse System Tri-state momentum gauge: +1 (green/buy) when EMA trend and MACD histogram both rise, -1 (red/sell) when both fall, 0 (blue/neutral) on disagreement. Four parameters (ema_period, macd_fast, macd_slow, macd_signal); defaults (13, 12, 26, 9) match Elder. Internally feeds both branches on every input so they warm in parallel; needs one bar past the slowest branch to seed direction state. Touchpoints: elder_impulse.rs + mod.rs + lib.rs re-export, PyElderImpulse + __init__.py + test_new_indicators SCALAR + test_known_values neutral reference, ElderImpulseNode + index.d.ts/index.js + indicators.test.js factory + reference, WasmElderImpulse via scalar macro, scalar-fuzz target, README + CHANGELOG. * feat(stc): add Schaff Trend Cycle Doug Schaff's doubly-Stochastic-smoothed MACD. Bounded [0, 100] reading that reacts faster than MACD by extracting the percentile of MACD within a recent window, half-EMA-smoothing it, and re-stochasing the smoothed series. Four parameters (fast = 23, slow = 50, schaff_period = 10, factor = 0.5); fast must be strictly less than slow and factor must lie in (0, 1]. Output clamped to [0, 100] to absorb floating-point rounding. The stochastic stages clamp to 0 when their rolling range collapses (flat input or perfectly monotone trend), so a flat series settles deterministically at 0 after warmup. Touchpoints: stc.rs + mod.rs + lib.rs re-export, PyStc + __init__.py + test_new_indicators SCALAR + test_known_values flat reference, StcNode + index.d.ts/index.js + indicators.test.js factory + reference, WasmStc via scalar macro, scalar-fuzz target, README + CHANGELOG. * fix(stc): rename last_stc -> last_value to satisfy clippy * ci: Retry setup-node and setup-python on CDN flakes Setup-node on Windows runners and setup-python across all OSes occasionally fail with a silent hang or 5xx mid-download ("Attempting to download 18..." → fail in <1s) — pure upstream CDN flake. The fix ran on this branch's previous merge commit (24e723f) had to be re-triggered manually via `gh run rerun --failed`. Wrap both setup actions with continue-on-error and a follow-up retry step that waits 30s and re-runs the same setup. The retry only fires when the first attempt failed (steps.<id>.outcome == 'failure'), so a green setup costs nothing extra. The retry uses the identical pinned SHA so we still get supply-chain verification on both attempts. Applied to ci.yml (Python matrix and Node matrix). release.yml has the same setup-node / setup-python steps but is rarely re-run, so the existing manual rerun pattern stays sufficient for now. * test(zero-lag-macd): Fix MULTI dict shape mismatch + cover warmup_period ZeroLagMACD was registered in the Python MULTI dict (which asserts a (n, 2) batch shape) but actually emits (n, 3) — macd, signal, histogram — like MACD. Moved out into its own standalone test test_zero_lag_macd_streaming_matches_batch (3-tuple shape), and included in the lifecycle sweep. Mirrors the existing Alligator pattern for 3-output candle indicators. Also adds a unit test for ZeroLagMacd::warmup_period that pins both the (12, 26, 9) classic case and a small-period config — these four lines were the codecov/patch miss on PR 41.
317 lines
15 KiB
Markdown
317 lines
15 KiB
Markdown
# Wickra
|
||
|
||
[](https://github.com/kingchenc/wickra/actions/workflows/ci.yml)
|
||
[](https://codecov.io/gh/kingchenc/wickra)
|
||
[](https://crates.io/crates/wickra)
|
||
[](https://pypi.org/project/wickra/)
|
||
[](https://www.npmjs.com/package/wickra)
|
||
[](LICENSE)
|
||
|
||
**Streaming-first technical indicators. Install with `pip install wickra` — no system dependencies.**
|
||
|
||
Wickra is a multi-language technical-analysis library with a Rust core and
|
||
bindings for Python, Node.js, and WebAssembly. Every indicator is a state
|
||
machine that updates in O(1) per new data point, so live trading bots and
|
||
historical backtests share the exact same implementation.
|
||
|
||
```python
|
||
import numpy as np
|
||
import wickra as ta
|
||
|
||
# Batch: classic TA-Lib-style usage
|
||
prices = np.linspace(100, 200, 1000)
|
||
rsi = ta.RSI(14)
|
||
values = rsi.batch(prices) # numpy array, NaN during warmup
|
||
|
||
# Streaming: same indicator, fed tick by tick
|
||
rsi = ta.RSI(14)
|
||
for price in live_feed:
|
||
value = rsi.update(price) # O(1) — no recomputation over history
|
||
if value is not None and value > 70:
|
||
print("overbought")
|
||
```
|
||
|
||
## Why Wickra exists
|
||
|
||
The Python TA ecosystem has plenty of libraries — TA-Lib, pandas-ta, finta,
|
||
talipp, tulipy — and every one of them shares the same blind spot:
|
||
|
||
| Library | Install pain | Streaming | Multi-language | Active |
|
||
|------------------------|-----------------|-----------|----------------|--------|
|
||
| **★ Wickra** | **clean** | **yes** | **Python + Node + WASM + Rust** | **yes** |
|
||
| TA-Lib (Python) | yes (C deps) | no | no | barely |
|
||
| pandas-ta | clean | no | no | slow |
|
||
| finta | clean | no | no | stale |
|
||
| ta-lib-python | yes (C deps) | no | no | barely |
|
||
| talipp | clean | yes | no | yes |
|
||
| Tulip Indicators | yes (C deps) | no | partial | stale |
|
||
| ooples (C#) | clean | no | C# only | yes |
|
||
|
||
Wickra is the only library that combines all of: clean install, streaming,
|
||
multi-language reach, and active maintenance.
|
||
|
||
## Benchmark: how much faster is "streaming-first"?
|
||
|
||
The numbers below were measured on a single developer workstation and are not
|
||
guaranteed to reproduce identically on different hardware — absolute µs values
|
||
depend on CPU, memory clock and OS scheduler. Read them as **relative
|
||
speedups** between libraries on identical input, not as a universal
|
||
performance contract.
|
||
|
||
- **Reproduced on:** Windows 11 Pro 26200, AMD Ryzen 9 9950X, 64 GB DDR5,
|
||
Rust 1.92 (release profile, `lto = "fat"`, `codegen-units = 1`),
|
||
Python 3.12, Node 20.
|
||
- **Reproduce yourself:** `pip install -e bindings/python[bench]` then
|
||
`python -m benchmarks.compare_libraries`. The script auto-detects every
|
||
installed peer library and runs them on the same generated inputs as
|
||
Wickra. The CI job `cross-library-bench` runs the same script on every
|
||
push and uploads the raw report as a build artefact.
|
||
|
||
Lower µs/op = faster. Wickra wins every batch category outright, and the
|
||
streaming gap widens linearly with how much history a batch-only library has
|
||
to recompute on every tick.
|
||
|
||
### Batch — single full pass over a 20 000-bar series
|
||
|
||
Reading the table: each cell shows that library's runtime, plus how many times
|
||
slower it is than Wickra in parentheses. **★** marks the winner per row.
|
||
|
||
| Indicator | **★ Wickra** | finta | talipp |
|
||
|---------------------|---------------------|-----------------------------|-------------------------------|
|
||
| SMA(20) | **95.6 µs ★** | 343.5 µs (3.6× slower) | 7 640.6 µs (79.9× slower) |
|
||
| EMA(20) | **64.6 µs ★** | 223.1 µs (3.5× slower) | 12 160.9 µs (188.2× slower) |
|
||
| RSI(14) | **126.2 µs ★** | 1 107.1 µs (8.8× slower) | 15 792.2 µs (125.1× slower) |
|
||
| MACD(12, 26, 9) | **119.0 µs ★** | 531.8 µs (4.5× slower) | 49 788.1 µs (418.2× slower) |
|
||
| Bollinger(20, 2.0) | **105.3 µs ★** | 812.0 µs (7.7× slower) | 130 938.3 µs (1 243.7× slower)|
|
||
| ATR(14) | **123.5 µs ★** | 5 144.8 µs (41.7× slower) | 28 816.0 µs (233.4× slower) |
|
||
|
||
### Streaming — per-tick latency after seeding with 5 000 historical bars
|
||
|
||
A batch-only library has to re-run its full indicator over the entire history on
|
||
every new tick; Wickra updates state in O(1).
|
||
|
||
| Indicator | **★ Wickra (per tick)** | talipp (per tick) |
|
||
|-----------|---------------------|---------------------------|
|
||
| RSI(14) | **0.119 µs ★** | 1.644 µs (13.8× slower) |
|
||
|
||
> TA-Lib and pandas-ta are not included here because both fail to install
|
||
> cleanly on Windows without C build tooling — which is precisely the install
|
||
> pain Wickra was built to remove. The benchmark script auto-detects every
|
||
> peer library it can find and runs them on the same inputs as Wickra; install
|
||
> them in your environment to see those rows light up too.
|
||
|
||
Run the suite yourself:
|
||
|
||
```bash
|
||
pip install -e bindings/python[bench]
|
||
python -m benchmarks.compare_libraries
|
||
```
|
||
|
||
## Indicators
|
||
|
||
91 streaming-first indicators across eight families. Every one passes the
|
||
`batch == streaming` equivalence test, reference-value tests, and reset
|
||
semantics tests.
|
||
|
||
| Family | Indicators |
|
||
|--------|-----------|
|
||
| Moving Averages | SMA, EMA, WMA, DEMA, TEMA, HMA, KAMA, SMMA, TRIMA, ZLEMA, T3, VWMA, ALMA, McGinley Dynamic, FRAMA, VIDYA, JMA, Alligator, EVWMA |
|
||
| Momentum Oscillators | RSI (Wilder), Stochastic, CCI, ROC, Williams %R, MFI, Awesome Oscillator, MOM, CMO, TSI, PMO, StochRSI, Ultimate Oscillator, RVI, PGO, KST, SMI, Laguerre RSI, Connors RSI, Inertia |
|
||
| Trend & Directional | MACD, ADX (+DI/-DI), Aroon, TRIX, Aroon Oscillator, Vortex, Mass Index, Choppiness Index, Vertical Horizontal Filter |
|
||
| Price Oscillators | PPO, DPO, Coppock, Accelerator Oscillator, Balance of Power, APO, AO Histogram, CFO, Zero-Lag MACD, Elder Impulse, STC |
|
||
| Volatility & Bands | ATR, Bollinger Bands, Keltner Channels, Donchian Channels, NATR, StdDev, Ulcer Index, Historical Volatility, Bollinger Bandwidth, %B, True Range, Chaikin Volatility |
|
||
| Trailing Stops | Parabolic SAR, SuperTrend, Chandelier Exit, Chande Kroll Stop, ATR Trailing Stop |
|
||
| Volume | OBV, VWAP (cumulative + rolling), ADL, Volume-Price Trend, Chaikin Money Flow, Chaikin Oscillator, Force Index, Ease of Movement |
|
||
| Price Statistics | Typical Price, Median Price, Weighted Close, Linear Regression, Linear Regression Slope, Z-Score, Linear Regression Angle |
|
||
|
||
Adding a new indicator means implementing one trait in Rust; all four bindings
|
||
inherit it automatically.
|
||
|
||
## Languages
|
||
|
||
| Binding | Install | Example |
|
||
|-------------------|-----------------------------------------------|---------|
|
||
| Python (PyO3) | `pip install wickra` | `examples/python/backtest.py` |
|
||
| Node.js (napi-rs) | `npm install wickra` | `examples/node/backtest.js` |
|
||
| Browser / WASM | `npm install wickra-wasm` | `examples/wasm/index.html` |
|
||
| Rust | `cargo add wickra` | `examples/rust/src/bin/backtest.rs` |
|
||
|
||
Each binding ships several runnable examples (streaming, backtest, live feed);
|
||
[`examples/README.md`](examples/README.md) is the full cross-language index.
|
||
|
||
The wickra-core crate is `unsafe`-forbidden, so every binding inherits a
|
||
memory-safe implementation.
|
||
|
||
## Rust API
|
||
|
||
```rust
|
||
use wickra::{Indicator, BatchExt, Chain, Ema, Rsi, Sma};
|
||
|
||
// Streaming or batch — same trait, same code.
|
||
let mut sma = Sma::new(14)?;
|
||
let out: Vec<Option<f64>> = sma.batch(&[1.0, 2.0, 3.0, 4.0, 5.0]);
|
||
|
||
let mut rsi = Rsi::new(14)?;
|
||
for price in live_feed {
|
||
if let Some(v) = rsi.update(price) {
|
||
println!("RSI = {v}");
|
||
}
|
||
}
|
||
|
||
// Compose indicators: RSI(7) on top of EMA(14).
|
||
let mut chain = Chain::new(Ema::new(14)?, Rsi::new(7)?);
|
||
chain.update(price);
|
||
```
|
||
|
||
## Live data sources
|
||
|
||
`wickra-data` (separate crate, opt-in) ships:
|
||
|
||
- A streaming OHLCV **CSV reader**.
|
||
- A **tick-to-candle aggregator** with arbitrary timeframes.
|
||
- A **candle resampler** for multi-timeframe analysis (1m → 5m → 1h on the fly).
|
||
- A **Binance Spot WebSocket** kline adapter (feature `live-binance`).
|
||
|
||
```rust
|
||
use wickra::{Indicator, Rsi};
|
||
use wickra_data::live::binance::{BinanceKlineStream, Interval};
|
||
|
||
let mut stream = BinanceKlineStream::connect(&["BTCUSDT".into()], Interval::OneMinute).await?;
|
||
let mut rsi = Rsi::new(14)?;
|
||
while let Some(event) = stream.next_event().await? {
|
||
if event.is_closed {
|
||
if let Some(v) = rsi.update(event.candle.close) {
|
||
println!("RSI = {v:.2}");
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
A Python live-trading example using the public `websockets` package lives at
|
||
`examples/python/live_trading.py`.
|
||
|
||
## Project layout
|
||
|
||
```
|
||
wickra/
|
||
├── crates/
|
||
│ ├── wickra-core/ core engine + all 85 indicators
|
||
│ ├── wickra/ top-level facade crate (publishes on crates.io) + benches/
|
||
│ └── wickra-data/ CSV reader, tick aggregator, live exchange feeds
|
||
├── bindings/
|
||
│ ├── python/ PyO3 + maturin (publishes on PyPI)
|
||
│ ├── node/ napi-rs (publishes on npm)
|
||
│ └── wasm/ wasm-bindgen (browsers, bundlers, Node)
|
||
├── examples/ examples/README.md indexes every language
|
||
│ ├── data/ real BTCUSDT OHLCV datasets, one per timeframe
|
||
│ ├── rust/ Rust workspace member (`wickra-examples`)
|
||
│ ├── python/ backtest, live trading, parallel assets, multi-tf
|
||
│ ├── node/ streaming, backtest, live trading (load `wickra`)
|
||
│ └── wasm/ browser demo for `wickra-wasm`
|
||
└── .github/workflows/ CI and release pipelines
|
||
```
|
||
|
||
Rust benchmarks live in `crates/wickra/benches/`; runnable Rust examples live
|
||
in the workspace member crate at `examples/rust/`. There is no top-level
|
||
`benches/` directory.
|
||
|
||
## Building everything from source
|
||
|
||
```bash
|
||
# Rust core + tests
|
||
cargo test --workspace
|
||
cargo clippy --workspace --all-targets -- -D warnings
|
||
cargo bench -p wickra
|
||
|
||
# Python binding (requires Rust toolchain + maturin)
|
||
cd bindings/python
|
||
maturin develop --release
|
||
pytest
|
||
|
||
# WASM binding (requires wasm-pack + wasm32-unknown-unknown target)
|
||
wasm-pack build bindings/wasm --target web --release --features panic-hook
|
||
|
||
# Node binding (requires @napi-rs/cli)
|
||
cd bindings/node && npm install && npm run build && npm test
|
||
```
|
||
|
||
## Testing
|
||
|
||
Every layer is covered; run the suites with the commands in
|
||
[Building everything from source](#building-everything-from-source).
|
||
|
||
- `wickra-core`: unit tests per indicator — textbook reference values
|
||
(Wilder RSI, Bollinger Bands, MACD, ATR, Stochastic), `batch == streaming`
|
||
equivalence, `reset` semantics, NaN/Inf handling, and property tests.
|
||
- `wickra-data`: unit tests for CSV decoding, the tick aggregator, the
|
||
resampler, and the Binance payload parser.
|
||
- `bindings/python`: pytest covering smoke checks, streaming/batch
|
||
equivalence, reference values, lifecycle, input validation, and
|
||
dict/tuple candle inputs.
|
||
- `bindings/node`: `node --test` cases for batch, streaming, and reference
|
||
values across all indicators.
|
||
- `bindings/wasm`: `wasm-bindgen-test` cases for constructors, equivalence,
|
||
and reference values.
|
||
|
||
## Contributing
|
||
|
||
Contributions are very welcome — issues, bug reports, ideas, and pull requests
|
||
all land in the same place: <https://github.com/kingchenc/wickra>.
|
||
|
||
A short orientation for first-time contributors:
|
||
|
||
- **Adding an indicator.** Implement the `Indicator` trait in
|
||
`crates/wickra-core/src/indicators/<name>.rs`, wire it into
|
||
`indicators/mod.rs` and the crate root, and add reference-value tests,
|
||
a `batch == streaming` equivalence test, and (where it makes sense) a
|
||
proptest. The four bindings inherit your indicator automatically once
|
||
you expose it in the language wrappers.
|
||
- **Fixing a numeric bug.** Add a failing test that pins the textbook value
|
||
first, then fix the math. Property tests in `crates/wickra-core` catch
|
||
most regressions; please don't disable them.
|
||
- **Improving a binding.** Each binding lives under `bindings/<lang>` with
|
||
its own tests; please keep the `batch == streaming` invariant.
|
||
- **Style.** `cargo fmt --all` + `cargo clippy --workspace --all-targets -- -D warnings`
|
||
are CI gates; running them locally before pushing keeps reviews short.
|
||
|
||
For larger architectural changes, open an issue first so we can sketch the
|
||
shape together before you invest the time.
|
||
|
||
## License
|
||
|
||
Licensed under the **PolyForm Noncommercial License 1.0.0**. See [LICENSE](LICENSE).
|
||
|
||
In plain English: use it, fork it, modify it, redistribute it, file issues, send
|
||
pull requests — all welcome. Personal projects, research, education, non-profits,
|
||
government, hobby trading bots: all fine. The one thing that's not allowed is
|
||
commercial sale of the software or of services built around it. If you want to
|
||
use Wickra commercially, get in touch about a license.
|
||
|
||
## Disclaimer
|
||
|
||
Wickra is an indicator toolkit, not a trading system. Values it computes are
|
||
deterministic transforms of the input data — they are not financial advice and
|
||
they do not predict the market. Any use of this library in a production
|
||
trading context is at your own risk.
|
||
|
||
The library is provided **as is**, without warranty of any kind; see
|
||
[LICENSE](LICENSE) for the full terms.
|
||
|
||
---
|
||
|
||
<p align="center">
|
||
<a href="https://github.com/kingchenc/wickra/stargazers">
|
||
<img alt="GitHub stars" src="https://img.shields.io/github/stars/kingchenc/wickra?style=for-the-badge&logo=github&logoColor=white&color=ffd866">
|
||
</a>
|
||
<a href="https://github.com/kingchenc/wickra/network/members">
|
||
<img alt="GitHub forks" src="https://img.shields.io/github/forks/kingchenc/wickra?style=for-the-badge&logo=github&logoColor=white&color=78dce8">
|
||
</a>
|
||
<a href="https://github.com/kingchenc/wickra/issues">
|
||
<img alt="GitHub issues" src="https://img.shields.io/github/issues/kingchenc/wickra?style=for-the-badge&logo=github&logoColor=white&color=ff6188">
|
||
</a>
|
||
</p>
|
||
|
||
<p align="center">
|
||
If Wickra saved you time, the cheapest way to say thanks is to ⭐ the repo.
|
||
</p>
|