0
# Momentum Indicators
1

2
Oscillators that measure the rate of price change and momentum to identify overbought/oversold conditions, trend strength, and potential reversal points. These indicators typically oscillate between fixed boundaries and are essential for timing market entries and exits.
3

4
## Capabilities
5

6
### Relative Strength Index (RSI)
7

8
Measures the strength of winning versus losing streaks on a scale of 0 to 100, commonly used to identify overbought (>70) and oversold (<30) conditions.
9

10
```python { .api }
11
def get_rsi(quotes: Iterable[Quote], lookback_periods: int = 14):
12
    """
13
    Relative Strength Index (RSI) measures strength of winning/losing streak
14
    over N lookback periods on a scale of 0 to 100.
15

16
    Args:
17
        quotes (Iterable[Quote]): Historical price quotes
18
        lookback_periods (int): Number of periods in the lookback window (defaults to 14)
19

20
    Returns:
21
        RSIResults[RSIResult]: Collection of RSI results
22
    """
23
```
24

25
**RSIResult Properties:**
26
- `date` (datetime): Result date
27
- `rsi` (Optional[Decimal]): RSI value (0-100)
28

29
### Stochastic Oscillator
30

31
Momentum indicator comparing closing price to its price range over a lookback period, producing %K and %D lines with optional %J extension for KDJ analysis.
32

33
```python { .api }
34
def get_stoch(quotes: Iterable[Quote], lookback_periods: int = 14, signal_periods: int = 3, 
35
              smooth_periods: int = 3, k_factor: float = 3, d_factor: float = 2, 
36
              ma_type: MAType = MAType.SMA):
37
    """
38
    Stochastic Oscillator with KDJ indexes - momentum indicator on a scale of 0 to 100.
39

40
    Args:
41
        quotes (Iterable[Quote]): Historical price quotes
42
        lookback_periods (int): Number of periods for the Oscillator (defaults to 14)
43
        signal_periods (int): Smoothing period for the %D signal line (defaults to 3)
44
        smooth_periods (int): Smoothing period for the %K Oscillator (defaults to 3, use 1 for Fast)
45
        k_factor (float): K factor for %J calculation (defaults to 3)
46
        d_factor (float): D factor for %J calculation (defaults to 2)
47
        ma_type (MAType): Moving average type for smoothing (defaults to SMA)
48

49
    Returns:
50
        STOCHResults[STOCHResult]: Collection of Stochastic results
51
    """
52
```
53

54
**STOCHResult Properties:**
55
- `date` (datetime): Result date
56
- `oscillator` (Optional[Decimal]): %K oscillator value (0-100)
57
- `signal` (Optional[Decimal]): %D signal line value (0-100)
58
- `percent_j` (Optional[Decimal]): %J extension value for KDJ analysis
59

60
### Stochastic RSI
61

62
Combines RSI and Stochastic oscillator concepts, applying stochastic calculation to RSI values for enhanced sensitivity.
63

64
```python { .api }
65
def get_stoch_rsi(quotes: Iterable[Quote], rsi_periods: int = 14, stoch_periods: int = 14, 
66
                  signal_periods: int = 3, smooth_periods: int = 1):
67
    """
68
    Stochastic RSI applies stochastic calculation to RSI values for enhanced sensitivity.
69

70
    Args:
71
        quotes (Iterable[Quote]): Historical price quotes
72
        rsi_periods (int): Number of periods for RSI calculation (defaults to 14)
73
        stoch_periods (int): Number of periods for Stochastic calculation (defaults to 14)
74
        signal_periods (int): Smoothing period for signal line (defaults to 3)
75
        smooth_periods (int): Smoothing period for oscillator (defaults to 1)
76

77
    Returns:
78
        StochRSIResults[StochRSIResult]: Collection of Stochastic RSI results
79
    """
80
```
81

82
**StochRSIResult Properties:**
83
- `date` (datetime): Result date
84
- `stoch_rsi` (Optional[Decimal]): Stochastic RSI value (0-100)
85
- `percent_k` (Optional[Decimal]): %K line value
86
- `percent_d` (Optional[Decimal]): %D signal line value
87

