kingchenc
d2f99efd78
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.
148 lines
4.4 KiB
Markdown
148 lines
4.4 KiB
Markdown
# 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.
|