0
# FITS File I/O
1

2
Complete FITS (Flexible Image Transport System) file support for reading, writing, and manipulating astronomical data files with headers, image data, and binary tables.
3

4
## Capabilities
5

6
### Basic FITS Operations
7

8
High-level functions for common FITS file operations including reading data and headers, writing files, and updating existing files.
9

10
```python { .api }
11
def open(name, mode='readonly', memmap=None, save_backup=False, cache=True, lazy_load_hdus=True, **kwargs):
12
    """
13
    Open a FITS file and return an HDUList object.
14
    
15
    Parameters:
16
    - name: file name or file-like object
17
    - mode: file access mode ('readonly', 'update', 'append', 'denywrite', 'ostream')
18
    - memmap: use memory mapping for large files
19
    - save_backup: save backup when updating files
20
    - cache: cache file in memory
21
    - lazy_load_hdus: load HDUs only when accessed
22
    
23
    Returns:
24
    HDUList: list of Header Data Units
25
    """
26

27
def getdata(filename, *args, header=False, lower=None, upper=None, view=None, **kwargs):
28
    """
29
    Get data from FITS file.
30
    
31
    Parameters:
32
    - filename: FITS file name
33
    - *args: HDU specification (ext, extname, extver)
34
    - header: also return header
35
    - lower, upper: data range bounds
36
    - view: numpy slice for data subset
37
    
38
    Returns:
39
    ndarray or tuple: data array, optionally with header
40
    """
41

42
def getheader(filename, *args, **kwargs):
43
    """
44
    Get header from FITS file.
45
    
46
    Parameters:
47
    - filename: FITS file name  
48
    - *args: HDU specification
49
    
50
    Returns:
51
    Header: FITS header object
52
    """
53

54
def writeto(filename, data, header=None, output_verify='exception', overwrite=False, checksum=False, **kwargs):
55
    """
56
    Write data to FITS file.
57
    
58
    Parameters:
59
    - filename: output file name
60
    - data: data array to write
61
    - header: FITS header
62
    - output_verify: verification level
63
    - overwrite: overwrite existing file
64
    - checksum: compute checksums
65
    """
66

67
def append(filename, data, header=None, checksum=False, verify=True, **kwargs):
68
    """Append HDU to existing FITS file."""
69

70
def update(filename, data, *args, header=None, verify=True, **kwargs):
71
    """Update HDU in existing FITS file."""
72

73
def info(filename, output=None, **kwargs):
74
    """
75
    Print summary information about FITS file.
76
    
77
    Parameters:
78
    - filename: FITS file name
79
    - output: output stream (default: stdout)
80
    """
81
```
82

83
### HDU Classes and Structure
84

85
HDU (Header Data Unit) classes representing different types of FITS extensions with headers and data.
86

87
```python { .api }
88
class HDUList:
89
    """
90
    List-like container for FITS Header Data Units.
91
    
92
    Parameters:
93
    - hdus: list of HDU objects
94
    - file: associated file object
95
    """
96
    def __init__(self, hdus=[], file=None): ...
97
    
98
    def writeto(self, fileobj, output_verify='exception', overwrite=False, checksum=False):
99
        """Write HDUList to file."""
100
    
101
    def append(self, hdu):
102
        """Append HDU to list."""
103
    
104
    def insert(self, index, hdu):
105
        """Insert HDU at specified index."""
106
    
107
    def info(self, output=None):
108
        """Print information about HDUs."""
109
    
110
    def verify(self, option='warn'):
111
        """Verify FITS standard compliance."""
112
    
113
    def close(self):
114
        """Close associated file."""
115
    
116
    def __getitem__(self, key):
117
        """Get HDU by index, name, or (name, version)."""
118

119
class PrimaryHDU:
120
    """
121
    Primary Header Data Unit (first HDU in FITS file).
122
    
123
    Parameters:
124
    - data: data array
125
    - header: FITS header
126
    - do_not_scale_image_data: disable automatic scaling
127
    - uint: treat signed integers as unsigned
128
    - scale_back: scale data when writing
129
    """
130
    def __init__(self, data=None, header=None, do_not_scale_image_data=False, uint=False, scale_back=None): ...
131
    
132
    @property
133
    def data(self):
134
        """HDU data array."""
135
    
136
    @property
137
    def header(self):
138
        """HDU header."""
139
    
140
    def writeto(self, name, output_verify='exception', overwrite=False, checksum=False): ...
141

142
class ImageHDU(PrimaryHDU):
143
    """Image extension HDU."""
144
    def __init__(self, data=None, header=None, name=None, **kwargs): ...
145

146
class BinTableHDU:
147
    """
148
    Binary table HDU.
149
    
150
    Parameters:
151
    - data: table data (structured array, Table, etc.)
152
    - header: FITS header
153
    - name: extension name
154
    - uint: handle unsigned integers
155
    - character_as_bytes: handle character columns
156
    """
157
    def __init__(self, data=None, header=None, name=None, uint=False, character_as_bytes=False): ...
158
    
159
    @classmethod
160
    def from_columns(cls, columns, header=None, nrows=None, fill=False, **kwargs):
161
        """Create from Column objects."""
162

163
class TableHDU:
164
    """ASCII table HDU."""
165
    def __init__(self, data=None, header=None, name=None): ...
166

167
class CompImageHDU:
168
    """Compressed image HDU."""
169
    def __init__(self, data=None, header=None, name=None, compression_type='RICE_1', **kwargs): ...
170
```
171

