specex.cube module

SPECEX - SPECtra EXtractor.

This module provides utility functions to handle spectroscopic datacubes.

Copyright (C) 2022-2024 Maurizio D’Addona <mauritiusdadd@gmail.com>

class specex.cube.SpectralCube[source]

Class to handle datacubes.

close() → None[source]

Clean up on closing.

Returns

None.

getSpatialSizePixels() → List[None | int][source]

Return spatial dimensions in pixels.

Returns

TYPE

DESCRIPTION.

getSpecWCS() → WCS[source]

Get the WCS of the spectrum datacube.

Returns

wcs

The WCS of the spectral HDU.

getVarWCS() → WCS[source]

Get the WCS of the variance datacube.

Returns

wcs

The WCS of the variance HDU.

getWdWCS() → WCS[source]

Get the WCS of the variance datacube.

Returns

wcs

The WCS of the resolution curve HDU.

classmethod open(filename: str, spec_hdu_index: int | str | None = None, var_hdu_index: int | str | None = None, mask_hdu_index: int | str | None = None, wd_hdu_index: int | str | None = None, mode: str | None = None) → SpectralCube[source]

Open a datacube from a FITS file.

Parameters

filenamestr

The file path.

spec_hdu_indexOptional[Union[int, str]], optional

The index or name of the HDU containing the spectrum. The default is None.

var_hdu_indexOptional[Union[int, str]], optional

The index or name of the HDU containing the variance. The default is None.

mask_hdu_indexOptional[Union[int, str]], optional

The index or name of the HDU containing the nans maks. The default is None.

wd_hdu_indexOptional[Union[int, str]], optional

The index or name of the HDU containing the R matrix. The default is None.

modeOptional[str], optional

The mode passed to astropy.io.fits.open

Returns

SpectralCube.

write(filename: str, **kwargs)[source]

Write the datacube if a FITS file.

Parameters

filenamestr

The path of the output file.

kwargsdict

Optional arguments passed to astropy.io.fits.HDUList.writeto. For example, it can be {‘overwrite’: True}.

Returns

bool

True if the write operation was succesfull.

specex.cube.cutout_main(options=None)[source]

Run the main cutout program.

Parameters

optionslist or None, optional

A list of cli input prameters. The default is None.

Returns

None.

specex.cube.get_continuum_subtracted_slice(data: ~numpy.ndarray, line_wave: int | ~astropy.units.quantity.Quantity, line_window: int | ~astropy.units.quantity.Quantity = <Quantity 10. Angstrom>, continuum_window: int | ~astropy.units.quantity.Quantity = <Quantity 10. Angstrom>, variance: ~numpy.ndarray | None = None, data_mask: ~numpy.ndarray | None = None, cube_wcs: ~astropy.wcs.wcs.WCS | None = None) → ndarray[source]

Get a continuum subtracted image from a spectral datacube.

Parameters

datanp.ndarray

DESCRIPTION.

line_waveUnion[int, units.Quantity]

DESCRIPTION.

line_windowUnion[int, units.Quantity], optional

DESCRIPTION. The default is 10 * units.angstrom.

continuum_windowUnion[int, units.Quantity], optional

DESCRIPTION. The default is 10 * units.angstrom.

varianceOptional[np.ndarray], optional

DESCRIPTION. The default is None.

data_maskOptional[np.ndarray], optional

DESCRIPTION. The default is None.

cube_wcsWCS, optional

DESCRIPTION. The default is None.

Returns

None.

specex.cube.get_cube_cutout(data: ndarray, center: SkyCoord | tuple | list, size: tuple | list, angle: float | Quantity | None = 0, wave_range: tuple | list | None = None, data_wcs: WCS | None = None, report_callback: Callable | None = None) → Dict[str, WCS | ndarray][source]

Get a cutout of a spectral datacube.

Parameters

datanp.ndarray

The datacube data.

centerastropy.coordinate.SkyCoord or tuple or list.

The center of the cutout. If a SkyCoord is provided then a WCS for the image data musto also be specified with the parameter data_wcs. If a tuple is provided, then the first two numbers of the tuple are interpreted as the X and Y coordinate of the cutout center: in this case, if no WCS is specified, the values are assumed to be in pixels, else if a WCS is provided then the values are assumed to be in degrees.

sizetuple or list

The first two values in the tuple are interpreted as the width and height of the cutout. Both adimensional values and angular quantities are accepted. Adimensional values are interpreted as pixels. Angular values are converted to pixel values ignoring any non-linear distorsion.

anglefloat or astropy.units.Quantity, optional

The rotation angle of the cutout. If it is a float, then it is interpreted in degrees. The default is 0.

wave_rangetuple or list, optional

If not None, he first two values in the tuple are interpreted as the minimum and maximum value of the wavelength range for the cutout. If it is None, the whole wavelength range is used. The default is None.

data_wcsastropy.wcs.WCS or None, optional

A WCS associated with the image data. The default is None..

report_callbackCallable or None, optional

A callable that will be executed every time the cutout of a single slice of the cube is computed. Must accept in input two arguments:

  • the number of slice processed so far

  • the total number of slices.

Returns

cutout_dict
A dictionary containing the following key: value pairs:
‘data’: np.ndarray

The cutout data.

‘wcs’: astropy.wcs.WCS or None

The wcs for the cutout data.

