pypeit.core.flexure module

Module for flexure routines

pypeit.core.flexure.calculate_image_offset(im_ref, image, nfit=3)[source]

Calculate the x,y offset between two images

Parameters:

im_ref (numpy.ndarray) – Reference image
image (numpy.ndarray) – Image that we want to measure the shift of (relative to im_ref)
nfit (int, optional) – Number of pixels (left and right of the maximum) to include in fitting the peak of the cross correlation.

Returns:

Returns two floats, the x and y offset of the image.

ra_diff – Relative shift (in pixels) of image relative to im_ref (x direction). In order to align image with im_ref, ra_diff should be added to the x-coordinates of image
dec_diff – Relative shift (in pixels) of image relative to im_ref (y direction). In order to align image with im_ref, dec_diff should be added to the y-coordinates of image

Return type:

tuple

pypeit.core.flexure.calculate_image_phase(imref, imshift, gpm_ref=None, gpm_shift=None, maskval=None)[source]

Perform a masked cross-correlation and optical flow calculation to robustly estimate the subpixel shifts of two images.

If gpm_ref, gpm_shift, and maskval are all None, no pixels will be masked

This routine (optionally) requires skimage to calculate the image phase. If skimage is not installed, a standard (unmasked) cross-correlation is used.

Parameters:

im_ref (numpy.ndarray) – Reference image
imshift (numpy.ndarray) – Image that we want to measure the shift of (relative to im_ref)
gpm_ref (numpy.ndarray) – Mask of good pixels (True = good) in the reference image
gpm_shift (numpy.ndarray) – Mask of good pixels (True = good) in the shifted image
maskval (float, optional) – If gpm_ref and gpm_shift are both None, a single value can be specified and this value will be masked in both images.

Returns:

ra_diff (float) – Relative shift (in pixels) of image relative to im_ref (x direction). In order to align image with im_ref, ra_diff should be added to the x-coordinates of image
dec_diff (float) – Relative shift (in pixels) of image relative to im_ref (y direction). In order to align image with im_ref, dec_diff should be added to the y-coordinates of image

pypeit.core.flexure.flexure_interp(shift, wave)[source]

Perform interpolation on wave given a shift in pixels

Parameters:

shift (float) – Shift in pixels
wave (numpy.ndarray) – extracted wave of size nspec
wavein (numpy.ndarray, optional) – Apply the shift to this array of wavelengths

Returns:

Wavelength scale corrected for spectral flexure

Return type:

numpy.ndarray

pypeit.core.flexure.get_archive_spectrum(sky_file, obj_skyspec=None, spec_fwhm_pix=None)[source]

Load an archival sky spectrum

Parameters:

sky_file (str) – Name of the archival sky file. If equal to ‘model’, instead, a model sky spectrum will be generated using nearIR_modelsky() and the spectral resolution of obj_skyspec. If obj_skyspec is None, then sky_file cannot be ‘model’.
obj_skyspec (OneSpec, optional) – Sky spectrum associated with the science target. This must be provided if sky_file is ‘model’.
spec_fwhm_pix (float, optional) – Spectral FWHM (in pixels) of the sky spectrum related to our object.

Returns:

sky_spectrum (OneSpec) – The sky spectrum
arx_fwhm_pix (float) – The FWHM of the sky lines in pixels.

pypeit.core.flexure.get_fwhm_gauss_smooth(arx_skyspec, obj_skyspec, arx_fwhm_pix, spec_fwhm_pix=None)[source]

Parameters:

arx_skyspec (OneSpec) – Archived sky spectrum.
obj_skyspec (OneSpec) – Sky spectrum associated with the science target.
arx_fwhm_pix (float) – Spectral FWHM (in pixels) of the archived sky spectrum.
spec_fwhm_pix (float, optional) – Spectral FWHM (in pixels) of the sky spectrum related to our object.

Returns:

FWHM of the smoothing Gaussian in pixels.

Return type:

float

pypeit.core.flexure.get_percentile_clipping(arr, percent=90.0)[source]

Get the values for clipping based on a percentile

Parameters:

arr (numpy.ndarray) – Array to clip.
percent (float) – Percentile to clip at. Default is 90.0

Returns:

Lower value for clipping float: Upper value for clipping

Return type:

float

pypeit.core.flexure.get_sky_spectrum(sciimg, ivar, waveimg, thismask, global_sky, box_radius, slits, trace_spat, pypeline, det)[source]

Obtain a boxcar extraction of the sky spectrum

Parameters:

