Extraction of the Spectra

Welcome to the documentation for the ‘extract_spec.py’ module, which contains the functions for extracting the spectra from the WiFeS data in each arm.

pywifes.extract_spec.aperture_extract(sci_cube, var_cube, source_ap, sky_ap=None, dq_cube=None, tell_data=None, sky_stat='wmean')

Extract and calculate spectral flux and variance within the given aperture.

Parameters:

  • sci_cube (array_like) – 3D array representing the scientific data cube.

  • var_cube (array_like) – 3D array representing the variance data cube.

  • source_ap (photutils.aperture object) – Aperture object representing the source region to be extracted.

  • sky_ap (photutils.aperture object, optional) – Aperture object representing the sky region to be extracted. Default is None.

  • dq_cube (array_like, optional) – 3D array representing the data quality cube. Default: None.

  • tell_data (array_like, optional) – 1D or 2D array with the applied telluric model. Default: None.

  • sky_stat (str, optional) – Statistical method for calculating sky spectrum. Options: “wmean”, “median”. Default: “wmean”.

Returns:

  • flux (numpy.ndarray) – 1D array containing the spectral flux values.

  • variance (numpy.ndarray) – 1D array containing the spectral variance values.

  • dq (numpy.ndarray) – 1D array containing the data quality values.

  • sky (numpy.ndarray) – 1D array containing the sky spectrum that was subtracted, or None if no sky extracted (e.g., Nod & Shuffle).

  • tell (numpy.ndarray) – 1D array containing the median telluric model applied to the spectrum, or None if not available in the datacube.

Notes

This function extracts spectral flux and variance values within the specified source aperture from the input data cubes. If a sky aperture is provided, it calculates and subtracts the corresponding sky values. If a data quality cube is provided, it also extracts the corresponding spectrum. If a telluric model is provided, it also extracts the median telluric spectrum applicable to the extraction region.

pywifes.extract_spec.collapse_cube(*data_cubes)

Collapse one or more data cubes by computing the median along the wavelength dimension.

Parameters:

*data_cubes (array_like) – Variable-length argument list of data cubes to be collapsed. Each data cube should have the same spatial shape.

Returns:

median_image – 2D array representing the median-collapsed image along the wavelength dimension.

Return type:

numpy.ndarray

Notes

This function takes one or more data cubes and collapses them by computing the median along the wavelength dimension. The resulting 2D array represents the median image.

pywifes.extract_spec.detect_extract_and_save(blue_cube_path=None, red_cube_path=None, output_dir=None, ns=False, subns=False, plot_path='detected_sources_plot.png', nsources=3, sigma_threshold=3, det_fwhm=2.0, extraction_method='aperture', r_arcsec=2, sky_method='annulus', sky_stat='wmean', bkg_in_factor=3, bkg_out_factor=4, border_width=2, ns_skysub=True, plot=True, get_dq=True, get_tell=True, get_extinct=True, debug=False)

Detects sources in the input cubes, extracts and saves their spectra. Optionally, it can plot the extracted sources and the sky regions around them.

Parameters:

blue_cube_pathstr, optional

Path to the blue cube file.

red_cube_pathstr, optional

Path to the red cube file.

output_dirstr, optional

Directory where the extracted spectra will be saved.

nsbool, optional

Flag indicating whether this is a nod & shuffle exposure. Default: False.

subnsbool, optional

Flag indicating whether this is a sub-aperture nod & shuffle exposure. Default: False.

plot_pathstr, optional

Path to save the plot. Default: “detected_sources_plot.png”.

Detection Parameters:

nsourcesint, optional

Number of sources above the threshold that will be found and extracted (in descending brightness). Default: 3.

sigma_thresholdfloat, optional

Number of sigma-clipped standard deviations above the median of the collapsed cube to use for source-finding. Default: 3.

border_widthint, optional

Width of the border to be excluded from the statistics and source-finding. Default: 2.

det_fwhmfloat, optional

Full-width at half maximum (in arcsec) of the Gaussian convolution kernal used for source-finding. Default: 2.0.

Extraction Parameters:

extraction_methodstr, optional

Method to extract source spectra from datacubes. Options: “aperture”. Default: “aperture”.

r_arcsecfloat, optional

Radius of the circular extraction aperture in arcseconds. Default: 2.

sky_methodstr, optional

