fitscube 2.9.0__tar.gz → 2.11.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. {fitscube-2.9.0 → fitscube-2.11.0}/.github/workflows/ci.yml +2 -2
  2. {fitscube-2.9.0 → fitscube-2.11.0}/PKG-INFO +114 -15
  3. {fitscube-2.9.0 → fitscube-2.11.0}/README.md +111 -11
  4. {fitscube-2.9.0 → fitscube-2.11.0}/fitscube/_version.py +2 -2
  5. {fitscube-2.9.0 → fitscube-2.11.0}/fitscube/cli.py +20 -0
  6. {fitscube-2.9.0 → fitscube-2.11.0}/fitscube/combine_fits.py +109 -142
  7. fitscube-2.11.0/fitscube/compress.py +630 -0
  8. {fitscube-2.9.0 → fitscube-2.11.0}/fitscube/extract.py +4 -0
  9. {fitscube-2.9.0 → fitscube-2.11.0}/pyproject.toml +4 -5
  10. {fitscube-2.9.0 → fitscube-2.11.0}/tests/test_combine_guards.py +30 -0
  11. fitscube-2.11.0/tests/test_compress.py +278 -0
  12. {fitscube-2.9.0 → fitscube-2.11.0}/tests/test_extract.py +6 -0
  13. {fitscube-2.9.0 → fitscube-2.11.0}/tests/test_frequencies.py +20 -9
  14. fitscube-2.11.0/tests/test_racs_all.py +112 -0
  15. {fitscube-2.9.0 → fitscube-2.11.0}/uv.lock +71 -445
  16. fitscube-2.9.0/tests/test_compress.py +0 -39
  17. {fitscube-2.9.0 → fitscube-2.11.0}/.github/CONTRIBUTING.md +0 -0
  18. {fitscube-2.9.0 → fitscube-2.11.0}/.github/dependabot.yml +0 -0
  19. {fitscube-2.9.0 → fitscube-2.11.0}/.github/release.yml +0 -0
  20. {fitscube-2.9.0 → fitscube-2.11.0}/.github/workflows/cd.yml +0 -0
  21. {fitscube-2.9.0 → fitscube-2.11.0}/.gitignore +0 -0
  22. {fitscube-2.9.0 → fitscube-2.11.0}/.pre-commit-config.yaml +0 -0
  23. {fitscube-2.9.0 → fitscube-2.11.0}/CHANGELOG.md +0 -0
  24. {fitscube-2.9.0 → fitscube-2.11.0}/LICENSE +0 -0
  25. {fitscube-2.9.0 → fitscube-2.11.0}/fitscube/__init__.py +0 -0
  26. {fitscube-2.9.0 → fitscube-2.11.0}/fitscube/asyncio.py +0 -0
  27. {fitscube-2.9.0 → fitscube-2.11.0}/fitscube/bounding_box.py +0 -0
  28. {fitscube-2.9.0 → fitscube-2.11.0}/fitscube/exceptions.py +0 -0
  29. {fitscube-2.9.0 → fitscube-2.11.0}/fitscube/logging.py +0 -0
  30. {fitscube-2.9.0 → fitscube-2.11.0}/fitscube/version.pyi +0 -0
  31. {fitscube-2.9.0 → fitscube-2.11.0}/noxfile.py +0 -0
  32. {fitscube-2.9.0 → fitscube-2.11.0}/tests/__init__.py +0 -0
  33. {fitscube-2.9.0 → fitscube-2.11.0}/tests/conftest.py +0 -0
  34. {fitscube-2.9.0 → fitscube-2.11.0}/tests/data/cube.zip +0 -0
  35. {fitscube-2.9.0 → fitscube-2.11.0}/tests/data/images.zip +0 -0
  36. {fitscube-2.9.0 → fitscube-2.11.0}/tests/data/time_images.zip +0 -0
  37. {fitscube-2.9.0 → fitscube-2.11.0}/tests/data/timecube.zip +0 -0
  38. {fitscube-2.9.0 → fitscube-2.11.0}/tests/test_bb.py +0 -0
  39. {fitscube-2.9.0 → fitscube-2.11.0}/tests/test_combine.py +0 -0
  40. {fitscube-2.9.0 → fitscube-2.11.0}/tests/test_combine_layouts.py +0 -0
  41. {fitscube-2.9.0 → fitscube-2.11.0}/tests/test_package.py +0 -0
  42. {fitscube-2.9.0 → fitscube-2.11.0}/tests/test_times.py +0 -0
  43. {fitscube-2.9.0 → fitscube-2.11.0}/tests/test_zero_beams.py +0 -0
