Utilities API¶

This page documents the shared utility helpers used throughout the package.

identical_units ¶

identical_units(u1, u2)

Check whether two units are exactly identical.

Parameters:

Name	Type	Description	Default
`u1`	str or `~astropy.units.UnitBase`	First unit specification.	required
`u2`	str or `~astropy.units.UnitBase`	Second unit specification.	required

Returns:

Type	Description
`bool`	`True` when the two inputs represent the same unit exactly, not merely equivalent units.

calc_pixel_area ¶

calc_pixel_area(header)

Calculate the projected area of one image pixel.

Parameters:

Name	Type	Description	Default
`header`	`~astropy.io.fits.Header`	FITS header describing a celestial image.	required

Returns:

Type	Description
`~astropy.units.Quantity`	Pixel area returned by the WCS projection.

calc_pixel_per_beam ¶

calc_pixel_per_beam(header, suppress_no_beam_error=True)

Calculate the number of pixels per synthesized beam.

Parameters:

Name	Type	Description	Default
`header`	`~astropy.io.fits.Header`	FITS header describing a radio image.	required
`suppress_no_beam_error`	`bool`	If `True`, return `None` when the header does not contain beam information. If `False`, re-raise the missing-beam exception.	`True`

Returns:

Type	Description
`float or None`	Number of pixels per beam, or `None` when no beam is present and `suppress_no_beam_error` is `True`.

Raises:

Type	Description
`NoBeamException`	Raised when beam information is missing and `suppress_no_beam_error` is `False`.

nanaverage ¶

nanaverage(a, **kwargs)

Compute a weighted average while ignoring NaN values.

Parameters:

Name	Type	Description	Default
`a`	`array_like`	Array containing data to be averaged.	required
`**kwargs`	`Any`	Additional keyword arguments passed to `~numpy.ma.average`.	`{}`

Returns:

Type	Description
`ndarray or scalar`	Weighted average along the requested axis.

nanrms ¶

nanrms(a, **kwargs)

Compute a weighted root-mean-square while ignoring NaN values.

Parameters:

Name	Type	Description	Default
`a`	`array_like`	Array containing data to be summarized.	required
`**kwargs`	`Any`	Additional keyword arguments passed to `~numpy.ma.average`.	`{}`

Returns:

Type	Description
`ndarray or scalar`	Root-mean-square along the requested axis.

reduce_image_input ¶

reduce_image_input(image, ihdu=0, header=None, suppress_error=False)

Normalize image inputs to data, header, and WCS objects.

Parameters:

Name	Type	Description	Default
`image`	str, bytes, path-like, `~astropy.io.fits.HDUList`, FITS HDU,	or ndarray Image source to normalize.	required
`ihdu`	`int`	HDU index to use when `image` is a FITS filename or HDU list.	`0`
`header`	`~astropy.io.fits.Header`	FITS header describing the array when `image` is an ndarray.	`None`
`suppress_error`	`bool`	If `True`, return `(None, None, None)` instead of raising when `image` looks like a file path but does not exist.	`False`

Returns:

Name	Type	Description
`data`	`ndarray or None`	Image data array.
`hdr`	`~astropy.io.fits.Header` or None	Header associated with the image data.
`wcs`	`~astropy.wcs.WCS` or None	Celestial WCS built from `hdr`.

Raises:

Type	Description
`ValueError`	Raised when the input image cannot be found, is not two-dimensional, has inconsistent dimensions, or does not use celestial RA/Dec axes.

deproject ¶

deproject(center_coord=None, incl=0 * u.deg, pa=0 * u.deg, header=None, wcs=None, naxis=None, ra=None, dec=None, return_offset=False)

Calculate deprojected coordinates from sky coordinates.

This function deals with sky images of astronomical objects with an intrinsic disk geometry. Given disk center coordinates, inclination, and position angle, it calculates the deprojected coordinates in the disk plane (radius and azimuthal angle) from (1) a FITS header (header), or (2) a WCS object with specified axis sizes (wcs + naxis), or (3) RA and DEC coodinates (ra + dec). Note that the deprojected azimuthal angle is defined w.r.t. the line of nodes (given by the position angle). For (1) and (2), the outputs are 2D images; for (3), the outputs are arrays with shapes matching the broadcasted shape of ra and dec.

Parameters:

Name	Type	Description	Default
`center_coord`	`~astropy.coordinates.SkyCoord` or 2-tuple	Sky coordinates of the disk center.	`None`
`incl`	number or `~astropy.units.Quantity`	Disk inclination angle. Zero degrees corresponds to a face-on disk.	`0 * deg`
`pa`	number or `~astropy.units.Quantity`	Disk position angle for the receding major axis, measured from north through east.	`0 * deg`
`header`	`~astropy.io.fits.Header`	FITS header specifying the WCS and output map shape.	`None`
`wcs`	`~astropy.wcs.WCS`	WCS of the output maps when `header` is not supplied.	`None`
`naxis`	`sequence of int`	Two-element map shape associated with `wcs`.	`None`
`ra`	array_like or `~astropy.units.Quantity`	Right ascension values to deproject when working from explicit coordinates instead of a WCS description.	`None`
`dec`	array_like or `~astropy.units.Quantity`	Declination values to deproject when working from explicit coordinates instead of a WCS description.	`None`
`return_offset`	`bool`	If `True`, also return intermediate offset coordinates in both sky and disk frames.	`False`

Returns:

Name	Type	Description
`deprojected_coordinates`	`tuple of ndarray`	Returns `(radius_deg, projang_deg)` by default. When `return_offset` is `True`, the returned tuple becomes `(radius_deg, projang_deg, dx_deg, dy_deg, dmaj_deg, dmin_deg)`.

Notes

This is the Python version of an IDL function deproject included in the cpropstoo package. See URL below: https://github.com/akleroy/cpropstoo/blob/master/cubes/deproject.pro