pypeit.core.extract module

Module for PypeIt extraction code

pypeit.core.extract.extract_asym_boxcar(sciimg, left_trace, righ_trace, gpm=None, ivar=None)[source]

Perform asymmetric boxcar extraction of the flux between two traces.

Parameters:

sciimg (numpy.ndarray) – Floating-point science image with shape \((N_{\rm spec}, N_{\rm spat})\). The first dimension (\(N_{\rm spec}\)) is spectral, and second dimension (\(N_{\rm spat}\)) is spatial.
left_trace (numpy.ndarray) – Left and right trace boundaries of the extraction region for each aperture. They are 2-d floating-point arrays with shape \((N_{\rm spec}, N_{\rm apertures})\).
right_trace (numpy.ndarray) – Left and right trace boundaries of the extraction region for each aperture. They are 2-d floating-point arrays with shape \((N_{\rm spec}, N_{\rm apertures})\).
gpm (numpy.ndarray, optional) – Boolean image representing the good-pixel mask for the science image. The pixels that have value of True are good to be used. Must have the same shape as sciimg, \((N_{\rm spec}, N_{\rm spat})\).
ivar (numpy.ndarray, optional) – Floating-point inverse variance image for the science image. It can be a model image, or deduced from sciimg. Shape must match sciimg, \((N_{\rm spec}, N_{\rm spat})\). If not None, the inverse variance of the boxcar extracted flux will be returned.

Returns:

flux_out (numpy.ndarray) – 2-d floating-point array containing, for each aperture, the boxcar extracted flux as a function of spectral position. Shape is \((N_{\rm spec}, N_{\rm apertures})\).
gpm_box (numpy.ndarray) – 2-d Boolean-point array representing, for each aperture, the good-pixel mask for the boxcar extracted flux. The pixels that have value of True are good to be used. Shape is \((N_{\rm spec}, N_{\rm apertures})\).
box_npix (numpy.ndarray) – 2-d floating-point array containing, for each aperture, the number of pixels in each spectral position that contributed to the boxcar sum of the flux. Shape is \((N_{\rm spec}, N_{\rm apertures})\).
ivar_out (numpy.ndarray) – 2-d floating-point array containing, for each aperture, the inverse variance of the boxcar extracted flux as a function of spectral position. Shape is \((N_{\rm spec}, N_{\rm apertures})\). This is only be returned if the input parameter ivar is not None.

pypeit.core.extract.extract_boxcar(sciimg, ivar, mask, waveimg, skyimg, spec, fwhmimg=None, base_var=None, count_scale=None, noise_floor=None)[source]

Perform boxcar extraction for a single SpecObj. The size of the boxcar must be available as an attribute of the SpecObj object.

The SpecObj object is changed in place with boxcar attributes being filled with the extraction parameters, and additional sky and noise estimates being added. The following are the attributes that are filled here:

spec.BOX_WAVE –> Box car extracted wavelengths

spec.BOX_COUNTS –> Box car extracted flux

spec.BOX_COUNTS_IVAR –> Box car extracted inverse variance

spec.BOX_COUNTS_SIG –> Box car extracted error

spec.BOX_COUNTS_NIVAR –> Box car extracted noise variance

spec.BOX_MASK –> Box car extracted mask

spec.BOX_FWHM –> Box car extracted spectral FWHM

spec.BOX_COUNTS_SKY –> Box car extracted sky

spec.BOX_COUNTS_SIG_DET –> Box car extracted read noise

spec.BOX_NPIX –> Number of pixels used in boxcar sum

Parameters:

sciimg (numpy.ndarray) – Floating-point science image with shape \((N_{\rm spec}, N_{\rm spat})\). The first dimension (\(N_{\rm spec}\)) is spectral, and second dimension (\(N_{\rm spat}\)) is spatial.
ivar (numpy.ndarray) – Floating-point inverse variance image for the science image. It can be a model image, or deduced from sciimg. Shape must match sciimg, \((N_{\rm spec}, N_{\rm spat})\).
mask (numpy.ndarray) – Boolean image representing the good-pixel mask for the science image. The pixels that have value of True are good to be used. Must have the same shape as sciimg, \((N_{\rm spec}, N_{\rm spat})\).
waveimg (numpy.ndarray) – Floating-point wavelength image. Must have the same shape as sciimg, \((N_{\rm spec}, N_{\rm spat})\).
skyimg (numpy.ndarray) – Floating-point image containing the modeled sky. Must have the same shape as sciimg, \((N_{\rm spec}, N_{\rm spat})\).
spec (SpecObj) – Container that holds object, trace, and extraction information for the object in question. This object is altered in place! Note that this routine operates one object at a time.
fwhmimg (numpy.ndarray, None, optional:) – Floating-point image containing the modeled spectral FWHM (in pixels) at every pixel location. Must have the same shape as sciimg, \((N_{\rm spec}, N_{\rm spat})\).
base_var (numpy.ndarray, optional) – Floating-point “base-level” variance image set by the detector properties and the image processing steps. See base_variance(). Must have the same shape as sciimg, \((N_{\rm spec}, N_{\rm spat})\).
count_scale (float or numpy.ndarray, optional) – A scale factor, \(s\), that has already been applied to the provided science image. It accounts for the number of frames contributing to the provided counts, and the relative throughput factors that can be measured from flat-field frames. For example, if the image has been flat-field corrected, this is the inverse of the flat-field counts. If None, set to 1. If a single float, assumed to be constant across the full image. If an array, the shape must match base_var. The variance will be 0 wherever \(s \leq 0\), modulo the provided adderr. This is one of the components needed to construct the model variance; see model_noise.
noise_floor (float, optional) – A fraction of the counts to add to the variance, which has the effect of ensuring that the S/N is never greater than 1/noise_floor; see variance_model(). If None, no noise floor is added.