@@ -34,7 +34,7 @@ jobs:
34
34
  strategy:
35
35
  fail-fast: false
36
36
  matrix:
37
- python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
37
+ python-version: ["3.11", "3.12", "3.13", "3.14"]
38
38
  runs-on: [ubuntu-latest]
39
39
 
40
40
  steps:
@@ -55,6 +55,6 @@ jobs:
55
55
  --durations=20
56
56
 
57
57
  - name: Upload coverage report
58
- uses: codecov/codecov-action@v7.0.0
58
+ uses: codecov/codecov-action@v7.1.1
59
59
  with:
60
60
  token: ${{ secrets.CODECOV_TOKEN }}
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: fitscube
3
- Version: 2.9.0
3
+ Version: 2.11.0
4
4
  Summary: A package to produce produce FITS cubes.
5
5
  Project-URL: Homepage, https://github.com/AlecThomson/fitscube
6
6
  Project-URL: Bug Tracker, https://github.com/AlecThomson/fitscube/issues
@@ -37,15 +37,14 @@ Classifier: Operating System :: OS Independent
37
37
  Classifier: Programming Language :: Python
38
38
  Classifier: Programming Language :: Python :: 3
39
39
  Classifier: Programming Language :: Python :: 3 :: Only
40
- Classifier: Programming Language :: Python :: 3.10
41
40
  Classifier: Programming Language :: Python :: 3.11
42
41
  Classifier: Programming Language :: Python :: 3.12
43
42
  Classifier: Programming Language :: Python :: 3.13
44
43
  Classifier: Programming Language :: Python :: 3.14
45
44
  Classifier: Topic :: Scientific/Engineering
46
45
  Classifier: Typing :: Typed
47
- Requires-Python: >=3.10
48
- Requires-Dist: astropy>=6.0
46
+ Requires-Python: >=3.11
47
+ Requires-Dist: astropy>=7.2
49
48
  Requires-Dist: numpy>=2
50
49
  Requires-Dist: radio-beam
51
50
  Requires-Dist: tqdm
@@ -151,17 +150,19 @@ Command line:
151
150
 
152
151
  ```
153
152
  ❯ fitscube -h
154
- usage: fitscube [-h] {combine,extract} ...
153
+ usage: fitscube [-h] {combine,extract,compress,decompress} ...
155
154
 
156
155
  Tooling to create fitscubes
157
156
 
158
157
  positional arguments:
159
- {combine,extract}
160
- combine Combine FITS images together into a cube
161
- extract Extract a plane from an existing cube
158
+ {combine,extract,compress,decompress}
159
+ combine Combine FITS images together into a cube
160
+ extract Extract a plane from an existing cube
161
+ compress Compress a cube to .fits.gz or .fits.fz
162
+ decompress Turn a .fits.gz or .fits.fz cube back into plain FITS
162
163
 
163
164
  options:
164
- -h, --help show this help message and exit
165
+ -h, --help show this help message and exit
165
166
  ```
166
167
 
