ism3d.xyhelper.maskmoment package

Submodules

ism3d.xyhelper.maskmoment.maskmoment module

ism3d.xyhelper.maskmoment.maskmoment.maskmoment(img_fits, gain_fits=None, rms_fits=None, mask_fits=None, outdir='.', outname=None, snr_hi=4, snr_lo=2, minbeam=1, snr_hi_minch=1, snr_lo_minch=1, min_tot_ch=2, nguard=[0, 0], edgech=5, fwhm=None, vsm=None, vsm_type='gauss', mom1_minch=2, mom2_minch=2, altoutput=False, output_snr_cube=False, output_snr_peak=False, output_snrsm_cube=False, output_2d_mask=False, to_kelvin=True, huge_operations=True, perpixel=False)[source]

Produce FITS images of moment maps using a dilated masking approach.

Parameters

  • img_fits (FITS file name, required) – The image cube, this should be in units of K, Jy/beam, or equivalent.

  • gain_fits (FITS file name, optional) – The gain cube, e.g. pb cube from CASA. This should have a value between 0 and 1, with 0 near the edges and 1 near the center of the image, and have the same dimensions as the image cube. NOTE: The gain cube is ignored if a noise cube (rms_fits) is given.

  • rms_fits (FITS file name, optional) – The noise cube, providing an estimate of the rms noise at each pixel. This should have the same dimensions and units as the image cube. NOTE: If rms_fits is not given, a noise cube is generated from the image cube, after removing any gain variation using the gain cube.

  • mask_fits (FITS file name, optional) – External mask cube to use. This cube should have 1’s for valid pixels and 0’s for excluded pixels. If this is provided then the mask generation is skipped and the program goes straight to calculating the moments.

  • outdir (string, optional) – Directory to write the output files. Default: Write to the directory where img_fits resides. NOTE: Currently this directory is assumed to exist.

  • outname (string, optional) – Basename for output files. For instance, outname=’foo’ produces files ‘foo.mom0.fits.gz’, etc. Default: Based on root name of img_fits.

  • snr_hi (float, optional) – The high significance sigma threshold from which to begin mask dilation. Default: 4

  • snr_lo (float, optional) – The low significance sigma threshold at which to end mask dilation. Default: 2

  • snr_hi_minch (int, optional) – High significance mask is required to span at least this many channels at all pixels. Default: 1

  • snr_lo_minch (int, optional) – Low significance mask is required to span at least this many channels at all pixels. Default: 1

  • min_tot_ch (int, optional) – Each contiguous mask region must span at least this many channels (but it’s not necessary that every pixel in the region span this many channels). Default: 2

  • minbeam (float, optional) – Minimum velocity-integrated area of a mask region in units of the beam size. Default: 1

  • nguard (tuple of two ints, optional) – Expand the final mask by nguard[0] pixels in the sky directions and nguard[1] channels in velocity. Currently these values must be equal if both are non-zero. If nguard[0] = 0 then no expansion is done in sky coordinates. If nguard[1] = 0 then no expansion is done in velocity. Default: [0,0]

  • edgech (int, optional) – Number of channels at each end of vel axis to use for rms estimation. Default: 5

  • fwhm (float or Quantity, optional) – Spatial resolution to smooth to before generating the dilated mask. If value is not an astropy quantity, assumed to be given in arcsec. Default: No spatial smoothing is applied.

  • vsm (float or Quantity, optional) – Full width of the spectral smoothing kernel (or FWHM for gaussian). If given as astropy quantity, should be given in velocity units. If not given as astropy quantity, interpreted as number of channels. Default: No spectral smoothing is applied.

  • vsm_type (string, optional) – What type of spectral smoothing to employ. Currently three options: (1) ‘boxcar’ - 1D boxcar smoothing, vsm rounded to integer # of chans. (2) ‘gauss’ - 1D gaussian smoothing, vsm is the convolving gaussian FWHM. (3) ‘gaussfinal’ - 1D gaussian smoothing, vsm is the gaussian FWHM

    after convolution, assuming FWHM before convolution is 1 channel.

    Default: ‘gauss’

  • mom1_minch (int, optional) – Minimum number of unmasked channels needed to calculate moment-1. Default: 2

  • mom2_minch (int, optional) – Minimum number of unmasked channels needed to calculate moment-2. Default: 2

  • perpixel (boolean, optional) – Whether to calculate the rms per XY pixel instead of over whole image. Set to True if you know there is a sensitivity variation across the image but you don’t have a gain cube - requires rms_fits and gain_fits unset. Default: False

  • output_snr_cube (boolean, optional) – Output the cube in SNR units in addition to the moment maps. Default: False

  • output_snr_peak (boolean, optional) – Output the peak SNR image in addition to the moment maps. Default: False

  • output_snrsm_cube (boolean, optional) – Output the smoothed cube in SNR units in addition to the moment maps. Default: False

  • output_2d_mask (boolean, optional) – Output the projected 2-D mask as well as the newly generated mask. The projected mask at a given pixel is valid for all channels as long as the parent mask is valid for any channel. Default: False

  • to_kelvin (boolean, optional) – Output the moment maps in K units if the cube is in Jy/beam units. Default: True

  • altoutput (boolean, optional) – Also output moment maps from a “direct” calculation instead of the moment method in spectral_cube. Mainly used for debugging. Default: False

  • huge_operations (boolean, optional) – Allow huge operations in spectral_cube. Default: True

