modules.masters

Masters modules: stack L0 frames into bias, dark, flat, and WLS products.

class kpfpipe.modules.masters.Bias(l0_file_list, config=None)

Bases: BaseMasterModule

Construct a master bias frame from a stack of L0 bias exposures.

Stacks frames using sigma-clipped statistics, interpolates bad pixels, and performs a final outlier pass on the combined image. Outputs a KPFMasterL1 containing per-chip IMG, SNR, and MASK extensions.

Standard reduction: a bias receives no calibration (_STANDARD_CALIBRATIONS is empty), so raw frames are stacked as-is.

Parameters:

l0_file_list (list of str) – Sorted list of L0 FITS file paths to stack.
config (None | dict | ConfigHandler) – Module configuration. Recognized keys: stack_sigma, chips.

info(): Print a summary of the module configuration and stacking results.

make_master_l1(l0_file_list=None, *, nstream=6, sigma=None, master_path=None)

Build master bias from stack.

The constructed KPFMasterL1 is returned and cached on self.ml1_obj; pass master_path to also persist it to disk via save_master(‘L1’, …).

A bias receives no calibrations, so there are no bias/dark/ flat overrides (unlike Dark/WLS).

Parameters:

l0_file_list (list of str, optional) – L0 files to stack. Defaults to self.l0_file_list.
nstream (int, optional) – Stream threshold passed to stack_frames.
sigma (float, optional) – Outlier rejection threshold passed to stack_frames.
master_path (str, optional) – If provided, calls self.save_master(‘L1’, master_path) at the end to persist the master L1 to a FITS file at this path.

class kpfpipe.modules.masters.Dark(l0_file_list, config=None)

Bases: BaseMasterModule

Construct a master dark frame from a stack of L0 dark exposures.

Standard reduction: a dark is bias-subtracted (_STANDARD_CALIBRATIONS = (“bias”,)). The associated master bias is subtracted from each frame via the shared _process_frame hook (CalibrationAssociation + ImageProcessing) before stacking with sigma-clipped statistics, interpolating bad pixels, and performing a final outlier pass. Outputs a KPFMasterL1 containing per-chip IMG, SNR, and MASK extensions, with IMG in electrons/sec.

Parameters:

l0_file_list (list of str) – Sorted list of L0 FITS file paths to stack.
config (None | dict | ConfigHandler) – Module configuration. Recognized keys: stack_sigma, chips.

info(): Print a summary of the module configuration and stacking results.

make_master_l1(l0_file_list=None, *, nstream=6, sigma=None, bias=None, master_path=None)

Build master dark from stack.

The constructed KPFMasterL1 is returned and cached on self.ml1_obj; pass master_path to also persist it to disk via save_master(‘L1’, …).

Parameters:

l0_file_list (list of str, optional) – L0 files to stack. Defaults to self.l0_file_list.
nstream (int, optional) – Stream threshold passed to stack_frames.
sigma (float, optional) – Outlier rejection threshold passed to stack_frames.
bias (bool | str | KPFMasterL1, optional) – Per-call master-bias override (same forms as ImageProcessing.perform: bool, a master filepath, or a KPFMasterL1 object). A dark’s standard is bias-only, so bias=False skips bias subtraction and bias=”/path/master_bias.fits” uses a specific master. Dark/flat are never applied to a dark, so they are not accepted.
master_path (str, optional) – If provided, calls self.save_master(‘L1’, master_path) at the end to persist the master L1 to a FITS file at this path.

class kpfpipe.modules.masters.Flat(l0_file_list, config=None)

Bases: BaseMasterModule

Construct a master flat frame from a stack of L0 flat exposures.

Standard reduction: a flat is bias- and dark-subtracted (_STANDARD_CALIBRATIONS = (“bias”, “dark”)). Not yet implemented.

Parameters:

l0_file_list (list of str) – Sorted list of L0 FITS file paths to stack.
config (None | dict | ConfigHandler) – Module configuration. Recognized keys: stack_sigma, chips.

info(): Print a summary of the module configuration (not yet implemented).

class kpfpipe.modules.masters.WLS(l0_file_list, config=None)

Bases: BaseMasterModule

Construct a master wavelength solution from a stack of WLS L0 exposures.

Each frame is processed individually through the L0→L2 pipeline. Fitted line positions across the stack are combined to derive per-fiber wavelength solutions.

Standard reduction: like science, a WLS frame is bias- and dark-subtracted before extraction (_STANDARD_CALIBRATIONS = (“bias”, “dark”)); flat division is part of the standard reduction but stays off until it is implemented.

Parameters:

l0_file_list (list of str) – Sorted list of L0 FITS file paths to process.
config (None | dict | ConfigHandler) – Module configuration. Recognized keys: linelist, lineprofile, polyorder_x, polyorder_m, polyorder_f, chips, fibers, min_stack_size (per-chip line-fit-QC survivor gate), KPF_MASTERS_OUTPUT.

info(): Print a summary of the module configuration and WLS results.

make_master_l2(l0_file_list=None, *, linelist=None, lineprofile=None, polyorder_x=None, polyorder_m=None, polyorder_f=None, bias=None, dark=None, flat=None, master_path=None)

