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/plan.py ADDED
@@ -0,0 +1,818 @@
1
+ """Planning a mosaic: grouping its images into inputs, and building its frame and the inputs on it.
2
+
3
+ Images and cubes are given as one list. Each image's Stokes parameter is read
4
+ from its STOKES axis, and images on one pixel grid are taken to be the Stokes
5
+ parameters of one beam. An image is a cube of one channel.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from pathlib import Path
11
+ from typing import TYPE_CHECKING, Any, NamedTuple
12
+
13
+ import numpy as np
14
+
15
+ from patchwork import __version__
16
+ from patchwork.coordinates import offset_vectors, ra_dec, unit_vectors
17
+ from patchwork.frame import (
18
+ BoundingBox,
19
+ Frame,
20
+ build_frame,
21
+ input_bounding_box,
22
+ intersect_boxes,
23
+ shift_box,
24
+ strips,
25
+ tiles,
26
+ union_of_boxes,
27
+ world_bounding_box,
28
+ )
29
+ from patchwork.io import NO_BEAM, BeamShape, ImageInfo, Slices, read_image_info
30
+ from patchwork.logging import logger
31
+ from patchwork.polarisation import (
32
+ NORTH,
33
+ STOKES_CODES,
34
+ LinearFrame,
35
+ frame_angle,
36
+ header_frame,
37
+ remove_frame_keywords,
38
+ write_frame_keywords,
39
+ )
40
+ from patchwork.primary_beam import BeamModel, beam_model
41
+ from patchwork.resample import kernel_width
42
+ from patchwork.tile import (
43
+ MosaicInput,
44
+ PlaneWeight,
45
+ group_members,
46
+ weight_groups,
47
+ )
48
+ from patchwork.weights import combined_weight, read_weights_log
49
+
50
+ if TYPE_CHECKING:
51
+ from astropy.io import fits
52
+
53
+ from patchwork.options import (
54
+ MosaicOptions,
55
+ PolarisationOptions,
56
+ RunOptions,
57
+ WeightOptions,
58
+ )
59
+
60
+
61
+ STOKES_NAMES = {code: name for name, code in STOKES_CODES.items()}
62
+
63
+
64
+ def _grid_key(info: ImageInfo) -> tuple[Any, ...]:
65
+ """What makes two cubes share a pixel grid."""
66
+ wcs = info.wcs.wcs
67
+ return (
68
+ info.shape,
69
+ tuple(wcs.ctype),
70
+ *(
71
+ tuple(np.round(values, decimals))
72
+ for values, decimals in ((wcs.crval, 9), (wcs.crpix, 6), (wcs.cdelt, 12))
73
+ ),
74
+ )
75
+
76
+
77
+ def _output_beams(
78
+ infos: list[ImageInfo], channels: slice, convolved: tuple[BeamShape, ...] | None
79
+ ) -> tuple[BeamShape, ...]:
80
+ """The restoring beam of each channel of the mosaic: the beam convolved to, else that of the first cube."""
81
+ if convolved is not None:
82
+ return convolved[channels]
83
+ beams = tuple(beam or NO_BEAM for beam in infos[0].channel_beams[channels])
84
+ for info in infos[1:]:
85
+ others = tuple(beam or NO_BEAM for beam in info.channel_beams[channels])
86
+ if not np.allclose(beams, others, rtol=0.01, equal_nan=True):
87
+ logger.warning(
88
+ f"The restoring beams of {info.path} differ from those of {infos[0].path}, "
89
+ "whose beams the mosaic is given. Convolve the cubes to a common beam to avoid this"
90
+ )
91
+ break
92
+ return beams
93
+
94
+
95
+ class MosaicNames(NamedTuple):
96
+ """The files a mosaic is written to"""
97
+
98
+ images: tuple[Path, ...]
99
+ """The mosaic images, one for each image of the inputs"""
100
+ weights: tuple[Path, ...]
101
+ """The weight of the mosaic images, one for each group of images that share a weight"""
102
+ noises: tuple[Path, ...] = ()
103
+ """The noise of each weight, the inverse of its square root, when it is written"""
104
+
105
+ @property
106
+ def image(self) -> Path:
107
+ """The first, and usually only, mosaic image."""
108
+ return self.images[0]
109
+
110
+ @property
111
+ def weight(self) -> Path:
112
+ """The first, and usually only, weight image."""
113
+ return self.weights[0]
114
+
115
+
116
+ class InputImages(NamedTuple):
117
+ """The images of one input, before they are placed on the frame"""
118
+
119
+ info: ImageInfo
120
+ """The description of the first image, which gives the grid, frequencies and beams"""
121
+ planes: tuple[Path, ...]
122
+ """The images of the input, which share its grid"""
123
+ stokes: tuple[int, ...]
124
+ """The FITS Stokes code of each image, or 0 where it is unknown"""
125
+ weights: tuple[PlaneWeight, ...]
126
+ """The weight of each image"""
127
+ stokes_i_path: Path | None = None
128
+ """Stokes I image of the input, whose leakage is removed from its other images"""
129
+ frame: LinearFrame | None = None
130
+ """What the POLFRAME keywords of its images say its Q and U are referenced to, or None if they say nothing"""
131
+
132
+
133
+ class MosaicPlan(NamedTuple):
134
+ """Everything needed to make and write the tiles of a mosaic"""
135
+
136
+ names: MosaicNames
137
+ """The files the mosaic is written to"""
138
+ frame: Frame
139
+ """The frame of the mosaic"""
140
+ inputs: list[MosaicInput]
141
+ """The inputs of the mosaic"""
142
+ tiles: list[Slices]
143
+ """The tiles the frame is split into"""
144
+ channels: slice = slice(0, 1)
145
+ """The channels of the inputs that are mosaicked"""
146
+ groups: tuple[int, ...] = (0,)
147
+ """The weight group of each mosaic image"""
148
+ headers: tuple[fits.Header, ...] = ()
149
+ """The header of each output: the images, then the weights, then the noises"""
150
+ beams: tuple[BeamShape, ...] = ()
151
+ """The restoring beam of each channel of the mosaic"""
152
+
153
+
154
+ def read_weight(path: str | Path, info: ImageInfo) -> PlaneWeight:
155
+ """The weight of an image or cube: a linmos weights log (``.txt``), with a weight for each of its channels, or a weight image or cube on its grid.
156
+
157
+ Raises:
158
+ ValueError: Raised if the weights do not cover the channels or grid of the image
159
+ """
160
+ path = Path(path)
161
+ if path.suffix == ".txt":
162
+ values = read_weights_log(path)
163
+ if len(values) != info.n_channels:
164
+ msg = f"{path} has {len(values)} channels, but {info.path} has {info.n_channels}"
165
+ raise ValueError(msg)
166
+ return PlaneWeight(values=values)
167
+
168
+ weight_info = read_image_info(path)
169
+ if weight_info.shape != info.shape or weight_info.n_channels not in (
170
+ 1,
171
+ info.n_channels,
172
+ ):
173
+ msg = f"The weight image {path} is not the shape of {info.path}"
174
+ raise ValueError(msg)
175
+ return PlaneWeight(values=(), paths=(path,))
176
+
177
+
178
+ def combine_weights(weights: list[PlaneWeight]) -> PlaneWeight:
179
+ """The one weight of images that are weighted together, such as Q and U: the inverse of their mean variance.
180
+
181
+ Raises:
182
+ ValueError: Raised if some of the images are weighted by weight images and others are not
183
+ """
184
+ paths = tuple(path for weight in weights for path in weight.paths)
185
+ if paths and not all(weight.paths for weight in weights):
186
+ msg = "Images weighted together must all have weight images, or none"
187
+ raise ValueError(msg)
188
+ if paths:
189
+ return PlaneWeight(values=(), paths=paths)
190
+ return PlaneWeight(
191
+ values=tuple(
192
+ combined_weight(list(channel))
193
+ for channel in zip(*(weight.values for weight in weights), strict=True)
194
+ )
195
+ )
196
+
197
+
198
+ def check_spectral_axes(infos: list[ImageInfo]) -> None:
199
+ """Raise unless every cube has the channels of the first, to within 1% of a channel.
200
+
201
+ Images of a single channel may be at any frequency, as each input's
202
+ primary beam is found at its own.
203
+
204
+ Raises:
205
+ ValueError: Raised if the cubes differ in their channels
206
+ """
207
+ if all(info.n_channels == 1 for info in infos):
208
+ return
209
+ reference = np.asarray(infos[0].frequencies_hz)
210
+ width = np.min(np.abs(np.diff(reference))) if len(reference) > 1 else 1.0
211
+ for info in infos[1:]:
212
+ frequencies = np.asarray(info.frequencies_hz)
213
+ if frequencies.shape != reference.shape or np.any(
214
+ np.abs(frequencies - reference) > 0.01 * width
215
+ ):
216
+ msg = (
217
+ f"{info.path} has {len(frequencies)} channels that do not match the "
218
+ f"{len(reference)} of {infos[0].path}. Every cube must share its channels"
219
+ )
220
+ raise ValueError(msg)
221
+
222
+
223
+ def group_inputs(
224
+ infos: list[ImageInfo],
225
+ weights: list[PlaneWeight],
226
+ remove_leakage: bool = False,
227
+ stokes_i: list[ImageInfo] | None = None,
228
+ ) -> list[InputImages]:
229
+ """Group images or cubes into the Stokes parameters of each beam, by the pixel grid they share.
230
+
231
+ Every beam must hold the same Stokes parameters. Their images are ordered
232
+ I, Q, U, V, and Q and U share a weight, the inverse of their mean
233
+ variance. Images of a single Stokes parameter that share a grid, such as
234
+ epochs of one pointing, are each an input of their own. Q without U cannot
235
+ be rotated into the frame of the mosaic, so it is mosaicked as it is.
236
+
237
+ Args:
238
+ infos (list[ImageInfo]): The images or cubes
239
+ weights (list[PlaneWeight]): The weight of each
240
+ remove_leakage (bool, optional): Remove the leakage of each beam's Stokes I from its other images. Defaults to False.
241
+ stokes_i (list[ImageInfo] | None, optional): Stokes I images, matched to beams by their grid, that the leakage is removed with but are not mosaicked. Defaults to None, using the beams' own.
242
+
243
+ Raises:
244
+ ValueError: Raised if beams hold different Stokes parameters, images of one Stokes parameter share a grid with other Stokes parameters, or the leakage is to be removed from an image of unknown Stokes parameter, or from a beam with no Stokes I image
245
+
246
+ Returns:
247
+ list[InputImages]: The images of each input
248
+ """
249
+ beams: dict[tuple[Any, ...], dict[int, list[tuple[ImageInfo, PlaneWeight]]]] = {}
250
+ for info, weight in zip(infos, weights, strict=True):
251
+ beam = beams.setdefault(_grid_key(info), {})
252
+ beam.setdefault(info.stokes or 0, []).append((info, weight))
253
+
254
+ stokes_sets = {tuple(sorted(beam)) for beam in beams.values()}
255
+ if len(stokes_sets) > 1:
256
+ msg = f"Every beam must hold the same Stokes parameters, but they hold {sorted(stokes_sets)}"
257
+ raise ValueError(msg)
258
+ codes = stokes_sets.pop()
259
+ repeated = [
260
+ members
261
+ for beam in beams.values()
262
+ for members in beam.values()
263
+ if len(members) > 1
264
+ ]
265
+ if repeated and len(codes) > 1:
266
+ msg = (
267
+ f"{repeated[0][0][0].path} and {repeated[0][1][0].path} are both Stokes code "
268
+ f"{repeated[0][0][0].stokes or 0} on one pixel grid, so cannot be paired with the other Stokes parameters of their beam"
269
+ )
270
+ raise ValueError(msg)
271
+ if (STOKES_CODES["Q"] in codes) != (STOKES_CODES["U"] in codes):
272
+ logger.warning(
273
+ "Stokes Q or U images are mosaicked without the other, so cannot be "
274
+ "rotated into the frame of the mosaic. Mosaic Q with U for that"
275
+ )
276
+
277
+ references: dict[tuple[Any, ...], Path] = {}
278
+ for info in stokes_i or []:
279
+ if references.setdefault(_grid_key(info), info.path) != info.path:
280
+ msg = f"{info.path} and {references[_grid_key(info)]} are Stokes I images on one pixel grid"
281
+ raise ValueError(msg)
282
+ leaky = remove_leakage and any(code != STOKES_CODES["I"] for code in codes)
283
+ unknown = [info.path for info in infos if not info.stokes]
284
+ if leaky and unknown:
285
+ msg = f"{unknown[0]} has no STOKES axis, so the leakage of Stokes I cannot be removed from it"
286
+ raise ValueError(msg)
287
+
288
+ images = []
289
+ for key, beam in beams.items():
290
+ # Each image of a single Stokes parameter sharing a grid is an input of its own
291
+ inputs = (
292
+ [{codes[0]: member} for member in beam[codes[0]]]
293
+ if repeated
294
+ else [{code: beam[code][0] for code in codes}]
295
+ )
296
+ for members in inputs:
297
+ first = members[codes[0]][0]
298
+ stokes_i_path = None
299
+ if leaky:
300
+ stokes_i_path = (
301
+ members[STOKES_CODES["I"]][0].path
302
+ if STOKES_CODES["I"] in members
303
+ else references.get(key)
304
+ )
305
+ if stokes_i_path is None:
306
+ msg = f"Removing the leakage needs a Stokes I image of every beam, but {first.path} has none"
307
+ raise ValueError(msg)
308
+ plane_weights = {code: members[code][1] for code in codes}
309
+ linear = [
310
+ code for code in (STOKES_CODES["Q"], STOKES_CODES["U"]) if code in codes
311
+ ]
312
+ if linear:
313
+ shared = combine_weights([members[code][1] for code in linear])
314
+ for code in linear:
315
+ plane_weights[code] = shared
316
+ images.append(
317
+ InputImages(
318
+ info=first,
319
+ planes=tuple(members[code][0].path for code in codes),
320
+ stokes=codes,
321
+ weights=tuple(plane_weights[code] for code in codes),
322
+ stokes_i_path=stokes_i_path,
323
+ frame=recorded_frame([members[code][0] for code in codes], codes),
324
+ )
325
+ )
326
+ return images
327
+
328
+
329
+ def rotates(stokes: tuple[int, ...]) -> bool:
330
+ """Whether the images of an input are rotated into the frame of the mosaic, which needs both Q and U."""
331
+ return STOKES_CODES["Q"] in stokes and STOKES_CODES["U"] in stokes
332
+
333
+
334
+ def recorded_frame(
335
+ infos: list[ImageInfo], stokes: tuple[int, ...]
336
+ ) -> LinearFrame | None:
337
+ """The frame the POLFRAME keywords of the images of one input give, or None if they give none.
338
+
339
+ For an input of Q and U, the frame is read from those two images, which
340
+ must both have the keywords, or neither, and agree. The keywords of its
341
+ other images are not used.
342
+
343
+ Any other input is not rotated, and its frame only orients its holography
344
+ beam. Keywords that cannot be read, or that disagree between its images,
345
+ are then ignored with a warning rather than stopping the mosaic.
346
+
347
+ Args:
348
+ infos (list[ImageInfo]): The images of the input
349
+ stokes (tuple[int, ...]): The Stokes code of each image
350
+
351
+ Raises:
352
+ ValueError: Raised if the keywords of Q and U cannot be read, are on only one of them, or disagree
353
+
354
+ Returns:
355
+ LinearFrame | None: The frame, or None if the keywords give none
356
+ """
357
+ if rotates(stokes):
358
+ linear = [
359
+ info
360
+ for info, code in zip(infos, stokes, strict=True)
361
+ if code in (STOKES_CODES["Q"], STOKES_CODES["U"])
362
+ ]
363
+ frames = [header_frame(info.header, info.path) for info in linear]
364
+ if (frames[0] is None) != (frames[1] is None):
365
+ tagged, untagged = linear if frames[0] is not None else linear[::-1]
366
+ msg = (
367
+ f"{tagged.path} has POLFRAME keywords, but {untagged.path}, the other of "
368
+ "its Q and U, does not. Write them into both, or neither"
369
+ )
370
+ raise ValueError(msg)
371
+ if (
372
+ frames[0] is not None
373
+ and frames[1] is not None
374
+ and not frames[0].matches(frames[1])
375
+ ):
376
+ msg = (
377
+ f"{linear[0].path} and {linear[1].path} are the Q and U of one beam, but "
378
+ f"their POLFRAME keywords disagree: {frames[0].describe()}, and "
379
+ f"{frames[1].describe()}"
380
+ )
381
+ raise ValueError(msg)
382
+ return frames[0]
383
+
384
+ found: list[tuple[ImageInfo, LinearFrame]] = []
385
+ for info in infos:
386
+ try:
387
+ frame = header_frame(info.header, info.path)
388
+ except ValueError as error:
389
+ logger.warning(
390
+ f"{error}. The keywords only orient its holography beam, so they are ignored"
391
+ )
392
+ continue
393
+ if frame is not None:
394
+ found.append((info, frame))
395
+ if any(not frame.matches(found[0][1]) for _, frame in found[1:]):
396
+ logger.warning(
397
+ f"The POLFRAME keywords of the images on the grid of {infos[0].path} disagree. "
398
+ "They only orient its holography beam, so they are ignored"
399
+ )
400
+ return None
401
+ return found[0][1] if found else None
402
+
403
+
404
+ def output_names(
405
+ output_base: str | Path,
406
+ stokes: tuple[int, ...],
407
+ cube: bool = False,
408
+ output_format: str = "fits",
409
+ noise: bool = False,
410
+ ) -> MosaicNames:
411
+ """The files of a mosaic: an image per Stokes parameter, and a weight (and noise) per group that shares a weight.
412
+
413
+ Each is labelled by the Stokes parameters it holds, where they are known:
414
+ ``<base>.i.mosaic.fits`` and ``<base>.qu.weight.fits`` for images, or
415
+ ``<base>.i.cube.fits`` and ``<base>.qu.weight.cube.fits`` for cubes.
416
+
417
+ Args:
418
+ output_base (str | Path): Base name of the files
419
+ stokes (tuple[int, ...]): The FITS Stokes code of each image, or 0 where it is unknown
420
+ cube (bool, optional): Whether the mosaic is a cube. Defaults to False.
421
+ output_format (str, optional): ``fits``, or ``zarr`` stores. Defaults to "fits".
422
+ noise (bool, optional): Whether noise images are written. Defaults to False.
423
+
424
+ Returns:
425
+ MosaicNames: The files of the mosaic
426
+ """
427
+ suffix = "zarr" if output_format == "zarr" else "fits"
428
+ kind = ".cube" if cube else ""
429
+
430
+ def label(codes: list[int]) -> str:
431
+ names = "".join(
432
+ STOKES_NAMES[code].lower() for code in codes if code in STOKES_NAMES
433
+ )
434
+ return f".{names}" if names else ""
435
+
436
+ groups = [
437
+ [stokes[index] for index in members]
438
+ for members in group_members(weight_groups(stokes))
439
+ ]
440
+ return MosaicNames(
441
+ images=tuple(
442
+ Path(f"{output_base}{label([code])}{kind or '.mosaic'}.{suffix}")
443
+ for code in stokes
444
+ ),
445
+ weights=tuple(
446
+ Path(f"{output_base}{label(codes)}.weight{kind}.{suffix}")
447
+ for codes in groups
448
+ ),
449
+ noises=tuple(
450
+ Path(f"{output_base}{label(codes)}.noise{kind}.{suffix}")
451
+ for codes in groups
452
+ )
453
+ if noise
454
+ else (),
455
+ )
456
+
457
+
458
+ def plan_mosaic(
459
+ images: list[InputImages],
460
+ names: MosaicNames,
461
+ options: MosaicOptions,
462
+ run_options: RunOptions,
463
+ beams: tuple[BeamShape, ...] | None = None,
464
+ ) -> MosaicPlan:
465
+ """Build the frame and inputs of a mosaic, and the headers of its outputs.
466
+
467
+ Args:
468
+ images (list[InputImages]): The images of each input
469
+ names (MosaicNames): The files the mosaic is written to
470
+ options (MosaicOptions): The mosaicking options
471
+ run_options (RunOptions): Which channels are mosaicked, and how the mosaic is written
472
+ beams (tuple[BeamShape, ...] | None, optional): The restoring beam of every channel of the inputs, such as the beams they were convolved to. Defaults to None, those of the first input.
473
+
474
+ Returns:
475
+ MosaicPlan: The plan of the mosaic
476
+ """
477
+ reference = images[options.frame.reference_index or 0].info
478
+ channels = slice(*(run_options.channels or (0, reference.n_channels)))
479
+ stokes = images[0].stokes
480
+ frame, prepared = plan_inputs(images, options)
481
+ check_holography_planes(prepared, channels)
482
+
483
+ linear = (STOKES_CODES["Q"], STOKES_CODES["U"])
484
+ # Q or U alone is not rotated, so its frame is whatever the inputs' was
485
+ output_frame = None
486
+ if rotates(stokes):
487
+ output_frame = (
488
+ NORTH
489
+ if options.polarisation.output_frame == "north"
490
+ else LinearFrame(
491
+ (float(frame.wcs.wcs.crval[0]), float(frame.wcs.wcs.crval[1]))
492
+ )
493
+ )
494
+ image_headers = []
495
+ for code in stokes:
496
+ header = output_header(frame, reference, stokes=code or None, channels=channels)
497
+ if output_frame is not None and code in linear:
498
+ write_frame_keywords(header, output_frame)
499
+ image_headers.append(header)
500
+ groups = weight_groups(stokes)
501
+ firsts = [groups.index(group) for group in sorted(set(groups))]
502
+ weight_headers = [weight_header(image_headers[first]) for first in firsts]
503
+ noise_headers = []
504
+ for first, header in zip(firsts[: len(names.noises)], weight_headers, strict=False):
505
+ noise_header = header.copy()
506
+ noise_header["BUNIT"] = image_headers[first].get("BUNIT", "")
507
+ noise_headers.append(noise_header)
508
+
509
+ if run_options.output_format == "zarr":
510
+ parts = tiles(frame, tile_size=run_options.zarr_chunk)
511
+ elif run_options.fits_writer == "workers":
512
+ # Each task writes a run of bytes of its own, not a piece of every row
513
+ parts = strips(frame, tile_size=options.resample.tile_size)
514
+ else:
515
+ parts = tiles(frame, tile_size=options.resample.tile_size)
516
+ return MosaicPlan(
517
+ names=names,
518
+ frame=frame,
519
+ inputs=prepared,
520
+ tiles=parts,
521
+ channels=channels,
522
+ groups=groups,
523
+ headers=(*image_headers, *weight_headers, *noise_headers),
524
+ beams=_output_beams([item.info for item in images], channels, beams),
525
+ )
526
+
527
+
528
+ def check_holography_planes(
529
+ inputs: list[MosaicInput], channels: slice, tolerance_hz: float = 2e6
530
+ ) -> None:
531
+ """Warn of channels whose holography beam is read from a plane more than ``tolerance_hz`` from their frequency, as happens amid flagged planes.
532
+
533
+ The plane is stretched to the channel's frequency, which is only a fair
534
+ model of the beam close to the plane. One warning covers every input, as
535
+ the beams of a cube are often flagged alike.
536
+ """
537
+ distant = []
538
+ for item in inputs:
539
+ model = item.primary_beam
540
+ planes = None if model is None else model.plane_frequencies_hz()
541
+ if model is None or planes is None:
542
+ continue
543
+ offsets = np.zeros(len(planes))
544
+ offsets[channels] = np.abs(planes - np.asarray(model.frequencies_hz))[channels]
545
+ if item.usable_channels:
546
+ offsets[~np.array(item.usable_channels)] = 0.0
547
+ far = offsets > tolerance_hz
548
+ if np.any(far):
549
+ logger.debug(
550
+ f"{np.sum(far)} channels of {item.info.path} are up to "
551
+ f"{np.max(offsets) / 1e6:.1f} MHz from a usable plane of holography beam {model.beam_number}"
552
+ )
553
+ distant.append(
554
+ (float(np.max(offsets)), int(np.sum(far)), len(far), item.info.path)
555
+ )
556
+ if distant:
557
+ offset, n_far, n_channels, path = max(distant)
558
+ logger.warning(
559
+ f"{len(distant)} of {len(inputs)} inputs have channels more than "
560
+ f"{tolerance_hz / 1e6:g} MHz from the nearest usable plane of the holography cube, "
561
+ f"so their beams are stretched from planes further away. The furthest is "
562
+ f"{offset / 1e6:.1f} MHz away, for {n_far} of {n_channels} channels of {path}"
563
+ )
564
+
565
+
566
+ def check_noise(options: WeightOptions, weighted_by_images: bool) -> None:
567
+ """Warn if a noise image is asked for of inputs whose weights cannot be the inverse of their variance."""
568
+ if options.noise_image and (
569
+ options.weight_type == "primary_beam"
570
+ or (not weighted_by_images and options.image_weight == "none")
571
+ ):
572
+ logger.warning(
573
+ "The noise image is only relative, as the inputs are not weighted by the "
574
+ "inverse of their variance. Weight them by their noise or weight images for one in Jy/beam"
575
+ )
576
+
577
+
578
+ def needs_image_weight(options: WeightOptions, weight_paths: list[Path] | None) -> bool:
579
+ """Whether the inputs are weighted by their measured noise."""
580
+ return (
581
+ options.weight_type != "primary_beam"
582
+ and weight_paths is None
583
+ and options.image_weight != "none"
584
+ )
585
+
586
+
587
+ def input_frame_centre(
588
+ images: InputImages, options: PolarisationOptions
589
+ ) -> tuple[float, float] | None:
590
+ """The position the Q and U of an input are referenced to north at, or None if they are referenced to north at each pixel.
591
+
592
+ The frame comes from the POLFRAME keywords of the input's images, or from
593
+ the options: ``frame_centre``, or ``input_frame`` of ``crval`` or
594
+ ``north``. If both give one, they must agree. The keywords record the
595
+ frame an image is in, such as that of a mosaic patchwork made, so rotating
596
+ it from another frame would turn it twice.
597
+
598
+ An input with no frame from either is refused if it holds Q and U.
599
+ Otherwise it is not rotated, and its frame only orients its holography
600
+ beam: options that disagree with its keywords are used with a warning,
601
+ and with neither its frame is north at its own reference position.
602
+
603
+ Args:
604
+ images (InputImages): The images of the input
605
+ options (PolarisationOptions): How polarisation is mosaicked
606
+
607
+ Raises:
608
+ ValueError: Raised if the keywords and options of an input of Q and U disagree, ``frame_centre`` is given with an ``input_frame`` it does not apply to, or an input of Q and U has no frame
609
+
610
+ Returns:
611
+ tuple[float, float] | None: The (RA, Dec) in degrees, or None for north at each pixel
612
+ """
613
+ info = images.info
614
+ crval = (float(info.wcs.wcs.crval[0]), float(info.wcs.wcs.crval[1]))
615
+ if options.frame_centre is not None and options.input_frame != "reference":
616
+ msg = (
617
+ "frame_centre is the position Q and U are referenced to, so it does not go "
618
+ f"with input_frame={options.input_frame!r}"
619
+ )
620
+ raise ValueError(msg)
621
+ given = {
622
+ "north": NORTH,
623
+ "crval": LinearFrame(crval),
624
+ "reference": None
625
+ if options.frame_centre is None
626
+ else LinearFrame(options.frame_centre),
627
+ }[options.input_frame]
628
+ recorded = images.frame
629
+ if recorded is not None and given is not None and not recorded.matches(given):
630
+ if rotates(images.stokes):
631
+ msg = (
632
+ f"The POLFRAME keywords of {info.path} say its Q and U are referenced to "
633
+ f"{recorded.describe()}, but the options say {given.describe()}. The keywords "
634
+ "record the frame the image is in, so rotating it from another would turn it "
635
+ "twice. Leave out the frame options, or correct the keywords"
636
+ )
637
+ raise ValueError(msg)
638
+ logger.warning(
639
+ f"The POLFRAME keywords of {info.path} say {recorded.describe()}, but the "
640
+ f"options say {given.describe()}. It is not rotated, so the options are used "
641
+ "to orient its holography beam"
642
+ )
643
+ recorded = None
644
+ frame = recorded if recorded is not None else given
645
+ if frame is not None:
646
+ return frame.centre
647
+ if rotates(images.stokes):
648
+ msg = (
649
+ f"{info.path} has Q and U, but nothing says what their angles are measured from. "
650
+ "For the beams of an ASKAP observation, give the boresight with --frame-centre RA DEC "
651
+ "(frame_centre); FixMS keeps it as the PHASE_DIR of the FIELD_OLD table of each "
652
+ "measurement set. If Q and U are already referenced to north at each pixel, give "
653
+ "--input-frame north. If each image is referenced to north at its own reference "
654
+ "position, as for a single pointing, give --input-frame crval"
655
+ )
656
+ raise ValueError(msg)
657
+ return crval
658
+
659
+
660
+ def contributing_box(
661
+ frame: Frame,
662
+ info: ImageInfo,
663
+ primary_beam: BeamModel | None,
664
+ cutoff: float,
665
+ margin: int,
666
+ ) -> BoundingBox | None:
667
+ """The region of the frame an input contributes to: its footprint, within where its beam reaches ``cutoff`` in any channel."""
668
+ box = input_bounding_box(frame, info, margin=margin)
669
+ reach = None if primary_beam is None else primary_beam.reach(cutoff)
670
+ if reach is None:
671
+ return box
672
+ world = np.array(ra_dec(offset_vectors(info.beam_centre, *reach)))
673
+ return intersect_boxes(box, world_bounding_box(frame, world, margin=margin))
674
+
675
+
676
+ def prepare_inputs(
677
+ images: list[InputImages], frame: Frame, options: MosaicOptions
678
+ ) -> list[MosaicInput]:
679
+ """Find the primary beam and footprint of each input on the frame.
680
+
681
+ Args:
682
+ images (list[InputImages]): The images of each input
683
+ frame (Frame): The frame of the mosaic
684
+ options (MosaicOptions): The mosaicking options
685
+
686
+ Returns:
687
+ list[MosaicInput]: The prepared inputs
688
+ """
689
+ weight_options, polarisation = options.weight, options.polarisation
690
+ margin = kernel_width(options.resample.kernel) // 2 + 1
691
+ weighted_by_beam = weight_options.weight_type != "weight_image"
692
+ inputs = []
693
+ for item in images:
694
+ info = item.info
695
+ for indices in group_members(weight_groups(item.stokes)):
696
+ if any(
697
+ item.weights[index] != item.weights[indices[0]] for index in indices
698
+ ):
699
+ msg = f"The images of {info.path} that share a weight (Q and U) are given different weights"
700
+ raise ValueError(msg)
701
+ frame_centre = input_frame_centre(item, polarisation)
702
+ frame_rotation = (
703
+ 0.0
704
+ if frame_centre is None
705
+ else float(frame_angle(frame_centre, unit_vectors(*info.beam_centre)))
706
+ )
707
+ leakage = item.stokes_i_path is not None
708
+ primary_beam = (
709
+ beam_model(
710
+ options.primary_beam,
711
+ info,
712
+ leakage=leakage,
713
+ normalise_leakage=not polarisation.keep_centre_leakage,
714
+ frame_rotation_rad=frame_rotation,
715
+ )
716
+ if weighted_by_beam or leakage
717
+ else None
718
+ )
719
+ inputs.append(
720
+ MosaicInput(
721
+ info=info,
722
+ planes=item.planes,
723
+ stokes=item.stokes,
724
+ weights=item.weights,
725
+ primary_beam=primary_beam,
726
+ bounding_box=contributing_box(
727
+ frame,
728
+ info,
729
+ primary_beam if weighted_by_beam else None,
730
+ cutoff=options.primary_beam.pb_cutoff,
731
+ margin=margin,
732
+ ),
733
+ stokes_i_path=item.stokes_i_path,
734
+ frame_centre=frame_centre,
735
+ usable_channels=tuple(
736
+ beam is None or beam.is_usable() for beam in info.channel_beams
737
+ ),
738
+ )
739
+ )
740
+ logger.info(
741
+ f"Prepared {info.path} with weights {[weight.values[:3] for weight in item.weights]}"
742
+ )
743
+ return inputs
744
+
745
+
746
+ def trim_to_inputs(
747
+ frame: Frame, inputs: list[MosaicInput]
748
+ ) -> tuple[Frame, list[MosaicInput]]:
749
+ """Trim a frame to where its inputs contribute, moving their footprints onto the trimmed frame."""
750
+ union = union_of_boxes([item.bounding_box for item in inputs])
751
+ if union is None:
752
+ return frame, inputs
753
+ trimmed = frame.crop(union)
754
+ if trimmed.shape != frame.shape:
755
+ logger.info(
756
+ f"Trimmed the frame from {frame.shape[1]}x{frame.shape[0]} to {trimmed.shape[1]}x{trimmed.shape[0]} pixels"
757
+ )
758
+ return trimmed, [
759
+ item._replace(bounding_box=shift_box(item.bounding_box, union))
760
+ for item in inputs
761
+ ]
762
+
763
+
764
+ def output_header(
765
+ frame: Frame,
766
+ reference: ImageInfo,
767
+ beam: BeamShape | None = None,
768
+ stokes: int | None = None,
769
+ channels: slice | None = None,
770
+ ) -> fits.Header:
771
+ """The header of a mosaic, with keywords and the restoring beam of a reference input, and its Stokes parameter.
772
+
773
+ Args:
774
+ frame (Frame): The frame of the mosaic
775
+ reference (ImageInfo): The input whose keywords and axes are kept
776
+ beam (BeamShape | None, optional): Restoring beam of the mosaic. Defaults to None, the beam of the reference input.
777
+ stokes (int | None, optional): FITS Stokes code of the mosaic. Defaults to None, that of the reference input.
778
+ channels (slice | None, optional): The channels of the reference input that the mosaic holds. Defaults to None, a single plane.
779
+
780
+ Returns:
781
+ fits.Header: The header
782
+ """
783
+ header = frame.header(reference.header, channels=channels)
784
+ for key in ("TELESCOP", "PROJECT", "SBID", "DATE-OBS", "DURATION", "BUNIT"):
785
+ if key in reference.header:
786
+ header[key] = reference.header[key]
787
+
788
+ if stokes is not None:
789
+ for axis in range(3, header["NAXIS"] + 1):
790
+ if str(header.get(f"CTYPE{axis}", "")).upper() == "STOKES":
791
+ header[f"CRVAL{axis}"] = stokes
792
+ header[f"CRPIX{axis}"] = 1
793
+
794
+ beam = beam or reference.beam
795
+ if beam is not None and beam.is_usable():
796
+ beam.to_header(header)
797
+ header["HISTORY"] = f"Mosaicked by patchwork {__version__}"
798
+ return header
799
+
800
+
801
+ def weight_header(image_header: fits.Header) -> fits.Header:
802
+ """The header of a weight image, from that of the first mosaic image of its group."""
803
+ header = image_header.copy()
804
+ header.remove("BUNIT", ignore_missing=True)
805
+ remove_frame_keywords(header)
806
+ return header
807
+
808
+
809
+ def plan_inputs(
810
+ images: list[InputImages], options: MosaicOptions
811
+ ) -> tuple[Frame, list[MosaicInput]]:
812
+ """Build the frame of a mosaic and prepare its inputs on it, trimming it to where they contribute."""
813
+ frame = build_frame([item.info for item in images], options.frame)
814
+ inputs = prepare_inputs(images, frame, options)
815
+ if not options.frame.full_frame and options.frame.image_size is None:
816
+ frame, inputs = trim_to_inputs(frame, inputs)
817
+ logger.info(f"Mosaic frame is {frame.shape[1]}x{frame.shape[0]} pixels")
818
+ return frame, inputs