pypeit.extraction module

Main driver class for skysubtraction and extraction

class pypeit.extraction.EchelleExtract(sciImg, slits, sobjs_obj, spectrograph, par, objtype, **kwargs)[source]

Bases: Extract

Child of Extract for Echelle reductions

See parent doc string for Args and Attributes

local_skysub_extract(global_sky, sobjs, bkg_redux_global_sky=None, spat_pix=None, model_noise=True, min_snr=2.0, fit_fwhm=False, show_profile=False, show_resids=False, show_fwhm=False, show=False)[source]

Perform local sky subtraction, profile fitting, and optimal extraction slit by slit

Wrapper to local_skysub_extract().

Parameters:

  • global_sky (numpy.ndarray) – Global sky model

  • sobjs (SpecObjs) – Class containing the information about the objects found

  • bkg_redux_global_sky (numpy.ndarray, optional) – Sky estimate without background subtraction. This is used for 1d sky spectrum extraction in the case bkg_redux=True. Default is None.

  • spat_pix (numpy.ndarray, optional) – Image containing the spatial location of pixels. If not input, it will be computed from spat_img = np.outer(np.ones(nspec), np.arange(nspat)).

  • model_noise (bool, optional) – If True, construct and iteratively update a model inverse variance image using variance_model(). If False, a variance model will not be created and instead the input sciivar will always be taken to be the inverse variance. See ~pypeit.core.skysub.local_skysub_extract for more info.

  • show_resids (bool, optional) – Show the model fits and residuals.

  • show_profile (bool, optional) – Show QA for the object profile fitting to the screen. Note that this will show interactive matplotlib plots which will block the execution of the code until the window is closed.

  • show (bool, optional) – Show debugging plots

Returns:

Return the model sky flux, object flux, inverse variance, and mask as numpy.ndarray objects, and returns a SpecObjs: instance c containing the information about the objects found.

Return type:

tuple

class pypeit.extraction.Extract(sciImg, slits, sobjs_obj, spectrograph, par, objtype, global_sky=None, bkg_redux_global_sky=None, waveTilts=None, tilts=None, wv_calib=None, waveimg=None, flatimages=None, bkg_redux=False, return_negative=False, std_redux=False, show=False, basename=None)[source]

Bases: object

This class will organize and run actions relatedt to sky subtraction, and extraction for a Science or Standard star exposure

Variables:

  • ivarmodel (numpy.ndarray) – Model of inverse variance

  • objimage (numpy.ndarray) – Model of object

  • skyimage (numpy.ndarray) – Final model of sky

  • global_sky (numpy.ndarray) – Fit to global sky

  • outmask (ImageBitMaskArray) – Final output mask

  • extractmask (numpy.ndarray) – Extraction mask

  • slits (SlitTraceSet)

  • sobjs_obj (SpecObjs) – Only object finding but no extraction

  • sobjs (SpecObjs) – Final extracted object list with trace corrections applied

  • spat_flexure_shift (float)

  • tilts (numpy.ndarray) – WaveTilts images generated on-the-spot

  • waveimg (numpy.ndarray) – WaveImage image generated on-the-spot

  • slitshift (numpy.ndarray) – Global spectral flexure correction for each slit (in pixels)

  • vel_corr (float) – Relativistic reference frame velocity correction (e.g. heliocentyric/barycentric/topocentric)

  • extract_bpm (numpy.ndarray) – Bad pixel mask for extraction

extract(global_sky, bkg_redux_global_sky=None, model_noise=None, spat_pix=None)[source]

Main method to extract spectra from the ScienceImage

Parameters:

  • global_sky (numpy.ndarray) – Sky estimate

  • sobjs_obj (SpecObjs) – List of SpecObj that have been found and traced

  • bkg_redux_global_sky (numpy.ndarray) – Sky estimate without background subtraction. This is used for 1d sky spectrum extraction in the case bkg_redux=True. Default is None.

  • model_noise (bool) – If True, construct and iteratively update a model inverse variance image using variance_model(). If False, a variance model will not be created and instead the input sciivar will always be taken to be the inverse variance. See local_skysub_extract() for more info. Default is None, which is to say pypeit will use the bkg_redux attribute to decide whether or not to model the noise.

  • spat_pix (numpy.ndarray) – Image containing the spatial coordinates. This option is used for 2d coadds where the spat_pix image is generated as a coadd of images. For normal reductions spat_pix is not required as it is trivially created from the image itself. Default is None.

