F13c: restructure the indicator catalogue into eight families
The original taxonomy was four classical families plus a statistics group, with the F1-F12 expansion slotted in as sub-categories. This regroups the whole 71-indicator catalogue into eight top-level families, each with at least five members: Moving Averages (12), Momentum Oscillators (13), Trend & Directional (9), Price Oscillators (5), Volatility & Bands (12), Trailing Stops (5), Volume (9), Price Statistics (7). - Wiki: docs/wiki/indicators/ reorganised into eight family folders; all 71 indicator pages moved with `git mv`. Every internal cross-link is normalised to `../<family>/Indicator-X.md`, each page's `Family` field is set to its new family, and two pre-existing `../Indicator-Chaining.md` links (should have been `../../`) are corrected. A link check confirms every relative wiki link resolves. - Indicators-Overview.md fully rewritten around the eight families; Home.md indicator reference and the README family table follow suit. - Warmup-Periods.md gains the eight F13 indicators; CHANGELOG records the 46-indicator expansion (25 -> 71) and the eight-family taxonomy. - Tests: Node indicators.test.js and Python test_new_indicators.py cover all eight new indicators (Node 91/91, Python 117/117 green). cargo fmt + clippy (core/wickra/data/wasm/node) clean; 508 core tests, 25 data tests and 74 doctests green.
This commit is contained in:
kingchenc
@@ -0,0 +1,147 @@
|
||||
# PercentB
|
||||
|
||||
> Bollinger %b — where price sits within the Bollinger Bands, scaled so
|
||||
> `0` is the lower band and `1` is the upper band.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Family | Volatility & Bands |
|
||||
| Input type | `f64` (single close) |
|
||||
| Output type | `f64` |
|
||||
| Output range | unbounded (`0` = lower band, `1` = upper band) |
|
||||
| Default parameters | `(period = 20, multiplier = 2.0)` (Python) |
|
||||
| Warmup period | `period` |
|
||||
| Interpretation | Price position in the band; `> 1` / `< 0` = band overshoot. |
|
||||
|
||||
## Formula
|
||||
|
||||
```
|
||||
%b = (price − lower) / (upper − lower)
|
||||
```
|
||||
|
||||
where `upper` and `lower` come from
|
||||
[`BollingerBands`](../volatility-bands/Indicator-BollingerBands.md). `%b = 1` is price exactly
|
||||
on the upper band, `%b = 0` on the lower band, `%b = 0.5` on the middle
|
||||
band. The value is **deliberately not clamped**: a close above the upper
|
||||
band gives `%b > 1`, a close below the lower band gives `%b < 0` — so %b
|
||||
shows band overshoots directly.
|
||||
|
||||
## Parameters
|
||||
|
||||
| Name | Type | Default | Valid range | Description |
|
||||
|--------------|---------|----------------|-------------|-------------|
|
||||
| `period` | `usize` | `20` (Python) | `>= 1` | Bollinger Bands period. `0` errors with `Error::PeriodZero`. |
|
||||
| `multiplier` | `f64` | `2.0` (Python) | `> 0` | Band standard-deviation multiplier. `<= 0` errors with `Error::NonPositiveMultiplier`. |
|
||||
|
||||
The Python binding defaults the pair to `(20, 2.0)`.
|
||||
|
||||
## Inputs / Outputs
|
||||
|
||||
From `crates/wickra-core/src/indicators/percent_b.rs`:
|
||||
|
||||
```rust
|
||||
impl Indicator for PercentB {
|
||||
type Input = f64;
|
||||
type Output = f64;
|
||||
// update(&mut self, input: f64) -> Option<f64>
|
||||
}
|
||||
```
|
||||
|
||||
A single `f64` close in, an `Option<f64>` out. Python maps this to
|
||||
`float | None` / `numpy.ndarray` (NaN warmup); Node to `number | null` /
|
||||
`Array<number>` (NaN warmup).
|
||||
|
||||
## Warmup
|
||||
|
||||
`warmup_period() == period` — identical to the underlying `BollingerBands`.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **Constant series.** Flat prices collapse the bands onto the middle;
|
||||
with zero band width the price is exactly mid-band and %b is reported
|
||||
as `0.5` (`constant_series_yields_midpoint` pins this).
|
||||
- **Band overshoot.** %b is not clamped — values outside `[0, 1]` are
|
||||
expected and meaningful.
|
||||
- **NaN / infinity inputs.** Passed straight to the underlying
|
||||
`BollingerBands`, which drops them.
|
||||
- **Reset.** `pb.reset()` clears the underlying bands.
|
||||
|
||||
## Examples
|
||||
|
||||
### Rust
|
||||
|
||||
```rust
|
||||
use wickra::{BatchExt, Indicator, PercentB};
|
||||
|
||||
fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
let mut pb = PercentB::new(5, 2.0)?;
|
||||
// A flat series: price is exactly mid-band, so %b is 0.5.
|
||||
let out = pb.batch(&[100.0; 20]);
|
||||
println!("{:?}", out[10]);
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
Some(0.5)
|
||||
```
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
import wickra as ta
|
||||
|
||||
pb = ta.PercentB(20, 2.0)
|
||||
prices = np.full(40, 100.0) # flat series -> mid-band
|
||||
print(pb.batch(prices)[-1]) # 0.5
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
0.5
|
||||
```
|
||||
|
||||
### Node
|
||||
|
||||
```javascript
|
||||
const ta = require('wickra');
|
||||
const pb = new ta.PercentB(20, 2.0);
|
||||
const prices = Array.from({ length: 60 }, (_, i) => 100 + Math.sin(i * 0.3) * 6);
|
||||
console.log('warmupPeriod:', pb.warmupPeriod());
|
||||
```
|
||||
|
||||
## Interpretation
|
||||
|
||||
`PercentB` turns "is price near a band?" into a single number. The
|
||||
canonical reads: `%b > 1` is a close above the upper band (strong, often
|
||||
overbought); `%b < 0` is a close below the lower band (weak, often
|
||||
oversold); `%b` crossing `0.5` is price crossing the middle SMA. Because
|
||||
it is normalised, %b is the right input when you want to *compare* band
|
||||
position across instruments, or feed band position into another rule —
|
||||
for example "buy when %b crosses back above 0 from below".
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- **Expecting `[0, 1]` bounds.** %b is intentionally unclamped; values
|
||||
outside `[0, 1]` are the band-overshoot signal, not an error.
|
||||
- **Confusing it with bandwidth.** %b is price *position*;
|
||||
[`BollingerBandwidth`](../volatility-bands/Indicator-BollingerBandwidth.md) is band *width*.
|
||||
|
||||
## References
|
||||
|
||||
John Bollinger, *Bollinger on Bollinger Bands* (2001). %b is one of
|
||||
Bollinger's two derived indicators (with bandwidth).
|
||||
|
||||
## See also
|
||||
|
||||
- [Indicator-BollingerBands.md](../volatility-bands/Indicator-BollingerBands.md) — the bands
|
||||
this locates price within.
|
||||
- [Indicator-BollingerBandwidth.md](../volatility-bands/Indicator-BollingerBandwidth.md) — the
|
||||
companion derived indicator: band *width*.
|
||||
- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
|
||||
Reference in New Issue
Block a user