pypeit.core.extract.extract_hist_spectrum(waveimg, frame, gpm=None, bins=1000)[source]

Generate a quick spectrum using the nearest grid point (histogram) algorithm.

Parameters:

waveimg (numpy.ndarray) – A 2D image of the wavelength at each pixel.
frame (numpy.ndarray) – The frame to use to extract a spectrum. Shape should be the same as waveimg
gpm (numpy.ndarray, optional) – A boolean array indicating the pixels to include in the histogram (True = include)
bins (numpy.ndarray, int, optional) – Either a 1D array indicating the bin edges to be used for the histogram, or an integer that specifies the number of bin edges to generate

Returns:

A tuple containing the wavelength and spectrum at the centre of each histogram bin. Both arrays returned in the tuple are numpy.ndarray.

pypeit.core.extract.extract_optimal(sciimg, ivar, mask, waveimg, skyimg, thismask, oprof, spec, min_frac_use=0.05, fwhmimg=None, base_var=None, count_scale=None, noise_floor=None)[source]

Perform optimal extraction (Horne 1986) for a single SpecObj.

The SpecObj object is changed in place with optimal attributes being filled with the extraction parameters, and additional sky and noise estimates being added. The following are the attributes that are filled here:

spec.OPT_WAVE –> Optimally extracted wavelengths

spec.OPT_COUNTS –> Optimally extracted flux

spec.OPT_COUNTS_IVAR –> Inverse variance of optimally extracted flux using modelivar image

spec.OPT_COUNTS_SIG –> Optimally extracted noise from IVAR

spec.OPT_COUNTS_NIVAR –> Optimally extracted noise variance (sky + read noise) only

spec.OPT_MASK –> Mask for optimally extracted flux

spec.OPT_FWHM –> Spectral FWHM (in A) for optimally extracted flux

spec.OPT_COUNTS_SKY –> Optimally extracted sky

spec.OPT_COUNTS_SIG_DET –> Square root of optimally extracted read noise squared

spec.OPT_FRAC_USE –> Fraction of pixels in the object profile subimage used for this extraction

spec.OPT_CHI2 –> Reduced chi2 of the model fit for this spectral pixel

Parameters:

