0
# Trend Indicators
1

2
Moving averages and trend-following indicators that smooth price data to identify market direction and trend strength. These indicators are essential for trend analysis and are often used as the basis for other technical indicators.
3

4
## Capabilities
5

6
### Simple Moving Average (SMA)
7

8
Calculates the arithmetic mean of prices over a specified lookback period. The most basic and widely used trend indicator.
9

10
```python { .api }
11
def get_sma(quotes: Iterable[Quote], lookback_periods: int,
12
            candle_part: CandlePart = CandlePart.CLOSE):
13
    """
14
    Simple Moving Average (SMA) is the average of price over a lookback window.
15

16
    Args:
17
        quotes (Iterable[Quote]): Historical price quotes
18
        lookback_periods (int): Number of periods in the lookback window
19
        candle_part (CandlePart): Selected OHLCV part (defaults to CLOSE)
20

21
    Returns:
22
        SMAResults[SMAResult]: Collection of SMA results
23
    """
24
```
25

26
**SMAResult Properties:**
27
- `date` (datetime): Result date
28
- `sma` (Optional[Decimal]): Simple moving average value
29

30
### SMA Analysis
31

32
Enhanced SMA calculation with statistical analysis including Mean Absolute Deviation (MAD), Mean Squared Error (MSE), and Mean Absolute Percentage Error (MAPE).
33

34
```python { .api }
35
def get_sma_analysis(quotes: Iterable[Quote], lookback_periods: int):
36
    """
37
    Simple Moving Average with analysis metrics.
38

39
    Args:
40
        quotes (Iterable[Quote]): Historical price quotes
41
        lookback_periods (int): Number of periods in the lookback window
42

43
    Returns:
44
        SMAAnalysisResults[SMAAnalysisResult]: Collection of SMA analysis results
45
    """
46
```
47

48
**SMAAnalysisResult Properties:**
49
- `date` (datetime): Result date
50
- `sma` (Optional[Decimal]): Simple moving average value
51
- `mad` (Optional[Decimal]): Mean Absolute Deviation
52
- `mse` (Optional[Decimal]): Mean Squared Error
53
- `mape` (Optional[Decimal]): Mean Absolute Percentage Error
54

55
### Exponential Moving Average (EMA)
56

57
Gives more weight to recent prices, making it more responsive to price changes than SMA.
58

59
```python { .api }
60
def get_ema(quotes: Iterable[Quote], lookback_periods: int):
61
    """
62
    Exponential Moving Average (EMA) gives more weight to recent prices.
63

64
    Args:
65
        quotes (Iterable[Quote]): Historical price quotes
66
        lookback_periods (int): Number of periods in the lookback window
67

68
    Returns:
69
        EMAResults[EMAResult]: Collection of EMA results
70
    """
71
```
72

73
**EMAResult Properties:**
74
- `date` (datetime): Result date
75
- `ema` (Optional[Decimal]): Exponential moving average value
76

77
### Weighted Moving Average (WMA)
78

79
Linear weighted moving average where the most recent price has the highest weight, decreasing linearly for older prices.
80

81
```python { .api }
82
def get_wma(quotes: Iterable[Quote], lookback_periods: int):
83
    """
84
    Weighted Moving Average (WMA) applies linear weights to price data.
85

86
    Args:
87
        quotes (Iterable[Quote]): Historical price quotes
88
        lookback_periods (int): Number of periods in the lookback window
89

90
    Returns:
91
        WMAResults[WMAResult]: Collection of WMA results
92
    """
93
```
94

95
**WMAResult Properties:**
96
- `date` (datetime): Result date
97
- `wma` (Optional[Decimal]): Weighted moving average value
98

99
### Hull Moving Average (HMA)
100

101
Fast-responding moving average that reduces lag while maintaining smoothness by using weighted calculations with square roots.
102

103
```python { .api }
104
def get_hma(quotes: Iterable[Quote], lookback_periods: int):
105
    """
106
    Hull Moving Average (HMA) reduces lag while maintaining smoothness.
107

108
    Args:
109
        quotes (Iterable[Quote]): Historical price quotes
110
        lookback_periods (int): Number of periods in the lookback window
111

112
    Returns:
113
        HMAResults[HMAResult]: Collection of HMA results
114
    """
115
```
116

117
**HMAResult Properties:**
118
- `date` (datetime): Result date
119
- `hma` (Optional[Decimal]): Hull moving average value
120

121
### Double Exponential Moving Average (DEMA)
122

123
Applies exponential smoothing twice to reduce lag while maintaining smoothness.
124