88
### MACD (Moving Average Convergence/Divergence)
89

90
Shows the relationship between two moving averages with signal line and histogram for trend and momentum analysis.
91

92
```python { .api }
93
def get_macd(quotes: Iterable[Quote], fast_periods: int = 12, slow_periods: int = 26, 
94
             signal_periods: int = 9, candle_part: CandlePart = CandlePart.CLOSE):
95
    """
96
    Moving Average Convergence/Divergence (MACD) - oscillator view of two
97
    converging/diverging exponential moving averages.
98

99
    Args:
100
        quotes (Iterable[Quote]): Historical price quotes
101
        fast_periods (int): Number of periods in the Fast EMA (defaults to 12)
102
        slow_periods (int): Number of periods in the Slow EMA (defaults to 26)
103
        signal_periods (int): Number of periods for the Signal moving average (defaults to 9)
104
        candle_part (CandlePart): Selected OHLCV part (defaults to CLOSE)
105

106
    Returns:
107
        MACDResults[MACDResult]: Collection of MACD results
108
    """
109
```
110

111
**MACDResult Properties:**
112
- `date` (datetime): Result date
113
- `macd` (Optional[Decimal]): MACD line (fast EMA - slow EMA)
114
- `signal` (Optional[Decimal]): Signal line (EMA of MACD)
115
- `histogram` (Optional[Decimal]): MACD histogram (MACD - Signal)
116
- `fast_ema` (Optional[Decimal]): Fast EMA value
117
- `slow_ema` (Optional[Decimal]): Slow EMA value
118

119
### Connors RSI
120

121
Multi-component momentum oscillator combining RSI, streak analysis, and rate of change for enhanced overbought/oversold signals.
122

123
```python { .api }
124
def get_connors_rsi(quotes: Iterable[Quote], rsi_periods: int = 3, streak_periods: int = 2, 
125
                    rank_periods: int = 100):
126
    """
127
    Connors RSI - multi-component momentum oscillator combining RSI, streak, and rank analysis.
128

129
    Args:
130
        quotes (Iterable[Quote]): Historical price quotes
131
        rsi_periods (int): RSI lookback periods (defaults to 3)
132
        streak_periods (int): Consecutive up/down periods for streak RSI (defaults to 2)
133
        rank_periods (int): Periods for percentile rank of rate of change (defaults to 100)
134

135
    Returns:
136
        ConnorsRSIResults[ConnorsRSIResult]: Collection of Connors RSI results
137
    """
138
```
139

140
**ConnorsRSIResult Properties:**
141
- `date` (datetime): Result date
142
- `rsi_close` (Optional[Decimal]): RSI of closing prices
143
- `rsi_streak` (Optional[Decimal]): RSI of streak values
144
- `percent_rank` (Optional[Decimal]): Percentile rank component
145
- `connors_rsi` (Optional[Decimal]): Combined Connors RSI value (0-100)
146

147
### Rate of Change (ROC)
148

149
Measures the percentage change in price over a specified number of periods.
150

151
```python { .api }
152
def get_roc(quotes: Iterable[Quote], lookback_periods: int):
153
    """
154
    Rate of Change (ROC) measures percentage change in price over lookback periods.
155

156
    Args:
157
        quotes (Iterable[Quote]): Historical price quotes
158
        lookback_periods (int): Number of periods for rate calculation
159

160
    Returns:
161
        ROCResults[ROCResult]: Collection of ROC results
162
    """
163
```
164

165
**ROCResult Properties:**
166
- `date` (datetime): Result date
167
- `roc` (Optional[Decimal]): Rate of change as percentage
168
- `roc_sma` (Optional[Decimal]): Simple moving average of ROC
169

170
### Rate of Change with Band
171

172
ROC with upper and lower bands based on standard deviation for volatility context.
173

