API¶

class gofish.imagecube(path, FOV=None, velocity_range=None, verbose=True, primary_beam=None, bunit=None, pixel_scale=None)¶

Base class containing all the FITS data. Must be a 3D cube containing two spatial and one velocity axis for and spectral shifting. A 2D ‘cube’ can be used to make the most of the deprojection routines. These can easily be made from CASA using the exportfits() command.

Parameters:

path (str) – Relative path to the FITS cube.
FOV (Optional[float]) – Clip the image cube down to a specific field-of-view spanning a range FOV, where FOV is in [arcsec].
velocity_range (Optional[tuple]) – A tuple of minimum and maximum velocities to clip the velocity range to.
verbose (Optional[bool]) – Whether to print out warning messages.
primary_beam (Optional[str]) – Path to the primary beam as a FITS file to apply the correction.
bunit (Optional[str]) – If no bunit header keyword is found, use this value, e.g., ‘Jy/beam’.
pixel_scale (Optional[float]) – If no axis information is found in the header, use this value for the pixel scaling in [arcsec], assuming an image centered on 0.0”.

average_spectrum(r_min, r_max, inc, PA, mstar, dist, dr=None, PA_min=None, PA_max=None, exclude_PA=False, abs_PA=False, x0=0.0, y0=0.0, z0=None, psi=None, r_cavity=None, r_taper=None, q_taper=None, z_func=None, resample=1, beam_spacing=False, mask_frame='disk', unit='Jy/beam', mask=None, skip_empty_annuli=True, shadowed=False, empirical_uncertainty=False, include_spectral_decorrelation=True, velocity_resolution=1.0, vrad_func=None)¶

Return the averaged spectrum over a given radial range, returning a spectrum in units of [Jy/beam] or [K] using the Rayleigh-Jeans approximation. As the Keplerian rotation of the disk needs to be accounted for, a stellar mass in [Msun] and distance in [pc] must be provided.

The resample parameter allows you to resample the spectrum at a different velocity spacing (by providing a float argument) or averaging of an integer number of channels (by providing an integer argument). For example, resample=3, will return a velocity axis which has been supersampled such that a channel is three times as narrow as the intrinsic width. Instead, resample=50.0 will result in a velocity axis with a channel spacing of 50 m/s.

The third variable returned is the standard error on the mean of each velocity bin, i.e. the standard deviation of that velocity bin divided by the square root of the number of samples.

Parameters:

r_min (float) – Inner radius in [arcsec] of the region to average.
r_max (float) – Outer radius in [arcsec] of the region to average.
inc (float) – Inclination of the disk in [degrees].
PA (float) – Position angle of the disk in [degrees], measured east-of-north towards the redshifted major axis.
mstar (float) – Stellar mass in [Msun].
dist (float) – Distance to the source in [pc].
dr (Optional[float]) – Width of the annuli to split the integrated region into in [arcsec]. Default is quater of the beam major axis.
PA_min (Optional[float]) – Minimum polar angle of the segment of the annulus in [degrees]. Note this is the polar angle, not the position angle.
PA_max (Optional[float]) – Maximum polar angle of the segment of the annulus in [degrees]. Note this is the polar angle, not the position angle.
exclude_PA (Optional[bool]) – If True, exclude the provided polar angle range rather than include it.
abs_PA (Optional[bool]) – If True, take the absolute value of the polar angle such that it runs from 0 [deg] to 180 [deg].
x0 (Optional[float]) – Source center offset along the x-axis in [arcsec].
y0 (Optional[float]) – Source center offset along the y-axis in [arcsec].
z0 (Optional[float]) – Emission height in [arcsec] at a radius of 1”.
psi (Optional[float]) – Flaring angle of the emission surface.
z_func (Optional[function]) – A function which provides $z(r)$ . Note that no checking will occur to make sure this is a valid function.
resample (Optional[float/int]) – Resampling parameter for the deprojected spectrum. An integer specifies an average of that many channels, while a float specifies the desired channel width. Default is resample=1.
beam_spacing (Optional[bool]) – When extracting the annuli, whether to choose spatially independent pixels or not.
PA_min – Minimum polar angle to include in the annulus in [degrees]. Note that the polar angle is measured in the disk-frame, unlike the position angle which is measured in the sky-plane.
PA_max – Maximum polar angleto include in the annulus in [degrees]. Note that the polar angle is measured in the disk-frame, unlike the position angle which is measured in the sky-plane.
exclude_PA – Whether to exclude pixels where PA_min <= PA_pix <= PA_max.
mask_frame (Optional[str]) – Which frame the radial and azimuthal mask is specified in, either 'disk' or 'sky'.
unit (Optional[str]) – Units for the spectrum, either 'Jy/beam' or 'K'. Note that the conversion to Kelvin assumes the Rayleigh-Jeans approximation which is typically invalid at sub-mm wavelengths.
mask (Optional[ndarray]) – Either a 2D or 3D mask to use when averaging the spectra. This will be used in addition to any geometrically defined mask.
assume_correlated (Optional[bool]) – Whether to treat the spectra which are stacked as correlated, by default this is True. If False, the uncertainty will be estimated using Poisson statistics, otherwise the uncertainty is just the standard deviation of each velocity bin.
skip_empty_annuli (Optional[bool]) – If True, skip any annuli which are empty (i.e. their masks have zero pixels in). If False, any empty masks will raise a ValueError.
empirical_uncertainty (Optional[bool]) – If True, use an empirical measure of the uncertainty based on an iterative sigma clipping described in imagecube.estimate_uncertainty.
include_spectral_decorrlation (Optional[bool]) – If True, take account of the spectral decorrelation when estimating uncertainties on the average spectrum and return a spectral correlation length too. Defaults to True.
velocity_resolution (Optional[float]) – Velocity resolution of the data as a fraction of the channel spacing. Defaults to 1.0.
vrad_func (Optional[callable]) – Define any radial velocity component here. Must return a radial velocity in [m/s] for a given radial position in [arcsec].

Returns:

The velocity axis of the spectrum, velax, in [m/s], the averaged spectrum, spectrum, and the variance of the velocity bin, scatter. The latter two are in units of either [Jy/beam] or [K] depending on the unit.

static estimate_uncertainty(a, nsigma=3.0, niter=20)¶

Estimate the noise by iteratively sigma-clipping. For each iteraction the a array is masked above abs(a) > nsigma * std and the standard deviation, std calculated. This is repeated until either convergence or for niter iteractions. In some cases, usually with low nsigma values, the std will approach zero and all a values are masked, resulting in an NaN. In this case, the function will return the last finite value.

Parameters:	a (array) – Array of data from which to estimate the uncertainty. nsigma (Optional[float]) – Factor of the standard devitation above which to mask `a` values. niter (Optional[int]) – Number of iterations to halt after if convergence is not reached.
Returns:	Standard deviation of the sigma-clipped data.
Return type:	std (float)

integrated_spectrum(r_min, r_max, inc, PA, mstar=None, dist=None, dr=None, x0=0.0, y0=0.0, z0=None, psi=None, r_cavity=None, r_taper=None, q_taper=None, z_func=None, resample=1, beam_spacing=False, PA_min=None, PA_max=None, exclude_PA=False, abs_PA=False, mask=None, mask_frame='disk', empirical_uncertainty=False, skip_empty_annuli=True, shadowed=False, velocity_resolution=1.0, vrad_func=None, include_spectral_decorrelation=True)¶

Return the integrated spectrum over a given radial range, returning a spectrum in units of [Jy]. If a stellar mass and distance are specified then this will split the data into concentric annuli, correcting each annulus for the Keplerian rotation of the disk to generate a more precise measurement. If no stellar mass or distance are given then a simple spatial integration will be used.