sciimg (numpy.ndarray) – Floating-point science image with shape \((N_{\rm spec}, N_{\rm spat})\). The first dimension (\(N_{\rm spec}\)) is spectral, and second dimension (\(N_{\rm spat}\)) is spatial.
ivar (numpy.ndarray) – Floating-point inverse variance image for the science image. It can be a model image, or deduced from sciimg. Shape must match sciimg, \((N_{\rm spec}, N_{\rm spat})\).
mask (numpy.ndarray) – Boolean image representing the good-pixel mask for the science image. The pixels that have value of True are good to be used. Must have the same shape as sciimg, \((N_{\rm spec}, N_{\rm spat})\).
waveimg (numpy.ndarray) – Floating-point wavelength image. Must have the same shape as sciimg, \((N_{\rm spec}, N_{\rm spat})\).
skyimg (numpy.ndarray) – Floating-point image containing the modeled sky. Must have the same shape as sciimg, \((N_{\rm spec}, N_{\rm spat})\).
thismask (numpy.ndarray) – Boolean image indicating which pixels are on the slit/order in question. Must have the same shape as sciimg, \((N_{\rm spec}, N_{\rm spat})\).
oprof (numpy.ndarray) – Floating-point image containing the profile of the object that is going to be extracted. Must have the same shape as sciimg, \((N_{\rm spec}, N_{\rm spat})\).
spec (SpecObj) – Container that holds object, trace, and extraction information for the object in question. This object is altered in place! Note that this routine operates one object at a time.
min_frac_use (float, optional) – Minimum accepted value for the sum of the normalized object profile across the spatial direction. For each spectral pixel, if the majority of the object profile has been masked, i.e., the sum of the normalized object profile across the spatial direction is less than min_frac_use, the optimal extraction will also be masked. The default value is 0.05.
fwhmimg (numpy.ndarray, None, optional:) – Floating-point image containing the modeled spectral FWHM (in pixels) at every pixel location. Must have the same shape as sciimg, \((N_{\rm spec}, N_{\rm spat})\).
base_var (numpy.ndarray, optional) – Floating-point “base-level” variance image set by the detector properties and the image processing steps. See base_variance(). Must have the same shape as sciimg, \((N_{\rm spec}, N_{\rm spat})\).
count_scale (float or numpy.ndarray, optional) – A scale factor, \(s\), that has already been applied to the provided science image. It accounts for the number of frames contributing to the provided counts, and the relative throughput factors that can be measured from flat-field frames. For example, if the image has been flat-field corrected, this is the inverse of the flat-field counts. If None, set to 1. If a single float, assumed to be constant across the full image. If an array, the shape must match base_var. The variance will be 0 wherever \(s \leq 0\), modulo the provided adderr. This is one of the components needed to construct the model variance; see model_noise.
noise_floor (float, optional) – A fraction of the counts to add to the variance, which has the effect of ensuring that the S/N is never greater than 1/noise_floor; see variance_model(). If None, no noise floor is added.

pypeit.core.extract.findfwhm(model, sig_x)[source]

Calculate the spatial FWHM of an object profile. This is utility routine is used in fit_profile().

Revision History:

11-Mar-2005 Written by J. Hennawi and S. Burles David Schlegel, Princeton.

28-May-2018 Ported to python by J. Hennawi

Parameters:

model (numpy.ndarray) – Model of the object profile. This is 2-d floating-point array with shape \((N_{\rm spec}, N_{\rm spat})\).
sig_x (numpy.ndarray) – Floating-point 2-d array containing the spatial location of the object profile. Shape is \((N_{\rm spec}, N_{\rm spat})\).

Returns:

peak (float) – Peak value of the object profile model.
peak_x (float) – sig_x location where the peak value is obtained.
lwhm (float) – Value of sig_x at the left width at half maximum.
rwhm (float) – Value of sig_x at the right width at half maximum.

pypeit.core.extract.fit_profile(image, ivar, waveimg, thismask, spat_img, trace_in, wave, flux, fluxivar, inmask=None, thisfwhm=4.0, max_trace_corr=2.0, sn_gauss=4.0, percentile_sn2=70.0, prof_nsigma=None, no_deriv=False, gauss=False, obj_string='', show_profile=False)[source]

Fit a non-parametric object profile to an object spectrum. If the S/N ratio of the object is less than sn_gauss, a simple Gaussian will be fitted.

This routine was ported from the IDL LOWREDUX routine long_gprofile.pro.

Parameters:

image (numpy.ndarray) – Floating-point sky-subtracted science image with shape \((N_{\rm spec}, N_{\rm spat})\). The first dimension (\(N_{\rm spec}\)) is spectral, and second dimension (\(N_{\rm spat}\)) is spatial.
ivar (numpy.ndarray) – Floating-point inverse variance image for the sky-subtracted science image. Shape must match image, \((N_{\rm spec}, N_{\rm spat})\).
waveimg (numpy.ndarray) – Floating-point wavelength image. Must have the same shape as image, \((N_{\rm spec}, N_{\rm spat})\).
thismask (numpy.ndarray) – Boolean image indicating which pixels are on the slit/order in question. Must have the same shape as sciimg, \((N_{\rm spec}, N_{\rm spat})\).
spat_img (numpy.ndarray) – Floating-point image containing the spatial location of pixels. Must have the same shape as image, \((N_{\rm spec}, N_{\rm spat})\).
trace_in (numpy.ndarray) – Floating-point 1-d array containing the object trace. Shape is \((N_{\rm spec},)\).
wave (numpy.ndarray) – Floating-point 1-d array containing the extracted wavelength of spectrum. Shape is \((N_{\rm spec},)\).
flux (numpy.ndarray) – Floating-point 1-d array containing the extracted flux of spectrum. Shape is \((N_{\rm spec},)\).
fluxivar (numpy.ndarray) – Floating-point 1-d array containing the inverse variance of extracted flux spectrum. Shape is \((N_{\rm spec},)\).
thisfwhm (float, optional) – FWHM value in pixels of the traced object. The default is 4.0.
max_trace_corr (float, optional) – Maximum correction in pixels to apply to the object trace. The default is 2.0.
sn_gauss (float, optional) – S/N ratio below which the routine just fit a simple Gaussian. The default is 4.0.
percentile_sn2 (float, optional) – Percentile of the S/N values along the spectral direction used to estimate the object median S/N. For example if percentile_sn2 = 70.0 then the upper 30% of the S/N values are used. This allows to determine the object median S/N even when the object shows signal only for part of fulle wavelength range. The default is 70.0.
prof_nsigma (float, optional) – Number of sigma to include in the profile fitting. This value is needed for bright objects that are not point sources, allowing to fit the high S/N wings of the object profile, rather than truncate it exponentially. Setting this value allows to extract all the object flux and provides a better sky-subtraction for bright extended objects. The default is None.
no_deriv (bool, optional) – If True, disables the determination of derivatives and exponential apodization. The default is False.
gauss (bool, optional) – If True, the profile fitting will not be attempted, and a Gaussian profile will be assumed.
obj_string (str) – String identifying the object. Used only to generate the QA plot.
show_profile (bool) – If True, the QA plot will be shown to screen.