174
```python { .api }
175
def get_roc_with_band(quotes: Iterable[Quote], lookback_periods: int, ema_periods: int, 
176
                      std_dev_periods: int):
177
    """
178
    Rate of Change with Bands - ROC with volatility bands.
179

180
    Args:
181
        quotes (Iterable[Quote]): Historical price quotes
182
        lookback_periods (int): Number of periods for ROC calculation
183
        ema_periods (int): EMA periods for center line
184
        std_dev_periods (int): Standard deviation periods for bands
185

186
    Returns:
187
        ROCWBResults[ROCWBResult]: Collection of ROC with Bands results
188
    """
189
```
190

191
**ROCWBResult Properties:**
192
- `date` (datetime): Result date
193
- `roc` (Optional[Decimal]): Rate of change value
194
- `upper_band` (Optional[Decimal]): Upper volatility band
195
- `lower_band` (Optional[Decimal]): Lower volatility band
196

197
### Awesome Oscillator
198

199
Bill Williams' Awesome Oscillator using the difference between 5-period and 34-period simple moving averages of midpoint prices.
200

201
```python { .api }
202
def get_awesome(quotes: Iterable[Quote], fast_periods: int = 5, slow_periods: int = 34):
203
    """
204
    Awesome Oscillator - difference between fast and slow SMAs of midpoint prices.
205

206
    Args:
207
        quotes (Iterable[Quote]): Historical price quotes
208
        fast_periods (int): Fast SMA periods (defaults to 5)
209
        slow_periods (int): Slow SMA periods (defaults to 34)
210

211
    Returns:
212
        AwesomeResults[AwesomeResult]: Collection of Awesome Oscillator results
213
    """
214
```
215

216
**AwesomeResult Properties:**
217
- `date` (datetime): Result date
218
- `oscillator` (Optional[Decimal]): Awesome Oscillator value
219

220
### Commodity Channel Index (CCI)
221

222
Momentum oscillator that identifies cyclical trends and overbought/oversold conditions.
223

224
```python { .api }
225
def get_cci(quotes: Iterable[Quote], lookback_periods: int = 20):
226
    """
227
    Commodity Channel Index (CCI) - momentum oscillator for cyclical trends.
228

229
    Args:
230
        quotes (Iterable[Quote]): Historical price quotes
231
        lookback_periods (int): Number of periods for calculation (defaults to 20)
232

233
    Returns:
234
        CCIResults[CCIResult]: Collection of CCI results
235
    """
236
```
237

238
**CCIResult Properties:**
239
- `date` (datetime): Result date
240
- `cci` (Optional[Decimal]): CCI value (typically between -100 and +100)
241

242
### Chande Momentum Oscillator (CMO)
243

244
Momentum oscillator that uses both up and down price movements in its calculation, similar to RSI but with different scaling.
245

246
```python { .api }
247
def get_cmo(quotes: Iterable[Quote], lookback_periods: int = 14):
248
    """
249
    Chande Momentum Oscillator (CMO) - momentum indicator using up/down movements.
250

251
    Args:
252
        quotes (Iterable[Quote]): Historical price quotes
253
        lookback_periods (int): Number of periods for calculation (defaults to 14)
254

255
    Returns:
256
        CMOResults[CMOResult]: Collection of CMO results
257
    """
258
```
259

260
**CMOResult Properties:**
261
- `date` (datetime): Result date
262
- `cmo` (Optional[Decimal]): CMO value (-100 to +100)
263

264
### Williams %R
265

266
Momentum indicator that measures overbought/oversold levels, similar to Stochastic but with inverted scale.
267

268
```python { .api }
269
def get_williams_r(quotes: Iterable[Quote], lookback_periods: int = 14):
270
    """
271
    Williams %R - momentum indicator measuring overbought/oversold levels.
272

273
    Args:
274
        quotes (Iterable[Quote]): Historical price quotes
275
        lookback_periods (int): Number of periods for calculation (defaults to 14)
276

277
    Returns:
278
        WilliamsResults[WilliamsResult]: Collection of Williams %R results
279
    """
280
```
281

282
**WilliamsResult Properties:**
283
- `date` (datetime): Result date
284
- `williams_r` (Optional[Decimal]): Williams %R value (-100 to 0)
285