The resample parameter allows you to resample the spectrum at a different velocity spacing (by providing a float argument) or averaging of an integer number of channels (by providing an integer argument). For example, resample=3, will return a velocity axis which has been supersampled such that a channel is three times as narrow as the intrinsic width. Instead, resample=50.0 will result in a velocity axis with a channel spacing of 50 m/s.

Note

The third variable returned is the scatter in each velocity bin and not the uncertainty on the bin mean as the data is not strictly independent due to spectral and spatial correlations in the data. If you want to assume uncorrelated data to get a better estimate of the uncertainty, set assumed_correlated=False.

Parameters:

r_min (float) – Inner radius in [arcsec] of the region to integrate.
r_max (float) – Outer radius in [arcsec] of the region to integrate.
inc (float) – Inclination of the disk in [degrees].
PA (float) – Position angle of the disk in [degrees], measured east-of-north towards the redshifted major axis.
mstar (Optional[float]) – Stellar mass in [Msun].
dist (Optional[float]) – Distance to the source in [pc].
dr (Optional[float]) – Width of the annuli to split the integrated region into in [arcsec]. Default is quater of the beam major axis.
x0 (Optional[float]) – Source center offset along the x-axis in [arcsec].
y0 (Optional[float]) – Source center offset along the y-axis in [arcsec].
z0 (Optional[float]) – Emission height in [arcsec] at a radius of 1”.
psi (Optional[float]) – Flaring angle of the emission surface.
z_func (Optional[function]) – A function which provides $z(r)$ . Note that no checking will occur to make sure this is a valid function.
resample (Optional[float/int]) – Resampling parameter for the deprojected spectrum. An integer specifies an average of that many channels, while a float specifies the desired channel width. Default is resample=1.
beam_spacing (Optional[bool]) – When extracting the annuli, whether to choose spatially independent pixels or not.
PA_min (Optional[float]) – Minimum polar angle to include in the annulus in [degrees]. Note that the polar angle is measured in the disk-frame, unlike the position angle which is measured in the sky-plane.
PA_max (Optional[float]) – Maximum polar angleto include in the annulus in [degrees]. Note that the polar angle is measured in the disk-frame, unlike the position angle which is measured in the sky-plane.
exclude_PA (Optional[bool]) – Whether to exclude pixels where PA_min <= PA_pix <= PA_max.
abs_PA (Optional[bool]) – If True, take the absolute value of the polar angle such that it runs from 0 [deg] to 180 [deg].
mask (Optional[ndarray]) – Either a 2D or 3D mask to use when averaging the spectra. This will be used in addition to any geometrically defined mask.
mask_frame (Optional[str]) – Which frame the radial and azimuthal mask is specified in, either 'disk' or 'sky'.
assume_correlated (Optional[bool]) – Whether to treat the spectra which are stacked as correlated, by default this is True. If False, the uncertainty will be estimated using Poisson statistics, otherwise the uncertainty is just the standard deviation of each velocity bin.
skip_empty_annuli (Optional[bool]) – If True, skip any annuli which are empty (i.e. their masks have zero pixels in). If False, any empty masks will raise a ValueError.
vrad_func (Optional[callable]) – Define any radial velocity component here. Must return a radial velocity in [m/s] for a given radial position in [arcsec].

Returns:

The velocity axis of the spectrum, velax, in [m/s], the integrated spectrum, spectrum, and the variance of the velocity bin, scatter. The latter two are in units of [Jy].

radial_spectra(rvals=None, rbins=None, dr=None, x0=0.0, y0=0.0, inc=0.0, PA=0.0, z0=None, psi=None, r_cavity=None, r_taper=None, q_taper=None, z_func=None, mstar=1.0, dist=100.0, resample=1, beam_spacing=False, r_min=None, r_max=None, PA_min=None, PA_max=None, exclude_PA=None, abs_PA=False, mask_frame='disk', mask=None, unit='Jy/beam', shadowed=False, skip_empty_annuli=True, empirical_uncertainty=False, vrad_func=None)¶

Return shifted and stacked spectra, over a given spatial region in the disk. The averaged spectra can be rescaled by using the unit argument for which the possible units are:

'mJy/beam'

'Jy/beam'

'mK'

'K'

'mJy'

'Jy'

where 'mJy' or 'Jy' will integrate the emission over the defined spatial range assuming that the averaged spectrum is the same for all pixels in that region.

In addition to a spatial region specified by the usual geometrical mask properties (r_min, r_max, PA_min, PA_max), a user-defined can be included, either as a 2D array (such that it is constant as a function of velocity), or as a 3D array, for example a CLEAN mask, for velocity-specific masks.

There are two ways to return the uncertainties for the spectra. The default are the straight statistical uncertainties which are propagated through from the annulus class. Sometimes these can appear to give a poor description of the true variance of the data. In this case the user can use empirical_uncertainty=True which will use an iterative sigma-clipping approach to estimate the uncertainty by the variance in line-free regions of the spectrum.

Note

Calculation of the empirircal uncertainty is experimental. Use the results with caution and if anything looks suspicious, please contact me.

Parameters:

rvals (Optional[floats]) – Array of bin centres for the profile in [arcsec]. You need only specify one of rvals and rbins.
rbins (Optional[floats]) – Array of bin edges for the profile in [arcsec]. You need only specify one of rvals and rbins.
dr (Optional[float]) – Width of the radial bins in [arcsec] to use if neither rvals nor rbins is set. Default is 1/4 of the beam major axis.
x0 (Optional[float]) – Source center offset along the x-axis in [arcsec].
y0 (Optional[float]) – Source center offset along the y-axis in [arcsec].
inc (Optional[float]) – Inclination of the disk in [degrees].
PA (Optional[float]) – Position angle of the disk in [degrees], measured east-of-north towards the redshifted major axis.
z0 (Optional[float]) – Emission height in [arcsec] at a radius of 1”.
psi (Optional[float]) – Flaring angle of the emission surface.
z_func (Optional[function]) – A function which provides $z(r)$ . Note that no checking will occur to make sure this is a valid function.
mstar (Optional[float]) – Stellar mass in [Msun].
dist (Optional[float]) – Distance to the source in [pc].
resample (Optional[float/int]) – Resampling parameter for the deprojected spectrum. An integer specifies an average of that many channels, while a float specifies the desired channel width. Default is resample=1.
beam_spacing (Optional[bool]) – When extracting the annuli, whether to choose spatially independent pixels or not. Default it not.
r_min (Optional[float]) – Inner radius in [arcsec] of the region to integrate. The value used will be greater than or equal to r_min.
r_max (Optional[float]) – Outer radius in [arcsec] of the region to integrate. The value used will be less than or equal to r_max.
PA_min (Optional[float]) – Minimum polar angle to include in the annulus in [degrees]. Note that the polar angle is measured in the disk-frame, unlike the position angle which is measured in the sky-plane.
PA_max (Optional[float]) – Maximum polar angleto include in the annulus in [degrees]. Note that the polar angle is measured in the disk-frame, unlike the position angle which is measured in the sky-plane.
exclude_PA (Optional[bool]) – Whether to exclude pixels where PA_min <= PA_pix <= PA_max. Default is False.
abs_PA (Optional[bool]) – If True, take the absolute value of the polar angle such that it runs from 0 [deg] to 180 [deg].
mask_frame (Optional[str]) – Which frame the radial and azimuthal mask is specified in, either 'disk' or 'sky'.
mask (Optional[arr]) – A 2D or 3D mask to include in addition to the geometrical mask. If 3D, must match the shape of the data array, while a 2D mask will be interpretted as a velocity independent mask and must match data[0].shape.
unit (Optional[str]) – Desired unit of the output spectra.
shadowed (Optional[bool]) – If True, use a slower but more accurate deprojection algorithm which will handle shadowed pixels due to sub-structure.
skip_empty_annuli (Optional[bool]) – If True, skip any annuli which are found to have no finite spectra in them, returning NaN for that annlus. Otherwise raise a ValueError.
empirical_uncertainty (Optional[bool]) – Whether to calculate the uncertainty on the spectra empirically (True) or using the statistical uncertainties.