172
### Header Manipulation
173

174
FITS header handling with keyword management, comments, and history records.
175

176
```python { .api }
177
class Header:
178
    """
179
    FITS header with ordered keyword-value pairs.
180
    
181
    Parameters:
182
    - cards: list of Card objects or keyword-value pairs
183
    - txtfile: read from text file
184
    - copy: copy input data
185
    """
186
    def __init__(self, cards=[], txtfile=None, copy=True): ...
187
    
188
    def __getitem__(self, key):
189
        """Get header value by keyword."""
190
    
191
    def __setitem__(self, key, value):
192
        """Set header keyword value."""
193
    
194
    def __delitem__(self, key):
195
        """Delete header keyword."""
196
    
197
    def __contains__(self, key):
198
        """Check if keyword exists."""
199
    
200
    def append(self, card=None, useblanks=True, bottom=False, end=False):
201
        """Append card to header."""
202
    
203
    def insert(self, key, card, useblanks=True, after=False):
204
        """Insert card before/after specified keyword."""
205
    
206
    def remove(self, keyword, ignore_missing=False, remove_all=False):
207
        """Remove keyword from header."""
208
    
209
    def rename_keyword(self, oldkeyword, newkeyword, force=False):
210
        """Rename header keyword."""
211
    
212
    def set(self, keyword, value=None, comment=None, before=None, after=None, savecomment=False):
213
        """Set keyword value with optional positioning."""
214
    
215
    def update(self, *args, **kwargs):
216
        """Update header with new keywords."""
217
    
218
    def add_history(self, value, before=None, after=None):
219
        """Add HISTORY record."""
220
    
221
    def add_comment(self, value, before=None, after=None):
222
        """Add COMMENT record."""
223
    
224
    def add_blank(self, value='', before=None, after=None):
225
        """Add blank card."""
226
    
227
    def copy(self, strip=False):
228
        """Copy header."""
229

230
class Card:
231
    """
232
    Individual FITS header card (keyword-value-comment).
233
    
234
    Parameters:
235
    - keyword: FITS keyword (8 characters max)
236
    - value: keyword value
237
    - comment: keyword comment
238
    - image: create from raw 80-character string
239
    """
240
    def __init__(self, keyword=None, value=None, comment=None, image=None): ...
241
    
242
    @property
243
    def keyword(self):
244
        """FITS keyword."""
245
    
246
    @property
247
    def value(self):
248
        """Keyword value."""
249
    
250
    @property
251
    def comment(self):
252
        """Keyword comment."""
253
    
254
    @property
255
    def image(self):
256
        """80-character card image."""
257
```
258

259
## Usage Examples
260

261
### Basic FITS File Operations
262

263
```python
264
from astropy.io import fits
265
import numpy as np
266

267
# Read FITS file
268
with fits.open('image.fits') as hdul:
269
    fits.info('image.fits')  # Print file info
270
    header = hdul[0].header  # Primary header
271
    data = hdul[0].data      # Primary data
272
    
273
    # Access extension by name
274
    if 'EVENTS' in hdul:
275
        events = hdul['EVENTS'].data
276

277
# Quick data access
278
data = fits.getdata('image.fits')
279
header = fits.getheader('image.fits')
280
data, header = fits.getdata('image.fits', header=True)
281
```
282

283
### Creating and Writing FITS Files
284

285
```python
286
# Create simple image
287
data = np.random.random((100, 100))
288

289
# Write with basic header
290
fits.writeto('output.fits', data, overwrite=True)
291

292
# Create custom header
293
hdr = fits.Header()
294
hdr['OBJECT'] = 'M31'
295
hdr['EXPTIME'] = 600.0
296
hdr['FILTER'] = 'V'
297
hdr.add_comment('This is a test image')
298

299
fits.writeto('output_with_header.fits', data, header=hdr, overwrite=True)
300
```