Build a master wavelength solution from a stack of L0 frames.

Processes each input L0 frame through the L0-to-L2 pipeline, fits per-frame line positions and WLS coefficients (_fit_and_qc_lines_stack), then combines the surviving frames into per-chip Legendre wavelength solutions (_combine_coeffs_stack). The resulting wavelength arrays are written to the per-fiber _WAVE extensions of a KPFMasterL2 object, which is returned and cached on self.ml2_obj. Per-frame diagnostics are always stashed on self._frame_diagnostics; pass master_path to persist the master and, into the thar_L2/ subdirectory beside it, the per-frame L2s and the diagnostics HDF5.

Parameters:

l0_file_list (list of str, optional) – L0 files to process. Defaults to self.l0_file_list.
linelist (str, optional) – Path to a CSV line list. If different from the currently cached self.linelist, the file is reloaded and the cache is updated. Defaults to self.linelist (no reload).
lineprofile (str, optional) – Line profile model name. Defaults to self.lineprofile.
polyorder_x (int, optional) – Polynomial degree along the pixel axis. Defaults to self.polyorder_x.
polyorder_m (int, optional) – Polynomial degree along the order axis. Defaults to self.polyorder_m.
polyorder_f (int, optional) – Polynomial degree along the fiber axis (used for 3- and 5-fiber fits). Defaults to self.polyorder_f.
bias (bool | str | KPFMasterL1, optional) – Per-call calibration overrides (same forms as ImageProcessing.perform: bool, a master filepath, or a KPFMasterL1 object), clamped by the WLS standard of bias+dark. E.g. dark=False extracts with bias only, and dark=”/path/master_dark.fits” uses a specific master.
dark (bool | str | KPFMasterL1, optional) – Per-call calibration overrides (same forms as ImageProcessing.perform: bool, a master filepath, or a KPFMasterL1 object), clamped by the WLS standard of bias+dark. E.g. dark=False extracts with bias only, and dark=”/path/master_dark.fits” uses a specific master.
flat (bool | str | KPFMasterL1, optional) – Per-call calibration overrides (same forms as ImageProcessing.perform: bool, a master filepath, or a KPFMasterL1 object), clamped by the WLS standard of bias+dark. E.g. dark=False extracts with bias only, and dark=”/path/master_dark.fits” uses a specific master.
master_path (str, optional) – If provided, persists the master L2 to this FITS path via save_master(‘L2’, …) and, into a thar_L2/ subdirectory beside it, each processed ThAr frame’s L2 (save_reduced_frames()) and the per-frame diagnostics HDF5 (save_diagnostics()).

Returns:

Master L2 object with per-fiber _WAVE extensions populated for every chip in self.chips, INPUT_FILES recording the stacked L0 files, and a ‘master_wls’ receipt entry.

Return type:

KPFMasterL2

Notes

Resets self._l2_obj_cache before processing so repeat calls do not carry stale frames forward.

Line fitting is attempted for every loaded frame; a frame whose line-fit QC or per-frame fit fails is warned and dropped, never raised. The per-frame L2s and diagnostics HDF5 are written before the survivor gate, so they persist even on gate failure. Raises ValueError if any chip has fewer than self.min_stack_size frames passing line-fit QC (the master is then not written).

save_diagnostics(master_path, *, overwrite=False)

Write the per-frame WLS diagnostics to an HDF5 file in the thar_L2/ subdirectory beside master_path, named {obs_id}_master_thar_diagnostics.h5 (obs_id from master_path).

Layout: /<obs_id>/<chip>/ per input frame and chip, each holding a coeffs dataset (per-frame Legendre coefficients; omitted for a rejected frame), a lines/ group with every key from the per-frame line dict (chip, fiber, index, echelle, wav, pix, std, amp, isgood), and a rejected group attribute flagging whole-frame QC rejection for that chip.

Parameters:

master_path (str) – The master L2 output path; its directory anchors the thar_L2/ subdirectory and its obs_id names the file.
overwrite (bool, optional) – If False (default), refuse to clobber an existing file and raise FileExistsError. If True, replace any existing file.

Raises:

RuntimeError – If make_master_l2() has not been run yet, or raised before populating any chip.
FileExistsError – If the file already exists and overwrite is False.

save_reduced_frames(master_path, *, overwrite=False)

Write each processed ThAr frame’s L2 to a thar_L2/ subdirectory beside master_path, as {obs_id}_thar_L2.fits.

Persists the per-frame L2 objects cached by make_master_l2() (every frame that loaded, processed, and extracted), for follow-up ThAr line/WLS-stability analysis.

Parameters:

master_path (str) – The master L2 output path; its directory anchors the thar_L2/ subdirectory.
overwrite (bool, optional) – If False (default), refuse to clobber an existing per-frame file and raise FileExistsError. If True, replace any existing file.

Raises:

RuntimeError – If make_master_l2() has not been run yet, or raised before extracting any frame.
FileExistsError – If a per-frame file already exists and overwrite is False.

Submodules

`base`	Base class for KPF Masters modules.
`bias`	KPF Master Bias construction module.
`dark`	KPF Master Dark construction module.
`flat`	KPF Master Flat construction module.
`wls`	KPF Master Wavelength Solution construction module.