Method to determine sky background. Options: “annulus”, “same_slice”. Default: “annulus”.

sky_statstr, optional

Statistical method for calculating sky spectrum. Options: “wmean”, “median”. Default: “wmean”.

bkg_in_factorfloat, optional

Inner radius of background annulus: bkg_in_factor * r_arcsec. Default: 3.

bkg_out_factorfloat, optional

Outer radius of background annulus: bkg_out_factor * r_arcsec. Default: 4.

ns_skysubbool, optional

Flag indicating whether to force sky subtraction even if a nod & shuffle of sub-frame nod & shuffle exposure. Default: True.

get_dqbool, optional

Whether to include the DQ extension in the output. Default: True.

get_tellbool, optional

Whether to include the telluric model extension in the output. Default: True.

get_extinctbool, optional

Whether to include the corrected extinction extension in the output. Default: True.

General Parameters:

plotbool, optional

Flag indicating whether to generate a plot of the detected sources. Default: True.

debugbool, optional

Whether to report the parameters used in this function call. Default: False.

Returns:

None

pywifes.extract_spec.plot_1D_spectrum(spec_path, plot_dir)

Plot a 1D spectrum with error bars and save the plot as a PNG file in the provided directory.

Parameters:

  • spec_path (str) – The path to the spectrum file.

  • plot_dir (str) – The directory where the plot will be saved.

Returns:

This function does not return anything.

Return type:

None

pywifes.extract_spec.plot_regions(data_cube, source_regions, sky_regions=None, border_width=0, bin_y=1)

Plot regions on a collapsed data cube image.

Parameters:

  • data_cube (numpy.ndarray) – The 3D data cube containing the image data.

  • source_regions (list of photutils.aperture objects) – List of source regions to plot on the image.

  • sky_regions (list of photutils.aperture objects, optional) – List of sky regions to plot on the image. Default is None.

  • border_width (int, optional) – Width of the border to exclude from the image when calculating the image contrast. Default is 0.

  • bin_y (int, optional) – Binning of y-axis, to preserve real on-sky shape. Default is 1.

Returns:

This function does not return any value. It plots the regions on the image.

Return type:

None

pywifes.extract_spec.sec_image(ap, image)

Extract pixel values from a section within the aperture.

Parameters:

  • aperture (photutils.aperture object) – Aperture object representing the region of interest.

  • image (array_like) – 2D or 3D array representing the image data.

Returns:

sec_data – 1D or 2D array containing the weighted pixel values from the section within the aperture.

Return type:

numpy.ndarray

Notes

This function extracts pixel values from a section within the specified aperture from the input image. The extraction is performed using a aperture mask, where pixel values outside the aperture are zero. The resulting 1D or 2D array contains the pixel values from the section within the aperture.

pywifes.extract_spec.write_1D_spec(sci_data, var_data, sci_cube_header, var_cube_header, output, dq_data=None, dq_cube_header=None, sky_data=None, wave_data=None, tell_data=None, kwlist=None, ext_data=None, ext_hdr=None)

This function writes the 1D spectrum data and its variance to a FITS file. It updates the WCS headers to match the 1D spectrum header.

Parameters:

  • sci_data (numpy.ndarray) – 1D array containing the science data (flux) of the spectrum.

  • var_data (numpy.ndarray) – 1D array containing the variance data of the spectrum.

  • sci_cube_header (astropy.io.fits.Header) – Header from the science cube.

  • var_cube_header (astropy.io.fits.Header) – Header object from the variance data.

  • output (str) – Output file path for the FITS file containing the 1D spectrum.

  • dq_data (numpy.ndarray, optional) – 1D array containing the data quality data of the spectrum. Optional.

  • dq_cube_header (astropy.io.fits.Header, optional) – Header object from the data quality extension.

  • sky_data (numpy.ndarray, optional) – 1D array containing the subtracted sky spectrum, or None.

  • wave_data (numpy.ndarray, optional) – 1D array containing wavelength value per pixel, or None.

  • tell_data (numpy.ndarray, optional) – 1D or 2D array containing the applied telluric model, or None.

  • kwlist (list of lists, optional) – List of header [keyword, list, commment] entries to write to output file.

  • ext_data (numpy.ndarray, optional) – 1D array containing the corrected extinction that was applied, or None.

  • ext_hdr (astropy.io.fits.Header, optional) – Header object from corrected extinction extension, or None.

Return type:

None