125
```python { .api }
126
def get_dema(quotes: Iterable[Quote], lookback_periods: int):
127
    """
128
    Double Exponential Moving Average (DEMA) applies exponential smoothing twice.
129

130
    Args:
131
        quotes (Iterable[Quote]): Historical price quotes
132
        lookback_periods (int): Number of periods in the lookback window
133

134
    Returns:
135
        DEMAResults[DEMAResult]: Collection of DEMA results
136
    """
137
```
138

139
**DEMAResult Properties:**
140
- `date` (datetime): Result date
141
- `dema` (Optional[Decimal]): Double exponential moving average value
142

143
### Triple Exponential Moving Average (TEMA)
144

145
Applies exponential smoothing three times for even smoother results with reduced lag.
146

147
```python { .api }
148
def get_tema(quotes: Iterable[Quote], lookback_periods: int):
149
    """
150
    Triple Exponential Moving Average (TEMA) applies exponential smoothing three times.
151

152
    Args:
153
        quotes (Iterable[Quote]): Historical price quotes
154
        lookback_periods (int): Number of periods in the lookback window
155

156
    Returns:
157
        TEMAResults[TEMAResult]: Collection of TEMA results
158
    """
159
```
160

161
**TEMAResult Properties:**
162
- `date` (datetime): Result date
163
- `tema` (Optional[Decimal]): Triple exponential moving average value
164

165
### T3 Moving Average
166

167
Tim Tillson's T3 moving average designed to be smoother than traditional moving averages while reducing lag.
168

169
```python { .api }
170
def get_t3(quotes: Iterable[Quote], lookback_periods: int = 5, volume_factor: float = 0.7):
171
    """
172
    T3 Moving Average designed to be smoother with reduced lag.
173

174
    Args:
175
        quotes (Iterable[Quote]): Historical price quotes
176
        lookback_periods (int): Number of periods in the lookback window (defaults to 5)
177
        volume_factor (float): Volume factor for smoothing (defaults to 0.7)
178

179
    Returns:
180
        T3Results[T3Result]: Collection of T3 results
181
    """
182
```
183

184
**T3Result Properties:**
185
- `date` (datetime): Result date
186
- `t3` (Optional[Decimal]): T3 moving average value
187

188
### Kaufman's Adaptive Moving Average (KAMA)
189

190
Adaptive moving average that adjusts its smoothing based on market volatility and noise.
191

192
```python { .api }
193
def get_kama(quotes: Iterable[Quote], er_periods: int = 10, fast_periods: int = 2, slow_periods: int = 30):
194
    """
195
    Kaufman's Adaptive Moving Average (KAMA) adapts to market conditions.
196

197
    Args:
198
        quotes (Iterable[Quote]): Historical price quotes
199
        er_periods (int): Efficiency Ratio periods (defaults to 10)
200
        fast_periods (int): Fast EMA constant periods (defaults to 2)
201
        slow_periods (int): Slow EMA constant periods (defaults to 30)
202

203
    Returns:
204
        KAMAResults[KAMAResult]: Collection of KAMA results
205
    """
206
```
207

208
**KAMAResult Properties:**
209
- `date` (datetime): Result date
210
- `kama` (Optional[Decimal]): KAMA value
211
- `efficiency_ratio` (Optional[float]): Efficiency ratio
212

213
### MESA Adaptive Moving Average (MAMA)
214

215
Adaptive moving average based on Hilbert Transform using MESA algorithms to adapt to market cycles.
216

217
```python { .api }
218
def get_mama(quotes: Iterable[Quote], fast_limit: float = 0.5, slow_limit: float = 0.05):
219
    """
220
    MESA Adaptive Moving Average (MAMA) using Hilbert Transform.
221

222
    Args:
223
        quotes (Iterable[Quote]): Historical price quotes
224
        fast_limit (float): Fast limit parameter (defaults to 0.5)
225
        slow_limit (float): Slow limit parameter (defaults to 0.05)
226

227
    Returns:
228
        MAMAResults[MAMAResult]: Collection of MAMA results
229
    """
230
```
231

232
**MAMAResult Properties:**
233
- `date` (datetime): Result date
234
- `mama` (Optional[Decimal]): MAMA value
235
- `fama` (Optional[Decimal]): Following Adaptive Moving Average (FAMA) value
236

237
### Arnaud Legoux Moving Average (ALMA)
238

239
Moving average designed to have less lag and be more responsive while reducing noise.
240

241
```python { .api }
242
def get_alma(quotes: Iterable[Quote], lookback_periods: int = 9, offset: float = 0.85, sigma: float = 6.0):
243
    """
244
    Arnaud Legoux Moving Average (ALMA) with reduced lag and noise.
245

246
    Args:
247
        quotes (Iterable[Quote]): Historical price quotes
248
        lookback_periods (int): Number of periods in the lookback window (defaults to 9)
249
        offset (float): Offset parameter (defaults to 0.85)
250
        sigma (float): Sigma parameter for smoothing (defaults to 6.0)
251

252
    Returns:
253
        ALMAResults[ALMAResult]: Collection of ALMA results
254
    """
255
```
256

