askap-patchwork 0.1.0__py3-none-any.whl

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.
patchwork/convolve.py ADDED
@@ -0,0 +1,534 @@
1
+ """Convolution of images to a common restoring beam.
2
+
3
+ The convolution is done in the Fourier domain by the ratio of the transforms of
4
+ the target and current beams, as the racs-tools ``robust`` mode does, so no
5
+ kernel image is ever formed. Images in Jy/beam are rescaled by the ratio of the
6
+ beam areas.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from argparse import ArgumentParser, Namespace
12
+ from concurrent.futures import ThreadPoolExecutor
13
+ from pathlib import Path
14
+ from typing import TYPE_CHECKING
15
+
16
+ import numpy as np
17
+ import scipy.fft
18
+ from astropy.io import fits
19
+ from capn_crunch import add_options_to_parser, create_options_from_parser
20
+ from radio_beam import Beams
21
+ from radio_beam.utils import BeamError
22
+
23
+ from patchwork.io import (
24
+ NO_BEAM,
25
+ BeamShape,
26
+ ImageInfo,
27
+ celestial_wcs,
28
+ check_output_fits,
29
+ create_output_fits,
30
+ read_block,
31
+ read_image_info,
32
+ suffixed_name,
33
+ write_block,
34
+ )
35
+ from patchwork.logging import logger, setup_logging
36
+ from patchwork.options import ConvolveOptions
37
+
38
+ if TYPE_CHECKING:
39
+ from numpy.typing import NDArray
40
+
41
+
42
+ def beam_covariance(beam: BeamShape) -> NDArray[np.float64]:
43
+ """The covariance in degrees squared of a beam, along (east, north)."""
44
+ pa = np.radians(beam.bpa_deg)
45
+ major = np.array([np.sin(pa), np.cos(pa)])
46
+ minor = np.array([np.cos(pa), -np.sin(pa)])
47
+ fwhm_to_sigma = 1 / np.sqrt(8 * np.log(2))
48
+ sigma_major = beam.bmaj_arcsec / 3600 * fwhm_to_sigma
49
+ sigma_minor = beam.bmin_arcsec / 3600 * fwhm_to_sigma
50
+ return np.asarray(
51
+ sigma_major**2 * np.outer(major, major)
52
+ + sigma_minor**2 * np.outer(minor, minor)
53
+ )
54
+
55
+
56
+ def _round_up(value: float, decimals: int) -> float:
57
+ """Round up to a number of decimal places."""
58
+ return float(np.ceil(value * 10**decimals) / 10**decimals)
59
+
60
+
61
+ def common_beam(
62
+ beams: list[BeamShape | None],
63
+ cutoff_arcsec: float | None = None,
64
+ circularise: bool = False,
65
+ tolerance: float = 1e-4,
66
+ nsamps: int = 200,
67
+ epsilon: float = 5e-4,
68
+ name: str | None = None,
69
+ ) -> BeamShape:
70
+ """The smallest beam that encloses every usable beam, rounded up as racs-tools does.
71
+
72
+ Missing, zero and NaN beams, and beams whose major axis is larger than the
73
+ cutoff, are left out. The axes are rounded up to 0.1 arcsec and the position
74
+ angle up to 0.01 degrees.
75
+
76
+ Args:
77
+ beams (list[BeamShape | None]): The beams to enclose
78
+ cutoff_arcsec (float | None, optional): Leave out beams with a major axis larger than this. Defaults to None.
79
+ circularise (bool, optional): Make the common beam circular. Defaults to False.
80
+ tolerance (float, optional): Tolerance of the common beam search. Defaults to 1e-4.
81
+ nsamps (int, optional): Number of samples of the common beam search. Defaults to 200.
82
+ epsilon (float, optional): Epsilon of the common beam search. Defaults to 5e-4.
83
+ name (str | None, optional): What the beams are of, such as a channel, for the log. Defaults to None.
84
+
85
+ Raises:
86
+ ValueError: Raised when no beam is usable
87
+
88
+ Returns:
89
+ BeamShape: The common beam
90
+ """
91
+ usable = [
92
+ beam
93
+ for beam in beams
94
+ if beam is not None
95
+ and beam.is_usable()
96
+ and (cutoff_arcsec is None or beam.bmaj_arcsec <= cutoff_arcsec)
97
+ ]
98
+ if not usable:
99
+ msg = f"None of the {len(beams)} beams is usable"
100
+ raise ValueError(msg)
101
+
102
+ radio_beams = Beams(beams=[beam.to_radio_beam() for beam in usable])
103
+ try:
104
+ found = radio_beams.common_beam(
105
+ tolerance=tolerance, nsamps=nsamps, epsilon=epsilon
106
+ )
107
+ except BeamError:
108
+ logger.warning(f"Retrying the common beam search with {tolerance=:.1g} / 10")
109
+ found = radio_beams.common_beam(
110
+ tolerance=tolerance * 0.1, nsamps=nsamps, epsilon=epsilon
111
+ )
112
+
113
+ found_shape = BeamShape.from_radio_beam(found)
114
+ bmaj = _round_up(found_shape.bmaj_arcsec, decimals=1)
115
+ shape = BeamShape(
116
+ bmaj_arcsec=bmaj,
117
+ bmin_arcsec=bmaj
118
+ if circularise
119
+ else _round_up(found_shape.bmin_arcsec, decimals=1),
120
+ bpa_deg=0.0 if circularise else _round_up(found_shape.bpa_deg, decimals=2),
121
+ )
122
+ n_missing = sum(beam is None or not beam.is_usable() for beam in beams)
123
+ n_large = len(beams) - len(usable) - n_missing
124
+ left_out = ([f"{n_missing} with no beam"] if n_missing else []) + (
125
+ [f'{n_large} larger than {cutoff_arcsec:g}"'] if n_large else []
126
+ )
127
+ logger.info(
128
+ f"Common beam{f' of {name}' if name else ''} is {shape}, "
129
+ f"from {len(usable)} of {len(beams)} beams"
130
+ + (f" ({', '.join(left_out)})" if left_out else "")
131
+ )
132
+ return shape
133
+
134
+
135
+ def convolve_to_beam(
136
+ image: NDArray[np.floating],
137
+ old_beam: BeamShape,
138
+ new_beam: BeamShape,
139
+ pixel_scale_matrix: NDArray[np.float64],
140
+ cutoff_arcsec: float | None = None,
141
+ ) -> NDArray[np.floating]:
142
+ """Convolve an image in Jy/beam from its restoring beam to a larger one.
143
+
144
+ NaNs are filled with zeros for the convolution and then blanked again, along
145
+ with every pixel where more than half of the convolved signal came from them.
146
+
147
+ Args:
148
+ image (NDArray[np.floating]): The (y, x) image
149
+ old_beam (BeamShape): The restoring beam of the image
150
+ new_beam (BeamShape): The beam to convolve to
151
+ pixel_scale_matrix (NDArray[np.float64]): Degrees (east, north) per (x, y) pixel, e.g. ``WCS.pixel_scale_matrix``
152
+ cutoff_arcsec (float | None, optional): Blank the whole image if its beam major axis is larger than this. Defaults to None.
153
+
154
+ Raises:
155
+ ValueError: Raised if the new beam does not enclose the old beam
156
+
157
+ Returns:
158
+ NDArray[np.floating]: The convolved image, in the precision of the input
159
+ """
160
+ if cutoff_arcsec is not None and old_beam.bmaj_arcsec > cutoff_arcsec:
161
+ logger.warning(
162
+ f'Blanking an image whose beam, {old_beam}, is larger than {cutoff_arcsec:g}"'
163
+ )
164
+ return np.full_like(image, np.nan)
165
+ if np.allclose(old_beam, new_beam, rtol=1e-9, atol=0):
166
+ return image.copy()
167
+
168
+ # The kernel is the difference of the beam covariances, in pixels. radio_beam's
169
+ # deconvolve is not used, as it fails when a common beam falls a hair inside an
170
+ # input, which rounding its position angle up can do, and its kernels ignore
171
+ # pixels that are not aligned with the sky
172
+ to_pixels = np.linalg.inv(pixel_scale_matrix)
173
+ difference = (
174
+ to_pixels
175
+ @ (beam_covariance(new_beam) - beam_covariance(old_beam))
176
+ @ to_pixels.T
177
+ )
178
+ eigenvalues, eigenvectors = np.linalg.eigh(difference)
179
+ old_size = np.max(
180
+ np.linalg.eigvalsh(to_pixels @ beam_covariance(old_beam) @ to_pixels.T)
181
+ )
182
+ if np.min(eigenvalues) < -1e-3 * old_size:
183
+ msg = f"Cannot convolve {old_beam} to {new_beam}, which does not enclose it"
184
+ raise ValueError(msg)
185
+ eigenvalues = np.clip(eigenvalues, 0, None)
186
+ difference = eigenvectors @ np.diag(eigenvalues) @ eigenvectors.T
187
+
188
+ real_dtype: type[np.floating] = (
189
+ np.float32 if image.dtype.itemsize <= 4 else np.float64
190
+ )
191
+ ny, nx = image.shape
192
+ # The transforms are circular, so zeros as wide as the kernel reaches (five of
193
+ # its sigma) keep flux from wrapping between opposite edges
194
+ reach = int(np.ceil(5 * np.sqrt(np.max(eigenvalues))))
195
+ padded = (
196
+ scipy.fft.next_fast_len(ny + reach, real=True),
197
+ scipy.fft.next_fast_len(nx + reach, real=True),
198
+ )
199
+ area_ratio = (new_beam.bmaj_arcsec * new_beam.bmin_arcsec) / (
200
+ old_beam.bmaj_arcsec * old_beam.bmin_arcsec
201
+ )
202
+
203
+ # Images can be large, so each plane-sized array is made once and worked on in
204
+ # place. The taper carries the ratio of the beam areas
205
+ fy = scipy.fft.fftfreq(padded[0]).astype(real_dtype)[:, None]
206
+ fx = scipy.fft.rfftfreq(padded[1]).astype(real_dtype)[None, :]
207
+ taper = (2 * float(difference[0, 1]) * fy) * fx
208
+ taper += float(difference[0, 0]) * fx**2
209
+ taper += float(difference[1, 1]) * fy**2
210
+ taper *= -2 * np.pi**2
211
+ np.exp(taper, out=taper)
212
+ taper *= area_ratio
213
+
214
+ def tapered(
215
+ plane: NDArray[np.generic], where: NDArray[np.bool_] | bool = True
216
+ ) -> NDArray[np.floating]:
217
+ """``plane``, zero where not ``where``, padded, multiplied by the taper in the Fourier domain, and cropped."""
218
+ padded_plane = np.zeros(padded, dtype=real_dtype)
219
+ np.copyto(padded_plane[:ny, :nx], plane, where=where)
220
+ spectrum = scipy.fft.rfft2(padded_plane, overwrite_x=True)
221
+ del padded_plane
222
+ spectrum *= taper
223
+ return np.asarray(
224
+ scipy.fft.irfft2(spectrum, s=padded, overwrite_x=True)[:ny, :nx]
225
+ )
226
+
227
+ # The NaNs are spread first, so only a mask of where they reach is held while
228
+ # the image is convolved
229
+ finite = np.isfinite(image)
230
+ blank = None
231
+ if not np.all(finite):
232
+ blank = ~finite
233
+ blank |= tapered(blank) > 0.5 * area_ratio
234
+
235
+ convolved = tapered(image, where=finite)
236
+ if blank is not None:
237
+ convolved[blank] = np.nan
238
+ logger.info(f"Blanked {np.mean(blank):.1%} of the convolved image")
239
+
240
+ return np.asarray(convolved, dtype=image.dtype)
241
+
242
+
243
+ def convolved_name(path: str | Path, suffix: str = "conv") -> Path:
244
+ """The name of a convolved image: ``suffix`` inserted before a final ``.fits``, or added with ``.fits`` after any other name, so it never names the image itself."""
245
+ return suffixed_name(path, suffix)
246
+
247
+
248
+ def convolve_fits(
249
+ path: str | Path,
250
+ beam: BeamShape,
251
+ output_path: str | Path | None = None,
252
+ suffix: str = "conv",
253
+ cutoff_arcsec: float | None = None,
254
+ overwrite: bool = False,
255
+ ) -> Path:
256
+ """Convolve a FITS image to a beam, writing a float32 image with the new beam in its header.
257
+
258
+ An image blanked by the cutoff is given a zero beam, as racs-tools does.
259
+
260
+ Args:
261
+ path (str | Path): The image to convolve
262
+ beam (BeamShape): The beam to convolve to
263
+ output_path (str | Path | None, optional): Where to write the convolved image. Defaults to None, the image name with ``suffix``.
264
+ suffix (str, optional): Suffix of the default output name. Defaults to "conv".
265
+ cutoff_arcsec (float | None, optional): Blank the image if its beam major axis is larger than this. Defaults to None.
266
+ overwrite (bool, optional): Replace an existing output. Defaults to False.
267
+
268
+ Raises:
269
+ ValueError: Raised if the image has no usable restoring beam
270
+
271
+ Returns:
272
+ Path: The convolved image
273
+ """
274
+ path = Path(path)
275
+ output_path = (
276
+ convolved_name(path, suffix) if output_path is None else Path(output_path)
277
+ )
278
+ check_output_fits(output_path, overwrite=overwrite, input_fits=[path])
279
+
280
+ with fits.open(path, memmap=True) as hdul:
281
+ header = hdul[0].header.copy()
282
+ data = np.array(hdul[0].data, dtype=np.float32)
283
+
284
+ old_beam = BeamShape.from_header(header)
285
+ if old_beam is None or not old_beam.is_usable():
286
+ msg = f"{path} has no usable restoring beam"
287
+ raise ValueError(msg)
288
+
289
+ plane = data.reshape(data.shape[-2:])
290
+ convolved = convolve_to_beam(
291
+ image=plane,
292
+ old_beam=old_beam,
293
+ new_beam=beam,
294
+ pixel_scale_matrix=celestial_wcs(header).pixel_scale_matrix,
295
+ cutoff_arcsec=cutoff_arcsec,
296
+ )
297
+ blanked = cutoff_arcsec is not None and old_beam.bmaj_arcsec > cutoff_arcsec
298
+ (BeamShape(0.0, 0.0, 0.0) if blanked else beam).to_header(header)
299
+ header["HISTORY"] = f"Convolved from {old_beam} to {beam}"
300
+
301
+ fits.writeto(
302
+ output_path, convolved.reshape(data.shape), header=header, overwrite=True
303
+ )
304
+ logger.info(f"Written {output_path}")
305
+ return output_path
306
+
307
+
308
+ def convolve_images(
309
+ images: list[Path],
310
+ options: ConvolveOptions = ConvolveOptions(), # noqa: B008
311
+ overwrite: bool = False,
312
+ ) -> tuple[BeamShape, list[Path]]:
313
+ """Convolve images to a target beam, or to their common beam, one after another.
314
+
315
+ Args:
316
+ images (list[Path]): The images to convolve
317
+ options (ConvolveOptions, optional): How the images are convolved. Defaults to ConvolveOptions().
318
+ overwrite (bool, optional): Replace existing outputs. Defaults to False.
319
+
320
+ Returns:
321
+ tuple[BeamShape, list[Path]]: The beam convolved to, and the convolved images
322
+ """
323
+ # Images matched by a pattern can include ones convolved before, so no output may be any input
324
+ for image in images:
325
+ check_output_fits(
326
+ convolved_name(image, options.suffix),
327
+ overwrite=overwrite,
328
+ input_fits=images,
329
+ )
330
+ beam = target_beam(images, options)
331
+ outputs = [
332
+ convolve_fits(
333
+ image,
334
+ beam=beam,
335
+ suffix=options.suffix,
336
+ cutoff_arcsec=options.beam_cutoff_arcsec,
337
+ overwrite=overwrite,
338
+ )
339
+ for image in images
340
+ ]
341
+ return beam, outputs
342
+
343
+
344
+ def target_beam(images: list[Path], options: ConvolveOptions) -> BeamShape:
345
+ """The beam images are convolved to: the target beam if given, otherwise their common beam."""
346
+ if options.target_beam is not None:
347
+ return BeamShape(*options.target_beam)
348
+ return common_beam(
349
+ beams=[BeamShape.from_header(fits.getheader(image)) for image in images],
350
+ cutoff_arcsec=options.beam_cutoff_arcsec,
351
+ circularise=options.circularise,
352
+ tolerance=options.tolerance,
353
+ nsamps=options.nsamps,
354
+ epsilon=options.epsilon,
355
+ )
356
+
357
+
358
+ def channel_target_beams(
359
+ infos: list[ImageInfo],
360
+ mode: str,
361
+ options: ConvolveOptions,
362
+ channels: slice,
363
+ ) -> tuple[BeamShape, ...]:
364
+ """The beam each channel is convolved to, or ``NO_BEAM`` for a channel left blank.
365
+
366
+ Channels outside ``channels`` are left blank.
367
+
368
+ Args:
369
+ infos (list[ImageInfo]): Every cube
370
+ mode (str): ``natural``, a common beam for each channel, or ``total``, one beam for every channel
371
+ options (ConvolveOptions): How the common beam is found
372
+ channels (slice): The channels that are convolved
373
+
374
+ Returns:
375
+ tuple[BeamShape, ...]: The beam of each channel
376
+ """
377
+ n_channels = infos[0].n_channels
378
+ selected = range(*channels.indices(n_channels))
379
+ if options.target_beam is not None:
380
+ target = BeamShape(*options.target_beam)
381
+ return tuple(
382
+ target if channel in selected else NO_BEAM for channel in range(n_channels)
383
+ )
384
+
385
+ def common(beams: list[BeamShape | None], name: str | None) -> BeamShape:
386
+ try:
387
+ return common_beam(
388
+ beams,
389
+ cutoff_arcsec=options.beam_cutoff_arcsec,
390
+ circularise=options.circularise,
391
+ tolerance=options.tolerance,
392
+ nsamps=options.nsamps,
393
+ epsilon=options.epsilon,
394
+ name=name,
395
+ )
396
+ except ValueError as error:
397
+ logger.info(f"Leaving {name or 'the images'} blank: {error}")
398
+ return NO_BEAM
399
+
400
+ def channel_name(channel: int) -> str | None:
401
+ if n_channels == 1:
402
+ return None
403
+ frequencies = infos[0].frequencies_hz
404
+ if channel < len(frequencies):
405
+ return f"channel {channel} ({frequencies[channel] / 1e6:.3f} MHz)"
406
+ return f"channel {channel}"
407
+
408
+ if mode == "total":
409
+ total = common(
410
+ [info.channel_beams[channel] for info in infos for channel in selected],
411
+ None if n_channels == 1 else f"channels {selected[0]} to {selected[-1]}",
412
+ )
413
+ return tuple(
414
+ total if channel in selected else NO_BEAM for channel in range(n_channels)
415
+ )
416
+ return tuple(
417
+ common([info.channel_beams[channel] for info in infos], channel_name(channel))
418
+ if channel in selected
419
+ else NO_BEAM
420
+ for channel in range(n_channels)
421
+ )
422
+
423
+
424
+ def convolve_cube(
425
+ path: str | Path,
426
+ beams: tuple[BeamShape, ...],
427
+ output_path: str | Path,
428
+ cutoff_arcsec: float | None = None,
429
+ overwrite: bool = False,
430
+ channels: slice | None = None,
431
+ threads: int = 1,
432
+ ) -> Path:
433
+ """Convolve some channels of a cube to their beams, a channel at a time in each of ``threads`` threads.
434
+
435
+ A channel whose target beam is ``NO_BEAM``, or whose own beam is not usable
436
+ or is larger than the cutoff, is blanked and given no beam. Channels outside
437
+ ``channels`` are given no beam and are not written at all, so they cost no
438
+ time, and read as zeros.
439
+
440
+ Each thread holds about three planes of the padded image at once (its
441
+ padded plane, its spectrum and its result), so 16 threads on 10000² planes
442
+ hold some 20 GB.
443
+
444
+ Args:
445
+ path (str | Path): The cube to convolve
446
+ beams (tuple[BeamShape, ...]): The beam to convolve each channel to
447
+ output_path (str | Path): Where to write the convolved cube
448
+ cutoff_arcsec (float | None, optional): Blank channels whose beam major axis is larger than this. Defaults to None.
449
+ overwrite (bool, optional): Replace an existing output. Defaults to False.
450
+ channels (slice | None, optional): The channels to convolve. Defaults to None, every channel.
451
+ threads (int, optional): Threads that each convolve a channel at a time. Defaults to 1.
452
+
453
+ Returns:
454
+ Path: The convolved cube
455
+ """
456
+ info = read_image_info(path)
457
+ output_path = Path(output_path)
458
+ check_output_fits(output_path, overwrite=overwrite, input_fits=[path])
459
+ selected = range(*(channels or slice(None)).indices(info.n_channels))
460
+
461
+ new_beams = []
462
+ for channel, (old, new) in enumerate(zip(info.channel_beams, beams, strict=True)):
463
+ usable = (
464
+ channel in selected
465
+ and old is not None
466
+ and old.is_usable()
467
+ and new.is_usable()
468
+ and (cutoff_arcsec is None or old.bmaj_arcsec <= cutoff_arcsec)
469
+ )
470
+ new_beams.append(new if usable else NO_BEAM)
471
+ if not usable and channel in selected:
472
+ logger.debug(f"Leaving channel {channel} of {path} blank")
473
+
474
+ header = info.header.copy()
475
+ header["HISTORY"] = "Convolved to a common beam by patchwork"
476
+ create_output_fits(output_path, header, tuple(new_beams))
477
+ pixel_scale_matrix = celestial_wcs(info.header).pixel_scale_matrix
478
+ with fits.open(output_path, mode="update", memmap=True) as hdul:
479
+ hdu = hdul[0]
480
+ hdu.data # noqa: B018 # Map the data once, before any thread writes to it
481
+
482
+ def convolve_channel(channel: int) -> None:
483
+ old, new = info.channel_beams[channel], new_beams[channel]
484
+ channel_slice = slice(channel, channel + 1)
485
+ if not new.is_usable() or old is None:
486
+ write_block(
487
+ hdu,
488
+ (slice(None), slice(None)),
489
+ np.full((1, *info.shape), np.nan),
490
+ channel_slice,
491
+ )
492
+ return
493
+ plane = read_block(path, channels=channel_slice, dtype=np.float32)[0]
494
+ convolved = convolve_to_beam(plane, old, new, pixel_scale_matrix)
495
+ write_block(hdu, (slice(None), slice(None)), convolved[None], channel_slice)
496
+
497
+ if threads > 1 and len(selected) > 1:
498
+ # The FFTs and the copies release the GIL, and each channel is its own
499
+ # part of the file
500
+ with ThreadPoolExecutor(min(threads, len(selected))) as pool:
501
+ list(pool.map(convolve_channel, selected))
502
+ else:
503
+ for channel in selected:
504
+ convolve_channel(channel)
505
+ logger.info(f"Written {output_path}")
506
+ return output_path
507
+
508
+
509
+ def get_parser(parser: ArgumentParser | None = None) -> ArgumentParser:
510
+ """The parser of the ``convolve`` command."""
511
+ if parser is None:
512
+ parser = ArgumentParser(description=__doc__)
513
+ parser.add_argument("images", nargs="+", type=Path, help="The images to convolve")
514
+ parser.add_argument(
515
+ "--overwrite", action="store_true", help="Replace existing output files"
516
+ )
517
+ return add_options_to_parser(parser=parser, options_class=ConvolveOptions)
518
+
519
+
520
+ def cli(args: Namespace | None = None) -> None:
521
+ """Run the ``convolve`` command."""
522
+ setup_logging()
523
+ args = get_parser().parse_args() if args is None else args
524
+ convolve_images(
525
+ images=args.images,
526
+ options=create_options_from_parser(
527
+ parser_namespace=args, options_class=ConvolveOptions
528
+ ),
529
+ overwrite=args.overwrite,
530
+ )
531
+
532
+
533
+ if __name__ == "__main__":
534
+ cli()