Returns:

Four arrays. An array of the bin centers, rvals, an array of the velocity axis, velax, and the averaged spectra, spectra and their associated uncertainties, scatter. The latter two will have shapes of (rvals.size, velax.size) and wil be in units given by the unit argument.

radial_profile(rvals=None, rbins=None, dr=None, unit='Jy/beam m/s', x0=0.0, y0=0.0, inc=0.0, PA=0.0, z0=0.0, psi=1.0, r_cavity=0.0, r_taper=<sphinx.ext.autodoc.importer._MockObject object>, q_taper=1.0, z_func=None, mstar=0.0, dist=100.0, resample=1, beam_spacing=False, r_min=None, r_max=None, PA_min=None, PA_max=None, exclude_PA=False, abs_PA=False, mask_frame='disk', mask=None, velo_range=None, assume_correlated=True, shadowed=False)¶

Generate a radial profile from shifted and stacked spectra. There are different ways to collapse the spectrum into a single value using the unit argument. Possible units for the flux (density) are:

'mJy/beam'

'Jy/beam'

'mK'

'K'

'mJy'

'Jy'

where '/beam' is equivalent to '/pix' if not beam information is found in the FITS header. For the velocity we have:

'm/s'

'km/s'

''

with the empty string resulting in the peak value of the spectrum. For example, unit='K' will return the peak brightness temperature as a function of radius, while unit='K km/s' will return the velocity integrated brightness temperature as a function of radius.

All conversions from [Jy/beam] to [K] are performed using the Rayleigh-Jeans approximation. For other units, or to develop more sophisticated statistics for the collapsed line profiles, use the radial_spectra function which will return the shifted and stacked line profiles.

Parameters:

rvals (Optional[floats]) – Array of bin centres for the profile in [arcsec]. You need only specify one of rvals and rbins.
rbins (Optional[floats]) – Array of bin edges for the profile in [arcsec]. You need only specify one of rvals and rbins.
dr (Optional[float]) – Width of the radial bins in [arcsec] to use if neither rvals nor rbins is set. Default is 1/4 of the beam major axis.
unit (Optional[str]) – Unit for the y-axis of the profile, as in the function description.
x0 (Optional[float]) – Source center offset along the x-axis in [arcsec].
y0 (Optional[float]) – Source center offset along the y-axis in [arcsec].
inc (Optional[float]) – Inclination of the disk in [degrees].
PA (Optional[float]) – Position angle of the disk in [degrees], measured east-of-north towards the redshifted major axis.
z0 (Optional[float]) – Emission height in [arcsec] at a radius of 1”.
psi (Optional[float]) – Flaring angle of the emission surface.
z_func (Optional[function]) – A function which provides $z(r)$ . Note that no checking will occur to make sure this is a valid function.
mstar (Optional[float]) – Stellar mass in [Msun].
dist (Optional[float]) – Distance to the source in [pc].
resample (Optional[float/int]) – Resampling parameter for the deprojected spectrum. An integer specifies an average of that many channels, while a float specifies the desired channel width. Default is resample=1.
beam_spacing (Optional[bool]) – When extracting the annuli, whether to choose spatially independent pixels or not.
r_min (Optional[float]) – Inner radius in [arcsec] of the region to integrate. The value used will be greater than or equal to r_min.
r_max (Optional[float]) – Outer radius in [arcsec] of the region to integrate. The value used will be less than or equal to r_max.
PA_min (Optional[float]) – Minimum polar angle to include in the annulus in [degrees]. Note that the polar angle is measured in the disk-frame, unlike the position angle which is measured in the sky-plane.
PA_max (Optional[float]) – Maximum polar angleto include in the annulus in [degrees]. Note that the polar angle is measured in the disk-frame, unlike the position angle which is measured in the sky-plane.
exclude_PA (Optional[bool]) – Whether to exclude pixels where PA_min <= PA_pix <= PA_max.
abs_PA (Optional[bool]) – If True, take the absolute value of the polar angle such that it runs from 0 [deg] to 180 [deg].
mask_frame (Optional[str]) – Which frame the radial and azimuthal mask is specified in, either 'disk' or 'sky'.
mask (Optional[array]) – A user-specified 2D or 3D array to mask the data with prior to shifting and stacking.
velo_range (Optional[tuple]) – A tuple containing the spectral range to integrate if required for the provided unit. Can either be a string, including units, or as channel integers.
shadowed (Optional[bool]) – If True, use a slower algorithm for deprojecting the pixel coordinates into disk-center coordiantes which can handle shadowed pixels.

Returns:

Arrays of the bin centers in [arcsec], the profile value in the requested units and the associated uncertainties.

shifted_cube(inc, PA, x0=0.0, y0=0.0, z0=None, psi=None, r_cavity=None, r_taper=None, q_taper=None, z_func=None, mstar=None, dist=None, vmod=None, r_min=None, r_max=None, fill_val=<sphinx.ext.autodoc.importer._MockObject object>, save=False, shadowed=False)¶

Apply the velocity shift to each pixel and return the cube, or save as as new FITS file. This would be useful if you want to create moment maps of the data where you want to integrate over a specific velocity range without having to worry about the Keplerian rotation in the disk.

Parameters:

inc (float) – Inclination of the disk in [degrees].
PA (float) – Position angle of the disk in [degrees], measured east-of-north towards the redshifted major axis.
x0 (Optional[float]) – Source center offset along the x-axis in [arcsec].
y0 (Optional[float]) – Source center offset along the y-axis in [arcsec].
z0 (Optional[float]) – Emission height in [arcsec] at a radius of 1”.
psi (Optional[float]) – Flaring angle of the emission surface.
z_func (Optional[callable]) – A function which returns the emission height in [arcsec] for a radius given in [arcsec].
mstar (Optional[float]) – Stellar mass in [Msun].
dist (Optional[float]) – Distance to the source in [pc].
v0 (Optional[callable]) – A function which returns the projected line of sight velocity in [m/s] for a radius given in [m/s].
r_min (Optional[float]) – The inner radius in [arcsec] to shift.
r_max (Optional[float]) – The outer radius in [arcsec] to shift.

Returns:

The shifted data cube.

keplerian(inc, PA, mstar, dist, x0=0.0, y0=0.0, vlsr=0.0, z0=None, psi=None, r_cavity=None, r_taper=None, q_taper=None, z_func=None, r_min=None, r_max=None, cylindrical=False, shadowed=False)¶

Projected Keplerian velocity profile in [m/s]. For positions outside r_min and r_max the values will be set to NaN.

Parameters:

inc (float) – Inclination of the disk in [degrees].
PA (float) – Position angle of the disk in [degrees], measured east-of-north towards the redshifted major axis.
mstar (float) – Stellar mass in [Msun].
dist (float) – Distance to the source in [pc].
x0 (Optional[float]) – Source center offset along the x-axis in [arcsec].
y0 (Optional[float]) – Source center offset along the y-axis in [arcsec].
vlsr (Optional[float]) – Systemic velocity in [m/s].
z0 (Optional[float]) – Emission height in [arcsec] at a radius of 1”.
psi (Optional[float]) – Flaring angle of the emission surface.
r_cavity (Optional[float]) – Edge of the inner cavity for the emission surface in [arcsec].
r_taper (Optional[float]) – Characteristic radius in [arcsec] of the exponential taper to the emission surface.
q_taper (Optional[float]) – Exponent of the exponential taper of the emission surface.
z_func (Optional[callable]) – A function which returns the emission height in [arcsec] for a radius given in [arcsec].
r_min (Optional[float]) – The inner radius in [arcsec] to model.
r_max (Optional[float]) – The outer radius in [arcsec] to model.
cylindrical (Optional[bool]) – If True, force cylindrical rotation, i.e. ignore the height in calculating the velocity.
shadowed (Optional[bool]) – If True, use a slower algorithm for deprojecting the pixel coordinates into disk-center coordiantes which can handle shadowed pixels.

find_center(dx=None, dy=None, Nx=None, Ny=None, mask=None, v_min=None, v_max=None, spectrum='avg', SNR='peak', normalize=True, **kwargs)¶

Find the source center (assuming the disk is azimuthally symmetric) by calculating the SNR of the averaged spectrum by varying the source center, (x0, y0).

Parameters:

dx (Optional[float]) – Maximum offset to consider in the x direction in [arcsec]. Default is one beam FWHM.
dy (Optional[float]) – Maximum offset to consider in the y direction in [arcsec]. Default is one beam FWHM.
Nx (Optional[int]) – Number of samples to take along the x direction. Default results in roughtly pixel spacing.
Ny (Optional[int]) – Number of samples to take along the y direction. Default results in roughtly pixel spacing.
mask (Optional[array]) – Boolean mask of channels to use when calculating the integrated flux or RMS noise.
v_min (Optional[float]) – Minimum velocity in [m/s] to consider if an explicit mask is not provided.
v_max (Optional[float]) – Maximum velocity in [m/s] to consider if an explicit mask is not provided.
spectrum (Optional[str]) – Type of spectrum to consider, either the integrated spectrum with 'int', or the average spectrum with 'avg'.
SNR (Optional[str]) – Type of signal-to-noise definition to use. Either 'int' to use the integrated flux density as the signal, or 'peak' to use the maximum value.
normalize (Optional[bool]) – Whether to normalize the SNR map relative to the SNR at (x0, y0) = (0, 0).

Returns:

The axes of the grid search, x0s and y0s, as well as the 2D array of SNR values, SNR.

get_vlos(rvals=None, rbins=None, r_min=None, r_max=None, PA_min=None, PA_max=None, exclude_PA=False, abs_PA=False, x0=0.0, y0=0.0, inc=0.0, PA=0.0, z0=None, psi=None, r_cavity=None, r_taper=None, q_taper=None, z_func=None, mstar=None, dist=None, mask=None, mask_frame='disk', beam_spacing=True, fit_vrad=True, annulus_kwargs=None, get_vlos_kwargs=None, shadowed=False)¶

Infer the rotational and radial velocity profiles from the data following the approach described in `Teague et al. (2018)`_. The cube will be split into annuli, with the get_vlos() function from annulus being used to infer the rotational (and radial) velocities.

Parameters:

rvals (Optional[floats]) – Array of bin centres for the profile in [arcsec]. You need only specify one of rvals and rbins.
rbins (Optional[floats]) – Array of bin edges for the profile in [arcsec]. You need only specify one of rvals and rbins.
r_min (float) – Minimum midplane radius of the annuli in [arcsec].
r_max (float) – Maximum midplane radius of the annuli in [arcsec].
PA_min (Optional[float]) – Minimum polar angle of the segment of the annulus in [degrees]. Note this is the polar angle, not the position angle.
PA_max (Optional[float]) – Maximum polar angle of the segment of the annulus in [degrees]. Note this is the polar angle, not the position angle.
exclude_PA (Optional[bool]) – If True, exclude the provided polar angle range rather than include.
abs_PA (Optional[bool]) – If True, take the absolute value of the polar angle such that it runs from 0 [deg] to 180 [deg].
x0 (Optional[float]) – Source right ascension offset [arcsec].
y0 (Optional[float]) – Source declination offset [arcsec].
inc (Optional[float]) – Source inclination [deg].
PA (Optional[float]) – Source position angle [deg]. Measured between north and the red-shifted semi-major axis in an easterly direction.
z0 (Optional[float]) – Aspect ratio at 1” for the emission surface. To get the far side of the disk, make this number negative.
psi (Optional[float]) – Flaring angle for the emission surface.
z_func (Optional[function]) – A function which provides z(r). Note that no checking will occur to make sure this is a valid function.
mstar (Optional[float]) – Stellar mass of the central star in [Msun] to calculate the starting positions for the MCMC. If specified, must also provide dist.
dist (Optional[float]) – Source distance in [pc] to use to calculate the starting positions for the MCMC. If specified, must also provide mstar.
mask (Optional[ndarray]) – A 2D array mask which matches the shape of the data.
mask_frame (Optional[str]) – Coordinate frame for the mask. Either 'disk' or 'sky'. If disk coordinates are used then the inclination and position angle of the mask are set to zero.
beam_spacing (Optional[bool/float]) – If True, randomly sample the annulus such that each pixel is at least a beam FWHM apart. A number can also be used in place of a boolean which will describe the number of beam FWHMs to separate each sample by.
fit_vrad (Optional[bool]) – Whether to include radial velocities in the optimization.
annulus_kwargs (Optional[dict]) – Kwargs to pass to get_annulus.
get_vlos_kwargs (Optional[dict]) – Kwargs to pass to annulus.get_vlos.

Returns:

The radial sampling of the annuli, rpnts, and a list of the values returned from annulus.get_vlos.

get_annulus(r_min, r_max, PA_min=None, PA_max=None, exclude_PA=False, abs_PA=False, x0=0.0, y0=0.0, inc=0.0, PA=0.0, z0=None, psi=None, r_cavity=None, r_taper=None, q_taper=None, z_func=None, mask=None, mask_frame='disk', beam_spacing=True, annulus_kwargs=None, shadowed=False)¶

Return an annulus (or section of), of spectra and their polar angles. Can select spatially independent pixels within the annulus, however as this is random, each draw will be different.

Parameters:

r_min (float) – Minimum midplane radius of the annulus in [arcsec].
r_max (float) – Maximum midplane radius of the annulus in [arcsec].
PA_min (Optional[float]) – Minimum polar angle of the segment of the annulus in [degrees]. Note this is the polar angle, not the position angle.
PA_max (Optional[float]) – Maximum polar angle of the segment of the annulus in [degrees]. Note this is the polar angle, not the position angle.
exclude_PA (Optional[bool]) – If True, exclude the provided polar angle range rather than include.
abs_PA (Optional[bool]) – If True, take the absolute value of the polar angle such that it runs from 0 [deg] to 180 [deg].
x0 (Optional[float]) – Source right ascension offset [arcsec].
y0 (Optional[float]) – Source declination offset [arcsec].
inc (Optional[float]) – Source inclination [deg].
PA (Optional[float]) – Source position angle [deg]. Measured between north and the red-shifted semi-major axis in an easterly direction.
z0 (Optional[float]) – Aspect ratio at 1” for the emission surface. To get the far side of the disk, make this number negative.
psi (Optional[float]) – Flaring angle for the emission surface.
z_func (Optional[function]) – A function which provides z(r). Note that no checking will occur to make sure this is a valid function.
mask (Optional[ndarray]) – A 2D array mask which matches the shape of the data.
mask_frame (Optional[str]) – Coordinate frame for the mask. Either 'disk' or 'sky'. If disk coordinates are used then the inclination and position angle of the mask are set to zero.
beam_spacing (Optional[bool/float]) – If True, randomly sample the annulus such that each pixel is at least a beam FWHM apart. A number can also be used in place of a boolean which will describe the number of beam FWHMs to separate each sample by.

