Data Calibration

Welcome to the documentation for the ‘wifes_calib.py’ module of PyWiFeS. This module contains functions to calibrate WiFeS data, including the extraction of standard stars, calibration of the data cubes, and telluric correction.

pywifes.wifes_calib.apply_wifes_telluric(inimg, outimg, tellcorr_fn, airmass=None, shift_sky=True, sky_wmin=7200.0, sky_wmax=8100.0, save_telluric=False, interactive_plot=False)

Apply telluric correction to the input image. The telluric correction is applied using the telluric correction file previously obtained in ‘derive_wifes_telluric()’. The correction is based on the airmass value and the wavelength-dependent correction factors. The corrected image is saved to the specified output file.

Parameters:

  • inimg (str) – Path to the input image file.

  • outimg (str) – Path to save the output image file.

  • tellcorr_fn (str) – Path to the telluric correction file.

  • airmass (float, optional) – Airmass value for the correction. If not provided, it will be extracted from the input image header. Default: None.

  • shift_sky (bool, optional) – Whether to shift the telluric to better align the sky lines between telluric and object. Default: True.

  • sky_wmin (float, optional) – Minimum wavelength to fit if shifting based on sky lines. Default: 7200.0.

  • sky_wmax (float, optional) – Maximum wavelength to fit if shifting based on sky lines. Default: 8100.0.

  • save_telluric (bool, optional) – Whether to save the applied telluric model in the datacube. Default: False.

  • interactive_plot (bool, optional) – Whether to interrupt processing to provide interactive plot to user. Default: False.

Return type:

None

Raises:

None –

pywifes.wifes_calib.calibrate_wifes_cube(inimg, outimg, calib_fn, mode='pywifes', extinction_fn=None, save_extinction=False)

Calibrates the WiFeS cube by applying flux calibration and extinction correction. The calibration is performed using the provided calibration file containing the flux calibration information. The extinction curve is retrieved based on the provided extinction file path. The calibrated WiFeS cube is saved to the specified output file path.

Parameters:

  • inimg (str) – Input FITS file path of the WiFeS cube.

  • outimg (str) – Output FITS file path for the calibrated WiFeS cube.

  • calib_fn (str) – Calibration file path containing the flux calibration information.

  • mode (str, optional) – Calibration mode. Options: ‘pywifes’, ‘iraf’. Default: ‘pywifes’.

  • extinction_fn (str, optional) – Extinction file path containing the extinction curve information. If None, defaults to standard SSO extinction curve. Default: None.

  • save_extinction (bool, optional) – Whether to save the extinction model that was applied to translate the flux calibration to airmass zero. Default: False.

Return type:

None

Raises:

ValueError – If the calibration mode is not defined.

Notes

This function performs the following steps:

  1. Determines the wavelength array based on the input WiFeS cube.

  2. Retrieves the extinction curve based on the provided extinction file path.

  3. Opens the input WiFeS cube file.

  4. Calculates the flux calibration array based on the calibration mode.

  5. Calculates the extinction curve for the observed airmass.

  6. Applies the flux calibration and extinction correction to the data.

  7. Saves the calibrated WiFeS cube to the output file path.

The function assumes that the input WiFeS cube file follows the FITS format and contains the necessary header keywords for wavelength, exposure time, and airmass.

Examples

>>> calibrate_wifes_cube('input.fits', 'output.fits', 'calibration.dat', mode='pywifes')
pywifes.wifes_calib.derive_wifes_calibration(cube_fn_list, calib_out_fn, stdstar_name_list=None, extract_in_list=None, airmass_list=None, ref_dir='/home/docs/checkouts/readthedocs.org/user_builds/pywifes-pipeline/checkouts/stable/reference_data', ref_fname_list=None, plot_stars=False, plot_sensf=False, plot_dir='.', plot_name='flux_calibration_solution.png', norm_stars=False, method='poly', polydeg=30, excise_cut=0.5, wave_min=None, wave_max=None, extinction_fn=None, ytrim=5, boxcar=11, prefactor=False, prefactor_fn=None, interactive_plot=False, debug=False)

Derives the flux calibration solution for WiFeS data. The calibration solution is derived by comparing the observed standard star spectra to reference data. The calibration solution is then used to correct the observed spectra for instrumental effects.