classmethod get_instance(sciImg, slits, sobjs_obj, spectrograph, par, objtype, global_sky=None, bkg_redux_global_sky=None, waveTilts=None, tilts=None, wv_calib=None, waveimg=None, flatimages=None, bkg_redux=False, return_negative=False, std_redux=False, show=False, basename=None)[source]

Instantiate the Extract subclass appropriate for the provided spectrograph.

The class must be subclassed from Extract. See Extract for the description of the valid keyword arguments.

Parameters:

  • sciImg (PypeItImage) – Image to reduce.

  • slits (SlitTraceSet) – Slit trace set object

  • sobjs_obj (SpecObjs) – Objects found but not yet extracted

  • spectrograph (Spectrograph)

  • par (PypeItPar) – Parameter set for Extract

  • objtype (str) – Specifies object being reduced ‘science’, ‘standard’, or ‘science_coadd2d’. This is used only to determine the spat_flexure_shift and ech_order for coadd2d.

  • global_sky (numpy.ndarray, optional) – Fit to global sky. If None, an array of zeroes is generated the same size as sciImg.

  • bkg_redux_global_sky (numpy.ndarray, optional) – Sky estimate without background subtraction. This is used for 1d sky spectrum extraction in the case bkg_redux=True. Default is None.

  • waveTilts (WaveTilts, optional) – This is waveTilts object which is optional, but either waveTilts or tilts must be provided.

  • tilts (numpy.ndarray, optional) – Tilts image. Either a tilts image or waveTilts object (above) must be provided.

  • wv_calib (WaveCalib, optional) – This is the waveCalib object which is optional, but either wv_calib or waveimg must be provided.

  • waveimg (numpy.ndarray, optional) – Wave image. Either a wave image or wv_calib object (above) must be provided

  • flatimages (FlatImages, optional) – FlatImages class. This is optional, but if provided, it is used to extract the normalized blaze profile.

  • bkg_redux (bool, optional) – If True, the sciImg has been subtracted by a background image (e.g. standard treatment in the IR)

  • return_negative (bool, optional) – If True, negative objects from difference imaging will also be extracted and returned. Default=False. This option only applies to the case where bkg_redux=True, i.e. typically a near-IR reduction where difference imaging has been employed to perform a first-pass at sky-subtraction. The default behavior is to not extract these objects, although they are masked in global sky-subtraction (performed in the find_objects class), and modeled in local sky-subtraction (performed by this class).

  • std_redux (bool, optional) – If True the object being extracted is a standards star so that the reduction parameters can be adjusted accordingly.

  • basename (str, optional) – Output filename used for spectral flexure QA

  • show (bool, optional) – Show plots along the way?

Returns:

Extraction object.

Return type:

Extract

initialize_slits(slits, initial=False)[source]

Gather all the SlitTraceSet attributes that we’ll use here in Extract

Args
slits (SlitTraceSet):

SlitTraceSet object containing the slit boundaries that will be initialized.

initial (bool, optional):

Use the initial definition of the slits. If False, tweaked slits are used.

local_skysub_extract(global_sky, sobjs, bkg_redux_global_sky=None, model_noise=True, spat_pix=None, show_profile=False, show_resids=False, show=False)[source]

Dummy method for local sky-subtraction and extraction.

Overloaded by class specific skysub and extraction.

property nsobj_to_extract

Number of sobj objects in sobjs_obj taking into account whether or not we are returning negative traces

Returns:

run(model_noise=None, spat_pix=None)[source]

Primary code flow for PypeIt reductions