sciimg (numpy.ndarray) – Science image - shape (nspec, nspat)
ivar (numpy.ndarray) – Inverse variance of the science image - shape (nspec, nspat)
waveimg (numpy.ndarray) – Wavelength image - shape (nspec, nspat)
thismask (numpy.ndarray) – Good pixel mask (True=good) that indicates the pixels that should be included in the boxcar extraction
global_sky (numpy.ndarray) – 2D array of the global_sky fit - shape (nspec, nspat)
box_radius (float) – Radius of the boxcar extraction (in pixels)
slits (SlitTraceSet) – Slit trace set
trace_spat (numpy.ndarray) – Spatial pixel values (usually the center of each slit) where the sky spectrum will be extracted. The shape of this array should be (nspec, nslits)
pypeline (str) – Name of the PypeIt pipeline method. Allowed options are MultiSlit, Echelle, or IFU.
det (str) – The name of the detector or mosaic from which the spectrum will be extracted. For example, DET01.

Returns:

The boxcar-extracted sky spectrum.

Return type:

OneSpec

pypeit.core.flexure.spat_flexure_qa(img, slits, shift, gpm=None, vrange=None, outfile=None)[source]

Generate QA for the spatial flexure

Parameters:

img (numpy.ndarray) – Image of the detector
slits (pypeit.slittrace.SlitTraceSet) – Slits object
shift (float) – Shift in pixels
gpm (numpy.ndarray, optional) – Good pixel mask (True = Bad)
vrange (tuple, optional) – Tuple with the min and max values for the imshow plot
outfile (str, optional) – Path to the output file where the QA is saved. If None, the QA is shown on screen and not saved.

pypeit.core.flexure.spat_flexure_shift(sciimg, slits, bpm=None, maxlag=20, sigdetect=10.0, debug=False, qa_outfile=None, qa_vrange=None)[source]

Calculate a rigid flexure shift in the spatial dimension between the slitmask and the science image.

It is important to use original=True when defining the slitmask as everything should be relative to the initial slits

Otherwise, the WaveTilts could get out of sync with science images

Parameters:

sciimg (numpy.ndarray) – Science image
slits (pypeit.slittrace.SlitTraceSet) – Slits object
bpm (numpy.ndarray, optional) – Bad pixel mask (True = Bad)
maxlag (int, optional) – Maximum flexure searched for
sigdetect (float, optional) – Sigma threshold above fluctuations for the slit detection in the collapsed sobel image
debug (bool, optional) – Run in debug mode
qa_outfile (str, optional) – Path to the output file where the QA is saved. If None, the QA is not generated.
qa_vrange (tuple, optional) – Tuple with the vmin and vmax values for the imshow plot in the QA. If None, the vmin and vmax values are calculated from the data.

Returns:

The spatial flexure shift relative to the initial slits

Return type:

float

pypeit.core.flexure.spec_flex_shift(obj_skyspec, sky_file=None, arx_skyspec=None, arx_fwhm_pix=None, spec_fwhm_pix=None, mxshft=20, excess_shft='crash', method='boxcar', minwave=None, maxwave=None)[source]

Calculate shift between object sky spectrum and archive sky spectrum

Parameters:

obj_skyspec (OneSpec) – Spectrum of the sky related to our object
sky_file (str, optional) – Name of the archival sky file. If equal to ‘model’, instead, a model sky spectrum will be generated using nearIR_modelsky() and the spectral resolution of obj_skyspec. If None, arx_skyspec and arx_fwhm_pix must be provided.
arx_skyspec (OneSpec, optional) – Archived sky spectrum. If None, it will be loaded from the sky_file (sky_file must be provided).
arx_fwhm_pix (float, optional) – Spectral FWHM (in pixels) of the archived sky spectrum. If None, it will be calculated using sky_file (sky_file must be provided).
spec_fwhm_pix (float, optional) – Spectral FWHM (in pixels) of the sky spectrum related to our object/slit.
mxshft (int, optional) – Maximum allowed shift from flexure; note there are cases that have been known to exceed even 30 pixels.
excess_shft (str, optional) – Behavior of the code when a measured flexure exceeds mxshft. Options are “crash”, “set_to_zero”, and “continue”, where “set_to_zero” sets the shift to zero and moves on, and “continue” simply uses the large flexure shift value.
method (str, optional) – Which method is used for the spectral flexure correction. Two methods are available: ‘boxcar’ and ‘slitcen’ (see spec_flexure_slit()). In this routine, ‘method’ is only passed to final dict.
minwave (float, optional) – Minimum wavelength to use for the correlation. If None or less than the minumum wavelength of either obj_skyspec or arx_skyspec, this has no effect. Default is None.
maxwave (float, optional) – Maximum wavelength to use for the correlation. If None or greater than the maximum wavelength of either obj_skyspec or arx_skyspec, this has no effect. Default is None.