Parameters:

  • cube_fn_list (list) – List of file paths to the WiFeS data cubes.

  • calib_out_fn (str) – File path to save the calibration output.

  • stdstar_name_list (list, optional) – List of standard star names corresponding to each cube.

  • extract_in_list (list, optional) – List of file paths to the extracted spectra.

  • airmass_list (list, optional) – List of airmass values corresponding to each cube.

  • ref_dir (str, optional) – Directory path to the reference data.

  • ref_fname_list (list, optional) – List of file names of the reference data corresponding to each cube.

  • plot_stars (bool, optional) – Whether to plot the stars during the calibration process.

  • plot_sensf (bool, optional) – Whether to plot the sensitivity function.

  • plot_dir (str, optional) – Directory path to save the plots.

  • plot_name (str, optional) – Filename for the output sensitivity plot.

  • norm_stars (bool, optional) – Whether to normalize the stars.

  • method (str, optional) – Method for fitting the calibration solution.

  • polydeg (int, optional) – Degree of the polynomial for fitting the calibration solution.

  • excise_cut (float, optional) – Cut-off value for excising outliers.

  • wave_min (float, optional) – Minimum wavelength for the calibration solution.

  • wave_max (float, optional) – Maximum wavelength for the calibration solution.

  • extinction_fn (str, optional) – File path to the extinction curve data.

  • ytrim (int, optional) – Number of pixels to trim from the edges of the extracted spectra.

  • boxcar (int, optional) – Size of the boxcar filter for smoothing the sensitivity function.

  • prefactor (bool, optional) – Whether to remove the flatfield shape to ease fitting of sensitivity curve. Default: False.

  • prefactor_fn (str, optional) – Filename of the smooth fit to the flatfield shape (generated in flat_response). Default: None.

  • interactive_plot (bool, optional) – Whether to interrupt processing to provide interactive plot to user. Default: False.

  • debug (bool, optional) – Whether to report the parameters used in this function call. Default: False.

Raises:

Exception – If calibration data for any stars cannot be found.

Return type:

None

pywifes.wifes_calib.derive_wifes_telluric(cube_fn_list, out_fn, plot=True, plot_dir=None, save_prefix='telluric', extract_in_list=None, airmass_list=None, telluric_threshold=0.97, fit_wmin=5500.0, fit_wmax=10000.0, H2O_power=0.72, O2_power=0.4, polydeg=4, ytrim=4, interactive_plot=False, debug=False)

Derives the telluric correction spectra for a list of cube files. The telluric correction spectra are derived by comparing the observed spectra to the telluric regions in the standard star data. The telluric correction spectra are saved to the specified output file.

Parameters:

  • cube_fn_list (list) – List of cube file names.

  • out_fn (str) – Output file name to save the telluric correction information.

  • plot (bool, optional) – Flag indicating whether to generate and save a plot of the telluric correction function.

  • plot_dir (str, optional) – Directory to save the plot file. Default: None.

  • save_prefix (str, optional) – Prefix for the saved plot file. Default: ‘telluric’.

  • extract_in_list (list, optional) – List of extracted spectrum file names. Default: None.

  • airmass_list (list, optional) – List of airmass values for each cube file. If not provided, the airmass values will be extracted from the cube headers. Default: None.

  • telluric_threshold (float, optional) – Threshold value for the telluric correction. Regions with a correction ratio above this threshold will be set to 1.0. Default: 0.97.

  • fit_wmin (float, optional) – Minimum wavelength for fitting the smooth polynomial to non-telluric regions. Default: 5400.0.

  • fit_wmax (float, optional) – Maximum wavelength for fitting the smooth polynomial to non-telluric regions. Default: 10000.0.

  • H2O_power (float, optional) – Power value for the H2O correction. Default: 0.72.

  • O2_power (float, optional) – Power value for the O2 correction. Default: 0.40.

  • polydeg (int, optional) – Degree of the polynomial used for fitting the smooth continuum. Default: 4.

  • ytrim (int, optional) – Number of (unbinned) pixels to trim from the top and bottom of the data cube if standard star spectrum has not been extracted previously. Default: 4.

  • interactive_plot (bool, optional) – Whether to interrupt processing to provide interactive plot to user. Default: False.

  • debug (bool, optional) – Whether to report the parameters used in this function call. Default: False.

Return type:

None

pywifes.wifes_calib.extract_wifes_stdstar(cube_fn, x_ctr=None, y_ctr=None, extract_radius=5.0, sky_radius=8.0, xtrim=2, ytrim=4, wmask=500, save_mode=None, save_fn=None, debug=False, interactive_plot=False)