Returns:

If annulus=True, will return an eddy.annulus instance, otherwise will be an array containing the polar angles of each spectrum in [degrees] and the array of spectra, ordered in increasing polar angle.

get_mask(r_min=None, r_max=None, exclude_r=False, PA_min=None, PA_max=None, exclude_PA=False, abs_PA=False, mask_frame='disk', x0=0.0, y0=0.0, inc=0.0, PA=0.0, z0=None, psi=None, r_cavity=None, r_taper=None, q_taper=None, z_func=None, shadowed=False)¶

Returns a 2D mask for pixels in the given region. The mask can be specified in either disk-centric coordinates, mask_frame='disk', or on the sky, mask_frame='sky'. If sky-frame coordinates are requested, the geometrical parameters (inc, PA, z0, etc.) are ignored, however the source offsets, x0, y0, are still considered.

Parameters:

r_min (Optional[float]) – Minimum midplane radius of the annulus in [arcsec]. Defaults to minimum deprojected radius.
r_max (Optional[float]) – Maximum midplane radius of the annulus in [arcsec]. Defaults to the maximum deprojected radius.
exclude_r (Optional[bool]) – If True, exclude the provided radial range rather than include.
PA_min (Optional[float]) – Minimum polar angle of the segment of the annulus in [degrees]. Note this is the polar angle, not the position angle.
PA_max (Optional[float]) – Maximum polar angle of the segment of the annulus in [degrees]. Note this is the polar angle, not the position angle.
exclude_PA (Optional[bool]) – If True, exclude the provided polar angle range rather than include it.
abs_PA (Optional[bool]) – If True, take the absolute value of the polar angle such that it runs from 0 [deg] to 180 [deg].
x0 (Optional[float]) – Source center offset along the x-axis in [arcsec].
y0 (Optional[float]) – Source center offset along the y-axis in [arcsec].
inc (Optional[float]) – Inclination of the disk in [degrees].
PA (Optional[float]) – Position angle of the disk in [degrees], measured east-of-north towards the redshifted major axis.
z0 (Optional[float]) – Emission height in [arcsec] at a radius of 1”.
psi (Optional[float]) – Flaring angle of the emission surface.
z_func (Optional[function]) – A function which provides $z(r)$ . Note that no checking will occur to make sure this is a valid function.

Returns:

A 2D array mask matching the shape of a channel.

radial_sampling(rbins=None, rvals=None, dr=None)¶

Return bins and bin center values. If the desired bin edges are known, will return the bin edges and vice versa. If neither are known will return default binning with the desired spacing.

Parameters:	rbins (Optional[list]) – List of bin edges. rvals (Optional[list]) – List of bin centers. dr (Optional[float]) – Spacing of bin centers in [arcsec]. Defaults to a quarter of the beam major axis.
Returns:	List of bin edges. rpnts (list): List of bin centres.
Return type:	rbins (list)

background_residual(x0=0.0, y0=0.0, inc=0.0, PA=0.0, z0=None, psi=None, r_cavity=None, r_taper=None, q_taper=None, z_func=None, r_min=None, r_max=None, PA_min=None, PA_max=None, exclude_PA=False, abs_PA=False, mask_frame='disk', interp1d_kw=None, background_only=False, shadowed=False)¶

Return the residual from an azimuthally avearged background. This is most appropriate for exploring azimuthally asymmetric emission in either the zeroth moment (integrated intensity) or the peak brightness temperature maps. As such, this function only works for 2D data.

The coordinates provided will be used to both build the azimuthally averaged profile (using the radial_profile function) and then project this onto the sky-plane. Any masking parameters used here will only be used when creating the azimuthally spectrum, but the residual with cover the entire data.

Parameters:

x0 (Optional[float]) – Source right ascension offset [arcsec].
y0 (Optional[float]) – Source declination offset [arcsec].
inc (Optional[float]) – Source inclination [deg].
PA (Optional[float]) – Source position angle [deg]. Measured between north and the red-shifted semi-major axis in an easterly direction.
z0 (Optional[float]) – Aspect ratio at 1” for the emission surface. To get the far side of the disk, make this number negative.
psi (Optional[float]) – Flaring angle for the emission surface.
z_func (Optional[function]) – A function which provides z(r). Note that no checking will occur to make sure this is a valid function.
r_min (Optional[float]) – Inner radius in [arcsec] of the region to integrate. The value used will be greater than or equal to r_min.
r_max (Optional[float]) – Outer radius in [arcsec] of the region to integrate. The value used will be less than or equal to r_max.
PA_min (Optional[float]) – Minimum polar angle to include in the annulus in [degrees]. Note that the polar angle is measured in the disk-frame, unlike the position angle which is measured in the sky-plane.
PA_max (Optional[float]) – Maximum polar angleto include in the annulus in [degrees]. Note that the polar angle is measured in the disk-frame, unlike the position angle which is measured in the sky-plane.
exclude_PA (Optional[bool]) – Whether to exclude pixels where PA_min <= PA_pix <= PA_max.
abs_PA (Optional[bool]) – If True, take the absolute value of the polar angle such that it runs from 0 [deg] to 180 [deg].
mask_frame (Optional[str]) – Which frame the radial and azimuthal mask is specified in, either 'disk' or 'sky'.
interp1d_kw (Optional[dict]) – Kwargs to pass to scipy.interpolate.interp1d.
background_only (Optional[bool]) – If True, return only the azimuthally averaged background rather than the residual. Default is False.

Returns:

Residual between the data and the azimuthally: averaged background. If background_only = True then this is just the azimuthally averaged background.

Return type:

residual (array)

disk_coords(x0=0.0, y0=0.0, inc=0.0, PA=0.0, z0=None, psi=None, r_cavity=None, r_taper=None, q_taper=None, z_func=None, force_positive_surface=False, force_negative_surface=False, frame='cylindrical', shadowed=False, extend=2.0, oversample=2.0, griddata_kw=None)¶

Get the disk coordinates given certain geometrical parameters and an emission surface. The emission surface is most simply described as a power law profile,

$z(r) = z_0 \times \left(\frac{r}{1^{\prime\prime}}\right)^{\psi}$

where z0 and psi can be provided by the user. With the increase in spatial resolution afforded by interferometers such as ALMA there are a couple of modifications that can be used to provide a better match to the data.

An inner cavity can be included with the r_cavity argument which makes the transformation:

$\tilde{r} = {\rm max}(0, r - r_{\rm cavity})$

Note that the inclusion of a cavity will mean that other parameters, such as z0, would need to change as the radial axis has effectively been shifted.

To account for the drop in emission surface in the outer disk where the gas surface density decreases there are two descriptions. The preferred way is to include an exponential taper to the power law profile,

$z_{\rm tapered}(r) = z(r) \times \exp\left( -\left[ \frac{r}{r_{\rm taper}} \right]^{q_{\rm taper}} \right)$

where both r_taper and q_taper values must be set.

It is also possible to override this parameterization and directly provide a user-defined z_func. This allow for highly complex surfaces to be included. If this is provided, the other height parameters are ignored.