Returns:

Contains flexure info. Keys are:

polyfit= fit to the cross-correlation

shift= best shift in pixels

subpix= subpixelation of input spectrum

corr= correlation function

sky_spec= object sky spectrum used (rebinned, etc.)

arx_spec= archived sky spectrum used

corr_cen= center of the correlation function

smooth= Degree of smoothing of input spectrum to match archive

Return type:

dict

pypeit.core.flexure.spec_flex_shift_global(slit_specs, islit, sky_file, empty_flex_dict, return_later_slits, flex_list, keys_to_update, spec_fwhm_pix=None, mxshft=20, excess_shft='crash', method='slitcen', minwave=None, maxwave=None)[source]

Calculate flexure shifts using the sky spectrum extracted at the center of the slit

Parameters:

slit_specs (list) – A list of OneSpec objects The spectra stored in this list are sky spectra, extracted from the center of each slit.
islit (int) – Index of the slit where the sky spectrum related to our object is.
sky_file (str) – Name of the archival sky file. If equal to ‘model’, instead, a model sky spectrum will be generated using nearIR_modelsky() and the spectral resolution of each spectrum from slit_specs.
empty_flex_dict (dict) – Empty dictionary to be filled with flexure results.
return_later_slits (list) – List of slit indexes that failed the shift calcultion and we want to come back to to assign a value from a different slit.
flex_list (list) – A list of dict objects containing flexure results of each slit.
keys_to_update (list) – List of flexure dictionary keys that we need to update.
spec_fwhm_pix (float, optional) – Spectral FWHM (in pixels) of the sky spectrum related to our object.
mxshft (int, optional) – Maximum allowed shift from flexure. Passed to spec_flex_shift().
excess_shft (str, optional) – Behavior of the code when a measured flexure exceeds mxshft. Passed to spec_flex_shift()
method (str, optional) – Which method is used for the spectral flexure correction. Two methods are available: ‘boxcar’ and ‘slitcen’ (see spec_flexure_slit()). Passed to spec_flex_shift().
minwave (float, optional) – Minimum wavelength to use for the correlation. If None or less than the minumum wavelength of either this sky or sky_spectrum, this has no effect. Default is None.
maxwave (float, optional) – Maximum wavelength to use for the correlation. If None or greater than the maximum wavelength of either this sky or sky_spectrum, this has no effect. Default is None.

Returns:

A list of dict objects containing flexure results of each slit. This is filled with a basically empty dict if the shift calculation failed for the relevant slit.

Return type:

list

pypeit.core.flexure.spec_flex_shift_local(slits, slitord, specobjs, islit, sky_file, empty_flex_dict, return_later_slits, flex_list, keys_to_update, spec_fwhm_pix=None, mxshft=20, excess_shft='crash', method='boxcar', minwave=None, maxwave=None)[source]

Calculate flexure shifts using the sky spectrum boxcar-extracted at the location of the detected objects

Parameters:

slits (SlitTraceSet) – Slit trace set.
slitord (numpy.ndarray) – Array of slit/order numbers.
specobjs (SpecObjs, optional) – Spectral extractions.
islit (int) – Index of the slit where the sky spectrum related to our object is.
sky_file (str) – Name of the archival sky file. If equal to ‘model’, instead, a model sky spectrum will be generated using nearIR_modelsky() and the spectral resolution of each spectrum in specobjs.
empty_flex_dict (dict) – Empty dictionary to be filled with flexure results.
return_later_slits (list) – List of slit indexes that failed the shift calcultion and we want to come back to to assign a value from a different slit.
flex_list (list) – A list of dict objects containing flexure results of each slit.
keys_to_update (list) – List of flexure dictionary keys that we need to update.
spec_fwhm_pix (float, optional) – Spectral FWHM (in pixels) of the sky spectrum related to our object.
mxshft (int, optional) – Maximum allowed shift from flexure. Passed to spec_flex_shift().
excess_shft (str, optional) – Behavior of the code when a measured flexure exceeds mxshft. Passed to spec_flex_shift()
method (str, optional) – Which method is used for the spectral flexure correction. Two methods are available: ‘boxcar’ and ‘slitcen’ (see spec_flexure_slit()). Passed to spec_flex_shift().
minwave (float, optional) – Minimum wavelength to use for the correlation. If None or less than the minumum wavelength of either this sky or sky_spectrum, this has no effect. Default is None.
maxwave (float, optional) – Maximum wavelength to use for the correlation. If None or greater than the maximum wavelength of either this sky or sky_spectrum, this has no effect. Default is None.

