Extraction API#

Spectral extraction from 2D images to 1D spectra, plus top-level orchestration modules for science and fibre-flat reduction. See the Pipeline Overview for how these stages connect.

Extraction Routines for KSPEC.

This module implements the extraction of spectra from image data using tramline maps, converting the 2dfdr MAKE_EX and related subroutines.

kspecdr.extract.make_ex.make_ex(args: Dict[str, Any]) → None[source]#

Main driver for extraction process. Replaces 2dfdr SUBROUTINE MAKE_EX.

Parameters:

args (dict) – Dictionary containing arguments: - IMAGE_FILENAME: Input image file - EXTRAC_FILENAME: Output extracted file - TLMAP_FILENAME: Tramline map file - WTSCHEME: Weighting scheme (optional)

kspecdr.extract.make_ex.make_ex_from_im(im_fname: str, tlm_fname: str, ex_fname: str, wtscheme: str, args: Dict[str, Any]) → None[source]#

Process image file to produce extracted spectra. Replaces 2dfdr SUBROUTINE MAKE_EX_FROM_IM.

Parameters:

  • im_fname (str) – Input image filename

  • tlm_fname (str) – Tramline map filename

  • ex_fname (str) – Output extracted filename

  • wtscheme (str) – Weighting scheme

  • args (dict) – Additional arguments

kspecdr.extract.make_ex.sum_extract(nspat: int, nspec: int, indat: ndarray, invar: ndarray, outdat: ndarray, outvar: ndarray, nfib: int, tlmap: ndarray, width: float) → None[source]#

Perform simple summing extraction. Replaces 2dfdr SUBROUTINE SUMEXTR.

Parameters:

  • nspat (int) – Number of spatial pixels (rows in indat)

  • nspec (int) – Number of spectral pixels (cols in indat)

  • indat (np.ndarray) – Input image (NSPAT, NSPEC) - Horizontal Dispersion

  • invar (np.ndarray) – Input variance (NSPAT, NSPEC) - Horizontal Dispersion

  • outdat (np.ndarray) – Output spectra (NSPEC, NFIB) - Updated in place

  • outvar (np.ndarray) – Output variance (NSPEC, NFIB) - Updated in place

  • nfib (int) – Number of fibers

  • tlmap (np.ndarray) – Tramline map (NSPEC, NFIB)

  • width (float) – Width of extraction window

Reduction Routines for KSPEC.

This module implements the reduction of extracted spectra (making RED files from EX files), converting the 2dfdr MAKE_RED subroutine.

kspecdr.extract.make_red.make_red(args: Dict[str, Any]) → None[source]#

Main driver for reduction process (EX -> RED). Replaces 2dfdr SUBROUTINE MAKE_RED.

Processes from the supplied arguments determine what extraction files are to be made from which image files and call MAKE_EX_FROM_IM for each. (Docstring from Fortran seems copy-pasted/wrong there).

Actual Description: Creates output red(uced) file by copying ex(tracted) file. Divides by fibre-flat-field if requested. Scrunches using input arc calibration file.

Parameters:

args (dict) – Dictionary containing arguments: - EXTRAC_FILENAME: Input extracted filename - OUTPUT_FILENAME: Output reduced filename - FLAT_FILENAME: (Optional) Fiber flat field file - WAVEL_FILENAME: (Optional) Wavelength calibration file (Arc)

kspecdr.reduce_fflat.bs_smooth_redflat(filename: str, args: Dict[str, Any])[source]#

Perform B-Spline Smoothing on the reduced flat field.

Parameters:

  • filename (str) – Path to the reduced FITS file (modified in place).

  • args (dict) – Arguments containing: - BSSNPARS (int): Number of knots (default 16). - BSSNSIGM (float): Sigma rejection threshold (default 6.0).

kspecdr.reduce_fflat.cmfff_aver(data: ndarray, goodfib: ndarray, laf_flag: bool, laf_par: int, trunc_flat: bool, start_pix: int, end_pix: int)[source]#

Normalizes fibers by median, then averages them.

Parameters:

  • data (np.ndarray) – Spectral data array (NSPEC, NFIB). Modified in place.

  • goodfib (np.ndarray) – Boolean array indicating good fibers.

  • laf_flag (bool) – If True, use local averaging (moving window across fibers). If False, use global averaging across all good fibers.

  • laf_par (int) – Window half-width for local averaging (used if laf_flag is True).

  • trunc_flat (bool) – If True, calculate median only within the specified pixel range.

  • start_pix (int) – Start pixel index (1-based from args, converted to 0-based implicitly via mask) for truncation.

  • end_pix (int) – End pixel index for truncation.

kspecdr.reduce_fflat.cmfff_extrap(data: ndarray)[source]#

Linearly extrapolate the ends of the spectra to cover bad pixels (NaNs).

Parameters:

data (np.ndarray) – Spectral data (NSPEC, NFIB). Modified in place.

kspecdr.reduce_fflat.cmfff_norm(red_data: ndarray, red_var: ndarray, aff_data: ndarray, trunc_flat: bool, start_pix: int, end_pix: int)[source]#

Normalize the reduced data by the Average Flat Field (AFF).

Parameters:

  • red_data (np.ndarray) – Reduced image data (NSPEC, NFIB). Modified in place.

  • red_var (np.ndarray) – Reduced variance data (NSPEC, NFIB). Modified in place.

  • aff_data (np.ndarray) – Average Flat Field data (NSPEC, NFIB).

  • trunc_flat (bool) – If True, normalization by median is restricted to a pixel range.

  • start_pix (int) – Start pixel for median normalization range.

  • end_pix (int) – End pixel for median normalization range.