286
### Price Momentum Oscillator (PMO)
287

288
Momentum oscillator that double-smooths price rate of change for cleaner signals.
289

290
```python { .api }
291
def get_pmo(quotes: Iterable[Quote], time_periods: int = 35, smoothing_periods: int = 20, 
292
            signal_periods: int = 10):
293
    """
294
    Price Momentum Oscillator (PMO) - double-smoothed rate of change oscillator.
295

296
    Args:
297
        quotes (Iterable[Quote]): Historical price quotes
298
        time_periods (int): Time periods for ROC calculation (defaults to 35)
299
        smoothing_periods (int): Smoothing periods for first EMA (defaults to 20)
300
        signal_periods (int): Signal line EMA periods (defaults to 10)
301

302
    Returns:
303
        PMOResults[PMOResult]: Collection of PMO results
304
    """
305
```
306

307
**PMOResult Properties:**
308
- `date` (datetime): Result date
309
- `pmo` (Optional[Decimal]): PMO oscillator value
310
- `signal` (Optional[Decimal]): PMO signal line
311

312
### Ultimate Oscillator
313

314
Multi-timeframe momentum oscillator that combines short, medium, and long-term price momentum.
315

316
```python { .api }
317
def get_ultimate(quotes: Iterable[Quote], short_periods: int = 7, middle_periods: int = 14, 
318
                 long_periods: int = 28, short_weight: float = 4, middle_weight: float = 2, 
319
                 long_weight: float = 1):
320
    """
321
    Ultimate Oscillator - multi-timeframe momentum combining short, medium, and long periods.
322

323
    Args:
324
        quotes (Iterable[Quote]): Historical price quotes
325
        short_periods (int): Short timeframe periods (defaults to 7)
326
        middle_periods (int): Middle timeframe periods (defaults to 14)
327
        long_periods (int): Long timeframe periods (defaults to 28)
328
        short_weight (float): Weight for short timeframe (defaults to 4)
329
        middle_weight (float): Weight for middle timeframe (defaults to 2)
330
        long_weight (float): Weight for long timeframe (defaults to 1)
331

332
    Returns:
333
        UltimateResults[UltimateResult]: Collection of Ultimate Oscillator results
334
    """
335
```
336

337
**UltimateResult Properties:**
338
- `date` (datetime): Result date
339
- `ultimate` (Optional[Decimal]): Ultimate Oscillator value (0-100)
340

341
### True Strength Index (TSI)
342

343
Double-smoothed momentum oscillator that reduces noise while maintaining sensitivity to price changes.
344

345
```python { .api }
346
def get_tsi(quotes: Iterable[Quote], lookback_periods: int = 25, smooth_periods: int = 13, 
347
            signal_periods: int = 7):
348
    """
349
    True Strength Index (TSI) - double-smoothed momentum oscillator.
350

351
    Args:
352
        quotes (Iterable[Quote]): Historical price quotes
353
        lookback_periods (int): Lookback periods for momentum (defaults to 25)
354
        smooth_periods (int): First smoothing periods (defaults to 13)
355
        signal_periods (int): Signal line smoothing periods (defaults to 7)
356

357
    Returns:
358
        TSIResults[TSIResult]: Collection of TSI results
359
    """
360
```
361

362
**TSIResult Properties:**
363
- `date` (datetime): Result date
364
- `tsi` (Optional[Decimal]): TSI oscillator value
365
- `signal` (Optional[Decimal]): TSI signal line
366

367
### TRIX
368

369
Triple exponentially smoothed moving average oscillator that filters out short-term price movements.
370

371
```python { .api }
372
def get_trix(quotes: Iterable[Quote], lookback_periods: int = 14, signal_periods: int = 9):
373
    """
374
    TRIX - triple exponentially smoothed moving average oscillator.
375

376
    Args:
377
        quotes (Iterable[Quote]): Historical price quotes
378
        lookback_periods (int): Number of periods for TRIX calculation (defaults to 14)
379
        signal_periods (int): Signal line EMA periods (defaults to 9)
380

381
    Returns:
382
        TRIXResults[TRIXResult]: Collection of TRIX results
383
    """
384
```
385

