easyspec.extraction package

class easyspec.extraction.extraction.extraction[source]

Bases: object

This class contains all the functions necessary to perform the spectral extraction from a cleaned/stacked image.

extinction_correction(spec_list, wavelengths_list, observatory, data_type, custom_observatory=None, spline_order=1, plots=True)[source]

This function removes the atmospheric extinction from the observed spectra.

Parameters:

  • spec_list (list) – List with the extracted spectra of all the targets in the image or only the brightest spectrum. This is one of the outputs from function extraction.extracting().

  • wavelengths_list (list) – List with the wavelength solutions for each given spectrum. This is the main result from function extraction.wavelength_calibration().

  • observatory (string) – This is the observatory where you collected yoru data. Options are “ctio”, “kpno”, “lapalma”, “mko”, “mtham”, “paranal”, “apo”.

  • data_type (string) – Options are “target” or “std_star”. We use this information to correctly select the airmass for the extinction correction.

  • custom_observatory (string) – Optional. Path to a txt file containing the airmass extinction curve. This file must have two columns, the first with the wavelengths in Angstroms and the second with the extinction in mag/airmass.

  • spline_order (integer) – The degree of the spline fit. Even values of spline_order should be avoided.

  • plots (boolean) – If True, easyspec will plot a comparison between the corrected and original spectrum, as well as the extinction interpolation curve.

Returns:

spec_atm_corrected_list – List with all the spectra corrected for atmospheric extinction.

Return type:

list

extracting(target_spec_data, fitted_polymodel_list, master_lamp_data=None, trace_half_width=7, shift_y_pixels=30, lamp_peak_height=None, peak_distance=None, diagnostic_plots=True, spec_plots=True)[source]

This function takes the traces as input to extract one or more spectra from the image with a Gaussian-weighted model.

In case you need references for the lamp peaks, here are some databases you can use (as of 12 September, 2024):
Parameters:

  • target_spec_data (numpy.ndarray (float)) – Matrix containing the target spectral image.

  • fitted_polymodel_list (string) – List with the fitted spine for one or more spectra in the target spectral image. This is the output of the function extraction.tracing().

  • master_lamp_data (string) – Optional. The path to the master lamp data file. This file can be produced with the easyspec cleaning() class.

  • trace_half_width (integer) – The half-width of the trace. The spectra will be extracted within a region 2*trace_half_width around their corresponding traces.

  • shift_y_pixels (integer) – Value used to shift the trace vertically by +-N pixels and repeat the extracting process to get the sky spectrum around each trace.

  • lamp_peak_height (float) – The height of the lamp peaks (in counts and with respect to zero) to be detected.

  • peak_distance (float) – The minimum distance between lamp peaks in pixels. Default is the length of the x-axis divided by 20.

  • diagnostic_plots (boolean) – If True, easyspec will plot the spectral images overlaid with the target’s spectral trace and corresponding sky traces.

  • spec_plots (boolean) – If True, easyspec will plot the extracted spectra for the target(s) and the lamp.

Returns:

  • spec_list (list) – List with the extracted spectra of all the targets in the image or only the brightest spectrum.

  • lamp_spec_list (list) – Optional. List with the extracted spectra of the lamp based on the traces of all spectra find in the image.

  • lamp_peak_positions_list (list) – Optional. List with the positions (in pixels) of all peaks in the lamp spectra with heights above the spectrum median. We have one list with peak positions for each trace given as an input in the variable fitted_polymodel_list. Notice that the peak positions are slightly different for different traces.

find_nearest(array, value)[source]

For a monotonically increasing/decreasing array, this function finds the index of the element nearest to the given value

Parameters:

  • array (numpy array (float)) – Monotonically increasing/decreasing array.

  • value (float) – Value to look for in the array.

Returns:

idx – The index corresponding to the closest element to the given value.

Return type:

int

import_data(target_spec_file, target_name, exposure_target=None, exposure_header_entry='AVEXP', airmass_target=None, airmass_header_entry='AVAIRMAS', std_star_spec_file=None, exposure_std_star=None, airmass_std_star=None, plot=True)[source]

This function opens the data file (i.e. fits image with one or more spectra) and reads the exposure time from its header. Optionally, the user can manually add the exposure time. If you want to calibrate your spectrum in flux, please also add the standard star spectral fits file and the reddening.

