Handling Beams

If you are using radio data, your cubes should have some sort of beam information included. spectral-cube handles beams using the radio_beam package.

There are two ways beams can be stored in FITS files: as FITS header keywords (BMAJ, BMIN, and BPA) or as a BinTableHDU extension. If the latter is present, spectral-cube will return a VaryingResolutionSpectralCube object.

For the simpler case of a single beam across all channels, the presence of the beam allows for direct conversion of a cube with Jy/beam units to surface brightness (K) units. Note, however, that this requires loading the entire cube into memory!:

>>> cube.unit  
Unit("Jy / beam")
>>> kcube = cube.to(u.K)  
>>> kcube.unit  

Adding a Beam

If your cube does not have a beam, a custom beam can be attached given:

>>> new_beam = Beam(1. * u.deg)  
>>> new_cube = cube.with_beam(new_beam)  
>>> new_cube.beam  
Beam: BMAJ=3600.0 arcsec BMIN=3600.0 arcsec BPA=0.0 deg

This is handy for synthetic observations, which initially have a point-like beam:

>>> point_beam = Beam(0 * u.deg)  
>>> new_cube = synth_cube.with_beam(point_beam)  
Beam: BMAJ=0.0 arcsec BMIN=0.0 arcsec BPA=0.0 deg

The cube can then be convolved to a new resolution:

>>> new_beam = Beam(60 * u.arcsec)  
>>> conv_synth_cube = synth_cube.convolve_to(new_beam)  
>>> conv_synth_cube.beam  
Beam: BMAJ=60.0 arcsec BMIN=60.0 arcsec BPA=0.0 deg

Beam can also be attached in the same way for Projection and Slice objects.

Multi-beam cubes

Varying resolution (multi-beam) cubes are somewhat trickier to work with in general, though unit conversion is easy. You can perform the same sort of unit conversion with VaryingResolutionSpectralCube s as with regular SpectralCube s; spectral-cube will use a different beam and frequency for each plane.

You can identify channels with bad beams (i.e., beams that differ from a reference beam, which by default is the median beam) using identify_bad_beams (the returned value is a mask array where True means the channel is good), mask channels with undesirable beams using mask_out_bad_beams, and in general mask out individual channels using mask_channels.

For other sorts of operations, discussion of how to deal with these cubes via smoothing to a common resolution is in the Smoothing document.