ism3d.xyhelper.maskmoment.momfuncs module

ism3d.xyhelper.maskmoment.momfuncs.calc_moments(imcube, rmscube, mask=None)[source]

Calculate moments of a masked cube and their errors

Parameters

  • imcube (SpectralCube) – The image cube for which to calculate the moments and their errors.

  • rmscube (SpectralCube) – A cube representing the noise estimate at each location in the image cube. Should have the same units as the image cube.

  • mask (~numpy.ndarray) – A binary mask array (0s and 1s) to be applied before measuring the flux and uncertainty. This should NOT be a SpectralCube.

Returns

  • altmom (~numpy.ndarray) – A stack of the three moment maps. These are generally redundant since they were previously calculated by SpectralCube.

  • errmom (~numpy.ndarray) – A stack of the three uncertainty maps.

ism3d.xyhelper.maskmoment.momfuncs.dilmsk(snrcube, header=None, snr_hi=4, snr_lo=2, minbeam=1, snr_hi_minch=1, snr_lo_minch=1, min_tot_ch=2, nguard=[0, 0], debug=False)[source]

Dilate a mask from one specified threshold to another.

Parameters

  • snrcube (SpectralCube or ~numpy.ndarray) – The image cube normalized by the estimated RMS noise. If a numpy array is provided the header must also be provided.

  • header (astropy.io.fits.Header) – The cube FITS header, required if a numpy array is given.

  • snr_hi (float, optional) – The high significance threshold from which to begin the mask dilation. Default: 4

  • snr_lo (float, optional) – The low significance threshold at which to end the mask dilation. Default: 2

  • minbeam (float, optional) – Minimum velocity-integrated area of a mask region in units of the beam size. Default: 1

  • snr_hi_minch (int, optional) – High significance mask is required to span at least this many channels at all pixels. Default: 1

  • snr_lo_minch (int, optional) – Low significance mask is required to span at least this many channels at all pixels. Default: 1

  • min_tot_ch (int, optional) – Dilated mask regions are required to span at least this many channels. Default: 2

  • nguard (tuple of two ints, optional) – Expand the final mask by this nguard[0] pixels in sky directions and nguard[1] channels in velocity. Currently these values must be equal if both are non-zero. If nguard[0] = 0 then no expansion is done in sky coordinates. If nguard[1] = 0 then no expansion is done in velocity. Default: [0,0]

  • debug (boolean, optional) – Output a bunch of FITS files to diagnose what’s going on. Default: False

Returns

dil_mask – A binary mask array (0s and 1s) which can be applied to a cube

Return type

~numpy.ndarray

ism3d.xyhelper.maskmoment.momfuncs.findflux(imcube, rmscube, mask=None, projmask=None)[source]

Calculate integrated spectrum and total integrated flux.

Parameters

  • imcube (SpectralCube) – The image cube over which to measure the flux.

  • rmscube (SpectralCube) – A cube representing the noise estimate at each location in the image cube. Should have the same units as the image cube.

  • mask (~numpy.ndarray) – A binary mask array (0s and 1s) to be applied before measuring the flux and uncertainty. This should NOT be a SpectralCube.

  • projmask (~numpy.ndarray) – A second mask array within which to measure the flux and uncertainty. This is normally the 2-D projected mask.

Returns

fluxtab – A 3-column table providing the velocity, flux, and uncertainty.

Return type

Table

ism3d.xyhelper.maskmoment.momfuncs.makenoise(cubearray, gainarray=None, rms=None, perpixel=False, edge=None, clip=0.2)[source]

Given a data cube and an optional gain cube, estimate the noise at each position, using the robust mad_std estimator in astropy.

