0
# Moving Window Functions
1

2
High-performance moving window operations for time series analysis and sequential data processing. These functions support customizable window sizes, minimum count requirements, and deliver substantial performance improvements over equivalent NumPy implementations.
3

4
## Capabilities
5

6
### Moving Aggregation Functions
7

8
Compute rolling statistics over sliding windows with NaN-aware implementations.
9

10
```python { .api }
11
def move_sum(a, window, min_count=None, axis=-1):
12
    """
13
    Moving sum over specified window size.
14

15
    Parameters:
16
    - a: array_like, input array
17
    - window: int, size of moving window
18
    - min_count: int or None, minimum number of valid values in window (default: window)
19
    - axis: int, axis along which to move (default: -1)
20

21
    Returns:
22
    ndarray, moving sum values
23
    """
24

25
def move_mean(a, window, min_count=None, axis=-1):
26
    """
27
    Moving arithmetic mean over specified window size.
28

29
    Parameters:
30
    - a: array_like, input array
31
    - window: int, size of moving window
32
    - min_count: int or None, minimum number of valid values in window (default: window)
33
    - axis: int, axis along which to move (default: -1)
34

35
    Returns:
36
    ndarray, moving mean values
37
    """
38
```
39

40
### Moving Dispersion Functions
41

42
Calculate rolling standard deviation and variance measures.
43

44
```python { .api }
45
def move_std(a, window, min_count=None, axis=-1, ddof=0):
46
    """
47
    Moving standard deviation over specified window size.
48

49
    Parameters:
50
    - a: array_like, input array
51
    - window: int, size of moving window
52
    - min_count: int or None, minimum number of valid values in window (default: window)
53
    - axis: int, axis along which to move (default: -1)
54
    - ddof: int, delta degrees of freedom (default: 0)
55

56
    Returns:
57
    ndarray, moving standard deviation values
58
    """
59

60
def move_var(a, window, min_count=None, axis=-1, ddof=0):
61
    """
62
    Moving variance over specified window size.
63

64
    Parameters:
65
    - a: array_like, input array
66
    - window: int, size of moving window
67
    - min_count: int or None, minimum number of valid values in window (default: window)
68
    - axis: int, axis along which to move (default: -1)
69
    - ddof: int, delta degrees of freedom (default: 0)
70

71
    Returns:
72
    ndarray, moving variance values
73
    """
74
```
75

76
### Moving Extrema Functions
77

78
Find minimum and maximum values within moving windows, including index locations.
79

80
```python { .api }
81
def move_min(a, window, min_count=None, axis=-1):
82
    """
83
    Moving minimum over specified window size.
84

85
    Parameters:
86
    - a: array_like, input array
87
    - window: int, size of moving window
88
    - min_count: int or None, minimum number of valid values in window (default: window)
89
    - axis: int, axis along which to move (default: -1)
90

91
    Returns:
92
    ndarray, moving minimum values
93
    """
94

95
def move_max(a, window, min_count=None, axis=-1):
96
    """
97
    Moving maximum over specified window size.
98

99
    Parameters:
100
    - a: array_like, input array
101
    - window: int, size of moving window
102
    - min_count: int or None, minimum number of valid values in window (default: window)
103
    - axis: int, axis along which to move (default: -1)
104

105
    Returns:
106
    ndarray, moving maximum values
107
    """
108

109
def move_argmin(a, window, min_count=None, axis=-1):
110
    """
111
    Moving indices of minimum values over specified window size.
112

113
    Parameters:
114
    - a: array_like, input array
115
    - window: int, size of moving window
116
    - min_count: int or None, minimum number of valid values in window (default: window)
117
    - axis: int, axis along which to move (default: -1)
118

119
    Returns:
120
    ndarray, indices of moving minimum values within each window
121
    """
122

123
def move_argmax(a, window, min_count=None, axis=-1):
124
    """
125
    Moving indices of maximum values over specified window size.
126

127
    Parameters:
128
    - a: array_like, input array
129
    - window: int, size of moving window
130
    - min_count: int or None, minimum number of valid values in window (default: window)
131
    - axis: int, axis along which to move (default: -1)
132

133
    Returns:
134
    ndarray, indices of moving maximum values within each window
135
    """
136
```
137

138
### Moving Order Statistics
139

140
Compute moving median and ranking statistics.
141

142
```python { .api }
143
def move_median(a, window, min_count=None, axis=-1):
144
    """
145
    Moving median over specified window size.
146

147
    Parameters:
148
    - a: array_like, input array
149
    - window: int, size of moving window
150
    - min_count: int or None, minimum number of valid values in window (default: window)
151
    - axis: int, axis along which to move (default: -1)
152

153
    Returns:
154
    ndarray, moving median values
155
    """
156

157
def move_rank(a, window, min_count=None, axis=-1):
158
    """
159
    Moving rank of the last element in each window.
160

161
    Rank is normalized to be between -1 and 1, where -1 indicates the last element
162
    is the minimum in the window, 1 indicates it's the maximum, and 0 indicates
163
    it's the median.
164

165
    Parameters:
166
    - a: array_like, input array
167
    - window: int, size of moving window
168
    - min_count: int or None, minimum number of valid values in window (default: window)
169
    - axis: int, axis along which to move (default: -1)
170

171
    Returns:
172
    ndarray, normalized rank of last element in each window (-1 to 1)
173
    """
174
```
175

