1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
//! Bollinger %b.
use crate::error::Result;
use crate::traits::Indicator;
use super::BollingerBands;
/// Bollinger %b — where price sits within the Bollinger Bands.
///
/// ```text
/// %b = (price − lower) / (upper − lower)
/// ```
///
/// `%b = 1` means price is exactly on the upper band, `%b = 0` on the lower
/// band, `%b = 0.5` on the middle band. The value is **not** clamped: price
/// breaking above the upper band gives `%b > 1`, breaking below the lower band
/// gives `%b < 0`. That makes %b a clean, scale-free way to compare a price's
/// band position across instruments and to spot band overshoots.
///
/// # Example
///
/// ```
/// use wickra_core::{Indicator, PercentB};
///
/// let mut indicator = PercentB::new(20, 2.0).unwrap();
/// let mut last = None;
/// for i in 0..80 {
/// last = indicator.update(100.0 + (f64::from(i) * 0.3).sin() * 6.0);
/// }
/// assert!(last.is_some());
/// ```
#[derive(Debug, Clone)]
pub struct PercentB {
bands: BollingerBands,
last: Option<f64>,
}
impl PercentB {
/// Construct a new %b indicator.
///
/// # Errors
///
/// Returns [`crate::Error::PeriodZero`] for `period == 0` and
/// [`crate::Error::NonPositiveMultiplier`] for `multiplier <= 0`.
pub fn new(period: usize, multiplier: f64) -> Result<Self> {
Ok(Self {
bands: BollingerBands::new(period, multiplier)?,
last: None,
})
}
/// Configured period.
pub const fn period(&self) -> usize {
self.bands.period()
}
/// Configured multiplier.
pub const fn multiplier(&self) -> f64 {
self.bands.multiplier()
}
/// Current value if available.
pub const fn value(&self) -> Option<f64> {
self.last
}
}
impl Indicator for PercentB {
type Input = f64;
type Output = f64;
fn update(&mut self, input: f64) -> Option<f64> {
let o = self.bands.update(input)?;
let width = o.upper - o.lower;
let percent_b = if width == 0.0 {
// Bands collapsed onto the middle: price is exactly mid-band.
0.5
} else {
(input - o.lower) / width
};
self.last = Some(percent_b);
Some(percent_b)
}
fn reset(&mut self) {
self.bands.reset();
self.last = None;
}
fn warmup_period(&self) -> usize {
self.bands.warmup_period()
}
fn is_ready(&self) -> bool {
self.last.is_some()
}
fn name(&self) -> &'static str {
"PercentB"
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::traits::BatchExt;
use approx::assert_relative_eq;
#[test]
fn new_rejects_invalid_parameters() {
assert!(PercentB::new(0, 2.0).is_err());
assert!(PercentB::new(20, 0.0).is_err());
assert!(PercentB::new(20, -1.0).is_err());
}
/// Cover the public const accessors `period`, `multiplier`, `value`
/// and the Indicator-impl `warmup_period` + `name` methods. Existing
/// tests only exercise the numeric output of `update` / `batch` /
/// `reset` / `is_ready`, so the five getter bodies (lines 53-65,
/// 90-92, 98-100) were dead.
#[test]
fn accessors_and_metadata() {
let mut pb = PercentB::new(20, 2.0).unwrap();
assert_eq!(pb.period(), 20);
assert_relative_eq!(pb.multiplier(), 2.0, epsilon = 1e-12);
assert_eq!(pb.value(), None);
assert_eq!(pb.warmup_period(), 20);
assert_eq!(pb.name(), "PercentB");
for i in 1..=20 {
pb.update(f64::from(i));
}
assert!(pb.value().is_some());
}
#[test]
fn constant_series_yields_midpoint() {
// Flat prices: bands collapse, price is exactly mid-band -> 0.5.
let mut pb = PercentB::new(5, 2.0).unwrap();
let out = pb.batch(&[100.0; 20]);
for v in out.iter().skip(4).flatten() {
assert_relative_eq!(*v, 0.5, epsilon = 1e-12);
}
}
#[test]
fn matches_bands_definition() {
// %b must equal (price - lower) / (upper - lower) from BollingerBands.
let prices: Vec<f64> = (1..=60)
.map(|i| 100.0 + (f64::from(i) * 0.3).sin() * 8.0)
.collect();
let pb_out = PercentB::new(20, 2.0).unwrap().batch(&prices);
let bands_out = BollingerBands::new(20, 2.0).unwrap().batch(&prices);
for (i, (p, b)) in pb_out.iter().zip(bands_out.iter()).enumerate() {
// Same warmup — emission shape must agree at every index.
assert_eq!(p.is_some(), b.is_some(), "warmup mismatch at index {i}");
if let (Some(pv), Some(bv)) = (p, b) {
let want = (prices[i] - bv.lower) / (bv.upper - bv.lower);
assert_relative_eq!(*pv, want, epsilon = 1e-12);
}
}
}
/// Deterministic price-at-middle assertion. With period=3, multiplier=2,
/// inputs `[1.0, 5.0, 3.0]` give SMA = (1+5+3)/3 = 3.0 at index 2, which
/// equals the third price exactly. The stddev is √(8/3) ≈ 1.633, so the
/// bands have non-zero width (the width==0 fallback at line 77 is NOT
/// taken) and the divide path at line 79 runs. Because price sits on
/// the centre line of symmetric bands, %b lands on exactly 0.5.
///
/// The previous oscillation-based variant of this test never landed
/// `prices[i]` within 1e-9 of the rolling SMA, so its inner
/// `assert_relative_eq!` line was never executed.
#[test]
fn price_at_middle_is_half() {
let mut pb = PercentB::new(3, 2.0).unwrap();
let out = pb.batch(&[1.0, 5.0, 3.0]);
assert_eq!(out[0], None);
assert_eq!(out[1], None);
let v = out[2].expect("warmed up at index 2");
assert_relative_eq!(v, 0.5, epsilon = 1e-12);
}
#[test]
fn reset_clears_state() {
let mut pb = PercentB::new(5, 2.0).unwrap();
pb.batch(&(1..=20).map(f64::from).collect::<Vec<_>>());
assert!(pb.is_ready());
pb.reset();
assert!(!pb.is_ready());
assert_eq!(pb.update(1.0), None);
}
#[test]
fn batch_equals_streaming() {
let prices: Vec<f64> = (1..=80)
.map(|i| 100.0 + (f64::from(i) * 0.3).cos() * 7.0)
.collect();
let batch = PercentB::new(20, 2.0).unwrap().batch(&prices);
let mut b = PercentB::new(20, 2.0).unwrap();
let streamed: Vec<_> = prices.iter().map(|p| b.update(*p)).collect();
assert_eq!(batch, streamed);
}
}