Parameters:

  • target_spec_file (string) – The path to the data ‘.fits’ or ‘.fit’ file containing the target spectrum.

  • target_name (string) – The name of the target to be used in subsequent plots.

  • exposure_target (float) – Optional. You can manually pass the exposure time (in seconds) of your observation. If ‘None’, easyspec will automatically look in the image header for the entry given by the variable ‘exposure_header_entry’.

  • exposure_header_entry (string) – Optional. If ‘exposure_target’ is not None, easyspec will automatically look into the image header for the exposure time corresponding to this entry. This entry will be used for the target and standard star images.

  • airmass_target (float) – Optional. You can manually pass the average airmass of your observation. If ‘None’, easyspec will automatically look in the image header for the entry given by the variable ‘airmass_header_entry’.

  • airmass_header_entry (string) – Optional. If ‘airmass_target’ is not None, easyspec will automatically look into the image header for the average airmass corresponding to this entry. This entry will be used for the target and standard star images.

  • std_star_spec_file (string) – Optional. The path to the data ‘.fits’ or ‘.fit’ file containing the standard star spectrum.

  • exposure_std_star (float) – Optional. You can manually pass the exposure time (in seconds) of your observation. If ‘None’, easyspec will automatically look in the image header for the entry given by the variable ‘exposure_header_entry’

  • airmass_std_star (float) – Optional. You can manually pass the average airmass of your standard star observation. If ‘None’, easyspec will automatically look in the image header for the entry given by the variable ‘airmass_header_entry’.

  • plot (boolean) – If True, easyspec will plot the input spectra.

Returns:

  • target_spec_data (numpy.ndarray (float)) – Matrix containing the target spectral image.

  • std_star_spec_data (numpy.ndarray (float)) – Matrix containing the standard star spectral image (only if the standard star spectral file is given by the user).

list_available_standards(std_star_dataset=None)[source]

This function lists the available datasets and their standard stars.

Parameters:

std_star_dataset (string) – If None, the function will plot all available datasets. Options are “ctiocal”, “irscal”, “bstdscal”, “spec16cal”, “spechayescal”, “iidscal”, “spec50cal”, “redcal”, “ctionewcal”, “ctio”, “oke1990”, “blackbody”.

Returns:

reference_dictionaty[dataset] – If a dataset is given, the function will return the reference for this dataset.

Return type:

string

std_star_normalization(spec_atm_corrected_std, wavelengths_std, std_star_dataset, std_star_archive_file, smooth_window=101, exclude_regions=None, smooth_window_archive=11, interpolation_order=1, plots=True)[source]

This function normalizes the measured standard spectrum by its exposure time (read in the function extraction.import_data()) and by its archival spectrum.

Parameters:

  • spec_atm_corrected_std (list) – This is the standard star spectrum after being corrected for atmospheric extinction.

  • wavelengths_std (list) – This is the wavelength solution for the standard star obtained with the function extraction.wavelength_calibration().

  • std_star_dataset (string) – This is the dataset where you can find your standard star.The options are “ctiocal”, “irscal”, “bstdscal”, “spec16cal”, “spechayescal”, “iidscal”, “spec50cal”, “redcal”, “ctionewcal”, “ctio”, “oke1990”, “blackbody”.

  • std_star_archive_file (string) – This is the name of the datafile of the archival standard star spectrum. You can find more by running the function extraction.list_available_standards(). In any case, it should be something like “l4364blue.dat”.

  • smooth_window (integer) – Must be an odd number. This is the number of neighbouring wavelength bins used to extract the standard star continuum with a median filter.

  • exclude_regions (list) – List of regions (in Angstroms) to be excluded from the measured standard star spectrum when extracting its continuum, e.g.: exclude_regions = [[4000,5000],[8000,8500]].

  • smooth_window_archive (integer) – Must be an odd number. Same as above but for the archival spectrum.

  • interpolation_order – The interpolation order for the spline.

  • plots (boolean) – If True, easyspec will plot several diagnostic plots showing the step-by-step of the flux calibration solution.

Returns:

correction_factor – This is an array in astropy units of erg/cm2/s/Angstrom containing the flux calibration solution for the standard star.

Return type:

array

target_flux_calibration(wavelengths_list, spec_atm_corrected_list, correction_factor, reddening=None, Rv=None, wavelength_cuts=None, output_directory='./', save_spec=True, plot=True)[source]

This function normalizes the target spectra for exposure time, corrects them by reddening (optional) and calibrate them using the correction_factor obtained with the standard star.

Parameters:

  • wavelengths_list (list) – List with the wavelength solutions for all target spectra.

  • spec_atm_corrected_list (list) – List with all the spectra corrected for atmospheric extinction.

  • correction_factor (array) – This is the array (in astropy units of erg/cm2/s/Angstrom) containing the flux calibration solution for the standard star. This is the main result from the function extraction.std_star_normalization().

  • reddening (float) – Optional. The E(B-V) reddening in magnitudes. This is the Galactic redening in the direction of your observation. You can look for the appropriate reddening for your target here: ‘https://irsa.ipac.caltech.edu/applications/DUST/’.

  • Rv (float) – visual extinction to reddening ratio. Default is 3.1, but depending on the case, even a value up to 5 can be used. You can check what is a reasonable value for your target here: ‘https://irsa.ipac.caltech.edu/applications/DUST/’.

  • wavelength_cuts (list) – List with two wavelength values. The spectrum within this wavelength range will survive the analysis. The rest will be removed. Example: wavelength_cuts = [3500,7500]. Assuming the units in Angstroms.

  • output_directory (string) – A string with the path to the output directory.

  • save_spec (boolean) – If True, the spectra will be saved in the output directory as “spec_0.dat”, “spec_1.dat” and so on.

  • plots (boolean) – If True, easyspec will plot several diagnostic plots showing the step-by-step of the flux calibration solution.

