StokesSpectralCube

class spectral_cube.StokesSpectralCube(stokes_data, mask=None, meta=None, fill_value=None)

Bases: object

A class to store a spectral cube with multiple Stokes parameters.

The individual Stokes cubes can share a common mask in addition to having component-specific masks.

Attributes Summary

components
mask	The underlying mask
read	Read and parse a dataset and return as a StokesSpectralCube
shape
stokes_data	The underlying data
stokes_type	Defines the type of stokes that has been setup. stokes_type can be sky, linear, circular, generic, or other.
wcs
write	Write this StokesSpectralCube object out in the specified format.

Methods Summary

minimal_subcube([spatial_only])	Return the minimum enclosing subcube where the mask is valid.
spectral_slab(lo, hi)	Extract a new cube between two spectral coordinates.
subcube([xlo, xhi, ylo, yhi, zlo, zhi, ...])	Extract a sub-cube spatially and spectrally.
subcube_from_crtfregion(crtf_region[, ...])	Extract a masked subcube from a CRTF region string (only functions on celestial dimensions).
subcube_from_ds9region(ds9_region[, allow_empty])	Extract a masked subcube from a DS9 region string (only functions on celestial dimensions).
subcube_from_mask(region_mask)	Given a mask, return the minimal subcube that encloses the mask.
subcube_from_regions(region_list[, ...])	Extract a masked subcube from a list of regions.Region objects (only functions on celestial dimensions).
subcube_slices_from_mask(region_mask[, ...])	Given a mask, return the slices corresponding to the minimum subcube that encloses the mask.
transform_basis([stokes_basis])	Transform the Stokes basis of the cube to the one specified if possible.
with_mask(mask[, inherit_mask])	Return a new StokesSpectralCube instance that contains a composite mask of the current StokesSpectralCube and the new mask.
with_spectral_unit(unit, **kwargs)

Attributes Documentation

components

mask

The underlying mask

read

Read and parse a dataset and return as a StokesSpectralCube

This allows easily reading a dataset in several supported data formats using syntax such as:

>>> from spectral_cube import StokesSpectralCube
>>> cube1 = StokesSpectralCube.read('cube.fits', format='fits')
>>> cube2 = StokesSpectralCube.read('cube.image', format='casa')

If the file contains Stokes axes, they will be read in. If you are only interested in the unpolarized emission (I), you can use read() instead.

Get help on the available readers for StokesSpectralCube using the``help()`` method:

>>> StokesSpectralCube.read.help()  # Get help reading StokesSpectralCube and list supported formats
>>> StokesSpectralCube.read.help('fits')  # Get detailed help on StokesSpectralCube FITS reader
>>> StokesSpectralCube.read.list_formats()  # Print list of available formats

See also: http://docs.astropy.org/en/stable/io/unified.html

Parameters:

*argstuple, optional

Positional arguments passed through to data reader. If supplied the first argument is typically the input filename.

formatstr

File format specifier.

**kwargsdict, optional

Keyword arguments passed through to data reader.

Returns:

cubeStokesSpectralCube

StokesSpectralCube corresponding to dataset

shape

stokes_data

The underlying data

stokes_type

Defines the type of stokes that has been setup. stokes_type can be sky, linear, circular, generic, or other.

• Sky refers to stokes in sky basis, I,Q,U,V

• Linear refers to the stokes in linear feed basis, XX, XY, YX, YY

• Circular refers to stokes in circular feed basis, RR, RL, LR, LL

• Generic refers to the general four orthogonal components, PP, PQ, QP, QQ

wcs

write

Write this StokesSpectralCube object out in the specified format.

This allows easily writing a dataset in many supported data formats using syntax such as:

>>> data.write('data.fits', format='fits')

Get help on the available writers for StokesSpectralCube using the``help()`` method:

>>> StokesSpectralCube.write.help()  # Get help writing StokesSpectralCube and list supported formats
>>> StokesSpectralCube.write.help('fits')  # Get detailed help on StokesSpectralCube FITS writer
>>> StokesSpectralCube.write.list_formats()  # Print list of available formats

See also: http://docs.astropy.org/en/stable/io/unified.html

Parameters:

*argstuple, optional

Positional arguments passed through to data writer. If supplied the first argument is the output filename.

formatstr

File format specifier.

**kwargsdict, optional

Keyword arguments passed through to data writer.

Methods Documentation

minimal_subcube(spatial_only=False)

Return the minimum enclosing subcube where the mask is valid.

Parameters:

spatial_onlybool

Only compute the minimal subcube in the spatial dimensions.

spectral_slab(lo, hi)

Extract a new cube between two spectral coordinates.

Parameters:

lo, hiQuantity

The lower and upper spectral coordinate for the slab range.

subcube(xlo='min', xhi='max', ylo='min', yhi='max', zlo='min', zhi='max', rest_value=None)

Extract a sub-cube spatially and spectrally.

Parameters:

xlo, xhi, ylo, yhi, zlo, zhiint or Quantity or min/max

The endpoints to extract. Quantity values are interpreted as world coordinates; plain ints or 'min'/'max' strings as pixel coordinates.

rest_valueQuantity, optional

The rest frequency/wavelength for spectral conversions.

subcube_from_crtfregion(crtf_region, allow_empty=False)

Extract a masked subcube from a CRTF region string (only functions on celestial dimensions).

Parameters:

crtf_regionstr

The CRTF region(s) string to extract.

allow_emptybool, optional

If False, raise an exception when the region has no overlap with the cube. Default is False.

subcube_from_ds9region(ds9_region, allow_empty=False)

Extract a masked subcube from a DS9 region string (only functions on celestial dimensions).

Parameters:

ds9_regionstr

The DS9 region(s) to extract.

allow_emptybool, optional

If False, raise an exception when the region has no overlap with the cube. Default is False.

subcube_from_mask(region_mask)

Given a mask, return the minimal subcube that encloses the mask.

Parameters:

region_maskMaskBase or boolean numpy.ndarray

The mask with appropriate WCS or an ndarray with matched coordinates.

subcube_from_regions(region_list, allow_empty=False, minimize=True)

Extract a masked subcube from a list of regions.Region objects (only functions on celestial dimensions).

Parameters:

region_listlist of regions.Region

The region(s) to extract.

allow_emptybool, optional

If False, raise an exception when the region has no overlap with the cube. Default is False.

minimizebool, optional

Run minimal_subcube() after masking. Default is True.

subcube_slices_from_mask(region_mask, spatial_only=False)

Given a mask, return the slices corresponding to the minimum subcube that encloses the mask.

Parameters:

region_maskMaskBase or boolean numpy.ndarray

The mask with appropriate WCS or an ndarray with matched coordinates.

spatial_onlybool

Return only slices that affect the spatial dimensions; the spectral dimension will be left unchanged.

transform_basis(stokes_basis='')

Transform the Stokes basis of the cube to the one specified if possible. Operates on the underlying data arrays, not SpectralCube objects. This makes the operation very expensive, so it should be used with care.

with_mask(mask, inherit_mask=True)

Return a new StokesSpectralCube instance that contains a composite mask of the current StokesSpectralCube and the new mask.

Parameters:

maskMaskBase instance, or boolean numpy array

The mask to apply. If a boolean array is supplied, it will be converted into a mask, assuming that True values indicate included elements.

inherit_maskbool (optional, default=True)

If True, combines the provided mask with the mask currently attached to the cube

Returns:

new_cubeStokesSpectralCube

A cube with the new mask applied.

Notes

This operation returns a view into the data, and not a copy.

with_spectral_unit(unit, **kwargs)