1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401, F403, F405
=
r"""
A 2-D Gaussian representation of a radio telescope's PSF (beam).
All axes use FITS conventions: FWHM major and minor axes in degrees,
position angle in degrees East of North.
Args:
major_deg: FWHM major axis in degrees (FITS BMAJ).
minor_deg: FWHM minor axis in degrees (FITS BMIN). Must be <= major_deg.
pa_deg: Position angle in degrees East of North (FITS BPA).
Raises:
ValueError: If minor_deg > major_deg or any value is non-finite.
See Also:
Beam.from_arcsec: Construct from arcsecond axes.
Beam.from_fits_header: Construct from an astropy FITS header.
Beam.from_radio_beam: Construct from a ``radio_beam.Beam`` object.
"""
r"""
FWHM major axis in degrees (FITS BMAJ).
"""
r"""
FWHM minor axis in degrees (FITS BMIN).
"""
r"""
Position angle in degrees East of North (FITS BPA).
"""
r"""
FWHM major axis in arcseconds.
"""
r"""
FWHM minor axis in arcseconds.
"""
...
r"""
Construct a Beam from arcsecond axes.
Args:
major_arcsec: FWHM major axis in arcseconds.
minor_arcsec: FWHM minor axis in arcseconds. Must be <= major_arcsec.
pa_deg: Position angle in degrees East of North.
Returns:
Beam: The constructed beam.
Raises:
ValueError: If minor_arcsec > major_arcsec or any value is non-finite.
"""
r"""
Solid angle of the beam in steradians.
Computed as ``(pi / (4 ln 2)) * major_rad * minor_rad``.
Returns:
float: Beam solid angle in steradians.
"""
r"""
Deconvolve ``other`` from ``self`` (i.e. ``self`` = result ⊛ ``other``).
Subtracts the Gaussian covariance matrices and reads off the residual
ellipse (Wild 1970).
Args:
other (Beam): The PSF to deconvolve from this beam.
Returns:
Beam: The deconvolved beam.
Raises:
ValueError: If ``other`` is larger than ``self`` and deconvolution
is impossible.
"""
r"""
Convolve ``self`` with ``other``.
Adds the Gaussian covariance matrices and reads off the resulting
ellipse (Wild 1970).
Args:
other (Beam): The beam to convolve with.
Returns:
Beam: The convolved beam.
"""
...
...
r"""
Find the smallest beam that every beam in ``beams`` can be convolved to.
Uses the 2-beam analytic CASA algorithm when ``len(beams) == 2``, otherwise
the Khachiyan minimum-volume-enclosing-ellipse algorithm — the same as
``radio_beam.Beams.common_beam(method='pts')``.
Args:
beams (list[Beam]): Input beams. Must contain at least one element.
tolerance (float): Convergence tolerance for the Khachiyan algorithm.
Default ``1e-4``.
nsamps (int): Number of points sampled from each beam ellipse boundary.
Default 200.
epsilon (float): Fractional padding added to each beam before the MVE
fit, to ensure the common beam can be marginally deconvolved from
all inputs. Default ``5e-4``.
Returns:
Beam: The smallest common beam.
Raises:
ValueError: If ``beams`` is empty or no valid common beam is found.
"""
r"""
Compute the flux-scaling factor for a Jy/beam convolution.
Returns the factor by which pixel values must be multiplied after
convolving a Jy/beam image from ``orig_beam`` to ``conv_beam``.
Args:
conv_beam (Beam): The convolving beam (the kernel applied on top of
``orig_beam``).
orig_beam (Beam): The original restoring beam of the image.
dx_arcsec (float): Pixel size along the x axis in arcseconds.
dy_arcsec (float): Pixel size along the y axis in arcseconds.
Returns:
tuple: ``(fac, amp, bmaj_out, bmin_out, bpa_out_deg)`` where
``fac`` is the pixel scaling factor, ``amp`` is the Gaussian kernel
integral, and the remaining three are the output beam parameters
(major/minor FWHM in arcseconds, PA in degrees).
"""
r"""
Smooth an image from ``old_beam`` to ``new_beam``.
Convolves ``image`` in the UV plane and applies the flux scaling
appropriate for ``bunit`` so that the output is in the same units as the
input: Jy/beam images get the Gaussian beam-area factor, Kelvin
(brightness temperature) images conserve surface brightness and are left
unscaled.
Args:
image (numpy.ndarray): Input image, shape ``(ny, nx)``,
dtype ``float32``.
old_beam (Beam): Current (input) restoring beam.
new_beam (Beam): Target (output) restoring beam. Must be larger than
``old_beam``.
dx_deg (float): Pixel size along the x (RA) axis in degrees
(FITS CDELT1, may be negative).
dy_deg (float): Pixel size along the y (Dec) axis in degrees
(FITS CDELT2).
cutoff_arcsec (float, optional): If given, raise ``ValueError`` if the
deconvolved kernel FWHM exceeds this value in arcseconds.
bunit (str, optional): FITS ``BUNIT`` brightness unit. If it denotes
Kelvin (e.g. ``"K"``), surface brightness is conserved and no flux
scaling is applied; if it denotes Jy/beam, the Gaussian
flux-scaling factor is applied. An unrecognised string emits a
``UserWarning`` and is treated as Jy/beam. Defaults to Jy/beam.
Returns:
numpy.ndarray: Smoothed image, shape ``(ny, nx)``, dtype ``float32``.
Raises:
ValueError: If ``new_beam`` is smaller than ``old_beam``, all pixels
are NaN, or the kernel exceeds ``cutoff_arcsec``.
Warns:
UserWarning: If ``bunit`` is given but not recognised as either a
Kelvin or Jy/beam unit (Jy/beam is then assumed).
"""