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/tile.py ADDED
@@ -0,0 +1,344 @@
1
+ """Making one tile of a mosaic: resampling, weighting and combining every input that covers it.
2
+
3
+ An input holds one or more images on one grid (I, Q, U or V, each a single
4
+ plane or a cube of channels), which are made together: Stokes Q and U so that
5
+ each input can be rotated into the frame the mosaic references its polarisation
6
+ to, and Stokes I so that its leakage into the others can be removed. Tiles are
7
+ independent, so they can be made in any order or in parallel.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from typing import TYPE_CHECKING, Literal, NamedTuple
13
+
14
+ import numpy as np
15
+
16
+ from patchwork.combine import TileSums, accumulate, empty_sums, finalise
17
+ from patchwork.coordinates import (
18
+ TileCoordinates,
19
+ map_to_input,
20
+ offsets,
21
+ tile_coordinates,
22
+ )
23
+ from patchwork.frame import tile_region
24
+ from patchwork.io import read_block
25
+ from patchwork.polarisation import (
26
+ STOKES_CODES,
27
+ frame_angle,
28
+ remove_leakage,
29
+ rotate_linear,
30
+ )
31
+ from patchwork.resample import (
32
+ Backend,
33
+ Kernel,
34
+ input_region,
35
+ interpolate_stack,
36
+ resolve_backend,
37
+ )
38
+ from patchwork.weights import combined_weights, weight_from_map, weighting
39
+
40
+ if TYPE_CHECKING:
41
+ from pathlib import Path
42
+
43
+ from numpy.typing import NDArray
44
+
45
+ from patchwork.frame import BoundingBox, Frame
46
+ from patchwork.io import ImageInfo, Slices
47
+ from patchwork.options import MosaicOptions, PolarisationOptions, WeightOptions
48
+ from patchwork.primary_beam import BeamModel
49
+
50
+
51
+ class PlaneWeight(NamedTuple):
52
+ """The weight of one image of an input: a value for each channel, or weight images"""
53
+
54
+ values: tuple[float, ...] = (1.0,)
55
+ """The weight of each channel, or one weight for every channel, used when there are no weight images"""
56
+ paths: tuple[Path, ...] = ()
57
+ """Weight images or cubes, combined as ``combined_weights`` does when there are several"""
58
+
59
+
60
+ class MosaicInput(NamedTuple):
61
+ """An input, ready to be added to the tiles it covers"""
62
+
63
+ info: ImageInfo
64
+ """The description of the first image of the input"""
65
+ planes: tuple[Path, ...]
66
+ """The images of the input, which share its grid"""
67
+ stokes: tuple[int, ...]
68
+ """The FITS Stokes code of each image, or 0 where it is unknown"""
69
+ weights: tuple[PlaneWeight, ...]
70
+ """The weight of each image"""
71
+ primary_beam: BeamModel | None
72
+ """Primary beam of the input, if it is weighted by one or has its leakage removed"""
73
+ bounding_box: BoundingBox | None
74
+ """The region of the frame the input contributes to"""
75
+ stokes_i_path: Path | None = None
76
+ """Stokes I image of the input, whose leakage is removed from its other images"""
77
+ frame_centre: tuple[float, float] | None = None
78
+ """The (RA, Dec) its Q and U are referenced to north at, or None if they are referenced to north at every pixel"""
79
+ usable_channels: tuple[bool, ...] = ()
80
+ """Which channels hold an image, by their restoring beam, where empty means every channel"""
81
+
82
+
83
+ class TileResult(NamedTuple):
84
+ """One finished tile of a mosaic, over some channels"""
85
+
86
+ slices: Slices
87
+ """The (y, x) region of the frame the tile covers"""
88
+ channels: slice
89
+ """The channels of the inputs the tile covers"""
90
+ images: tuple[NDArray[np.float32], ...]
91
+ """The (channel, y, x) mosaic of each image of the inputs"""
92
+ weights: tuple[NDArray[np.float32], ...]
93
+ """The (channel, y, x) weight of each group of images that share a weight"""
94
+
95
+
96
+ def weight_groups(stokes: tuple[int, ...]) -> tuple[int, ...]:
97
+ """The group of each image that shares its weight: Q and U share one, and every other image has its own."""
98
+ keys = [
99
+ "qu" if code in (STOKES_CODES["Q"], STOKES_CODES["U"]) else str(code)
100
+ for code in stokes
101
+ ]
102
+ order = list(dict.fromkeys(keys))
103
+ return tuple(order.index(key) for key in keys)
104
+
105
+
106
+ def group_members(groups: tuple[int, ...]) -> list[list[int]]:
107
+ """The indices of the images in each weight group, in the order of the groups."""
108
+ return [
109
+ [index for index, member in enumerate(groups) if member == group]
110
+ for group in sorted(set(groups))
111
+ ]
112
+
113
+
114
+ def _rotation_into_mosaic(
115
+ item: MosaicInput,
116
+ options: PolarisationOptions,
117
+ frame: Frame,
118
+ vectors: NDArray[np.float64],
119
+ ) -> NDArray[np.float64] | float:
120
+ """The angle that turns polarisation from the frame of an input into the frame of the mosaic."""
121
+ rotation: NDArray[np.float64] | float = (
122
+ 0.0 if item.frame_centre is None else frame_angle(item.frame_centre, vectors)
123
+ )
124
+ if options.output_frame == "centre":
125
+ centre = (float(frame.wcs.wcs.crval[0]), float(frame.wcs.wcs.crval[1]))
126
+ rotation = rotation - frame_angle(centre, vectors)
127
+ return rotation
128
+
129
+
130
+ class _Sampler(NamedTuple):
131
+ """Interpolates the channels of images on one input grid at the positions of a region of a tile"""
132
+
133
+ window: Slices
134
+ channels: slice
135
+ x: NDArray[np.float64]
136
+ y: NDArray[np.float64]
137
+ kernel: Kernel
138
+ backend: Backend
139
+
140
+ def image(self, path: Path) -> tuple[NDArray[np.float64], NDArray[np.bool]]:
141
+ """The interpolated channels of an image, and which are valid."""
142
+ # float32 halves the memory of the block, and interpolation sums in float64 either way
143
+ block = read_block(path, self.window, self.channels, dtype=np.float32)
144
+ return interpolate_stack(block, self.x, self.y, self.kernel, self.backend)
145
+
146
+ def weight(
147
+ self, path: Path, map_type: Literal["weight", "variance", "rms"]
148
+ ) -> tuple[NDArray[np.float64], NDArray[np.bool]]:
149
+ """The interpolated channels of a weight image, as weights, and which are valid."""
150
+ block = weight_from_map(read_block(path, self.window, self.channels), map_type)
151
+ return interpolate_stack(block, self.x, self.y, self.kernel, self.backend)
152
+
153
+
154
+ def mosaic_tile(
155
+ tile: Slices,
156
+ frame: Frame,
157
+ inputs: list[MosaicInput],
158
+ options: MosaicOptions,
159
+ channels: slice | None = None,
160
+ ) -> TileResult:
161
+ """Resample, weight and combine every input that covers one tile of the frame, over some channels.
162
+
163
+ Each input is only worked on over the part of the tile it contributes to.
164
+ Positions in it are found once and used for each of its images and channels.
165
+
166
+ Args:
167
+ tile (Slices): The (y, x) region of the frame to make
168
+ frame (Frame): The frame of the mosaic
169
+ inputs (list[MosaicInput]): The inputs of the mosaic
170
+ options (MosaicOptions): The mosaicking options
171
+ channels (slice | None, optional): The channels of the inputs to make. Defaults to None, the first channel.
172
+
173
+ Returns:
174
+ TileResult: The finished tile
175
+ """
176
+ if resolve_backend(options.resample.backend) == "fused":
177
+ from patchwork.fused import mosaic_tile_fused # noqa: PLC0415
178
+
179
+ return mosaic_tile_fused(tile, frame, inputs, options, channels)
180
+ combine_type = options.combine.combine_type
181
+ channels = channels or slice(0, 1)
182
+ channel_range = range(channels.start or 0, channels.stop)
183
+
184
+ coordinates = tile_coordinates(
185
+ frame.wcs, tile, step=options.resample.coordinate_step
186
+ )
187
+ shape = (len(channel_range), *coordinates.vectors.shape[1:])
188
+ stokes = inputs[0].stokes if inputs else (0,)
189
+ members = group_members(weight_groups(stokes))
190
+ sums = [empty_sums(shape, len(indices), combine_type) for indices in members]
191
+ for item in inputs:
192
+ _add_input(item, tile, frame, coordinates, sums, members, options, channels)
193
+
194
+ images: list[NDArray[np.float32]] = [np.empty(0, dtype=np.float32)] * len(stokes)
195
+ group_weights = []
196
+ for group_sums, indices in zip(sums, members, strict=True):
197
+ group_images, group_weight = finalise(group_sums, combine_type)
198
+ for index, image in zip(indices, group_images, strict=True):
199
+ images[index] = image
200
+ group_weights.append(group_weight)
201
+ return TileResult(
202
+ slices=tile,
203
+ channels=slice(channel_range.start, channel_range.stop),
204
+ images=tuple(images),
205
+ weights=tuple(group_weights),
206
+ )
207
+
208
+
209
+ def _add_input(
210
+ item: MosaicInput,
211
+ tile: Slices,
212
+ frame: Frame,
213
+ coordinates: TileCoordinates,
214
+ sums: list[TileSums],
215
+ members: list[list[int]],
216
+ options: MosaicOptions,
217
+ channels: slice,
218
+ ) -> None:
219
+ """Resample, weight and add one input to the sums of a tile, over the part of the tile it contributes to.
220
+
221
+ Its arrays are let go on return, so a tile only ever holds those of one input.
222
+ """
223
+ weight_options, kernel = options.weight, options.resample.kernel
224
+ backend = resolve_backend(options.resample.backend)
225
+ weighted_by_beam = weight_options.weight_type != "weight_image"
226
+ combine_type = options.combine.combine_type
227
+ channel_range = range(channels.start or 0, channels.stop)
228
+
229
+ region = tile_region(tile, item.bounding_box)
230
+ if region is None:
231
+ return
232
+ usable = np.array(
233
+ [
234
+ item.usable_channels[index] if item.usable_channels else True
235
+ for index in channel_range
236
+ ]
237
+ )
238
+ if not np.any(usable):
239
+ return
240
+ x, y = map_to_input(coordinates, item.info.wcs, region)
241
+ window = input_region(item.info.shape, x, y, kernel)
242
+ if window is None:
243
+ return
244
+ x, y = x - window[1].start, y - window[0].start
245
+
246
+ sampler = _Sampler(window, channels, x, y, kernel, backend)
247
+ interpolated = [sampler.image(path) for path in item.planes]
248
+ planes = [values for values, _ in interpolated]
249
+ valid = [is_valid & usable[:, None, None] for _, is_valid in interpolated]
250
+
251
+ vectors = coordinates.vectors[:, region[0], region[1]]
252
+ east, north = offsets(item.info.beam_centre, vectors)
253
+ primary_beam = None
254
+ cutoff: NDArray[np.float64] | float = options.primary_beam.pb_cutoff
255
+ if item.primary_beam is not None and weighted_by_beam:
256
+ primary_beam = item.primary_beam.responses(channel_range, east, north)
257
+ cutoff = cutoff * item.primary_beam.cutoff_scales(channel_range).reshape(
258
+ -1, 1, 1
259
+ )
260
+
261
+ if item.stokes_i_path is not None and item.primary_beam is not None:
262
+ if item.stokes_i_path in item.planes:
263
+ position = item.planes.index(item.stokes_i_path)
264
+ stokes_i, stokes_i_valid = planes[position], valid[position]
265
+ else:
266
+ stokes_i, stokes_i_valid = sampler.image(item.stokes_i_path)
267
+ leaky = [
268
+ index for index, code in enumerate(item.stokes) if code != STOKES_CODES["I"]
269
+ ]
270
+ corrected = remove_leakage(
271
+ tuple(planes[index] for index in leaky),
272
+ tuple(item.stokes[index] for index in leaky),
273
+ stokes_i,
274
+ np.moveaxis(
275
+ item.primary_beam.leakage_responses(
276
+ channel_range,
277
+ east,
278
+ north,
279
+ include_v=STOKES_CODES["V"] in item.stokes,
280
+ ),
281
+ 1,
282
+ 0,
283
+ ),
284
+ )
285
+ for index, plane in zip(leaky, corrected, strict=True):
286
+ planes[index] = plane
287
+ valid[index] = valid[index] & stokes_i_valid
288
+
289
+ if STOKES_CODES["Q"] in item.stokes and STOKES_CODES["U"] in item.stokes:
290
+ q_index, u_index = (
291
+ item.stokes.index(STOKES_CODES["Q"]),
292
+ item.stokes.index(STOKES_CODES["U"]),
293
+ )
294
+ planes[q_index], planes[u_index] = rotate_linear(
295
+ planes[q_index],
296
+ planes[u_index],
297
+ _rotation_into_mosaic(item, options.polarisation, frame, vectors),
298
+ )
299
+ valid[q_index] = valid[u_index] = valid[q_index] & valid[u_index]
300
+
301
+ # The images of a group share a weight, so it is found once for them all
302
+ for group_sums, indices in zip(sums, members, strict=True):
303
+ weight, contributes = _group_weight(
304
+ item.weights[indices[0]], sampler, channels, weight_options
305
+ )
306
+ for index in indices:
307
+ contributes = contributes & valid[index]
308
+ if primary_beam is not None:
309
+ contributes &= primary_beam >= cutoff
310
+ factor, weight = weighting(
311
+ primary_beam=primary_beam,
312
+ weight=weight,
313
+ weight_type=weight_options.weight_type,
314
+ weight_state=weight_options.weight_state,
315
+ )
316
+ accumulate(
317
+ group_sums.region((slice(None), *region)),
318
+ [planes[index] for index in indices],
319
+ factor,
320
+ np.where(contributes, weight, 0.0),
321
+ combine_type,
322
+ )
323
+
324
+
325
+ def _group_weight(
326
+ plane_weight: PlaneWeight,
327
+ sampler: _Sampler,
328
+ channels: slice,
329
+ options: WeightOptions,
330
+ ) -> tuple[NDArray[np.float64], NDArray[np.bool] | bool]:
331
+ """The weight of a group of an input's images over a region of a tile, and where it is valid."""
332
+ if not plane_weight.paths:
333
+ values = np.asarray(plane_weight.values, dtype=np.float64)
334
+ values = values if len(values) == 1 else values[channels]
335
+ return values.reshape(-1, 1, 1), True
336
+ maps = [
337
+ sampler.weight(path, options.weight_map_type) for path in plane_weight.paths
338
+ ]
339
+ weight = (
340
+ maps[0][0]
341
+ if len(maps) == 1
342
+ else combined_weights([values for values, _ in maps])
343
+ )
344
+ return weight, np.logical_and.reduce([is_valid for _, is_valid in maps])
patchwork/weights.py ADDED
@@ -0,0 +1,175 @@
1
+ """Weights of the inputs, and how they are applied to the images"""
2
+
3
+ from __future__ import annotations
4
+
5
+ from concurrent.futures import ThreadPoolExecutor
6
+ from pathlib import Path
7
+ from typing import TYPE_CHECKING, Literal
8
+
9
+ import numpy as np
10
+ from astropy.stats import mad_std
11
+
12
+ from patchwork.io import read_block, read_image_info, read_plane
13
+
14
+ if TYPE_CHECKING:
15
+ from numpy.typing import NDArray
16
+
17
+
18
+ def image_noise_weight(
19
+ data: NDArray[np.floating],
20
+ mode: Literal["mad", "std"] = "mad",
21
+ stride: int = 8,
22
+ ) -> float:
23
+ """The inverse variance of an image from the finite pixels of every ``stride``'th row, or 0 if it has none."""
24
+ values = np.ravel(data[::stride])
25
+ values = values[np.isfinite(values)]
26
+ if values.size == 0:
27
+ return 0.0
28
+
29
+ rms = float(mad_std(values) if mode == "mad" else np.std(values))
30
+ return 1.0 / rms**2 if np.isfinite(rms) and rms > 0 else 0.0
31
+
32
+
33
+ def measure_image_weight(
34
+ path: str | Path,
35
+ mode: Literal["mad", "std", "none"] = "mad",
36
+ stride: int = 8,
37
+ ) -> float:
38
+ """The inverse variance weight of an image file from every ``stride``'th row, or 1 when ``mode`` is ``none``."""
39
+ if mode == "none":
40
+ return 1.0
41
+ rows = read_plane(path, (slice(None, None, stride), slice(None)))
42
+ return image_noise_weight(data=rows, mode=mode, stride=1)
43
+
44
+
45
+ def combined_weight(weights: list[float]) -> float:
46
+ """The weight of images that are combined with one weight, such as Q and U: the inverse of their mean variance."""
47
+ if any(weight <= 0 for weight in weights):
48
+ return 0.0
49
+ return len(weights) / sum(1 / weight for weight in weights)
50
+
51
+
52
+ def combined_weights(weights: list[NDArray[np.floating]]) -> NDArray[np.float64]:
53
+ """Combine weights element by element as ``combined_weight`` does, giving 0 wherever any is not positive."""
54
+ stacked = np.asarray(weights, dtype=np.float64)
55
+ usable = np.all(stacked > 0, axis=0)
56
+ with np.errstate(divide="ignore"):
57
+ variance = np.sum(1 / np.where(stacked > 0, stacked, 1.0), axis=0)
58
+ return np.where(usable, len(weights) / variance, 0.0)
59
+
60
+
61
+ def measure_channel_weights(
62
+ path: str | Path,
63
+ mode: Literal["mad", "std", "none"] = "mad",
64
+ stride: int = 8,
65
+ channel_chunk: int = 16,
66
+ channels: slice | None = None,
67
+ threads: int = 1,
68
+ ) -> tuple[float, ...]:
69
+ """The inverse variance weight of each channel of a cube, from every ``stride``'th row, or 1 when ``mode`` is ``none``.
70
+
71
+ Only the channels in ``channels`` are measured (by default every channel),
72
+ and every other channel is given no weight. The channels are read and
73
+ measured ``channel_chunk`` at a time, in ``threads`` threads; with more
74
+ than one, the chunks are made small enough to keep every thread busy.
75
+ """
76
+ n_channels = read_image_info(path).n_channels
77
+ if mode == "none":
78
+ return (1.0,) * n_channels
79
+ start, stop, _ = (channels or slice(None)).indices(n_channels)
80
+ weights = [0.0] * n_channels
81
+ if threads > 1:
82
+ channel_chunk = max(1, min(channel_chunk, -(-(stop - start) // threads)))
83
+ chunks = [
84
+ slice(first, min(first + channel_chunk, stop))
85
+ for first in range(start, stop, channel_chunk)
86
+ ]
87
+
88
+ def measure(chunk: slice) -> list[float]:
89
+ block = read_block(
90
+ path, region=(slice(None, None, stride), slice(None)), channels=chunk
91
+ )
92
+ return [image_noise_weight(plane, mode=mode, stride=1) for plane in block]
93
+
94
+ if threads > 1 and len(chunks) > 1:
95
+ with ThreadPoolExecutor(min(threads, len(chunks))) as pool:
96
+ measured = list(pool.map(measure, chunks))
97
+ else:
98
+ measured = [measure(chunk) for chunk in chunks]
99
+ for chunk, values in zip(chunks, measured, strict=True):
100
+ weights[chunk] = values
101
+ return tuple(weights)
102
+
103
+
104
+ def read_weights_log(path: str | Path) -> tuple[float, ...]:
105
+ """The weight of each channel from a linmos weights log, a ``#Channel Weight`` header then a line per channel.
106
+
107
+ Raises:
108
+ ValueError: Raised if the log has no channels, or skips any
109
+ """
110
+ rows = [
111
+ line.split()
112
+ for line in Path(path).read_text().splitlines()
113
+ if line.strip() and not line.lstrip().startswith("#")
114
+ ]
115
+ channels = {int(row[0]): float(row[1]) for row in rows}
116
+ if not channels or sorted(channels) != list(range(len(channels))):
117
+ msg = f"{path} should hold a weight for each channel from 0, but holds channels {sorted(channels)}"
118
+ raise ValueError(msg)
119
+ return tuple(channels[channel] for channel in range(len(channels)))
120
+
121
+
122
+ def weight_from_map(
123
+ values: NDArray[np.floating],
124
+ map_type: Literal["weight", "variance", "rms"] = "weight",
125
+ ) -> NDArray[np.float64]:
126
+ """Convert a weight, variance or rms map to weights, which are 0 wherever the map is unusable."""
127
+ with np.errstate(divide="ignore", invalid="ignore"):
128
+ if map_type == "weight":
129
+ weights = np.asarray(values, dtype=np.float64)
130
+ elif map_type == "variance":
131
+ weights = 1.0 / np.asarray(values, dtype=np.float64)
132
+ else:
133
+ weights = 1.0 / np.asarray(values, dtype=np.float64) ** 2
134
+ return np.where(np.isfinite(weights) & (weights > 0), weights, 0.0)
135
+
136
+
137
+ def weighting(
138
+ primary_beam: NDArray[np.floating] | None,
139
+ weight: float | NDArray[np.floating],
140
+ weight_type: Literal["primary_beam", "weight_image", "combined"] = "combined",
141
+ weight_state: Literal["corrected", "inherent", "weighted"] = "inherent",
142
+ ) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
143
+ """The factor that weights an input's images, and the weight the input adds to the mosaic.
144
+
145
+ An input adds ``image * factor`` to the sum of weighted images and ``weight``
146
+ to the sum of weights, and the mosaic is their ratio. With an ``inherent``
147
+ image (one still carrying its primary beam ``pb``) and ``combined`` weights
148
+ ``w`` this is ``sum(w pb I) / sum(w pb^2)``. Images that share a weight share
149
+ both, so they are found once for all of them.
150
+
151
+ Args:
152
+ primary_beam (NDArray[np.floating] | None): Primary beam response at each pixel, or None for a flat response
153
+ weight (float | NDArray[np.floating]): Weight of the input, or of each of its pixels
154
+ weight_type (Literal["primary_beam", "weight_image", "combined"], optional): Where the weights come from. Defaults to "combined".
155
+ weight_state (Literal["corrected", "inherent", "weighted"], optional): Whether the images are corrected for the primary beam, still carry it, or are already weighted. Defaults to "inherent".
156
+
157
+ Returns:
158
+ tuple[NDArray[np.float64], NDArray[np.float64]]: The factor and the weight, which broadcast against the images
159
+ """
160
+ weights = np.asarray(weight, dtype=np.float64)
161
+ if weight_type == "weight_image":
162
+ if weight_state == "corrected":
163
+ return weights, weights
164
+ if weight_state == "inherent":
165
+ return np.sqrt(np.clip(weights, 0, None)), weights
166
+ return np.ones_like(weights), weights
167
+
168
+ scale = weights if weight_type == "combined" else np.ones_like(weights)
169
+ if primary_beam is None:
170
+ return scale, scale
171
+ pb = np.asarray(primary_beam, dtype=np.float64)
172
+ factor = scale if weight_state == "weighted" else scale * pb
173
+ if weight_state == "corrected":
174
+ factor = factor * pb
175
+ return factor, scale * pb**2