Returns:

A list of dict objects containing flexure results of each slit. This is filled with a basically empty dict if the shift calculation failed for the relevant slit.

Return type:

list

pypeit.core.flexure.spec_flexure_corrQA(ax, this_flex_dict, cntr, name)[source]

Spectral Flexure QA Plot

Creates one panel of the spectral felxure QA plot, with the overall figure container being handled by the calling function.

Parameters:

ax (Axes) – Axes onto which to draw the plot
this_flex_dict (dict) – Dictionary of flexure-related information needed for the plot
cntr (int) – The index into this_flex_dict’s arrays corresponding to the particular object, trace, or location of interest.
name (str) – Object, trace, or location name to be printed in the plot

pypeit.core.flexure.spec_flexure_qa(slitords, bpm, basename, flex_list, specobjs=None, out_dir=None)[source]

Generate QA for the spectral flexure calculation

Parameters:

slitords (numpy.ndarray) – Array of slit/order numbers
bpm (numpy.ndarray) – Boolean mask; True = masked slit
basename (str) – Used to generate the output file name
flex_list (list) – list of dict objects containing the flexure information
specobjs (SpecObjs, optional) – Spectrally extracted objects
out_dir (str, optional) – Path to the output directory for the QA plots. If None, the current is used.

pypeit.core.flexure.spec_flexure_slit(slits, slitord, slit_bpm, sky_file, method='boxcar', specobjs=None, slit_specs=None, wv_calib=None, mxshft=None, excess_shft='crash', minwave=None, maxwave=None)[source]

Calculate the spectral flexure for every slit (global) or object (local)

Parameters:

slits (SlitTraceSet) – Slit trace set
slitord (numpy.ndarray) – Array of slit/order numbers
slit_bpm (numpy.ndarray) – True = masked slit
sky_file (str) – Name of the archival sky file. If equal to ‘model’, instead, a model sky spectrum will be generated using nearIR_modelsky() and the spectral resolution of each spectrum that we want to correct for flexure.
method (str, optional) –
Two methods are available:
- ’boxcar’: Recommended for object extractions. This method uses the boxcar extracted sky and wavelength spectra from the input specobjs
- ’slitcen’: Recommended when no objects are being extracted. This method uses a spectrum (stored in slitspecs) that is extracted from the center of each slit.
specobjs (SpecObjs, optional) – Spectral extractions
slit_specs (list, optional) – A list of OneSpec, one for each slit. The spectra stored in this list are sky spectra, extracted from the center of each slit. This is only used if method='slitcen'.
wv_calib (pypeit.wavecalib.WaveCalib) – Wavelength calibration object
mxshft (int, optional) – Passed to spec_flex_shift()
excess_shft (str, optional) – Passed to spec_flex_shift()
minwave (float, optional) – Minimum wavelength to use for the correlation. If None or less than the minumum wavelength of either this sky or sky_spectrum, this has no effect. Default is None.
maxwave (float, optional) – Maximum wavelength to use for the correlation. If None or greater than the maximum wavelength of either this sky or sky_spectrum, this has no effect. Default is None.

Returns:

A list of dict objects containing flexure results of each slit. This is filled with a basically empty dict if the slit is skipped.

Return type:

list

pypeit.core.flexure.spec_flexure_slit_global(sciImg, waveimg, global_sky, par, slits, slitmask, trace_spat, gd_slits, wv_calib, pypeline, det)[source]

Calculate the spectral flexure for every slit

Parameters:

sciImg (PypeItImage) – Science image.
waveimg (numpy.ndarray) – Wavelength image - shape (nspec, nspat)
global_sky (numpy.ndarray) – 2D array of the global_sky fit - shape (nspec, nspat)
par (PypeItPar) – Parameters of the reduction.
slits (SlitTraceSet) – Slit trace set
slitmask (numpy.ndarray) – An image with the slit index identified for each pixel (returned from slittrace.slit_img).
trace_spat (numpy.ndarray) – Spatial pixel values (usually the center of each slit) where the sky spectrum will be extracted. The shape of this array should be (nspec, nslits)
gd_slits (numpy.ndarray) – True = good slit
wv_calib (pypeit.wavecalib.WaveCalib) – Wavelength calibration
pypeline (str) – Name of the PypeIt pipeline method. Allowed options are MultiSlit, Echelle, or IFU.
det (str) – The name of the detector or mosaic from which the spectrum will be extracted. For example, DET01.

Returns:

A list of dict objects containing flexure results of each slit. This is filled with a basically empty dict if the slit is skipped.

Return type:

list