Feathering two cubes

Two cubes can be feathered with the feather_simple_cube. This function handles a variety of operations to prepare for two cubes to be feathered, including pre-processing checks (spatial/spectral reprojection, SD beam reading, units). The same feathering settings used for 2D images in feather_simple can be passed to feather_simple_cube.

>>> from uvcombine import feather_simple_cube
>>> from spectral_cube import SpectralCube
>>> highres_cube = SpectralCube.read("highres.fits")  
>>> lowres_cube = SpectralCube.read("lowres.fits")  
>>> feathered_cube = feather_simple_cube(highres_cube, lowres_cube)  

The defaults settings in feather_simple_cube match those used by CASA’s feather task. For more information on the feathering settings available, see Feathering two images.

For large cubes, the use_memmap option can be enabled to avoid keeping the feathered cube in memory.

Note

When there is a large difference in the spectral channels between the two cubes, we recommend following the spectral-cube smoothing guide to appropriately smooth the higher spectral resolution data prior to interpolation prior to using feather_simple_cube, as this only applies the interpolation step.

If the cubes you are using have already been appropriately smoothed and/or reprojected, you can avoid unnecessary pre-processing using the kwargs for feather_simple_cube. To avoid spectral interpolation of the low resolution data:

>>> feathered_cube = feather_simple_cube(highres_cube, lowres_cube, allow_spectral_resample=False)  

To avoid reprojecting the low resolution data:

>>> feathered_cube = feather_simple_cube(highres_cube, lowres_cube, allow_lo_reproj=False)  

In both cases, consistency checks are applied and a ValueError describing any discrepancies will be returned.

Feathering large cubes using dask

When dask is installed, we can use the dask-integration in spectral-cube to parallelize and load the cubes in chunk to avoid high memory use. See the spectral-cube documentation on using dask for more information.

To enable using dask, load the spectral-cubes in dask mode:

>>> highres_cube = SpectralCube.read("highres.fits", use_dask=True)  
>>> lowres_cube = SpectralCube.read("lowres.fits", use_dask=True)  
>>> feathered_cube = feather_simple_cube(highres_cube, lowres_cube)  

This will automatically enable using dask mode in feather_simple_cube.

A required pre-processing step is to reproject lowres_cube to the same pixel grid as highres_cube and match the brightness units. As this can be computationally expensive, the spectral-cube dask integration exposes an option to save temporary intermediate products as zarr files. This is especially useful when rechunking the data to optimize different computations (e.g., spectral versus spatial regridding.) To enable this mode, use_save_to_tmp_dir can be enabled in feather_simple_cube:

>>> feathered_cube = feather_simple_cube(highres_cube, lowres_cube, use_save_to_tmp_dir=True)  

If the cubes already have matching chunk size, you can avoid rechunking the cubes with:

>>> feathered_cube = feather_simple_cube(highres_cube, lowres_cube, force_spatial_rechunk=False)  

Previous functionality

A similar function fourier_combine_cubes was previously implemented in uvcombine. Its use is now depcrecated as it lacks new features implemented in feather_simple_cube. This method is appropriate for two cubes that each have a single beam size (i.e., the beam does not change between spectral channels). The low resolution beam size is also set using lowresfwhm, and is NOT read from the FITS header.