In some cases, the projection of the emission surface can lead to regions of the disk being ‘shadowed’ by itself along the line of sight to the observer. The default method for calculating the disk coordinates does not take this into account in preference to speed. If you work with some emission surface that suffers from this, you can use the shadowed=True argument which will use a more precise method to calculate the disk coordinates. This can be much slower for large cubes as it requires rotating large grids.

Parameters:

x0 (Optional[float]) – Source right ascension offset [arcsec].
y0 (Optional[float]) – Source declination offset [arcsec].
inc (Optional[float]) – Source inclination [deg].
PA (Optional[float]) – Source position angle [deg]. Measured between north and the red-shifted semi-major axis in an easterly direction.
z0 (Optional[float]) – Aspect ratio at 1” for the emission surface. To get the far side of the disk, make this number negative.
psi (Optional[float]) – Flaring angle for the emission surface.
r_cavity (Optional[float]) – Edge of the inner cavity for the emission surface in [arcsec].
r_taper (Optional[float]) – Characteristic radius in [arcsec] of the exponential taper to the emission surface.
q_taper (Optional[float]) – Exponent of the exponential taper of the emission surface.
z_func (Optional[function]) – A function which provides $z(r)$ . Note that no checking will occur to make sure this is a valid function.
force_positive_surface (Optional[bool]) – Force the emission surface to be positive, default is False.
force_negative_surface (Optioanl[bool]) – Force the emission surface to be negative, default is False.
frame (Optional[str]) – Frame of reference for the returned coordinates. Either 'polar' or 'cartesian'.
shadowed (Optional[bool]) – Use a slower, but more precise, method for deprojecting the pixel coordinates if the emission surface is shadowed.

Returns:

Three coordinate arrays, either the cylindrical coordaintes, (r, theta, z) or cartestian coordinates, (x, y, z), depending on frame.

sky_to_disk(coords, x0=0.0, y0=0.0, inc=0.0, PA=0.0, coord_type='cartesian', coord_type_out='cartesian')¶

Deproject the sky plane coordinates into midplane disk-frame coordinates. Accounting for non-zero emission heights in progress.

Parameters:

coords (tuple) – A tuple of the sky-frame coordinates to transform. Must be either cartestian or cylindrical frames specified by the coord_type argument. All spatial coordinates should be given in [arcsec], while all angular coordinates should be given in [radians].
x0 (Optional[float]) – Source right ascension offset in [arcsec].
y0 (Optional[float]) – Source declination offset in [arcsec].
inc (float) – Inclination of the disk in [deg].
PA (float) – Position angle of the disk, measured Eastwards to the red-shifted major axis from North in [deg].
coord_type (Optional[str]) – The coordinate type of the sky-frame coordinates, either 'cartesian' or 'cylindrical'.
coord_type_out (Optional[str]) – The coordinate type of the returned disk-frame coordinates, either 'cartesian' or 'cylindrical'.

Returns:

Two arrays representing the deprojection of the input coordinates into the disk-frame, x_disk and y_disk if coord_type_out='cartesian' otherwise r_disk and t_disk.

disk_to_sky(coords, inc, PA, x0=0.0, y0=0.0, coord_type='cylindrical', return_idx=False)¶

Project disk-frame coordinates onto the sky plane. Can return either the coordinates (the default return), useful for plotting, or the pixel indices (if return_idx=True) which can be used to extract a spectrum at a particular location.

Parameters:

coords (tuple) – A tuple of the disk-frame coordinates to transform. Must be either cartestian, cylindrical or spherical frames, specified by the frame argument. If only two coordinates are given, the input is assumed to be 2D. All spatial coordinates should be given in [arcsec], while all angular coordinates should be given in [radians].
inc (float) – Inclination of the disk in [deg].
PA (float) – Position angle of the disk, measured Eastwards to the red-shifted major axis from North in [deg].
x0 (Optional[float]) – Source right ascension offset in [arcsec].
y0 (Optional[float]) – Source declination offset in [arcsec].
coord_type (Optional[str]) – Coordinate system used for the disk coordinates, either 'cartesian', 'cylindrical' or 'spherical'.
return_idx (Optional[bool]) – If true, return the index of the nearest pixel to each on-sky position.

Returns:

Two arrays representing the projection of the input coordinates onto the sky, x_sky and y_sky, unless return_idx is True, in which case the arrays are the indices of the nearest pixels on the sky.

velocity_to_restframe_frequency(velax=None, vlsr=0.0)¶: Return restframe frequency [Hz] of the given velocity [m/s].

restframe_frequency_to_velocity(nu, vlsr=0.0)¶: Return velocity [m/s] of the given restframe frequency [Hz].

spectral_resolution(dV=None)¶: Convert velocity resolution in [m/s] to [Hz].

velocity_resolution(dnu)¶: Convert spectral resolution in [Hz] to [m/s].

keplerian_mask(inc, PA, dist, mstar, vlsr, x0=0.0, y0=0.0, z0=0.0, psi=1.0, r_cavity=None, r_taper=None, q_taper=None, dV0=300.0, dVq=-0.5, r_min=0.0, r_max=4.0, nbeams=None, tolerance=0.01, restfreqs=None, max_dz0=0.2, return_type='float')¶

Generate a make based on a Keplerian velocity model. Original code from https://github.com/richteague/keplerian_mask. Unlike with the original code, the mask will be built on the same cube grid as the attached data. Multiple lines can be considered at once by providing a list of the rest frequencies of the line.

Unlike other functions, this does not accept z_func.

Parameters:	inc (float) – Inclination of the disk in [deg]. PA (float) – Position angle of the disk, measured Eastwards to the red-shifted major axis from North in [deg]. dist (float) – Distance to source in [pc]. mstar (float) – Stellar mass in [Msun]. vlsr (float) – Systemic velocity in [m/s]. x0 (Optional[float]) – Source right ascension offset in [arcsec]. y0 (Optional[float]) – Source declination offset in [arcsec]. z0 (Optional[float]) – Aspect ratio at 1” for the emission surface. To get the far side of the disk, make this number negative. psi (Optional[float]) – Flaring angle for the emission surface. r_cavity (Optional[float]) – Edge of the inner cavity for the emission surface in [arcsec]. r_taper (Optional[float]) – Characteristic radius in [arcsec] of the exponential taper to the emission surface. q_taper (Optional[float]) – Exponent of the exponential taper of the emission surface. dV0 (Optional[float]) – Line Doppler width at 1” in [m/s]. dVq (Optional[float]) – Powerlaw exponent for the Doppler-width dependence. r_min (Optional[float]) – Inner radius to consider in [arcsec]. r_max (Optional[float]) – Outer radius to consider in [arcsec]. nbeams (Optional[float]) – Size of convolution kernel to smooth the mask by. tolerance (Optional[float]) – After smoothing, the limit used to decide if a pixel is masked or not. Lower values will include more pixels. restfreqs (Optional[list]) – Rest frequency (or list of rest frequencies) in [Hz] to allow for multiple (hyper-)fine components. max_dz0 (Optional[float]) – The maximum step size between different `z0` values used for the different emission heights. return_type (Optional[str]) – The value type used for the returned mask, the default is `'float'`.
Returns:	The Keplerian mask with the desired value type.
Return type:	ndarry

print_beam()¶: Print the beam properties.

beams_per_pix¶: Number of beams per pixel.

pix_per_beam¶: Number of pixels in a beam.

FOV¶: Field of view.

frequency(vlsr=0.0, unit='GHz')¶

A velocity_to_restframe_frequency wrapper with unit conversion.

Parameters:	vlsr (optional[float]) – Sytemic velocity in [m/s]. unit (optional[str]) – Unit for the output axis.
Returns:	1D array of frequency values.

