Cube Object DocString

Cube class, for manipulating JWST spectro-imaging data.

This class is used to create and manage Cube objects. JWST spectro-imaging data consists of a series of images, each associated with a specific wavelength. The array of values is then in the form of a 3D list. The first dimension is a spectral dimension, defaulting to micron wavelengths. The wavelength range is specific to the instrument’s grism and/or filter. The other two dimensions are spatial dimensions, forming images.

The Cube object has two headers containing all data information. The structure and information of the headers are identical to those of the files output by the reduction pipeline. The first header is called ‘primary’ and contains all general information about the observations (PI, instrument, date, time and duration of observations, configuration, etc.). The second header provides more information about the data, such as 3D array size, 3-axis sampling and units. A summary of the information can be displayed using the .info() method.

The values (in surface brightness if units are the default) of the 3D array are stored in the .data attribute. The uncertainties at each pixel of the cube are also stored in an .errs attribute, an array of the same size as the data.

When creating a Cube object, you must provide the file name in .fits format.

param file_name:

The name of the file in .fits format. For JWST spectro-imaging data, the default name contains the suffix “_s3d”.

type file_name:

str

JWSToolKit.Cube.primary_header

The FITS primary header, using astropy.io tools.

Type:

‘astropy.io.fits.Header’

JWSToolKit.Cube.data_header

The FITS header associated with the data, using astropy.io tools.

Type:

‘astropy.io.fits.Header’

JWSToolKit.Cube.data

Data stored as a cube (3D array). The first dimension is the spectral dimension, the other two dimensions are the spatial dimensions.

Type:

array_like

JWSToolKit.Cube.errs

Uncertainties associated with ‘science’ data stored in the .data attribute.

Type:

array_like

JWSToolKit.Cube.size

The number of points in each dimension. The first value gives the number of spectral pixels, the second the number of x-axis pixels and the third the number of y-axis pixels.

Type:

array_like

JWSToolKit.Cube.px_area

Area of a spatial pixel in images. The value is given in steradian.

Type:

float

JWSToolKit.Cube.units

The unit of values stored in the .data table. Default values are surface brightness in MJy/sr.

Type:

str

class JWSToolKit.Cube.Cube(file_name: str)[source]

Bases: object

extract_spec_circ_aperture(radius: int, position: list[int], err=False, units: str = 'Jy')[source]

Extracts a summed spectrum in a circular aperture

Parameters:

  • radius (int) – Radius in pixel of the integration aperture

  • position (list) – Position in pixels of the aperture center. It must contains two values: the horizontale and verticale coordinates respectively.

  • err (bool, optional) – If True, return the errors of each spectral flux value.

  • units (str, optional) – The character string specifies the units of the output spectrum.

Returns:

If err is False, the routine returns flux values of the summed spectrum If err is True, the routine returns 2 sub-lists. The first containing flux values of the summed spectrum and the second containing erros associated with flux values.

Return type:

array_like

classmethod from_file_extension(primary_header, data_header, data, errs=None)[source]

Builds a ‘Cube’ object from file headers and data.

Parameters:

  • primary_header (astropy.io.fits.header.Header) – The JWST data cube primary header, extract with astropy.io.

  • data_header (astropy.io.fits.header.Header) – The science header for JWST data cubes, extract with astropy.io.

  • data (array_like) – Science data from the cube, stored in a 3D array.

  • errs (array_like, optional) – Error data associated with the data array, stored in a 3D array

Returns:

A Cube object.

Return type:

Cube object

get_px_coords(coords: list)[source]

Returns the coordinates in pixels (x,y) of one or more pixel positions in the data cube.

Parameters:

coords (list) – Coordinates in degrees (R.A., Dec.) to be converted into pixel coordinates. It can contain two elements (corresponding to the position of a single point) or two sub-lists containing the R.A. and Dec. positions of several points respectively.

Returns:

If the coordinates of a single point have been given, the list contains two elements being the (x,y) coordinates converted into pixel coordinates. If the coordinates are those of several points, the list contains two sub-lists containing respectively the x and y positions of the different points.

Return type:

array_like

get_world_coords(coords: list)[source]

Returns the coordinates in degrees (R.A., Dec.) of one or more pixel positions in the data cube.

Parameters:

coords (list) – Coordinates in pixels to be converted into degrees. It can contain two elements (corresponding to the position of a single point) or two sub-lists containing the horizontal and vertical positions of several points respectively.

Returns:

If the coordinates of a single point have been given, the list contains two elements being the R.A., Dec. coordinates converted into degrees. If the coordinates are those of several points, the list contains two sub-lists containing respectively the R.A., Dec. positions of the different points.

Return type:

array_like

get_wvs(units: str = 'um')[source]

Returns the wavelength grid of the data cube

Parameters:

units (str, optional) – The character string specifying the units of the wavelengths.

Returns:

The wavelength grid

Return type:

array_like

info()[source]

Prints information stored in headers associated with the data cube.

line_emission_map(wv_line: float, continuum_range: float = 2000.0, line_width: float = 400.0, continuum_degree: int = 1, map_units: str = 'MJy um sr-1', control_plot: bool = False)[source]

Builds the integrated emission map of a line at a given wavelength

Parameters:

  • wv_line (float) – Wavelength in vacuum and at rest of the emission line, given in the same unit as the x-axis of the spectra.

  • continuum_range (float, optional) – Spectral half-interval used to adjust the spectrum continuum, given in km/s. The interval is centered on the wavelength of the line.

  • line_width (float, optional) – Spectral width of the emission line, given in km/s.

  • continuum_degree (int, optional) – Polynomial order used to fit the continuum around the line.

  • map_units (str, optional) – Map pixel units.

  • control_plot (bool, optional) – If True, show the integrated emission map.

Returns:

The integrated emission map, with the same dimensions as the spatial dimensions of the initial data cube.

Return type:

array_like

pv_diagram(wv_line: float, slit_position: list, slit_params: list[int], baseline_width: float = 1500.0, line_width: float = 200.0, range_diagram: float = 500, control_plot=False)[source]

Generate a position-velocity diagram from the data cube for an emission line.

Parameters:

  • wv_line (float) – Wavelength in vacuum and at rest of the emission line, given in µm.

  • slit_position (array_like) – Central spatial position of the slit in the data cube. The first element of the list is the x position and the second the y position. Values must be given in pixels.

  • slit_params (array_like) – The first element of the list corresponds to the width of the slit and the second element to the height. Values must be given in pixels.

  • baseline_width (float, optional) – Interval in which spectra baseline fitting is performed. The value must be given in km/s.

  • line_width (float, optional) – Spectral width of the emission line. The value must be given in km/s. This interval is used to exclude the spectral pixels of the line in the baseline fit.

  • range_diagram (float, optional) – Half-interval of radial velocities in the PV diagram (i.e. half the size of the diagram’s y-axis). The value must be given in km/s.

  • control_plot (float, optional) – If True, show control map at the wavelength of the line and PV diagram.

Returns:

The PV diagram in array_like form. The x-axis corresponds to the x-dimension of the data cube and the y-axis to radial velocities.

Return type:

array_like

rotate(angle: float, control_plot: bool = False)[source]

Rotates the data cube by modifying the WCS of the file headers.

Parameters:

  • angle (float) – Angle of rotation to be applied to data. The angle follows the counter-clockwise convention.

  • control_plot (float, optional) – If True, show a channel map before and after rotation.

Returns:

Data cube rotated, with headers updated.

Return type:

Cube object