386
**TRIXResult Properties:**
387
- `date` (datetime): Result date
388
- `ema1` (Optional[Decimal]): First EMA value
389
- `ema2` (Optional[Decimal]): Second EMA value
390
- `ema3` (Optional[Decimal]): Third EMA value
391
- `trix` (Optional[Decimal]): TRIX oscillator value (as percentage)
392
- `signal` (Optional[Decimal]): TRIX signal line
393

394
### Detrended Price Oscillator (DPO)
395

396
Removes trend from price data to focus on shorter-term cycles by comparing price to a displaced moving average.
397

398
```python { .api }
399
def get_dpo(quotes: Iterable[Quote], lookback_periods: int):
400
    """
401
    Detrended Price Oscillator (DPO) - removes trend to focus on cycles.
402

403
    Args:
404
        quotes (Iterable[Quote]): Historical price quotes
405
        lookback_periods (int): Number of periods for moving average calculation
406

407
    Returns:
408
        DPOResults[DPOResult]: Collection of DPO results
409
    """
410
```
411

412
**DPOResult Properties:**
413
- `date` (datetime): Result date
414
- `sma` (Optional[Decimal]): Simple moving average value
415
- `dpo` (Optional[Decimal]): Detrended Price Oscillator value
416

417
## Usage Examples
418

419
### RSI Overbought/Oversold Analysis
420

421
```python
422
from stock_indicators.indicators import get_rsi
423

424
# Calculate RSI with standard 14-period setting
425
rsi_results = get_rsi(quotes, lookback_periods=14)
426

427
# Identify overbought/oversold conditions
428
for result in rsi_results:
429
    if result.rsi is not None:
430
        if result.rsi > 70:
431
            print(f"{result.date}: RSI {result.rsi:.2f} - Overbought")
432
        elif result.rsi < 30:
433
            print(f"{result.date}: RSI {result.rsi:.2f} - Oversold")
434
```
435

436
### MACD Signal Analysis
437

438
```python
439
from stock_indicators.indicators import get_macd
440

441
# Calculate MACD with standard settings
442
macd_results = get_macd(quotes, fast_periods=12, slow_periods=26, signal_periods=9)
443

444
# Look for MACD crossovers
445
previous_result = None
446
for result in macd_results:
447
    if result.macd is not None and result.signal is not None and previous_result:
448
        # Bullish crossover: MACD crosses above signal
449
        if (previous_result.macd <= previous_result.signal and 
450
            result.macd > result.signal):
451
            print(f"{result.date}: Bullish MACD crossover")
452
        # Bearish crossover: MACD crosses below signal  
453
        elif (previous_result.macd >= previous_result.signal and 
454
              result.macd < result.signal):
455
            print(f"{result.date}: Bearish MACD crossover")
456
    previous_result = result
457
```
458

459
### Multi-Indicator Momentum Confirmation
460

461
```python
462
from stock_indicators.indicators import get_rsi, get_stoch, get_cci
463

464
# Calculate multiple momentum indicators
465
rsi_results = get_rsi(quotes, lookback_periods=14)
466
stoch_results = get_stoch(quotes, lookback_periods=14)
467
cci_results = get_cci(quotes, lookback_periods=20)
468

469
# Look for momentum confirmation across indicators
470
for i in range(len(rsi_results)):
471
    rsi_val = rsi_results[i].rsi
472
    stoch_val = stoch_results[i].oscillator
473
    cci_val = cci_results[i].cci
474
    
475
    if rsi_val and stoch_val and cci_val:
476
        # Check for oversold confirmation
477
        oversold_signals = 0
478
        if rsi_val < 30: oversold_signals += 1
479
        if stoch_val < 20: oversold_signals += 1
480
        if cci_val < -100: oversold_signals += 1
481
        
482
        if oversold_signals >= 2:
483
            print(f"{rsi_results[i].date}: Oversold confirmation - {oversold_signals}/3 indicators")
484
```