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.
- askap_patchwork-0.1.0.dist-info/METADATA +179 -0
- askap_patchwork-0.1.0.dist-info/RECORD +33 -0
- askap_patchwork-0.1.0.dist-info/WHEEL +4 -0
- askap_patchwork-0.1.0.dist-info/entry_points.txt +4 -0
- askap_patchwork-0.1.0.dist-info/licenses/LICENSE +28 -0
- patchwork/__init__.py +11 -0
- patchwork/__main__.py +8 -0
- patchwork/_version.py +24 -0
- patchwork/_version.pyi +2 -0
- patchwork/cli.py +60 -0
- patchwork/combine.py +146 -0
- patchwork/convolve.py +534 -0
- patchwork/coordinates.py +222 -0
- patchwork/frame.py +439 -0
- patchwork/fused.py +618 -0
- patchwork/fused_kernels.py +695 -0
- patchwork/io.py +668 -0
- patchwork/logging.py +62 -0
- patchwork/mosaic.py +546 -0
- patchwork/numba_kernels.py +203 -0
- patchwork/options.py +211 -0
- patchwork/pipeline/__init__.py +3 -0
- patchwork/pipeline/cluster.py +73 -0
- patchwork/pipeline/flow.py +143 -0
- patchwork/plan.py +818 -0
- patchwork/polarisation.py +178 -0
- patchwork/primary_beam.py +636 -0
- patchwork/py.typed +0 -0
- patchwork/resample.py +267 -0
- patchwork/rotate.py +319 -0
- patchwork/tile.py +344 -0
- patchwork/weights.py +175 -0
- patchwork/write.py +502 -0
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
|