mirror of
https://github.com/mihakralj/QuanTAlib.git
synced 2026-07-30 18:47:42 +00:00
Miha Kralj
130 lines
5.3 KiB
Markdown
130 lines
5.3 KiB
Markdown
# BBWP: Bollinger Band Width Percentile
|
|
|
|
> *Where does current volatility rank in the historical distribution? BBWP answers with a percentile.*
|
|
|
|
| Property | Value |
|
|
| ---------------- | -------------------------------- |
|
|
| **Category** | Volatility |
|
|
| **Inputs** | Source (close) |
|
|
| **Parameters** | `period`, `multiplier` (default 2.0), `lookback` (default 252) |
|
|
| **Outputs** | Single series (Bbwp) |
|
|
| **Output range** | $\geq 0$ |
|
|
| **Warmup** | `period + lookback` bars |
|
|
| **PineScript** | [bbwp.pine](bbwp.pine) |
|
|
|
|
- BBWP (Bollinger Band Width Percentile) measures where the current Bollinger Band Width falls within its historical distribution, expressing the res...
|
|
- **Similar:** [BBW](../bbw/bbw.md) | **Complementary:** Percentile rank | **Trading note:** BandWidth Percentile; ranks current width in historical context.
|
|
- Validated against TA-Lib, Skender, and Tulip reference implementations where available.
|
|
|
|
BBWP (Bollinger Band Width Percentile) measures where the current Bollinger Band Width falls within its historical distribution, expressing the result as a percentile rank between 0 and 1. Unlike BBWN which normalizes using min/max values, BBWP uses percentile ranking which is more robust to outliers.
|
|
|
|
## Historical Context
|
|
|
|
BBWP evolved from the need for a more statistically robust volatility indicator than simple min/max normalization. While BBWN can be heavily influenced by a single extreme BBW value in the lookback period, BBWP counts how many historical values fall below the current reading, providing a true percentile rank that is less sensitive to outliers.
|
|
|
|
The percentile approach aligns with standard statistical practice for comparing a value to a distribution, making BBWP particularly useful for:
|
|
- Identifying volatility regime changes
|
|
- Setting dynamic stop-loss levels based on historical volatility context
|
|
- Generating signals when volatility reaches extreme percentiles (e.g., below 10th or above 90th percentile)
|
|
|
|
## Architecture & Physics
|
|
|
|
### 1. BBW Calculation (inherited from BBW)
|
|
|
|
$$
|
|
BBW_t = 2 \cdot k \cdot \sigma_t
|
|
$$
|
|
|
|
where:
|
|
- $k$ = standard deviation multiplier (default 2.0)
|
|
- $\sigma_t$ = population standard deviation over period $n$
|
|
|
|
### 2. Percentile Ranking
|
|
|
|
$$
|
|
BBWP_t = \frac{\text{count}(BBW_i < BBW_t)}{N}
|
|
$$
|
|
|
|
where:
|
|
- $BBW_i$ = historical BBW values in the lookback window
|
|
- $N$ = total count of BBW values in lookback
|
|
- The count includes only values strictly less than $BBW_t$
|
|
|
|
### 3. Edge Cases
|
|
|
|
When insufficient history exists ($N < 2$), BBWP returns 0.5 (median) as a neutral default.
|
|
|
|
## Mathematical Foundation
|
|
|
|
### Standard Deviation (Population)
|
|
|
|
$$
|
|
\sigma = \sqrt{\frac{1}{n}\sum_{i=1}^{n}(x_i - \bar{x})^2}
|
|
$$
|
|
|
|
Using Welford's running algorithm:
|
|
$$
|
|
\sigma = \sqrt{\frac{\sum x^2}{n} - \left(\frac{\sum x}{n}\right)^2}
|
|
$$
|
|
|
|
### Percentile Rank Formula
|
|
|
|
For a value $v$ in a dataset of $N$ values:
|
|
$$
|
|
\text{Percentile} = \frac{\text{count of values} < v}{N}
|
|
$$
|
|
|
|
This is the "exclusive" percentile definition (values strictly less than $v$).
|
|
|
|
## Performance Profile
|
|
|
|
### Operation Count (Streaming Mode, per bar)
|
|
|
|
| Operation | Count | Notes |
|
|
|:---|:---:|:---|
|
|
| ADD/SUB | 4 | Running sum/sumSq update |
|
|
| MUL | 2 | Square calculations |
|
|
| DIV | 3 | Mean, variance, percentile |
|
|
| SQRT | 1 | Standard deviation |
|
|
| CMP | L | Lookback comparisons for percentile |
|
|
| **Total** | **~L+10** | Dominated by lookback size |
|
|
|
|
where L = lookback period (default 252)
|
|
|
|
### Quality Metrics
|
|
|
|
| Metric | Score | Notes |
|
|
|:---|:---:|:---|
|
|
| **Accuracy** | 10/10 | Exact percentile calculation |
|
|
| **Robustness** | 9/10 | More outlier-resistant than BBWN |
|
|
| **Timeliness** | 8/10 | Reflects current position in distribution |
|
|
| **Interpretability** | 10/10 | True statistical percentile |
|
|
|
|
## Validation
|
|
|
|
| Library | Status | Notes |
|
|
|:---|:---:|:---|
|
|
| **TA-Lib** | N/A | Not implemented |
|
|
| **Skender** | N/A | Not implemented |
|
|
| **Tulip** | N/A | Not implemented |
|
|
| **Ooples** | N/A | Not implemented |
|
|
| **Internal** | ✅ | Validated against PineScript reference |
|
|
|
|
## Common Pitfalls
|
|
|
|
1. **Interpretation difference from BBWN**: BBWP of 0.80 means 80% of historical BBW values were lower, not that BBW is at 80% of its range. These can differ significantly when the distribution is skewed.
|
|
|
|
2. **Lookback period impact**: Shorter lookbacks (e.g., 50) respond faster but may miss longer-term volatility regimes. Standard practice uses 252 (trading days in a year) for daily data.
|
|
|
|
3. **Warmup period**: Requires period + lookback bars for statistically meaningful percentiles. Early values default to 0.5.
|
|
|
|
4. **Zero volatility**: When all prices are identical, BBW=0 and the percentile of 0 among all 0s is 0 (nothing is below 0).
|
|
|
|
5. **Computational cost**: The percentile calculation requires O(L) comparisons per bar, which can be noticeable for very large lookback values.
|
|
|
|
6. **Distribution assumptions**: BBWP makes no assumptions about the underlying distribution of BBW values, which is both a strength (non-parametric) and a consideration (may not capture extreme tail behavior well).
|
|
|
|
## References
|
|
|
|
- Bollinger, J. (2001). "Bollinger on Bollinger Bands." McGraw-Hill.
|
|
- QuanTAlib PineScript reference implementation (bbwp.pine) |