167
168
  ```
@@ -170,7 +171,8 @@ usage: fitscube combine [-h] [-o] [--create-blanks] [--time-domain]
170
171
  [--spec-file SPEC_FILE | --specs SPECS [SPECS ...] | --ignore-spec] [-v]
171
172
  [--max-workers MAX_WORKERS] [--bounding-box] [--invalidate-zeros]
172
173
  [--no-blank-zero-beams] [--floating {32,64}] [--compress]
173
- [--compress-method {gzip,pgzip}]
174
+ [--compress-method {gzip,pgzip,tile-gzip,tile-rice}]
175
+ [--quantize-level QUANTIZE_LEVEL]
174
176
  file_list [file_list ...] out_cube
175
177
 
176
178
  positional arguments:
@@ -202,11 +204,16 @@ options:
202
204
  --floating {32,64}
203
205
  The number of floating point bits to use in the out cube. If None the
204
206
  input data precision is used.
205
- --compress Gzip-compress the output cube
206
- --compress-method {gzip,pgzip}
207
- Compression backend for --compress. 'gzip' is stdlib and needs nothing
208
- extra. 'pgzip' parallelizes across --max-workers threads but requires the
209
- 'pgzip' extra: pip install fitscube[pgzip]
207
+ --compress Compress the output cube once written
208
+ --compress-method {gzip,pgzip,tile-gzip,tile-rice}
209
+ How --compress compresses. 'gzip' and 'pgzip' gzip the whole file to
210
+ .fits.gz; 'pgzip' parallelizes across --max-workers threads but requires
211
+ the 'pgzip' extra. 'tile-gzip' (lossless) and 'tile-rice' (lossy, see
212
+ --quantize-level) tile-compress to .fits.fz, as fpack does, so single
213
+ planes can be read without decompressing the whole cube
214
+ --quantize-level QUANTIZE_LEVEL
215
+ Quantization steps per noise sigma for 'tile-rice'. Higher keeps more
216
+ precision and compresses less
210
217
  ```
211
218
 
212
219
  ```
@@ -228,6 +235,45 @@ options:
228
235
  The name of the new output file. If not specified it is generated from the fits cube name
229
236
  ```
230
237
 
238
+ ```
239
+ ❯ fitscube compress -h
240
+ usage: fitscube compress [-h] [--method {gzip,pgzip,tile-gzip,tile-rice}]
241
+ [--quantize-level QUANTIZE_LEVEL] [--max-workers MAX_WORKERS]
242
+ [--allow-requantize] [--remove] [-v]
243
+ cube
244
+
245
+ positional arguments:
246
+ cube An uncompressed FITS cube
247
+
248
+ options:
249
+ -h, --help show this help message and exit
250
+ --method {gzip,pgzip,tile-gzip,tile-rice}
251
+ 'gzip'/'pgzip' gzip the whole file to .fits.gz. 'tile-gzip' (lossless) and
252
+ 'tile-rice' (lossy) tile-compress to .fits.fz, as fpack does
253
+ --quantize-level QUANTIZE_LEVEL
254
+ Quantization steps per noise sigma for 'tile-rice'
255
+ --max-workers MAX_WORKERS
256
+ Compression threads
257
+ --allow-requantize Let 'tile-rice' quantize a cube that was already quantized once
258
+ --remove Delete the input once done
259
+ -v, --verbosity Increase output verbosity
260
+ ```
261
+
262
+ ```
263
+ ❯ fitscube decompress -h
264
+ usage: fitscube decompress [-h] [-o OUTPUT] [--overwrite] [--remove] [-v] cube
265
+
266
+ positional arguments:
267
+ cube A .fits.gz or tile-compressed .fits.fz cube
268
+
269
+ options:
270
+ -h, --help show this help message and exit
271
+ -o, --output OUTPUT Output path. Defaults to the input without .gz/.fz
272
+ --overwrite Replace the output if it exists
273
+ --remove Delete the compressed input once done
274
+ -v, --verbosity Increase output verbosity
275
+ ```
276
+
231
277
  Python:
232
278
 
233
279
  ```python
@@ -242,6 +288,59 @@ frequencies = combine_fits(
242
288
  )
243
289
  ```
244
290
 
