# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401, F403, F405
import builtins
import numpy
import numpy.typing
import typing
__all__ = [
"Beam",
"common_beam",
"gauss_factor",
"smooth",
]
[docs]
class Beam:
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.
"""
@property
[docs]
def major_deg(self) -> builtins.float:
r"""
FWHM major axis in degrees (FITS BMAJ).
"""
@property
[docs]
def minor_deg(self) -> builtins.float:
r"""
FWHM minor axis in degrees (FITS BMIN).
"""
@property
[docs]
def pa_deg(self) -> builtins.float:
r"""
Position angle in degrees East of North (FITS BPA).
"""
@property
[docs]
def major_arcsec(self) -> builtins.float:
r"""
FWHM major axis in arcseconds.
"""
@property
[docs]
def minor_arcsec(self) -> builtins.float:
r"""
FWHM minor axis in arcseconds.
"""
def __new__(cls, major_deg: builtins.float, minor_deg: builtins.float, pa_deg: builtins.float) -> Beam: ...
@classmethod
[docs]
def from_arcsec(cls, major_arcsec: builtins.float, minor_arcsec: builtins.float, pa_deg: builtins.float) -> Beam:
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.
"""
[docs]
def area_sr(self) -> builtins.float:
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.
"""
[docs]
def deconvolve(self, other: Beam) -> Beam:
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.
"""
[docs]
def convolve(self, other: Beam) -> Beam:
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.
"""
[docs]
def __repr__(self) -> builtins.str: ...
[docs]
def __str__(self) -> builtins.str: ...
[docs]
def common_beam(beams: typing.Sequence[Beam], tolerance: builtins.float = 0.0001, nsamps: builtins.int = 200, epsilon: builtins.float = 0.0005) -> 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.
"""
[docs]
def gauss_factor(conv_beam: Beam, orig_beam: Beam, dx_arcsec: builtins.float, dy_arcsec: builtins.float) -> tuple[builtins.float, builtins.float, builtins.float, builtins.float, builtins.float]:
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).
"""
[docs]
def smooth(image: numpy.typing.NDArray[numpy.float32], old_beam: Beam, new_beam: Beam, dx_deg: builtins.float, dy_deg: builtins.float, cutoff_arcsec: typing.Optional[builtins.float] = None, bunit: typing.Optional[builtins.str] = None) -> numpy.typing.NDArray[numpy.float32]:
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).
"""