frequency_offset(nu0=None, vlsr=0.0, unit='MHz')¶

Return the frequency offset relative to nu0 for easier plotting.

Parameters:	nu0 (optional[float]) – Reference restframe frequency in [Hz]. vlsr (optional[float]) – Sytemic velocity in [m/s]. unit (optional[str]) – Unit for the output axis.
Returns:	1D array of frequency values.

jybeam_to_Tb_RJ(data=None, nu=None)¶: [Jy/beam] to [K] conversion using Rayleigh-Jeans approximation.

jybeam_to_Tb(data=None, nu=None)¶: [Jy/beam] to [K] conversion using the full Planck law.

Tb_to_jybeam_RJ(data=None, nu=None)¶: [K] to [Jy/beam] conversion using Rayleigh-Jeans approxmation.

Tb_to_jybeam(data=None, nu=None)¶: [K] to [Jy/beam] conversion using the full Planck law.

estimate_RMS(N=5, r_in=0.0, r_out=10000000000.0)¶

Estimate RMS of the cube based on first and last N channels and a circular area described by an inner and outer radius.

Parameters:	N (int) – Number of edge channels to include. r_in (float) – Inner edge of pixels to consider in [arcsec]. r_out (float) – Outer edge of pixels to consider in [arcsec].
Returns:	The RMS based on the requested pixel range.
Return type:	RMS (float)

print_RMS(N=5, r_in=0.0, r_out=10000000000.0)¶: Print the estimated RMS in Jy/beam and K (using RJ approx.).

correct_PB(path)¶: Correct for the primary beam given by path.

shift_image(x0=0.0, y0=0.0, data=None)¶

Shift the source center of the provided data by d0 [arcsec] and y0 [arcsec] in the x- and y-directions, respectively. The shifting is performed with scipy.ndimage.shift which uses a third-order spline interpolation.

Parameters:	x0 (Optional[float]) – Shfit along the x-axis in [arcsec]. y0 (Optional[float]) – Shifta long the y-axis in [arcsec]. data (Optional[ndarray]) – Data to shift.
Returns:	The shifted array.
Return type:	ndarray

rotate_image(PA, data=None)¶

Rotate the image such that the red-shifted axis aligns with the x-axis.

Parameters:	PA (float) – Position angle of the disk, measured to the red-shifted major axis of the disk, anti-clockwise from North, in [deg]. data (Optional[ndarray]) – Data to rotate if not the attached data.
Returns:	The rotated array.
Return type:	ndarray

rms¶: RMS of the cube based on the first and last 5 channels.

extent¶: Cube field of view for use with Matplotlib’s imshow.

get_spectrum(coords, x0=0.0, y0=0.0, inc=0.0, PA=0.0, frame='sky', coord_type='cartesian', area=0.0, beam_weighting=False, return_mask=False)¶

Return a spectrum at a position defined by a coordinates given either in sky-frame position (frame='sky') or a disk-frame location (frame='disk'). The coordinates can be either in cartesian or cylindrical frames set by coord_type.

By default the returned spectrum is extracted at the pixel closest to the provided coordinates. If area is set to a positive value, then a beam-shaped area is averaged over, where area sets the size of this region in number of beams. For example area=2.0 will result in an average over an area twice the size of the beam.

If an average is averaged over, you can also weight the pixels by the beam response with beam_weighting=True. This will reduce the weight of pixels that are further away from the beam center.

Finally, to check that you’re extracting what you think you are, you can return the mask (and weights) used for the extraction with return_mask=True. Note that if beam_weighting=False then all weights will be 1.

TODO: Check that the returned uncertainties are reasonable.

Parameters:

coords (tuple) – The coordinates from where you want to extract a spectrum. Must be a length 2 tuple.
x0 (Optional[float]) – RA offset in [arcsec].
y0 (Optional[float]) – Dec offset in [arcsec].
inc (Optional[float]) – Inclination of source in [deg]. Only required for frame='disk'.
PA (Optional[float]) – Position angle of source in [deg]. Only required for frame='disk'.
frame (Optional[str]) – The frame that the coords are given. Either 'disk' or 'sky'.
coord_type (Optional[str]) – The type of coordinates given, either 'cartesian' or 'cylindrical'.
area (Optional[float]) – The area to average over in units of the beam area. Note that this take into account the beam aspect ratio and position angle. For a single pixel extraction use area=0.0.
beam_weighting (Optional[bool]) – Whether to use the beam response function to weight the averaging of the spectrum.
return_mask (Optional[bool]) – Whether to return the mask and weights used to extract the spectrum.

Retuns (if return_mask=False):: x, y, dy (arrays): The velocity axis, extracted spectrum and associated uncertainties.
(if return_mask=True):: mask, weights (arrays): Arrays of the mask used to extract the spectrum and the weighted used for the averaging.

convolve_with_beam(data, scale=1.0, circular=False, convolve_kwargs=None)¶

Convolve the attached data with a 2D Gaussian kernel matching the synthesized beam. This can be scaled with scale, or forced to be circular (taking the major axis as the radius of the beam).

Parameters:	data (ndarray) – The data to convolve. Must be either 2D or 3D. scale (Optional[float]) – Factor to scale the synthesized beam by. circular (Optional[bool]) – Force a cicular kernel. If `True1`, the kernel will adopt the scaled major axis of the beam to use as the radius. convolve_kwargs (Optional[dict]) – Keyword arguments to pass to `astropy.convolution.convolve`.
Returns:	Data convolved with the requested kernel.
Return type:	ndarray

cross_section(x0=0.0, y0=0.0, PA=0.0, mstar=1.0, dist=100.0, vlsr=None, grid=True, grid_spacing=None, downsample=1, cylindrical_rotation=False, clip_noise=True, min_npnts=5, statistic='mean', mask_velocities=None)¶

Return the cross section of the data following Dutrey et al. (2017). This yields I_nu(r, z). If grid=True then this will be gridded using scipy.interpolate.griddata onto axes with the same pixel spacing as the attached data.

Reference:

Dutrey et al. (2017):: https://ui.adsabs.harvard.edu/abs/2017A%26A…607A.130D

Parameters:	x0 (Optional[float]) – Source right ascension offset [arcsec]. y0 (Optional[float]) – Source declination offset [arcsec]. PA (Optional[float]) – Position angle of the disk in [deg]. mstar (Optional[float]) – Mass of the central star in [Msun]. dist (Optional[float]) – Distance to the source in [pc]. vlsr (Optional[float]) – Systemic velocity in [m/s]. If `None`, assumes the central velocity. grid (Optional[bool]) – Whether to grid the coordinates to a regular grid. Default is `True`. grid_spacing (Optional[float]) – The spacing, in [arcsec], for the R and Z grids. If `None` is provided, will use pixel spacing. downsample (Optional[int]) – If provided, downsample the coordinates to grid by this factor to speed up the interpolation for large datasets. Default is `1`. cylindrical_rotation (Optional[bool]) – If `True`, assume that the Keplerian rotation decreases with height above the midplane. clip_noise (Optional[bool]) – If `True`, remove all pixels which fall below 3 times the standard deviation of the two edge channels. If the argument is a `float`, use this as the clip level. min_npnts (Optional[int]) – Number of minimum points in each bin for the average. Default is 5. statistic (Optional[str]) – Statistic to calculate for each bin. Note that the uncertainty returned will only make sense with `'max'`, `'mean'` or `'median'`. mask_velocities (Optional[list of tuples]) – List of `(v_min, v_max)` tuples to mask (i.e. remove from the averaging).
Returns:	Either two 1D arrays containing `(r, z, I_nu)`, or, if `grid=True`, two 1D arrays with the `r` and `z` axes and two 2D array of `I_nu` and `dI_nu`.
Return type:	ndarray