291
+ ## Compressed cubes
292
+
293
+ `fitscube compress`, or `combine --compress`, writes the cube in one of three ways:
294
+
295
+ | Method | Output | |
296
+ |---|---|---|
297
+ | `gzip`, `pgzip` | `.fits.gz` | The whole file gzipped. Lossless. |
298
+ | `tile-gzip` | `.fits.fz` | [Tile compressed](https://heasarc.gsfc.nasa.gov/fitsio/fpack/) with GZIP_2. Lossless. |
299
+ | `tile-rice` | `.fits.fz` | Tile compressed with RICE_1, after quantising to `--quantize-level` steps per noise sigma. Lossy. |
300
+
301
+ `.fits.fz` files are what `fpack` writes, so DS9, CARTA, `funpack` and astropy can all
302
+ read them. The image is in HDU 1, and `.section` only decompresses the tiles it needs:
303
+
304
+ ```python
305
+ from astropy.io import fits
306
+
307
+ with fits.open("cube.fits.fz") as hdul:
308
+ plane = hdul[1].section[10]
309
+ ```
310
+
311
+ `.data` and `fits.getdata` decompress the whole cube into memory, for both `.fits.gz`
312
+ and `.fits.fz`. A `.fits.gz` cube has no cheap way to read part of it. CARTA (6.0) also
313
+ reads the whole cube into memory when it opens either kind, so decompress large cubes
314
+ before viewing them there.
315
+
316
+ To compress an existing cube, and to get plain FITS back:
317
+
318
+ ```
319
+ fitscube compress cube.fits --method tile-rice
320
+ fitscube decompress cube.fits.fz
321
+ ```
322
+
323
+ `funpack` works too, though `funpack` from CFITSIO 4.3.1 mis-decodes RICE files whose
324
+ tiles are narrower than a row. fitscube always writes full-width tiles.
325
+
326
+ Quantise once. Every decompress and recompress with `tile-rice` adds a new error, so
327
+ `fitscube decompress` marks lossy cubes with `FCLOSSY`, and `tile-rice` refuses them
328
+ unless given `allow_requantize=True`. Smooth images such as weights do not shrink under
329
+ RICE; use `tile-gzip` for them.
330
+
331
+ ## Blank channels
332
+
333
+ `--create-blanks` puts the inputs on one evenly spaced axis, with NaN planes
334
+ where there is no input. It picks the widest step that holds every input, so
335
+ images of uneven width, or images either side of a gap between bands (as in
336
+ RACS-low3, -mid and -high together), still make a single cube.
337
+
338
+ An input counts as on the grid if it is within ~1 Hz at 1 GHz of a plane (or
339
+ ~0.5 s for times). If any input is off by more than float rounding, `fitscube`
340
+ logs a warning, and the cube's `CSYERi` (the FITS systematic error of the axis)
341
+ records the largest offset. A grid of more than 1000 planes per input, or one
342
+ that cannot hold every input, is refused.
343
+
245
344
  ## Zero-sized beams
246
345
 
247
346
  wsclean writes `BMAJ = BMIN = 0` into an image when no PSF was fitted for that
@@ -78,17 +78,19 @@ Command line:
78
78
 
79
79
  ```
80
80
  ❯ fitscube -h
81
- usage: fitscube [-h] {combine,extract} ...
81
+ usage: fitscube [-h] {combine,extract,compress,decompress} ...
82
82
 
83
83
  Tooling to create fitscubes
84
84
 
85
85
  positional arguments:
86
- {combine,extract}
87
- combine Combine FITS images together into a cube
88
- extract Extract a plane from an existing cube
86
+ {combine,extract,compress,decompress}
87
+ combine Combine FITS images together into a cube
88
+ extract Extract a plane from an existing cube
89
+ compress Compress a cube to .fits.gz or .fits.fz
90
+ decompress Turn a .fits.gz or .fits.fz cube back into plain FITS
89
91
 
90
92
  options:
91
- -h, --help show this help message and exit
93
+ -h, --help show this help message and exit
92
94
  ```
93
95
 
94
96
  ```
@@ -97,7 +99,8 @@ usage: fitscube combine [-h] [-o] [--create-blanks] [--time-domain]
97
99
  [--spec-file SPEC_FILE | --specs SPECS [SPECS ...] | --ignore-spec] [-v]
98
100
  [--max-workers MAX_WORKERS] [--bounding-box] [--invalidate-zeros]
99
101
  [--no-blank-zero-beams] [--floating {32,64}] [--compress]
100
- [--compress-method {gzip,pgzip}]
102
+ [--compress-method {gzip,pgzip,tile-gzip,tile-rice}]
103
+ [--quantize-level QUANTIZE_LEVEL]
101
104
  file_list [file_list ...] out_cube
102
105
 
103
106
  positional arguments:
@@ -129,11 +132,16 @@ options:
129
132
  --floating {32,64}
130
133
  The number of floating point bits to use in the out cube. If None the
131
134
  input data precision is used.
132
- --compress Gzip-compress the output cube
133
- --compress-method {gzip,pgzip}
134
- Compression backend for --compress. 'gzip' is stdlib and needs nothing
135
- extra. 'pgzip' parallelizes across --max-workers threads but requires the
136
- 'pgzip' extra: pip install fitscube[pgzip]
135
+ --compress Compress the output cube once written
136
+ --compress-method {gzip,pgzip,tile-gzip,tile-rice}
137
+ How --compress compresses. 'gzip' and 'pgzip' gzip the whole file to
138
+ .fits.gz; 'pgzip' parallelizes across --max-workers threads but requires
139
+ the 'pgzip' extra. 'tile-gzip' (lossless) and 'tile-rice' (lossy, see
140
+ --quantize-level) tile-compress to .fits.fz, as fpack does, so single
141
+ planes can be read without decompressing the whole cube
142
+ --quantize-level QUANTIZE_LEVEL
143
+ Quantization steps per noise sigma for 'tile-rice'. Higher keeps more
144
+ precision and compresses less
137
145
  ```
138
146
 
139
147
  ```
@@ -155,6 +163,45 @@ options:
155
163
  The name of the new output file. If not specified it is generated from the fits cube name
156
164
  ```
157
165
 
166
+ ```
167
+ ❯ fitscube compress -h
168
+ usage: fitscube compress [-h] [--method {gzip,pgzip,tile-gzip,tile-rice}]
169
+ [--quantize-level QUANTIZE_LEVEL] [--max-workers MAX_WORKERS]
170
+ [--allow-requantize] [--remove] [-v]
171
+ cube
172
+
173
+ positional arguments:
174
+ cube An uncompressed FITS cube
175
+
176
+ options:
177
+ -h, --help show this help message and exit
178
+ --method {gzip,pgzip,tile-gzip,tile-rice}
179
+ 'gzip'/'pgzip' gzip the whole file to .fits.gz. 'tile-gzip' (lossless) and
180
+ 'tile-rice' (lossy) tile-compress to .fits.fz, as fpack does
181
+ --quantize-level QUANTIZE_LEVEL
182
+ Quantization steps per noise sigma for 'tile-rice'
183
+ --max-workers MAX_WORKERS
184
+ Compression threads
185
+ --allow-requantize Let 'tile-rice' quantize a cube that was already quantized once
186
+ --remove Delete the input once done
187
+ -v, --verbosity Increase output verbosity
188
+ ```
189
+
190
+ ```
191
+ ❯ fitscube decompress -h
192
+ usage: fitscube decompress [-h] [-o OUTPUT] [--overwrite] [--remove] [-v] cube
193
+
194
+ positional arguments:
195
+ cube A .fits.gz or tile-compressed .fits.fz cube
196
+
197
+ options:
198
+ -h, --help show this help message and exit
199
+ -o, --output OUTPUT Output path. Defaults to the input without .gz/.fz
200
+ --overwrite Replace the output if it exists
201
+ --remove Delete the compressed input once done
202
+ -v, --verbosity Increase output verbosity
203
+ ```
204
+
158
205
  Python:
159
206
 
160
207
  ```python
@@ -169,6 +216,59 @@ frequencies = combine_fits(
169
216
  )
170
217
  ```
171
218
 
219
+ ## Compressed cubes
220
+
221
+ `fitscube compress`, or `combine --compress`, writes the cube in one of three ways:
222
+
223
+ | Method | Output | |
224
+ |---|---|---|
225
+ | `gzip`, `pgzip` | `.fits.gz` | The whole file gzipped. Lossless. |
226
+ | `tile-gzip` | `.fits.fz` | [Tile compressed](https://heasarc.gsfc.nasa.gov/fitsio/fpack/) with GZIP_2. Lossless. |
227
+ | `tile-rice` | `.fits.fz` | Tile compressed with RICE_1, after quantising to `--quantize-level` steps per noise sigma. Lossy. |
228
+
229
+ `.fits.fz` files are what `fpack` writes, so DS9, CARTA, `funpack` and astropy can all
230
+ read them. The image is in HDU 1, and `.section` only decompresses the tiles it needs:
231
+
232
+ ```python
233
+ from astropy.io import fits
234
+
235
+ with fits.open("cube.fits.fz") as hdul:
236
+ plane = hdul[1].section[10]
237
+ ```
238
+
239
+ `.data` and `fits.getdata` decompress the whole cube into memory, for both `.fits.gz`
240
+ and `.fits.fz`. A `.fits.gz` cube has no cheap way to read part of it. CARTA (6.0) also
241
+ reads the whole cube into memory when it opens either kind, so decompress large cubes
242
+ before viewing them there.
243
+
244
+ To compress an existing cube, and to get plain FITS back:
245
+
246
+ ```
247
+ fitscube compress cube.fits --method tile-rice
248
+ fitscube decompress cube.fits.fz
249
+ ```
250
+
251
+ `funpack` works too, though `funpack` from CFITSIO 4.3.1 mis-decodes RICE files whose
252
+ tiles are narrower than a row. fitscube always writes full-width tiles.
253
+
254
+ Quantise once. Every decompress and recompress with `tile-rice` adds a new error, so
255
+ `fitscube decompress` marks lossy cubes with `FCLOSSY`, and `tile-rice` refuses them
256
+ unless given `allow_requantize=True`. Smooth images such as weights do not shrink under
257
+ RICE; use `tile-gzip` for them.
258
+
259
+ ## Blank channels
260
+
261
+ `--create-blanks` puts the inputs on one evenly spaced axis, with NaN planes
262
+ where there is no input. It picks the widest step that holds every input, so
263
+ images of uneven width, or images either side of a gap between bands (as in
264
+ RACS-low3, -mid and -high together), still make a single cube.
265
+
266
+ An input counts as on the grid if it is within ~1 Hz at 1 GHz of a plane (or
267
+ ~0.5 s for times). If any input is off by more than float rounding, `fitscube`
268
+ logs a warning, and the cube's `CSYERi` (the FITS systematic error of the axis)
269
+ records the largest offset. A grid of more than 1000 planes per input, or one
270
+ that cannot hold every input, is refused.
271
+
172
272
  ## Zero-sized beams
173
273
 
174
274
  wsclean writes `BMAJ = BMIN = 0` into an image when no PSF was fitted for that
@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
18
18
  commit_id: str | None
19
19
  __commit_id__: str | None
20
20
 
21
- __version__ = version = '2.9.0'
22
- __version_tuple__ = version_tuple = (2, 9, 0)
21
+ __version__ = version = '2.11.0'
22
+ __version_tuple__ = version_tuple = (2, 11, 0)
23
23
 
24
24
  __commit_id__ = commit_id = None
@@ -6,6 +6,12 @@ from argparse import ArgumentParser
6
6
 
7
7
  from fitscube.combine_fits import cli as combine_cli
8
8
  from fitscube.combine_fits import get_parser as combine_get_parser
9
+ from fitscube.compress import (
10
+ compress_cli,
11
+ decompress_cli,
12
+ get_compress_parser,
13
+ get_decompress_parser,
14
+ )
9
15
  from fitscube.extract import cli as extract_cli
10
16
  from fitscube.extract import get_parser as extract_get_parser
11
17
  from fitscube.logging import logger
@@ -26,6 +32,16 @@ def get_parser() -> ArgumentParser:
26
32
  )
27
33
  extract_parser = extract_get_parser(parser=extract_parser)
28
34
 
35
+ compress_parser = subparser.add_parser(
36
+ "compress", help="Compress a cube to .fits.gz or .fits.fz"
37
+ )
38
+ compress_parser = get_compress_parser(parser=compress_parser)
39
+
40
+ decompress_parser = subparser.add_parser(
41
+ "decompress", help="Turn a .fits.gz or .fits.fz cube back into plain FITS"
42
+ )
43
+ decompress_parser = get_decompress_parser(parser=decompress_parser)
44
+
29
45
  return parser
30
46
 
31
47
 
@@ -38,6 +54,10 @@ def cli() -> None:
38
54
  combine_cli(args=args)
39
55
  elif args.mode == "extract":
40
56
  extract_cli(args=args)
57
+ elif args.mode == "compress":
58
+ compress_cli(args=args)
59
+ elif args.mode == "decompress":
60
+ decompress_cli(args=args)
41
61
  else:
42
62
  logger.critical(f"Unknown mode {args.mode=}")
43
63