Returns:

profile_model (numpy.ndarray) – Floating-point 2-d array containing the model of the object profile. Shape is \((N_{\rm spec}, N_{\rm spat})\).
xnew (numpy.ndarray) – Floating-point 1-d array containing the new trace of the object. Shape is \((N_{\rm spec},)\).
fwhmfit (numpy.ndarray) – Floating-point 1-d array containing the estimated FWHM in pixels of the object profile along the spectral direction. Shape is \((N_{\rm spec},)\).
med_sn2 (float) – Estimated median S/N^2 of the object profile.

pypeit.core.extract.qa_fit_profile(x_tot, y_tot, model_tot, l_limit=None, r_limit=None, ind=None, title=' ', xtrunc=1000000.0, xlim=None, ylim=None)[source]

Generate a QA plot for the object fitted profile.

Parameters:

x_tot (numpy.ndarray) – Floating-point 2-d array containing the spatial location of the object profile. Shape is \((N_{\rm spec}, N_{\rm spat})\).
y_tot (numpy.ndarray) – Floating-point 2-d array containing the flux of the object profile. Shape is \((N_{\rm spec}, N_{\rm spat})\).
model_tot (numpy.ndarray) – Floating-point 2-d array containing the model of the object profile. Shape is \((N_{\rm spec}, N_{\rm spat})\).
l_limit (float, optional) – If not None, draw a vertical line at this left position.
r_limit (float, optional) – If not None, draw a vertical line at this right position.
ind (numpy.ndarray, optional) – Integer 1-d array containing the indices of a subset of the object profile to be plot. The default is None.
title (str, optional) – Title to show on plot. Defaults to ‘ ‘.
xtrunc (float, optional) – Number of sigma to include in the plot of the object profile when generating the QA plot. The default is 1e6.
xlim (float, optional) – Minimum and maximum x-axis limits for the plot. Defaults is None.
ylim (tuple, optional) – Minimum and maximum y-axis limits for the plot. Defaults is None.

pypeit.core.extract.return_gaussian(sigma_x, norm_obj, fwhm, med_sn2, obj_string, show_profile, ind=None, l_limit=None, r_limit=None, xlim=None, xtrunc=1000000.0)[source]

Utility function to return a Gaussian object profile.

Parameters:

sigma_x (numpy.ndarray) – Floating-point 2-d array containing the location of the Gaussian profile. Shape is \((N_{\rm spec}, N_{\rm spat})\).
norm_obj (numpy.ndarray) – Floating-point 2-d array containing the normalized spectrum. Shape is \((N_{\rm spec}, N_{\rm spat})\).
fwhm (float) – FWHM value in pixels for the Gaussian profile.
med_sn2 (float) – Median (S/N)^2. Used only to generate the QA plot.
obj_string (str) – String identifying object. Used only to generate the QA plot.
show_profile (bool) – If True, the QA plot will be shown to screen.
ind (numpy.ndarray, optional) – Integer 1-d array containing the indices of the good pixels for the object profile. Used only to generate the QA plot. The deafault is None.
l_limit (float, optional) – Left and right limits of profile fit where derivative is evaluated for Gaussian apodization. Used only to generate the QA plot. The default is None.
r_limit (float, optional) – Left and right limits of profile fit where derivative is evaluated for Gaussian apodization. Used only to generate the QA plot. The default is None.
xlim (float, optional) – Minimum and maximum x-axis limits for plotting the object profile when generating the QA plot.
xtrunc (float, optional) – Number of sigma to include in the plot of the object profile when generating the QA plot. The default is 1e6.

Returns:

profile_model – Floating-point 2-d array containing the model of the object profile. Shape is \((N_{\rm spec}, N_{\rm spat})\).

Return type:

numpy.ndarray