Parameters:

  • model_noise (bool) – If True, construct and iteratively update a model inverse variance image using variance_model(). If False, a variance model will not be created and instead the input sciivar will always be taken to be the inverse variance. See local_skysub_extract() for more info. Default is None, which is to say pypeit will use the bkg_redux attribute to decide whether or not to model the noise.

  • spat_pix (numpy.ndarray) – Image containing the spatial coordinates. This option is used for 2d coadds where the spat_pix image is generated as a coadd of images. For normal reductions spat_pix is not required as it is trivially created from the image itself. Default is None.

Returns:

skymodel (ndarray), bkg_redux_skymodel (ndarray), objmodel (ndarray), ivarmodel (ndarray),

outmask (ndarray), sobjs (SpecObjs), waveimg (numpy.ndarray), tilts (numpy.ndarray), slits (SlitTraceSet). See main doc string for description

Return type:

tuple

show(attr, image=None, showmask=False, sobjs=None, chname=None, slits=False, clear=False)[source]

Show one of the internal images

Todo

Should probably put some of these in ProcessImages

Parameters:

  • attr (str) – global – Sky model (global) sci – Processed science image rawvar – Raw variance image modelvar – Model variance image crmasked – Science image with CRs set to 0 skysub – Science image with global sky subtracted image – Input image

  • display (str, optional)

  • image (ndarray, optional) – User supplied image to display

spec_flexure_correct(mode='local', sobjs=None)[source]

Correct for spectral flexure

Spectra are modified in place (wavelengths are shifted)

Parameters:

  • mode (str) – “local” - Use sobjs to determine flexure correction “global” - Use waveimg and global_sky to determine flexure correction at the centre of the slit

  • sobjs (SpecObjs, None) – Spectrally extracted objects

class pypeit.extraction.FiberExtract(sciImg, slits, sobjs_obj, spectrograph, par, objtype, global_sky=None, bkg_redux_global_sky=None, waveTilts=None, tilts=None, wv_calib=None, waveimg=None, flatimages=None, bkg_redux=False, return_negative=False, std_redux=False, show=False, basename=None)[source]

Bases: Extract

Child of Extract for fiber-fed spectrographs.

Extracts 1D spectra from each fiber using boxcar and optimal (Horne 1986) extraction. Skips local sky subtraction — the global sky model is used directly.

See parent doc string for Args and Attributes.

static _build_empirical_profile(flatimg, slitmask, sobj, nspec, nspat)[source]

Build one fiber’s empirical spatial profile from the flat field.

This is the 2D oprof image that extract_optimal() requires – the same (nspec, nspat) profile interface the MultiSlit/Echelle pypelines use, except it is populated empirically from the flat (each fiber’s measured spatial PSF, wings included) rather than from a fitted or analytic Gaussian.

Algorithm, per spectral row:

  1. Take the spatial aperture of half-width BOX_R_PIX centered on the fiber trace, keeping only pixels on this fiber’s slit (or in the unassigned slitmask == -1 gap; see below).

  2. Weight each aperture pixel by its flat value and normalize the row to unit sum – the empirical PSF. If too few aperture pixels carry a usable flat value, fall back to a uniform 1 / n_aperture_pixels weight (see below).

The rest of the function is just a vectorized form of that per-row loop (see “Vectorized across rows” below); it is bit-identical to the legacy row-loop implementation.

Returns a fresh (nspec, nspat) profile each call so callers can process and discard one fiber at a time – caching the dense profile for every fiber simultaneously would cost ~134 MB per fiber on a 4k detector (~48 GB for 360 fibers).

Fiber pseudo-slit edges are not hard apertures (they sit on the outermost fiber, not a physical edge), so the per-row aperture extends into unassigned pixels (slitmask == -1 – inter-block gaps and detector edges) to capture the fiber’s PSF wings. Pixels belonging to a different slit are always excluded.

Per row, if too few pixels in the aperture have a usable flat value (NaN / non-positive), the profile falls back to a uniform aperture weight (1 / n_aperture_pixels). This guards against BPM rows and low-throughput wavelength regions, where a profile built from a few positive flat outliers would concentrate the sky on 1-2 pixels and produce huge spurious spikes.

Vectorized across rows: assembles the per-row aperture in a compact (nspec, max_aper) form, evaluates the slit and flat-validity predicates with numpy, and scatters the normalized weights into a fresh dense array. Bit-identical to the legacy row-loop implementation.