specex.cube.get_gray_cutout(data: ndarray, center: SkyCoord | tuple | list, size: tuple | list, angle: float | Quantity | None = 0, data_wcs: WCS | None = None) → Dict[str, WCS | ndarray][source]

Get the cutout for a grayscale image.

This is a basic wrapper around astropy.nddata.utils.Cutout2D

Parameters

datanp.ndarray

The actual image data. Should have only two dimensions (a grayscale image has only X and Y corrdinates).

centerastropy.coordinate.SkyCoord or tuple.

The center of the cutout. If a SkyCoord is provided then a WCS for the image data musto also be specified with the parameter data_wcs. If a tuple is provided, then the first two numbers of the tuple are interpreted as the X and Y coordinate of the cutout center: in this case, if no WCS is specified, the values are assumed to be in pixels, else if a WCS is provided then the values are assumed to be in degrees.

sizetuple or list

The first two values in the tuple are interpreted as the width and height of the cutout. if no WCS is specified, the values are assumed to be in pixels, else if a WCS is provided then the values are assumed to be in degrees. Astropy.units.Quantity values are also supported.

anglefloat or astropy.units.Quantity, optional

The rotation angle of the cutout. If it is a float, then it is interpreted in degrees. The default is 0.

data_wcsastropy.wcs.WCS or None, optional

A WCS associated with the image data. The default is None.

Returns

cutout_dict: dict
A dictionary containing the following key: value pairs:
‘data’: np.ndarray

The cutout data.

‘wcs’: astropy.wcs.WCS or None

The wcs for the cutout data.

specex.cube.get_hdu(hdl, valid_names, hdu_index=None, msg_err_notfound=None, msg_index_error=None, exit_on_errors=True)[source]

Find a valid HDU in a HDUList.

Parameters

hdllist of astropy.io.fits HDUs

A list of HDUs.

valid_nameslist or tuple of str

A list of possible names for the valid HDU.

hdu_indexint or str, optional

Manually specify which HDU to use. The default is None.

msg_err_notfoundstr or None, optional

Error message to be displayed if no valid HDU is found. The default is None.

msg_index_errorstr or None, optional

Error message to be displayed if the specified index is outside the HDU list boundaries. The default is None.

exit_on_errorsbool, optional

If it is set to True, then exit the main program with an error if a valid HDU is not found, otherwise just return None. The default value is True.

Returns

valid_hduastropy.io.fits HDU or None

The requested HDU.

specex.cube.get_rgb_cutout(data: tuple | list | ndarray, center: SkyCoord | tuple, size: tuple | list, angle: float | Quantity | None = 0, data_wcs: WCS | list | tuple | None = None, resample_to_wcs: bool = False) → Dict[str, Tuple[WCS, WCS, WCS] | Tuple[ndarray, ndarray, ndarray]][source]

Get a cutout from a bigger RGB.

Parameters

datanp.ndarray or tuple or list

The actual image data.

centerastropy.coordinate.SkyCoord or tuple.

The center of the cutout. If a SkyCoord is provided then a WCS for the image data musto also be specified with the parameter data_wcs. If a tuple is provided, then the first two numbers of the tuple are interpreted as the X and Y coordinate of the cutout center: in this case, if no WCS is specified, the values are assumed to be in pixels, else if a WCS is provided then the values are assumed to be in degrees.

sizetuple

The first two values in the tuple are interpreted as the width and height of the cutout. if no WCS is specified, the values are assumed to be in pixels, else if a WCS is provided then the values are assumed to be in degrees. Astropy.units.Quantity values are also supported.

anglefloat or astropy.units.Quantity, optional

The rotation angle of the cutout. If it is a float, then it is interpreted in degrees. The default is 0.

data_wcsastropy.wcs.WCS or None, optional

A WCS associated with the image data. The default is None.

resample_to_wcsbool, optional

If true reample the red, green and blue data to share the same WCS. In order to use this option, the WCSs for the input data must be provided, otherwise this option will be ignored and a warning message is outputed. The default is False.

Returns

cutout_dict: dict
A dictionary containing the following key: value pairs:
‘data’: np.ndarray

The cutout data.

‘wcs’: astropy.wcs.WCS or None

The wcs for the cutout data.

specex.cube.smooth_cube(data: ndarray, data_mask: ndarray | None = None, spatial_sigma: float | Quantity | None = 1.0, wave_sigma: float | Quantity | None = 0.0, cube_wcs: WCS | None = None, report_callback: Callable | None = None) → ndarray[source]

Smooth a datacube spatially and/or along the spectral axis.

Parameters

datanumpy.ndarray

The spectral datacube.

data_masknumpy.ndarray, optional

The mask for the spectral datacube. The default is None.

spatial_sigmafloat, optional

The sigma for the spatial smoothing gaussian kernel. The default is 1.0.

wave_sigmafloat, optional

The sigma fot the spectral smoothing gaussian kernel. The default is 0.0.

report_callbackCallable or None, optional

A callable that will be execute every time the cutout of a single slice of the cube is computed. Must accept in input two arguments:

  • the number of slice processed so far

  • the total number of slices.

Raises

ValueError

If the shape of data does not match the shape of data_mask.

Returns

smoothed_arrnumpy.ndarray

The smoothed version of the input data.

specex.cube.smoothing_main(options=None)[source]

Run the main cutout program.

Parameters

optionslist or None, optional

A list of cli input prameters. The default is None.

Returns

None.