176
## Usage Examples
177

178
### Time Series Analysis
179

180
```python
181
import bottleneck as bn
182
import numpy as np
183

184
# Sample time series data with some missing values
185
prices = np.array([100, 102, np.nan, 98, 101, 103, 97, 105, np.nan, 99])
186

187
# Calculate moving averages with different window sizes
188
ma_3 = bn.move_mean(prices, window=3, min_count=2)
189
ma_5 = bn.move_mean(prices, window=5, min_count=3)
190

191
# Moving standard deviation for volatility analysis
192
volatility = bn.move_std(prices, window=5, min_count=3)
193

194
# Moving min/max for support/resistance levels
195
support = bn.move_min(prices, window=5, min_count=3)
196
resistance = bn.move_max(prices, window=5, min_count=3)
197

198
print("Original prices:", prices)
199
print("3-period MA:   ", ma_3)
200
print("5-period MA:   ", ma_5)
201
print("Volatility:    ", volatility)
202
```
203

204
### Signal Processing
205

206
```python
207
import bottleneck as bn
208
import numpy as np
209

210
# Generate noisy signal
211
t = np.linspace(0, 4*np.pi, 100)
212
signal = np.sin(t) + 0.3 * np.random.randn(100)
213

214
# Apply moving window smoothing
215
window_size = 5
216
smoothed = bn.move_mean(signal, window=window_size, min_count=1)
217

218
# Calculate moving statistics for signal analysis
219
rolling_std = bn.move_std(signal, window=window_size, min_count=1)
220
rolling_median = bn.move_median(signal, window=window_size, min_count=1)
221

222
# Detect signal extremes using moving min/max
223
local_mins = bn.move_min(signal, window=window_size, min_count=1)
224
local_maxs = bn.move_max(signal, window=window_size, min_count=1)
225
```
226

227
### Financial Technical Analysis
228

229
```python
230
import bottleneck as bn
231
import numpy as np
232

233
# Stock price data
234
prices = np.array([45.5, 46.2, 47.1, 46.8, 47.5, 48.2, 47.9, 49.1, 48.7, 49.5])
235

236
# Simple moving average (SMA)
237
sma_5 = bn.move_mean(prices, window=5, min_count=1)
238

239
# Bollinger Bands calculation
240
window = 5
241
rolling_mean = bn.move_mean(prices, window=window, min_count=1)
242
rolling_std = bn.move_std(prices, window=window, min_count=1)
243
upper_band = rolling_mean + 2 * rolling_std
244
lower_band = rolling_mean - 2 * rolling_std
245

246
# Rate of change using moving windows
247
roc_3 = (prices / bn.move_mean(prices, window=3, min_count=1) - 1) * 100
248

249
# Moving rank for momentum analysis  
250
momentum = bn.move_rank(prices, window=5, min_count=3)
251

252
print("Prices:      ", prices)
253
print("SMA(5):      ", sma_5)
254
print("Upper Band:  ", upper_band)
255
print("Lower Band:  ", lower_band)
256
print("Momentum:    ", momentum)
257
```
258

259
### Multi-dimensional Data
260

261
```python
262
import bottleneck as bn
263
import numpy as np
264

265
# Multi-dimensional time series (e.g., multiple sensors)
266
data = np.random.randn(3, 20)  # 3 sensors, 20 time points
267
data[:, [5, 12, 17]] = np.nan  # Add some missing values
268

269
# Moving statistics along time axis (axis=1)
270
moving_avg = bn.move_mean(data, window=5, min_count=3, axis=1)
271
moving_vol = bn.move_std(data, window=5, min_count=3, axis=1)
272

273
# Moving statistics along sensor axis (axis=0)
274
cross_sensor_avg = bn.move_mean(data, window=2, min_count=1, axis=0)
275

276
print("Original shape:", data.shape)
277
print("Moving avg shape:", moving_avg.shape)
278
print("Cross-sensor avg shape:", cross_sensor_avg.shape)
279
```
280

281
## Performance Characteristics
282

283
Moving window functions provide exceptional performance improvements:
284

285
- **10x to 1000x faster** than equivalent NumPy implementations
286
- **Memory efficient**: Optimized algorithms minimize memory allocation
287
- **NaN handling**: Automatic handling of missing values without performance penalty
288
- **Flexible parameters**: `min_count` allows partial windows at boundaries
289

290
The performance advantage is most pronounced for:
291
- Large arrays (1000+ elements)
292
- Small to medium window sizes (2-50 elements)  
293
- Repeated operations on similar data
294
- Time series with irregular missing data patterns