0
# Masked Arrays
1

2
Arrays that can contain invalid or missing data. Masked arrays suppress invalid values during operations, allowing for robust statistical and mathematical computations on datasets with missing or undefined values.
3

4
## Capabilities
5

6
### Core Masked Array Classes
7

8
Main classes for creating and working with masked arrays that handle missing or invalid data.
9

10
```python { .api }
11
class MaskedArray:
12
    """N-dimensional array with masked values."""
13
    def __init__(self, data, mask=False, dtype=None, **kwargs): ...
14
    def __array__(self, dtype=None): ...
15
    def __getitem__(self, indx): ...
16
    def __setitem__(self, indx, value): ...
17
    def filled(self, fill_value=None): ...
18
    def compressed(self): ...
19
    def count(self, axis=None, keepdims=False): ...
20
    def sum(self, axis=None, **kwargs): ...
21
    def mean(self, axis=None, **kwargs): ...
22
    def std(self, axis=None, **kwargs): ...
23
    def var(self, axis=None, **kwargs): ...
24
    def min(self, axis=None, **kwargs): ...
25
    def max(self, axis=None, **kwargs): ...
26
    @property
27
    def mask(self): ...
28
    @property
29
    def data(self): ...
30
    @property
31
    def fill_value(self): ...
32

33
def masked_array(data, mask=False, dtype=None, **kwargs):
34
    """
35
    An array class with possibly masked values.
36
    
37
    Parameters:
38
    - data: array_like, input data
39
    - mask: sequence, condition to mask invalid entries
40
    - dtype: dtype, desired data type
41
    - fill_value: scalar, value used to fill masked array
42
    
43
    Returns:
44
    MaskedArray: Masked array object
45
    """
46

47
def array(data, dtype=None, **kwargs):
48
    """
49
    Shortcut to MaskedArray constructor.
50
    
51
    Parameters:
52
    - data: array_like, input data
53
    - dtype: dtype, desired data type
54
    
55
    Returns:
56
    MaskedArray: Masked array object
57
    """
58
```
59

60
### Mask Creation Functions
61

62
Functions for creating and manipulating masks to identify invalid or missing data.
63

64
```python { .api }
65
def make_mask(m, copy=False, shrink=True, dtype=None):
66
    """
67
    Create a boolean mask from an array.
68
    
69
    Parameters:
70
    - m: array_like, potential mask
71
    - copy: bool, whether to copy the mask
72
    - shrink: bool, whether to shrink mask to nomask if no values masked
73
    - dtype: dtype, data type of mask
74
    
75
    Returns:
76
    ndarray or nomask: Boolean mask array
77
    """
78

79
def mask_or(m1, m2, copy=False, shrink=True):
80
    """
81
    Combine two masks with the logical_or operator.
82
    
83
    Parameters:
84
    - m1, m2: array_like, input masks
85
    - copy: bool, whether to copy result
86
    - shrink: bool, whether to shrink result
87
    
88
    Returns:
89
    ndarray or nomask: Combined mask
90
    """
91

92
def mask_and(m1, m2, copy=False, shrink=True):
93
    """
94
    Combine two masks with the logical_and operator.
95
    
96
    Parameters:
97
    - m1, m2: array_like, input masks
98
    - copy: bool, whether to copy result
99
    - shrink: bool, whether to shrink result
100
    
101
    Returns:
102
    ndarray or nomask: Combined mask
103
    """
104

105
def masked_where(condition, a, copy=True):
106
    """
107
    Mask an array where a condition is met.
108
    
109
    Parameters:
110
    - condition: array_like, masking condition
111
    - a: array_like, array to mask
112
    - copy: bool, whether to copy array
113
    
114
    Returns:
115
    MaskedArray: Masked version of array
116
    """
117

118
def masked_invalid(a, copy=True):
119
    """
120
    Mask an array where invalid values occur (NaNs or infs).
121
    
122
    Parameters:
123
    - a: array_like, array to mask
124
    - copy: bool, whether to copy array
125
    
126
    Returns:
127
    MaskedArray: Masked array with invalid values masked
128
    """
129

130
def masked_equal(x, value, copy=True):
131
    """
132
    Mask an array where equal to a given value.
133
    
134
    Parameters:
135
    - x: array_like, array to mask
136
    - value: scalar, value to mask
137
    - copy: bool, whether to copy array
138
    
139
    Returns:
140
    MaskedArray: Masked array
141
    """
142

143
def masked_not_equal(x, value, copy=True):
144
    """
145
    Mask an array where not equal to a given value.
146
    
147
    Parameters:
148
    - x: array_like, array to mask  
149
    - value: scalar, comparison value
150
    - copy: bool, whether to copy array
151
    
152
    Returns:
153
    MaskedArray: Masked array
154
    """
155

156
def masked_less(x, value, copy=True):
157
    """
158
    Mask an array where less than a given value.
159
    
160
    Parameters:
161
    - x: array_like, array to mask
162
    - value: scalar, comparison value
163
    - copy: bool, whether to copy array
164
    
165
    Returns:
166
    MaskedArray: Masked array
167
    """
168

169
def masked_greater(x, value, copy=True):
170
    """
171
    Mask an array where greater than a given value.
172
    
173
    Parameters:
174
    - x: array_like, array to mask
175
    - value: scalar, comparison value  
176
    - copy: bool, whether to copy array
177
    
178
    Returns:
179
    MaskedArray: Masked array
180
    """
181

182
def masked_inside(x, v1, v2, copy=True):
183
    """
184
    Mask an array inside a given interval.
185
    
186
    Parameters:
187
    - x: array_like, array to mask
188
    - v1, v2: scalar, interval endpoints
189
    - copy: bool, whether to copy array
190
    
191
    Returns:
192
    MaskedArray: Masked array
193
    """
194

195
def masked_outside(x, v1, v2, copy=True):
196
    """
197
    Mask an array outside a given interval.
198
    
199
    Parameters:
200
    - x: array_like, array to mask
201
    - v1, v2: scalar, interval endpoints
202
    - copy: bool, whether to copy array
203
    
204
    Returns:
205
    MaskedArray: Masked array
206
    """
207
```
208