Returns:

calibrated_flux_list – This is a list with the spectra calibrated in flux density.

Return type:

list

tracing(target_spec_data, method='argmax', y_pixel_range=15, xlims=None, poly_order=2, trace_half_width=7, peak_height=100, distance=50, Number_of_slices=20, peak_dispersion_limit=3, main_plot=True, plot_residuals=True)[source]

This function detects all the spectra available in an image and fits a polynomial to recover the trace of each one of them. It can be used to recover the spectral spine (or trace) of one or several spectra in the same image.

Parameters:

  • target_spec_data (numpy.ndarray (float)) – Matrix containing the target spectral image.

  • method (string) – The method to be adopted in finding the trace. Options are “argmax” or “moments” if you want to extract only the strongest spectrum in the image, or “multi” if you want to extract more than one spectrum. The option “argmax” works very well although is limited by the pixel size. The option “moments” is suited only for spectra with a very high signal-to-noise ratio. The option “multi” will use the “argmax” method to look for several spectra in a single image.

  • y_pixel_range (integer) – Y-axis range of pixels to be used to extract a specific spectrum. The total y-axis interval adopted is 2*y_pixel_range.

  • xlims (list or array) – A list/array with the two limits in the x-axis delimiting the region where we will look for the spectra. E.g. if your image x-axis has 2000 pixels but your spectrum goes from pixels ~700 up to pixel ~1800, you can set xlims = [700,1800] to avoid fitting regions of pure noise. This variable is useful only for the “argmax” or “moments” methods.

  • poly_order (integer) – The order of the polynomial(s) used to fit the trace.

  • trace_half_width (integer) – The half-width of the trace. Here it is useful for estimating the background and plotting the data.

  • peak_height (float) – The required height of the peaks. The smaller this value, the more spectra you will find in your image.

  • distance (float) – Required minimal distance (>= 1) in pixels between neighbouring peaks in the y-axis. Default is 20 pixels. If you set this value too high with respect to the y-axis resolultion of your image, this function will return undesired results.

  • Number_of_slices (integer) – Useful only for the “multi” mode. This is the number of slices in which every spectra in the image is divided in the x-axis. It is used to set the best x-axis interval at which easyspec will fit the trace.

  • peak_dispersion_limit (float) – Useful only for the “multi” mode. This parameter sets the dispersion limit (with respect to the trace slice of minimum dispersion) of a trace slice such that we can use this slice to fit the trace, i.e. if the trace dispersion in a slice is larger than peak_dispersion_limit*minimum_dispersion, this slice will be ignored in the fit, where the term ‘minimum_dispersion’ stands for the dispersion in the slice with minimum trace dispersion.

  • main_plot (boolean) – If True, easyspec will plot all the traces over all the spectra (or the main spectra) in the image.

  • plot_residuals (boolean) – If True, easyspec will plot the residuals for each trace fitted to the data.

Returns:

fitted_polymodel_list – List with the fitted spine for all spectra in the image or only the brighter spectrum.

Return type:

list

wavelength_calibration(lamp_peak_positions_list, corresponding_wavelengths, poly_order=2, diagnostic_plots=True)[source]

This function takes the list of lamp spectral peak positions (in pixels) and their corresponding wavelengths, and returns a list with the calibrated x-axis for one or more spectra.

In case you need references for the lamp peaks, here are some databases you can use (as of 12 September, 2024):
Parameters:

  • lamp_peak_positions_list (list) – This is one of the outputs from function extraction.extracting(). It contains the positions (in pixels) of all peaks in the lamp spectra with heights above the spectrum median.

  • corresponding_wavelengths (list) – List with wavelengths (in Angstroms) corresponding to each peak given in lamp_peak_positions_list. Even if the peak positions are slightly different for different traces, a single list with the corresponding wavelengths will do the job here.

  • poly_order (integer) – The order of the polynomial used to find the wavelength solution.

  • diagnostic_plots (boolean) – If True, easyspec will plot the wavelength solution and fit residuals.

Returns:

  • wavelengths_list (list) – List with the wavelength solutions for each given spectrum.

  • wavelengths_fit_std_list (list) – The standard deviation of the data points with respect to the wavelength solution for each given spectrum.