spiral_coords(r_p, t_p, m=None, r_min=None, r_max=None, mstar=1.0, T0=20.0, Tq=-0.5, dist=100.0, clockwise=True, frame_out='cartesian')¶

Spiral coordinates from Bae & Zhaohuan (2018a). In order to recover the linear spirals from Rafikov (2002), use m >> 1. :param r_p: Orbital radius of the planet in [arcsec]. :type r_p: float :param t_p: Polar angle of planet relative to the red-shifted

major axis of the disk in [radians].

Parameters:	m (optional[int]) – Azimuthal wavenumber of the spiral. If not specified, will assume the dominant term based on the rotation and temperature profiles. r_min (optional[float]) – Inner radius of the spiral in [arcsec]. r_max (optional[float]) – Outer radius of the spiral in [arcsec]. mstar (optioanl[float]) – Stellar mass of the central star in [Msun] to calculate the rotation profile. T0 (optional[float]) – Gas temperature in [K] at 1 arcsec. Tq (optional[float]) – Exoponent of the radial gas temperature profile. dist (optional[float]) – Source distance in [pc] used to scale [arcsec] to [au] in the calculation of the rotation profile. clockwise (optional[bool]) – Direction of the spiral. frame_out (optional[str]) – Coordinate frame of the returned values, either ‘cartesian’ or ‘cylindrical’.
Returns:	Coordinates of the spiral in either cartestian or cylindrical frame.
Return type:	ndarray

plot_center(x0s, y0s, SNR, normalize=True)¶: Plot the array of SNR values.

plot_teardrop(inc, PA, mstar, dist, ax=None, rvals=None, rbins=None, dr=None, x0=0.0, y0=0.0, z0=None, psi=None, r_cavity=None, r_taper=None, q_taper=None, z_func=None, resample=1, beam_spacing=False, r_min=None, r_max=None, PA_min=None, PA_max=None, exclude_PA=False, abs_PA=False, mask_frame='disk', mask=None, unit='Jy/beam', pcolormesh_kwargs=None, shadowed=False, vrad_func=None)¶

Make a teardrop plot. For argument descriptions see radial_spectra. For all properties related to pcolormesh, include them in pcolormesh_kwargs as a dictionary, e.g.

pcolormesh_kwargs = dict(cmap=’inferno’, vmin=0.0, vmax=1.0)

This will override any of the default style parameters.

plot_beam(ax, x0=0.1, y0=0.1, **kwargs)¶

Plot the sythensized beam on the provided axes.

Parameters:	ax (matplotlib axes instance) – Axes to plot the FWHM. x0 (float) – Relative x-location of the marker. y0 (float) – Relative y-location of the marker. kwargs (dic) – Additional kwargs for the style of the plotting.

plot_surface(x0=0.0, y0=0.0, inc=0.0, PA=0.0, z0=None, psi=None, r_cavity=None, r_taper=None, q_taper=None, z_func=None, shadowed=False, r_max=None, fill=None, ax=None, contour_kwargs=None, imshow_kwargs=None, return_fig=True)¶

Overplot the assumed emission surface.

Parameters:

x0 (Optional[float]) – Source right ascension offset [arcsec].
y0 (Optional[float]) – Source declination offset [arcsec].
inc (Optional[float]) – Source inclination [deg].
PA (Optional[float]) – Source position angle [deg]. Measured between north and the red-shifted semi-major axis in an easterly direction.
z0 (Optional[float]) – Aspect ratio at 1” for the emission surface. To get the far side of the disk, make this number negative.
psi (Optional[float]) – Flaring angle for the emission surface.
r_cavity (Optional[float]) – Edge of the inner cavity for the emission surface in [arcsec].
r_taper (Optional[float]) – Characteristic radius in [arcsec] of the exponential taper to the emission surface.
q_taper (Optional[float]) – Exponent of the exponential taper of the emission surface.
z_func (Optional[function]) – A function which provides $z(r)$ . Note that no checking will occur to make sure this is a valid function.
shadowed (Optional[bool]) – If True, use the slower, but more robust method for deprojecting pixel values.
r_max (Optional[float]) – Maximum radius in [arcsec] to plot the emission surface out to.
fill (Optional[str]) – A string to execute (be careful!) to fill in the emission surface using rvals, tvals and zvals as returned by disk_coords. For example, to plot the radial values use fill='rvals'. To plot the projection of rotational velocities, use fill='rvals * np.cos(tvals)'.
ax (Optional[matplotlib axis instance]) – Axis to plot onto. contour_kwargs (Optional[dict]): Kwargs to pass to matplolib.contour to overplot the mesh.
return_fig (Optional[bool]) – If True, return the figure for additional plotting.

Returns:

The ax instance.

plot_maximum(ax=None, imshow_kwargs=None)¶

Plot the maximum along the spectral axis.

Parameters:	ax (Optional[matplotlib axis instance]) – Axis to use for plotting. imshow_kwargs (Optional[dict]) – Kwargs to pass to imshow.
Returns:	The axis with the maximum plotted.

plot_mask(ax, r_min=None, r_max=None, exclude_r=False, PA_min=None, PA_max=None, exclude_PA=False, abs_PA=False, mask_frame='disk', mask=None, x0=0.0, y0=0.0, inc=0.0, PA=0.0, z0=None, psi=None, r_cavity=None, r_taper=None, q_taper=None, z_func=None, mask_color='k', mask_alpha=0.5, contour_kwargs=None, contourf_kwargs=None, shadowed=False)¶

Plot the boolean mask on the provided axis to check that it makes sense.

Parameters:	ax (matplotib axis instance) – Axis to plot the mask. r_min (Optional[float]) – Minimum midplane radius of the annulus in [arcsec]. Defaults to minimum deprojected radius. r_max (Optional[float]) – Maximum midplane radius of the annulus in [arcsec]. Defaults to the maximum deprojected radius. exclude_r (Optional[bool]) – If `True`, exclude the provided radial range rather than include. PA_min (Optional[float]) – Minimum polar angle of the segment of the annulus in [degrees]. Note this is the polar angle, not the position angle. PA_max (Optional[float]) – Maximum polar angle of the segment of the annulus in [degrees]. Note this is the polar angle, not the position angle. exclude_PA (Optional[bool]) – If `True`, exclude the provided polar angle range rather than include it. abs_PA (Optional[bool]) – If `True`, take the absolute value of the polar angle such that it runs from 0 [deg] to 180 [deg]. x0 (Optional[float]) – Source center offset along the x-axis in [arcsec]. y0 (Optional[float]) – Source center offset along the y-axis in [arcsec]. inc (Optional[float]) – Inclination of the disk in [degrees]. PA (Optional[float]) – Position angle of the disk in [degrees], measured east-of-north towards the redshifted major axis. z0 (Optional[float]) – Emission height in [arcsec] at a radius of 1”. psi (Optional[float]) – Flaring angle of the emission surface. z_func (Optional[function]) – A function which provides $z(r)$ . Note that no checking will occur to make sure this is a valid function. mask_color (Optional[str]) – Color used for the mask lines. mask_alpha (Optional[float]) – The alpha value of the filled contour of the masked regions. Setting `mask_alpha=0.0` will remove the filling. contour_kwargs (Optional[dict]) – Kwargs to pass to contour for drawing the mask.
Returns:	The matplotlib axis instance.
Return type:	ax