kspecdr.reduce_fflat.do_aff(filename: str, args: Dict[str, Any])[source]#

Normalise and average the spectra in the given file.

Parameters:

  • filename (str) – Path to the FITS file to process (modified in place).

  • args (dict) – Arguments containing: - LAF_FLAG (bool): Use local averaging if True. - LAF_PAR (int): Window size for local averaging. - TRUNCFLAT (bool): Use truncated flat range. - USEFLATSTART (int): Start pixel for truncation. - USEFLATEND (int): End pixel for truncation.

kspecdr.reduce_fflat.do_all(data: ndarray, goodfib: ndarray, ypix: ndarray)[source]#

Average across all good fibers with iterative sigma clipping.

Parameters:

  • data (np.ndarray) – Spectral data (NSPEC, NFIB).

  • goodfib (np.ndarray) – Boolean array of good fibers.

  • ypix (np.ndarray) – Output averaged spectrum (NSPEC).

kspecdr.reduce_fflat.do_local(data: ndarray, goodfib: ndarray, laf_par: int, ypix: ndarray)[source]#

Local averaging using a moving window of fibers (+/- laf_par).

Parameters:

  • data (np.ndarray) – Spectral data (NSPEC, NFIB). Modified in place with local averages.

  • goodfib (np.ndarray) – Boolean array of good fibers.

  • laf_par (int) – Half-width of the fiber window.

  • ypix (np.ndarray) – Output array to store the central fiber’s average (for plotting/reference).

kspecdr.reduce_fflat.reduce_fflat(args: Dict[str, Any])[source]#

Reduces a raw multi-fibre flat file to produce im(age), ex(tracted) and red(uced) fflat files.

This routine performs the complete flat field reduction workflow: 1. Preprocessing (IM creation, Tramline Mapping, Extraction) 2. Copying Extraction to Reduced file 3. Scrunching (rebinning to linear wavelength scale) 4. Averaging and Normalizing (creating a master flat response) 5. Reverse Scrunching (back to pixel space) 6. Extrapolation or B-Spline Smoothing 7. Normalizing the original extracted frame by the master flat

Parameters:

args (dict) – Argument dictionary containing the following keys: - RAW_FILENAME (str): Input raw file. - IMAGE_FILENAME (str): Output IM file. - EXTRAC_FILENAME (str): Output EX file. - OUTPUT_FILENAME (str): Output RED file. - TLMAP_FILENAME (str): Tramline map file. - WAVEL_FILENAME (str): Wavelength calibration (Arc) file. - DO_TLMAP (bool, optional): Whether to create IM/TLM. Default True. - DO_EXTRA (bool, optional): Whether to create EX. Default True. - DO_REDFL (bool, optional): Whether to perform reduction. Default True. - MAKE_TLM_ONLY (bool, optional): If True, stop after TLM. Default False. - LAF_FLAG (bool, optional): If True, use local averaging. Default False. - LAF_PAR (int, optional): Window size for local averaging. Default 10. - TRUNCFLAT (bool, optional): If True, use truncated range. Default False. - USEFLATSTART (int, optional): Start pixel for truncation. Default 1. - USEFLATEND (int, optional): End pixel for truncation. Default 2048. - BSSMOOTH (bool, optional): If True, perform B-Spline smoothing. Default False. - BSSNPARS (int, optional): Number of knots for B-Spline. Default 16. - BSSNSIGM (float, optional): Sigma rejection threshold for B-Spline. Default 6.0. - VERBOSE (bool, optional): Verbosity flag. Default False.

Reduce Object Module

This module implements the top-level reduce_object routine for the KSPEC pipeline, orchestrating the reduction of a raw science file to produce im(age), ex(tracted), and red(uced) science files.

kspecdr.reduce_object.reduce_object(args: Dict[str, Any]) → None[source]#

Reduce a raw science file to produce im, ex, and red science files.

Parameters:

args (dict) –

Dictionary containing reduction arguments:

Required keys: - RAW_FILENAME: Input raw filename - IMAGE_FILENAME: Output IM filename - EXTRAC_FILENAME: Output extracted filename - OUTPUT_FILENAME: Output reduced filename - TLMAP_FILENAME: Tramline map filename - WAVEL_FILENAME: Wavelength calibration (arc RED) filename

Optional keys: - FFLAT_FILENAME: Fiber flat filename - OUT_DIRNAME: Output directory - DPCRREX: Double pass cosmic ray rejection (bool) - EXTR_OPERATION: Extraction method (default "SUM") - OPTEX_MKRES: Make residual map for optimal extraction (bool) - VERBOSE: Verbosity (bool, default True) - USE_GENCAL: Use skyline recalibration (bool) - TST_SKYCAL: Test skyline calibration (bool) - INC_RWSS: Include Reduced Without Sky Subtraction copy (bool) - SKYSPRSMP: Super sky subtraction (bool) - SKYSUB: Enable sky subtraction (bool, default True) - SKYCOMBINE: Sky fiber combination method

('MEAN' | 'MEDIAN' | 'SIGCLIP', default 'MEAN')

  • SKYCOMBINE_SIGMA: Sigma-clipping threshold for SIGCLIP (float, default 3.0)

  • SKYCOMBINE_ITERS: Max iterations for SIGCLIP (int, default 5)

  • SKYSUB_PCA: Enable PCA sky subtraction (bool)

  • CALIBFLUX: Enable flux calibration (bool)

  • TELCOR: Enable telluric correction (bool)

  • VELCOR: Enable velocity correction (bool)

  • TRANSFUNC: Transfer function correction (bool)

  • DEWIGGLE: De-wiggle (bool)