Parameters:

  • flatimg (numpy.ndarray) – Raw (unnormalized) flat field image, shape (nspec, nspat).

  • slitmask (numpy.ndarray) – Slit ID image from slits.slit_img(pad=0), shape (nspec, nspat).

  • sobj (SpecObj) – One fiber with SLITID, TRACE_SPAT and BOX_R_PIX set.

  • nspec (int) – Detector image shape.

  • nspat (int) – Detector image shape.

Returns:

Per-pixel profile normalized to unit sum per row in the aperture, shape (nspec, nspat). None when the fiber’s slit footprint is empty or no row has any valid data.

Return type:

numpy.ndarray or None

local_skysub_extract(global_sky, sobjs, bkg_redux_global_sky=None, spat_pix=None, model_noise=True, show_resids=False, show_profile=False, show=False)[source]

Extract fiber spectra without local sky subtraction.

For each pseudo-slit group of fibers, performs Horne (1986) optimal extraction for every fiber SpecObj using flat-derived empirical profiles. The global sky model is used directly (no local sky subtraction). Boxcar extraction is skipped for fibers whose BOX_COUNTS attribute is already populated (e.g., by FiberFindObjects), which performs boxcar extraction and 1D sky subtraction as part of object finding.

Parameters:

  • global_sky (numpy.ndarray) – Global sky model, shape (nspec, nspat).

  • sobjs (SpecObjs) – Objects to extract (multiple per block-slit from FiberFindObjects).

  • bkg_redux_global_sky (numpy.ndarray, optional) – Sky estimate without background subtraction.

  • spat_pix (numpy.ndarray, optional) – Image containing the spatial location of pixels.

  • model_noise (bool, optional) – Not used for fiber extraction.

  • show_resids (bool, optional) – Not used for fiber extraction.

  • show_profile (bool, optional) – Not used for fiber extraction.

  • show (bool, optional) – Show debugging plots.

Returns:

skymodel, bkg_redux_skymodel, objmodel, ivarmodel, outmask, sobjs

Return type:

tuple

class pypeit.extraction.MultiSlitExtract(sciImg, slits, sobjs_obj, spectrograph, par, objtype, **kwargs)[source]

Bases: Extract

Child of Extract for Multislit and Longslit reductions

See parent doc string for Args and Attributes

local_skysub_extract(global_sky, sobjs, bkg_redux_global_sky=None, spat_pix=None, model_noise=True, show_resids=False, show_profile=False, show=False)[source]

Perform local sky subtraction, profile fitting, and optimal extraction slit by slit.

Wrapper to local_skysub_extract().

Parameters:

  • global_sky (numpy.ndarray) – Global sky model

  • sobjs (SpecObjs) – Class containing the information about the objects found

  • bkg_redux_global_sky (numpy.ndarray, optional) – Sky estimate without background subtraction. This is used for 1d sky spectrum extraction in the case bkg_redux=True. Default is None.

  • spat_pix (numpy.ndarray, optional) – Image containing the spatial location of pixels. If not input, it will be computed from spat_img = np.outer(np.ones(nspec), np.arange(nspat)).

  • model_noise (bool, optional) – If True, construct and iteratively update a model inverse variance image using variance_model(). If False, a variance model will not be created and instead the input sciivar will always be taken to be the inverse variance. See local_skysub_extract() for more info.

  • show_resids (bool, optional) – Show the model fits and residuals.

  • show_profile (bool, optional) – Show QA for the object profile fitting to the screen. Note that this will show interactive matplotlib plots which will block the execution of the code until the window is closed.

  • show (bool, optional) – Show debugging plots

Returns:

Return the model sky flux, object flux, inverse variance, and mask as numpy.ndarray objects, and returns a SpecObjs: instance c containing the information about the objects found.

Return type:

tuple

class pypeit.extraction.SlicerIFUExtract(sciImg, slits, sobjs_obj, spectrograph, par, objtype, **kwargs)[source]

Bases: MultiSlitExtract

Child of Extract for IFU reductions

See parent doc string for Args and Attributes