Extracts the standard star spectrum from a WiFeS data cube. The standard star spectrum is extracted by performing apperture photometry for each frame along the wavelenght axis within a circular aperture centered on the standard star centroid. The sky background is estimated by taking the median flux within an annulus centered on the standard star centroid.

Parameters:

  • cube_fn (str) – The filename of the WiFeS data cube.

  • x_ctr (float, optional) – The x-coordinate of the standard star centroid. If not provided, the centroid will be determined automatically. Default: None.

  • y_ctr (float, optional) – The y-coordinate of the standard star centroid. If not provided, the centroid will be determined automatically. Default: None.

  • extract_radius (float, optional) – The radius (in arcseconds) within which to extract the standard star spectrum. Default: 5.0.

  • sky_radius (float, optional) – The radius (in arcseconds) outside which to estimate the sky background. Default: 8.0.

  • xtrim (int, optional) – The number of pixels to trim from the left and right of the data cube in the x spatial direction. Default: 2.

  • ytrim (int, optional) – The number of (unbinned) pixels to trim from the top and bottom of the data cube in the y spatial direction. Default: 4.

  • wmask (int, optional) – The number of (unbinned) wavelength pixels to mask from each end when peak-finding. Default: 500.

  • save_mode (str, optional) – The mode for saving the extracted spectrum. Options: ‘ascii’, ‘iraf’, None (returns (wave, flux) to the calling function). Default: None.

  • save_fn (str, optional) – The filename to save the extracted spectrum if ‘save_mode’ is ‘ascii’ or ‘iraf’. Default: None.

  • debug (bool, optional) – Whether to report the parameters used in this function call. Default: False.

  • interactive_plot (bool, optional) – Whether to interrupt processing to provide interactive plot to user. Default: False.

Returns:

  • If ‘save_mode’ = ‘save_fn’ = None –

    filtered_lam_arraynumpy.ndarray

    The wavelength array of the extracted spectrum.

    filtered_std_fluxnumpy.ndarray

    The flux values of the extracted spectrum.

    filtered_sky_fluxnumpy.ndarray

    The sky values subtracted from the flux.

  • Else – None

Raises:

ValueError – If the save_mode is not recognized.

pywifes.wifes_calib.find_nearest_stdstar(inimg, data_hdu=0, stdtype='flux')

Find the standard star of the specified type that is closest on the sky to the input image.

stdtypestr, optional

Type of standard to find: “flux”, “telluric”, or “any”. Default: “flux”.

Returns:

  • list –

    • List of observations of the closest standard star

  • float –

    • Angular offset of the closest standard star

  • str –

    • Calibration type(s) of the closest standard star

pywifes.wifes_calib.savitzky_golay(y, window_size, order, deriv=0, rate=1)

Smooth (and optionally differentiate) data with a Savitzky-Golay filter. The Savitzky-Golay filter removes high frequency noise from data. It has the advantage of preserving the original shape and features of the signal better than other types of filtering approaches, such as moving averages techniques.

Parameters:

  • y (array_like, shape (N,)) – the values of the time history of the signal.

  • window_size (int) – the length of the window. Must be an odd integer number.

  • order (int) – the order of the polynomial used in the filtering. Must be less then window_size - 1.

  • deriv (int) – the order of the derivative to compute (default = 0 means only smoothing)

Returns:

ys – the smoothed signal (or it’s n-th derivative).

Return type:

ndarray, shape (N)

Notes

The Savitzky-Golay is a type of low-pass filter, particularly suited for smoothing noisy data. The main idea behind this approach is to make for each point a least-square fit with a polynomial of high order over a odd-sized window centered at the point.

Examples

t = np.linspace(-4, 4, 500)

y = np.exp( -t**2 ) + np.random.normal(0, 0.05, t.shape)

ysg = savitzky_golay(y, window_size=31, order=4)

import matplotlib.pyplot as plt

plt.plot(t, y, label=’Noisy signal’)

plt.plot(t, np.exp(-t**2), ‘k’, lw=1.5, label=’Original signal’)

plt.plot(t, ysg, ‘r’, label=’Filtered signal’)

plt.legend()

plt.show()

References

  1. A. Savitzky, M. J. E. Golay, Smoothing and Differentiation of Data by Simplified Least Squares Procedures. Analytical Chemistry, 1964, 36 (8), pp 1627-1639.

  2. Numerical Recipes 3rd Edition: The Art of Scientific Computing W.H. Press, S.A. Teukolsky, W.T. Vetterling, B.P. Flannery Cambridge University Press ISBN-13: 9780521880688