257
**ALMAResult Properties:**
258
- `date` (datetime): Result date
259
- `alma` (Optional[Decimal]): ALMA value
260

261
### Endpoint Moving Average (EPMA)
262

263
Linear regression-based moving average that uses the endpoint of linear regression as the moving average value.
264

265
```python { .api }
266
def get_epma(quotes: Iterable[Quote], lookback_periods: int):
267
    """
268
    Endpoint Moving Average (EPMA) based on linear regression endpoint.
269

270
    Args:
271
        quotes (Iterable[Quote]): Historical price quotes
272
        lookback_periods (int): Number of periods in the lookback window
273

274
    Returns:
275
        EPMAResults[EPMAResult]: Collection of EPMA results
276
    """
277
```
278

279
**EPMAResult Properties:**
280
- `date` (datetime): Result date
281
- `epma` (Optional[Decimal]): EPMA value
282

283
### Smoothed Moving Average (SMMA)
284

285
Also known as Modified Moving Average (MMA), applies exponential smoothing with a smoothing factor.
286

287
```python { .api }
288
def get_smma(quotes: Iterable[Quote], lookback_periods: int):
289
    """
290
    Smoothed Moving Average (SMMA) using exponential smoothing.
291

292
    Args:
293
        quotes (Iterable[Quote]): Historical price quotes
294
        lookback_periods (int): Number of periods in the lookback window
295

296
    Returns:
297
        SMMAResults[SMMAResult]: Collection of SMMA results
298
    """
299
```
300

301
**SMMAResult Properties:**
302
- `date` (datetime): Result date
303
- `smma` (Optional[Decimal]): SMMA value
304

305
### Volume Weighted Moving Average (VWMA)
306

307
Moving average weighted by trading volume, giving more importance to periods with higher volume.
308

309
```python { .api }
310
def get_vwma(quotes: Iterable[Quote], lookback_periods: int):
311
    """
312
    Volume Weighted Moving Average (VWMA) weighted by trading volume.
313

314
    Args:
315
        quotes (Iterable[Quote]): Historical price quotes
316
        lookback_periods (int): Number of periods in the lookback window
317

318
    Returns:
319
        VWMAResults[VWMAResult]: Collection of VWMA results
320
    """
321
```
322

323
**VWMAResult Properties:**
324
- `date` (datetime): Result date
325
- `vwma` (Optional[Decimal]): VWMA value
326

327
## Usage Examples
328

329
### Basic Moving Average Comparison
330

331
```python
332
from stock_indicators.indicators import get_sma, get_ema, get_hma
333
from stock_indicators.indicators.common import Quote
334

335
# Calculate different moving averages for comparison
336
sma_20 = get_sma(quotes, lookback_periods=20)
337
ema_20 = get_ema(quotes, lookback_periods=20)
338
hma_20 = get_hma(quotes, lookback_periods=20)
339

340
# Compare the latest values
341
latest_sma = sma_20[-1].sma
342
latest_ema = ema_20[-1].ema
343
latest_hma = hma_20[-1].hma
344

345
print(f"SMA: {latest_sma}, EMA: {latest_ema}, HMA: {latest_hma}")
346
```
347

348
### Adaptive Moving Average with Market Conditions
349

350
```python
351
from stock_indicators.indicators import get_kama
352

353
# KAMA adapts to market volatility
354
kama_results = get_kama(quotes, er_periods=14, fast_periods=2, slow_periods=30)
355

356
# Analyze efficiency ratio to understand market conditions
357
for result in kama_results[-10:]:  # Last 10 periods
358
    if result.efficiency_ratio is not None:
359
        market_condition = "Trending" if result.efficiency_ratio > 0.3 else "Sideways"
360
        print(f"Date: {result.date}, KAMA: {result.kama}, Market: {market_condition}")
361
```
362

363
### Volume-Weighted Analysis
364

365
```python
366
from stock_indicators.indicators import get_vwma, get_sma
367

368
# Compare volume-weighted vs regular moving average
369
vwma_20 = get_vwma(quotes, lookback_periods=20)
370
sma_20 = get_sma(quotes, lookback_periods=20)
371

372
# Identify periods where volume emphasis makes a difference
373
for i in range(len(vwma_20)):
374
    if vwma_20[i].vwma and sma_20[i].sma:
375
        diff_pct = abs(vwma_20[i].vwma - sma_20[i].sma) / sma_20[i].sma * 100
376
        if diff_pct > 1.0:  # More than 1% difference
377
            print(f"Date: {vwma_20[i].date}, VWMA: {vwma_20[i].vwma}, SMA: {sma_20[i].sma}, Diff: {diff_pct:.2f}%")
378
```