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(box_radius, trace_spat, imgminsky, ivar, mask, waveimg, skyimg, fwhmimg=None, flatimg=None, base_var=None, count_scale=None, noise_floor=None, trace_spec=None)[source]

Perform boxcar extraction.

Parameters:

box_radius (float) – The boxcar radius (half of the full width) to use for the extraction.
trace_spat (numpy.ndarray) – The spatial pixel to use for the center of the extraction aperture as a function of the spectral dimension. That is, these are the pixels in the second axis of the input image at which to perform the extraction. If trace_spec is None, the shape must be \((N_{\rm spec},)\); otherwise, the shape must match trace_spec.
imgminsky (numpy.ndarray) – Floating-point science image minus skymodel (i.e., imgminsky = sciimg - skyimg) 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})\).
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})\).
flatimg (numpy.ndarray, None, optional) – Floating-point image containing the normalized flat-field. 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 plus a scaling factor applied if the counts of each frame are scaled to the mean counts of all 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.
trace_spec (numpy.ndarray, optional) – The pixel locations along the spectral axis at which to place each aperture defined by trace_spat. If provided, the shape must match trace_spat. If None, the code assumes trace_spat covers the full image and runs from 0 to the number of spectral pixels.

Returns:

wave (numpy.ndarray) – Wavelength vector
counts (numpy.ndarray) – Extracted counts
counts_ivar (numpy.ndarray) – Inverse variance in the extracted counts
counts_sig (numpy.ndarray) – 1-sigma uncertainties in the extracted counts
counts_nivar (numpy.ndarray) – Same as counts_nivar, but excludes shot-noise contributions from the extracted object.
gpm (numpy.ndarray) – Good-pixel mask selected valid data in the extracted spectrum.
fwhm (numpy.ndarray) – Estimated FWHM of the wavelength-dependent spectral resolution element. This will be None if fwhmimg is not provided.
flat (numpy.ndarray) – Spectrum extracted from the normalized flat-field image at the same location as the object spectrum. This will be None if flatimg is not provided.
counts_sky (numpy.ndarray) – Sky-only spectrum extraced from the sky image (skyimg).
counts_sig_det (numpy.ndarray) – Same as counts_sig but only includes uncertainties introduced by the detector.
npix (numpy.ndarray) – Wavelength-dependent (fractional) number of valid pixels included in the extraction.

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(imgminsky, ivar, mask, waveimg, skyimg, thismask, oprof, min_frac_use=0.9, fwhmimg=None, flatimg=None, base_var=None, count_scale=None, noise_floor=None, box_radius=None, trace_spec=None, trace_spat=None)[source]

Perform optimal extraction (Horne 1986).

When necessary, the function will fall back to a boxcar extraction algorithm for setting the wavelength for a wavelength channel that is fully masked. If this happens, the box_radius, trace_spat, and trace_spec parameters must be provided; an exception is raised otherwise.

Parameters:

imgminsky (numpy.ndarray) – Floating-point science image minus skymodel (i.e., imgminsky = sciimg - skyimg) 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})\).
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})\).
flatimg (numpy.ndarray, None, optional:) – Floating-point image containing the unnormalized flat-field image. This image is used to extract the blaze function. 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.
box_radius (float, optional) – When necessary, use this boxcar radius in pixels to determine the wavelength of a fully masked spectral channel.
trace_spec (numpy.ndarray, optional) – When necessary, use these spectral trace positions to determine the wavelength of a fully masked spectral channel.
trace_spat (numpy.ndarray, optional) – When necessary, use these spatial trace positions to determine the wavelength of a fully masked spectral channel.

Returns:

wave (numpy.ndarray) – Wavelength vector
counts (numpy.ndarray) – Extracted counts
counts_ivar (numpy.ndarray) – Inverse variance in the extracted counts
counts_sig (numpy.ndarray) – 1-sigma uncertainties in the extracted counts
counts_nivar (numpy.ndarray) – Same as counts_nivar, but excludes shot-noise contributions from the extracted object.
gpm (numpy.ndarray) – Good-pixel mask selected valid data in the extracted spectrum.
fwhm (numpy.ndarray) – Estimated FWHM of the wavelength-dependent spectral resolution element. This will be None if fwhmimg is not provided.
flat (numpy.ndarray) – Spectrum extracted from the normalized flat-field image at the same location as the object spectrum. This will be None if flatimg is not provided.
counts_sky (numpy.ndarray) – Sky-only spectrum extraced from the sky image (skyimg).
counts_sig_det (numpy.ndarray) – Same as counts_sig but only includes uncertainties introduced by the detector.
frac_use (numpy.ndarray) – Wavelength-dependent fraction of pixels in the object profile subimage used for the extraction.
chi2 (numpy.ndarray) – Wavelength-dependent reduced chi-square of the model fit.