Parameters

  • cubearray (SpectralCube or ~numpy.ndarray) – The input data cube. No default.

  • gainarray (SpectralCube or ~numpy.ndarray, optional) – Gain of a point source at each position of the cube (typically 0 to 1). Can be 2-D or 3-D image, e.g. from pb.fits file from CASA. Default is to assume the rms is constant with position.

  • rms (float, optional) – Global estimate of the rms noise, to be used instead of trying to estimate it from the data. It should have the units of the input cube. Default is to calculate the rms from the data.

  • perpixel (boolean, optional) – Whether to calculate the rms per pixel instead of over whole image. Set to True if you know there is a sensitivity variation across the image but you don’t have a gain cube. Only used if rms is unset. Default: False

  • edge (int, optional) – Number of channels at left and right edges of each spectrum to use for rms estimation. Default is to use all channels.

  • clip (float, optional) – Pixels below this value in the input gainarray are marked invalid. Default: 0.2

Returns

noisecube *or* noisearray – The noise estimate as a 3-D array with the same shape and units as the input cube. If the input cube was a SpectralCube, a SpectralCube is returned.

Return type

SpectralCube or ~numpy.ndarray

ism3d.xyhelper.maskmoment.momfuncs.maskguard(maskarray, niter=1, xyonly=False, vonly=False)[source]

Pad a mask by specified number of pixels in all three dimensions.

Parameters

  • maskarray (~numpy.ndarray) – The 3-D mask array with 1s for valid pixels and 0s otherwise.

  • niter (int, optional) – Number of iterations for expanding mask by binary dilation. Default: 1

  • xyonly (boolean, optional) – Whether to expand only in the two sky coordinates Default: False

  • vonly (boolean, optional) – Whether to expand only in the spectral coordinate Default: False (ignored if xyonly==True)

Returns

maskarray – A copy of the input maskarray after padding.

Return type

~numpy.ndarray

ism3d.xyhelper.maskmoment.momfuncs.prunemask(maskarray, minarea=0, minch=2, byregion=True)[source]

Apply area and velocity width criteria on mask regions.

Parameters

  • maskarray (~numpy.ndarray) – The 3-D mask array with 1s for valid pixels and 0s otherwise.

  • minarea (int, optional) – Minimum velocity-integrated area in pixel units. Default: 0

  • minch (int, optional) – Minimum velocity width in channel units. Default: 2

  • byregion (boolean, optional) – Whether to enforce min velocity width on whole region, rather than by pixel Default: True

Returns

maskarray – A copy of the input maskarray with regions failing the tests removed.

Return type

~numpy.ndarray

ism3d.xyhelper.maskmoment.momfuncs.smcube(snrcube, header=None, fwhm=None, vsm=None, vsm_type='gauss', edgech=None)[source]

Smooth an SNRcube to produce a higher signal-to-noise SNRcube.

Parameters

  • snrcube (SpectralCube or ~numpy.ndarray) – The image cube normalized by the estimated RMS noise. If a numpy array is provided the header must also be provided.

  • header (astropy.io.fits.Header) – The cube FITS header, required if a numpy array is given.

  • fwhm (float or Quantity, optional) – Final spatial resolution to smooth to. If not astropy quantity, assumed to be given in arcsec. Default: 10 arcsec

  • vsm (float or Quantity, optional) – Full width of the spectral smoothing kernel (or FWHM if gaussian). If given as astropy quantity, should be given in velocity units. If not given as astropy quantity, interpreted as number of channels. Default: No spectral smoothing is applied.

  • vsm_type (string, optional) – What type of spectral smoothing to employ. Currently three options: (1) ‘boxcar’ - 1D boxcar smoothing, vsm rounded to integer # of chans. (2) ‘gauss’ - 1D gaussian smoothing, vsm is the convolving gaussian FWHM. (3) ‘gaussfinal’ - 1D gaussian smoothing, vsm is the gaussian FWHM after convolution, assuming FWHM before convolution is 1 channel. Default: ‘gauss’

  • edgech (int, optional) – Number of channels at left and right edges of each spectrum to use for rms estimation. Default is to use all channels.

Returns

sm_snrcube – A cube is SNR units after smoothing to the desired resolution.

Return type

SpectralCube

ism3d.xyhelper.maskmoment.momfuncs.writemom(imarray, filename='outfile', type='mom1', hdr=None)[source]

Write out a moment map as a FITS file.

Parameters

  • imarray (SpectralCube or ~numpy.ndarray) – The 2D array with the moment map values

  • filename (string) – The root of the file name

  • type (string) – A label for the filename extension

  • hdr (astropy.io.fits.Header) – The FITS header to write out

Module contents

submodule maskmoment