pypeit.scripts.ql module

Script for quick-look PypeIt reductions.

Use cases:

1. User inputs N files: arc, flat, science(s)

2. User inputs 1 or more science files for a fixed-format instrument (e.g. NIRES)

3. User inputs 1 folder of files

4. User inputs 1 folder of files including 1 new science frame

5. User inputs an ASCII file of files

6. User inputs 2 science files with A-B [and calibs or uses defaults]

7. User inputs N science files with A and B (only), stacks all files at A and B independently, A-B, add pos+neg

8. User inputs N science files with an arbitrary set of dither patterns that are encoded in the headers (e.g. MOSFIRE, currently this works for just one dither pattern, and that may be all we need). Total stack is computed

Notes with JFH:

1. Label B images as “sky” for A-B redux

2. Write spec2D A images to disk with a minus sign and call B

3. Consider not writing out but return instead

class pypeit.scripts.ql.QL

Bases: ScriptBase

classmethod get_parser(width=None)

Construct the command-line argument parser.

Derived classes should override this. Ideally they should use this base-class method to instantiate the ArgumentParser object and then fill in the relevant parser arguments

Warning

Any argument that defaults to the string 'current working directory' will be replaced by the result of os.getcwd() when the script is executed. This means help dialogs will include this replacement, and parsing of the command line will use os.getcwd() as the default. This functionality is largely to allow for PypeIt’s automated documentation of script help dialogs without the “current working” directory being that of the developer that most recently compiled the docs.

Parameters:

• description (str, optional) – A short description of the purpose of the script.

• width (int, optional) – Restrict the width of the formatted help output to be no longer than this number of characters, if possible given the help formatter. If None, the width is the same as the terminal width.

• formatter (argparse.HelpFormatter) – Class used to format the help output.

Returns:

Command-line interpreter.

Return type:

argparse.ArgumentParser

static main(args)

Execute the script.

pypeit.scripts.ql.calib_manifest(calib_dir, spectrograph)

Collate the list of setups with processed calibrations.

The calibrations must exist within the provided parent directory. The calibration directories must start with the PypeIt-specific name used for the relevant spectrograph (e.g., shane_kast_blue), and the sub-directories must have a pypeit file that provides the instrument configuration (setup). Directories that contain a pypeit file but no calibration subdirectory are ignored.

Parameters:

• calib_dir (str, Path) – Parent directory with the calibrations; see above. This directory must exist.

• spectrograph (str) – The PypeIt-specific name of the spectrograph.

Returns:

Dictionary with the list of instruments setups with available calibrations. If no calibrations are found, either because no pypeit files are found or none of the directories with pypeit files include a calibrations directory, None is returned. The dictionary has one item for every setup found. Each item includes all the configuration parameters used to define a unique setup for this instrument, and it also includes the item 'calib_dir' giving the directory with the processed calibrations.

Return type:

dict

pypeit.scripts.ql.folder_name_from_scifiles(sci_files: list)

Construct the directory name for QL output.

If one file, use the filename without its suffix (see remove_suffix()). If multiple files, use a dash-separated string of the first and last filenames (also without their suffixes).

Parameters:

sci_files (list) – List of str or Path objects with the science files.

Returns:

Directory name

Return type:

str

pypeit.scripts.ql.generate_sci_pypeitfile(redux_path: str, ref_calib_dir: Path, ps_sci, det: str | None = None, clear: bool = False, slitspatnum: str | None = None, maskID: str | None = None, boxcar_radius: float | None = None, snr_thresh: float | None = None, chk_version: bool = True)

Prepare to reduce the science frames:

• Correct the setup and calibration group for the science frames to be the same as the associated calibration files.

• Create the path for the science reductions, and including a symlink to the pre-processed (reference) calibration frames.

• Write the pypeit file with the requested parameter adjustments.

Parameters:

• redux_path (str) – Path to the redux folder

• ref_calib_dir (Path) – Path with the pre-processed calibration frames. A symlink will be created to this directory from within redux_path to mimic the location of the calibrations expected by PypeIt.

• ps_sci (PypeItSetup) – Setup object for the science frame(s) only.

• det (str, optional) – Detector/mosaic identifier. If None, all detectors are reduced.

• clear (bool, optional) – Remove the directory structure for these files; i.e., start a completely clean reduction. If false, any existing directory structure will remain, but any existing science reduction products will still be overwritten.