209
### Operations on Masked Arrays
210

211
Statistical and mathematical operations that properly handle masked data.
212

213
```python { .api }
214
def count(a, axis=None, keepdims=False):
215
    """
216
    Count the non-masked elements of the array along the given axis.
217
    
218
    Parameters:
219
    - a: array_like, input data
220
    - axis: None or int or tuple, axis along which to count
221
    - keepdims: bool, whether to keep dimensions
222
    
223
    Returns:
224
    ndarray: Number of non-masked elements
225
    """
226

227
def sum(a, axis=None, **kwargs):
228
    """Sum of array elements over a given axis, ignoring masked values."""
229

230
def mean(a, axis=None, **kwargs): 
231
    """Compute the arithmetic mean along the specified axis, ignoring masked values."""
232

233
def std(a, axis=None, **kwargs):
234
    """Compute the standard deviation along the specified axis, ignoring masked values."""
235

236
def var(a, axis=None, **kwargs):
237
    """Compute the variance along the specified axis, ignoring masked values."""
238

239
def min(a, axis=None, **kwargs):
240
    """Return the minimum along a given axis, ignoring masked values."""
241

242
def max(a, axis=None, **kwargs):
243
    """Return the maximum along a given axis, ignoring masked values."""
244

245
def compressed(x):
246
    """
247
    Return all the non-masked data as a 1-D array.
248
    
249
    Parameters:
250
    - x: MaskedArray, input array
251
    
252
    Returns:
253
    ndarray: Compressed array with only non-masked values
254
    """
255

256
def filled(a, fill_value=None):
257
    """
258
    Return input as an array with masked data replaced by a fill value.
259
    
260
    Parameters:
261
    - a: MaskedArray, input array
262
    - fill_value: scalar, value to use for masked entries
263
    
264
    Returns:
265
    ndarray: Filled array
266
    """
267
```
268

269
### Mask Manipulation
270

271
Functions for working with and modifying masks.
272

273
```python { .api }
274
def getmask(a):
275
    """
276
    Return the mask of a masked array, or nomask.
277
    
278
    Parameters:
279
    - a: array_like, input array
280
    
281
    Returns:
282
    ndarray or nomask: Mask array
283
    """
284

285
def getmaskarray(arr):
286
    """
287
    Return the mask of a masked array, or full boolean array of False.
288
    
289
    Parameters:
290
    - arr: array_like, input array
291
    
292
    Returns:
293
    ndarray: Mask array
294
    """
295

296
def is_mask(m):
297
    """
298
    Return True if m is a valid, standard mask.
299
    
300
    Parameters:
301
    - m: array_like, array to test
302
    
303
    Returns:
304
    bool: Whether array is a valid mask
305
    """
306

307
def is_masked(x):
308
    """
309
    Determine whether input has masked values.
310
    
311
    Parameters:
312
    - x: array_like, array to test
313
    
314
    Returns:
315
    bool: Whether array has masked values
316
    """
317

318
def isMA(x):
319
    """
320
    Test whether input is an instance of MaskedArray.
321
    
322
    Parameters:
323
    - x: object, object to test
324
    
325
    Returns:
326
    bool: Whether object is MaskedArray
327
    """
328
```
329

330
## Usage Examples
331

332
### Basic Masked Array Operations
333

334
```python
335
import numpy as np
336
import numpy.ma as ma
337

338
# Create array with missing values
339
data = [1, 2, np.nan, 4, 5]
340
masked_data = ma.masked_invalid(data)
341
print(masked_data)
342
# masked_array(data=[1.0, 2.0, --, 4.0, 5.0], mask=[False, False, True, False, False])
343

344
# Calculate statistics ignoring masked values
345
print(ma.mean(masked_data))  # 3.0
346
print(ma.std(masked_data))   # 1.58...
347

348
# Get non-masked data
349
print(masked_data.compressed())  # [1. 2. 4. 5.]
350
```
351

352
### Creating Custom Masks
353

354
```python
355
import numpy as np
356
import numpy.ma as ma
357

358
# Create masked array with custom conditions
359
data = np.array([1, 2, 3, 4, 5, 6])
360
masked_data = ma.masked_where(data > 3, data)
361
print(masked_data)
362
# masked_array(data=[1, 2, 3, --, --, --], mask=[False, False, False, True, True, True])
363

364
# Combine masks
365
mask1 = data < 2
366
mask2 = data > 5  
367
combined_mask = ma.mask_or(mask1, mask2)
368
result = ma.array(data, mask=combined_mask)
369
print(result)
370
# masked_array(data=[--, 2, 3, 4, 5, --], mask=[True, False, False, False, False, True])
371
```
372

373
### Fill Missing Values
374

375
```python
376
import numpy as np
377
import numpy.ma as ma
378

379
# Create masked array and fill missing values
380
data = ma.array([1, 2, 3, 4], mask=[0, 0, 1, 0])
381
filled = data.filled(fill_value=-999)
382
print(filled)  # [1 2 -999 4]
383

384
# Use different fill values
385
data.fill_value = 0
386
print(data.filled())  # [1 2 0 4]
387
```