0
# N-Dimensional Data
1
2
Framework for handling N-dimensional astronomical data with metadata, masks, and uncertainty propagation.
3
4
## Core Imports
5
6
```python
7
from astropy.nddata import NDData, CCDData
8
from astropy.nddata import StdDevUncertainty, VarianceUncertainty, InverseVariance
9
from astropy.nddata import block_reduce, block_replicate
10
```
11
12
## Capabilities
13
14
### Core NDData Classes
15
16
Base classes for representing N-dimensional data with associated metadata, uncertainty, and masking.
17
18
```python { .api }
19
class NDData:
20
"""
21
Base class for N-dimensional data with metadata.
22
23
Parameters:
24
- data: array-like data
25
- uncertainty: uncertainty information
26
- mask: boolean mask array
27
- meta: metadata dictionary
28
- unit: physical unit of the data
29
- wcs: world coordinate system information
30
"""
31
def __init__(self, data, uncertainty=None, mask=None, meta=None, unit=None, wcs=None): ...
32
33
@property
34
def data(self):
35
"""The stored data array."""
36
37
@property
38
def uncertainty(self):
39
"""Uncertainty information."""
40
41
@property
42
def mask(self):
43
"""Boolean mask array."""
44
45
@property
46
def meta(self):
47
"""Metadata dictionary."""
48
49
@property
50
def unit(self):
51
"""Physical unit of the data."""
52
53
@property
54
def wcs(self):
55
"""World coordinate system."""
56
57
class NDDataArray(NDData):
58
"""NDData with arithmetic operations support."""
59
60
def __add__(self, other): ...
61
def __sub__(self, other): ...
62
def __mul__(self, other): ...
63
def __truediv__(self, other): ...
64
```
65
66
### CCD Data Handling
67
68
Specialized class for CCD/detector data with enhanced I/O and FITS integration.
69
70
```python { .api }
71
class CCDData(NDData):
72
"""
73
CCD data container with FITS I/O support.
74
75
Parameters:
76
- data: CCD data array
77
- unit: physical unit (required for CCDData)
78
- uncertainty: uncertainty information
79
- mask: boolean mask
80
- meta: metadata dictionary
81
- header: FITS header
82
- wcs: world coordinate system
83
"""
84
def __init__(self, data, unit=None, uncertainty=None, mask=None, meta=None, header=None, wcs=None): ...
85
86
@classmethod
87
def read(cls, filename, hdu=0, unit=None, **kwargs):
88
"""
89
Read CCDData from FITS file.
90
91
Parameters:
92
- filename: file path or file-like object
93
- hdu: HDU number or name
94
- unit: unit to assign to data
95
- **kwargs: additional arguments for fits.open
96
97
Returns:
98
CCDData: loaded CCD data
99
"""
100
101
def write(self, filename, hdu_mask='MASK', hdu_uncertainty='UNCERT', **kwargs):
102
"""
103
Write CCDData to FITS file.
104
105
Parameters:
106
- filename: output filename
107
- hdu_mask: HDU name for mask
108
- hdu_uncertainty: HDU name for uncertainty
109
- **kwargs: additional arguments for fits.writeto
110
"""
111
112
@property
113
def header(self):
114
"""FITS header information."""
115
```
116
117
### Uncertainty Classes
118
119
Classes for representing and propagating uncertainties in astronomical data.
120
121
```python { .api }
122
class NDUncertainty:
123
"""Base class for uncertainty information."""
124
125
def __init__(self, array, unit=None): ...
126
127
@property
128
def array(self):
129
"""Uncertainty array."""
130
131
@property
132
def unit(self):
133
"""Unit of uncertainty."""
134
135
class StdDevUncertainty(NDUncertainty):
136
"""
137
Standard deviation uncertainty.
138
139
Parameters:
140
- array: standard deviation values
141
- unit: unit of uncertainty values
142
"""
143
def __init__(self, array, unit=None): ...
144
145
@property
146
def uncertainty_type(self):
147
"""Return 'std' for standard deviation."""
148
149
class VarianceUncertainty(NDUncertainty):
150
"""
151
Variance uncertainty.
152
153
Parameters:
154
- array: variance values
155
- unit: unit of variance values
156
"""
157
def __init__(self, array, unit=None): ...
158
159
@property
160
def uncertainty_type(self):
161
"""Return 'var' for variance."""
162
163
class InverseVariance(NDUncertainty):
164
"""
165
Inverse variance uncertainty (weights).
166
167
Parameters:
168
- array: inverse variance values
169
- unit: unit of inverse variance
170
"""
171
def __init__(self, array, unit=None): ...
172
173
@property
174
def uncertainty_type(self):
175
"""Return 'ivar' for inverse variance."""
176
```
177
178
### Data Processing Functions
179
180
Functions for manipulating and processing N-dimensional data arrays.
181
182
```python { .api }
183
def block_reduce(data, block_size, func=np.sum, cval=0.0):
184
"""
185
Downsample data by applying a function to blocks.
186
187
Parameters:
188
- data: input data array
189
- block_size: size of blocks for reduction
190
- func: function to apply to each block
191
- cval: value for padding if needed
192
193
Returns:
194
array: reduced data array
195
"""
196
197
def block_replicate(data, block_size, conserve_sum=True):
198
"""
199
Upsample data by replicating blocks.
200
201
Parameters:
202
- data: input data array
203
- block_size: replication factor
204
- conserve_sum: whether to conserve total sum
205
206
Returns:
207
array: upsampled data array
208
"""
209
210
def overlap_slices(large_array_shape, small_array_shape, position, mode='partial'):
211
"""
212
Calculate overlap slices for array positioning.
213
214
Parameters:
215
- large_array_shape: shape of target array
216
- small_array_shape: shape of array to position
217
- position: position tuple
218
- mode: overlap mode ('partial', 'trim', 'strict')
219
220
Returns:
221
tuple: (large_slices, small_slices)
222
"""
223
224
def extract_array(array_large, shape, position):
225
"""
226
Extract smaller array from larger array at given position.
227
228
Parameters:
229
- array_large: source array
230
- shape: shape of extracted array
231
- position: center position for extraction
232
233
Returns:
234
array: extracted sub-array
235
"""
236
237
def add_array(array_large, array_small, position):
238
"""
239
Add small array to large array at given position.
240
241
Parameters:
242
- array_large: target array (modified in-place)
243
- array_small: array to add
244
- position: position for addition
245
"""
246
```
247
248
### Bitmask Utilities
249
250
Tools for working with bitmask arrays and flag collections.
251
252
```python { .api }
253
def interpret_bitmask(bitmask, flip_bits=None):
254
"""
255
Interpret bitmask array or integer.
256
257
Parameters:
258
- bitmask: bitmask specification
259
- flip_bits: bits to flip interpretation
260
261
Returns:
262
int or array: interpreted bitmask
263
"""
264
265
class FlagCollection:
266
"""
267
Collection of named bit flags.
268
269
Parameters:
270
- **kwargs: flag_name=bit_value pairs
271
"""
272
def __init__(self, **kwargs): ...
273
274
def __getitem__(self, key):
275
"""Get flag value by name."""
276
277
def __setitem__(self, key, value):
278
"""Set flag value by name."""
279
```
280
281
## Usage Examples
282
283
### Basic NDData Usage
284
285
```python
286
import numpy as np
287
from astropy.nddata import NDData, StdDevUncertainty
288
import astropy.units as u
289
290
# Create data with uncertainty
291
data = np.random.random((100, 100))
292
uncertainty = StdDevUncertainty(np.sqrt(data))
293
mask = data < 0.1
294
295
# Create NDData object
296
nd = NDData(data, uncertainty=uncertainty, mask=mask,
297
unit=u.adu, meta={'exposure': 300})
298
299
print(f"Data shape: {nd.data.shape}")
300
print(f"Unit: {nd.unit}")
301
print(f"Masked pixels: {nd.mask.sum()}")
302
```
303
304
### CCD Data I/O
305
306
```python
307
from astropy.nddata import CCDData
308
import astropy.units as u
309
310
# Create CCD data
311
data = np.random.random((512, 512))
312
ccd = CCDData(data, unit=u.adu)
313
314
# Add uncertainty and mask
315
ccd.uncertainty = StdDevUncertainty(np.sqrt(data) * u.adu)
316
ccd.mask = data < 0.05
317
318
# Save to FITS
319
ccd.write('image.fits', overwrite=True)
320
321
# Read back
322
ccd_loaded = CCDData.read('image.fits', unit=u.adu)
323
```
324
325
### Block Operations
326
327
```python
328
from astropy.nddata import block_reduce, block_replicate
329
330
# Reduce resolution by factor of 2
331
data = np.random.random((100, 100))
332
reduced = block_reduce(data, 2, func=np.mean)
333
print(f"Original: {data.shape}, Reduced: {reduced.shape}")
334
335
# Replicate to higher resolution
336
replicated = block_replicate(reduced, 2)
337
print(f"Replicated: {replicated.shape}")
338
```
339
340
## Types
341
342
```python { .api }
343
# Core NDData types
344
NDData = astropy.nddata.NDData
345
NDDataArray = astropy.nddata.NDDataArray
346
CCDData = astropy.nddata.CCDData
347
348
# Uncertainty types
349
NDUncertainty = astropy.nddata.NDUncertainty
350
StdDevUncertainty = astropy.nddata.StdDevUncertainty
351
VarianceUncertainty = astropy.nddata.VarianceUncertainty
352
InverseVariance = astropy.nddata.InverseVariance
353
354
# Utility types
355
FlagCollection = astropy.nddata.FlagCollection
356
```