• slitspatnum (str, optional) – Used to identify the slit that should be reduced; see ReduxPar Keywords. If None, all slits are reduced.

• maskID (str, optional) – Slit identifier from the mask design, used to select a single slit to reduce. If None, all slits are reduced.

• boxcar_radius (float, optional) – Boxcar radius in arcsec used for extraction.

Returns:

The name of the pypeit file.

Return type:

str

pypeit.scripts.ql.get_files(raw_files, raw_path)

Use the user-provided input to get the files to process.

Parameters:

• raw_files (list) – The list of strings parsed from the raw_files command line argument. Can be None.

• raw_path (str) – The path to the raw files parsed from the raw_path command line argument.

Returns:

List of strings providing the full path to each raw file.

Return type:

list

pypeit.scripts.ql.get_setup_calib(calib_dir, calib_grp=None)

Using all of the files found in the provided directory, determine the setup and calibration group to use for the quicklook science frame(s).

Parameters:

• calib_dir (str, Path) – Directory with the calibration files.

• calib_grp (int, optional) – If the calibration directory contains results from more than one calibration group, this must be provided, specifying which calibration group should be used.

Returns:

The setup name and calibration group.

Return type:

tuple

pypeit.scripts.ql.match_to_calibs(ps: PypeItSetup, calib_dir: str, calibrated_setups=None)

Match observations to existing calibrations.

The function first builds the list of existing calibration setups; see calib_manifest(). Then, each setup for data provided by the PypeItSetup object is matched to the existing setups.

Parameters:

• ps (PypeItSetup) – Object providing metadata and parameters necessary to execute PypeIt data reduction. This must contain data from a single setup/configuration; an error is raised if not.

• calib_dir (str) – Parent directory with the calibrations; see calib_manifest(). This directory must exist.

Returns:

A nested dictionary with the matched setups. There is one dictionary key for each setup in ps. Each setup dictionary item is itself a dictionary with two items, setup and calib_dir, where setup is setup identifier of the existing calibrations (as opposed to the setups provided in ps) and the Path to the calibrations. If a setup in ps is not matched, the associated dictionary item is None.

Return type:

dict

pypeit.scripts.ql.merge_setups(calibrated_setups, calib_match, frame_setup)

Merge the setup identifiers for new reductions to those matched to existing reductions.

Parameters:

• calibrated_setups (array-like) – The list of setup identifiers with existing calibrations. This can be the list of keys in the top-level dictionary returned by calib_manifest(). This is used to determine the next identifier for new setups to be calibrated. All existing setups and every setup in calib_match must be included in this list.

• calib_match (dict) – A dictionary that provides, for each new setup to be reduced, the matched set of existing calibrations, if there are any. See match_to_calibs(). The identifier for any matched setup must be included in calibrated_setups.

• frame_setup (array-like) – The setups associated with each frame in the new set of reductions.

Returns:

The list of replacement setups for each frame that consolidates existing calibrations with new ones.

Return type:

list

pypeit.scripts.ql.print_offset_report(fitstbl: Table, platescale: float)

Print the dither pattern for a set of files to the screen.

The files in the provided table must come from a single dither pattern!

Parameters:

• fitstbl (astropy.table.Table) – Table with the file metadata. This should be the table extracted from a PypeItMetaData instance, selecting the relevant science frames.

• platescale (float) – The relevant (binned) pixelscale in arcsec/pixel.

pypeit.scripts.ql.quicklook_regroup(fitstbl)

Regroup frames for quick-look reductions.

Restrictions/Alterations applied are:

• Science and standard frames each must be observations of a single target (according to the 'target' keyword).

• For metadata tables where the background image are not set, all science and standard frames are each assigned to a single combination group, so that all observations are stacked.

• For metadata tables where the background images are set (e.g., for difference-imaging dither sequences), all frames of a given offset are combined (the column dithoff must exist). I.e., if there are multiple dither sequences peformed (e.g., ABBA, then ABBA), all with the same offset (e.g., +/- 5 arcsec), the image combination and background IDs are changed so that all the As are combined and all the Bs are combined before calculating the difference.

This function directly alters the input object!

Parameters:

fitstbl (PypeItMetaData) – Metadata table for frames to be processed.