convolve_rs¶

Submodules¶

convolve_rs._convolve_rs

Classes¶

Beam

A 2-D Gaussian representation of a radio telescope's PSF (beam).

Functions¶

`common_beam`(→ Beam)	Find the smallest beam that every beam in `beams` can be convolved to.
`gauss_factor`(→ tuple[float, float, float, float, float])	Compute the flux-scaling factor for a Jy/beam convolution.
`smooth`(→ numpy.typing.NDArray[numpy.float32])	Smooth an image from `old_beam` to `new_beam`.

Package Contents¶

class convolve_rs.Beam[source]¶

Bases: _convolve_rs.Beam

A 2-D Gaussian representation of a radio telescope’s PSF (beam).

Extends the base Beam with convenience constructors for the astropy and radio_beam ecosystems. All core functionality (convolve, deconvolve, area_sr, etc.) is inherited from the Rust implementation.

All axes use FITS conventions: FWHM major and minor axes in degrees, position angle in degrees East of North.

Parameters:

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).

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.
common_beam: Find the smallest common beam for a set of beams.

classmethod from_fits_header(header: astropy.io.fits.Header) → Beam[source]¶

Construct from an astropy FITS header.

Reads BMAJ and BMIN (in degrees) and BPA (in degrees, defaults to 0 if absent) from the header.

Parameters:: header – An astropy.io.fits.Header (or any mapping with BMAJ and BMIN keys and an optional BPA key).
Return type:: Beam

Examples

>>> from astropy.io import fits
>>> header = fits.Header({"BMAJ": 0.005, "BMIN": 0.004, "BPA": 30.0})
>>> beam = Beam.from_fits_header(header)
>>> beam.major_deg
0.005

classmethod from_radio_beam(rb: Any) → Beam[source]¶

Construct from a radio_beam.Beam object.

Duck-typed: any object with major, minor, and pa attributes that are astropy Quantity angle values works. radio_beam is not a hard dependency.

Parameters:: rb – A radio_beam.Beam (or compatible object).
Return type:: Beam

Examples

>>> import astropy.units as u
>>> import radio_beam
>>> rb = radio_beam.Beam(10 * u.arcsec, 8 * u.arcsec, 30 * u.deg)
>>> beam = Beam.from_radio_beam(rb)
>>> round(beam.major_arcsec, 6)
10.0

convolve_rs.common_beam(beams: Sequence[Beam], tolerance: float = 0.0001, nsamps: int = 200, epsilon: float = 0.0005) → Beam[source]¶

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').

Parameters:

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:

The smallest common beam.

Return type:

Beam

Raises:

ValueError – If beams is empty or no valid common beam is found.

convolve_rs.gauss_factor(conv_beam: Beam, orig_beam: Beam, dx_arcsec: float, dy_arcsec: float) → tuple[float, float, float, float, float][source]¶

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.

Parameters:

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:

(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).

Return type:

tuple

convolve_rs.smooth(image: numpy.typing.NDArray[numpy.float32], old_beam: Beam, new_beam: Beam, dx_deg: float, dy_deg: float, cutoff_arcsec: float | None = None, bunit: str | None = None) → numpy.typing.NDArray[numpy.float32][source]¶

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.

Parameters:

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:

Smoothed image, shape (ny, nx), dtype float32.

Return type:

numpy.ndarray

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).