Command-line Scripts

PypeIt is packaged with several scripts that should have been installed directly into your path (e.g. ~/anaconda/bin). This document provides brief summaries of each script and points to other pages with more information.

If you are developing a new script, see Developing New PypeIt Scripts.

Warning

Whenever you upgrade PypeIt, beware that this may include changes to the output file data models. These changes are not required to be backwards-compatible, meaning that, e.g., pypeit_show_2dspec may fault when trying to view spec2d* files produced with your existing PypeIt version after upgrading to a new version. The best approach is to always re-reduce data you’re still working with anytime you update PypeIt.


Installation Scripts

To install PypeIt, see Installation. The following scripts are used to install ancillary data not included in the baseline package distribution; see Additional Data.

pypeit_cache_github_data

Because a fresh install of PypeIt does not contain all of the ancillary data that might be required for data reduction, users planning to run the pipeline without an internet connection will need to cache the necessary data files ahead of time. The pypeit_cache_github_data script eases this process. For example, to download the needed files for the keck_deimos spectrograph, you would execute:

$ pypeit_cache_github_data keck_deimos

The script usage can be displayed by calling the script with the -h option:

$ pypeit_cache_github_data -h
usage: pypeit_cache_github_data [-h] [--force_update]
                                spectrograph [spectrograph ...]

Script to download/cache PypeIt github data

positional arguments:
  spectrograph    A valid spectrograph identifier: bok_bc, gemini_flamingos1,
                  gemini_flamingos2, gemini_gmos_north_e2v,
                  gemini_gmos_north_ham, gemini_gmos_north_ham_ns,
                  gemini_gmos_south_ham, gemini_gnirs_echelle, gemini_gnirs_ifu,
                  gtc_maat, gtc_osiris, gtc_osiris_plus, jwst_nircam,
                  jwst_nirspec, keck_deimos, keck_esi, keck_hires, keck_kcrm,
                  keck_kcwi, keck_lris_blue, keck_lris_blue_orig, keck_lris_red,
                  keck_lris_red_mark4, keck_lris_red_orig, keck_mosfire,
                  keck_nires, keck_nirspec_high, keck_nirspec_high_old,
                  keck_nirspec_low, lbt_luci1, lbt_luci2, lbt_mods1b,
                  lbt_mods1r, lbt_mods2b, lbt_mods2r, ldt_deveny, magellan_fire,
                  magellan_fire_long, magellan_mage, mdm_modspec,
                  mdm_osmos_mdm4k, mdm_osmos_r4k, mmt_binospec, mmt_bluechannel,
                  mmt_mmirs, not_alfosc, not_alfosc_vert, ntt_efosc2,
                  p200_dbsp_blue, p200_dbsp_red, p200_tspec, shane_kast_blue,
                  shane_kast_red, shane_kast_red_ret, soar_goodman_blue,
                  soar_goodman_red, tng_dolores, vlt_fors2, vlt_sinfoni,
                  vlt_xshooter_nir, vlt_xshooter_uvb, vlt_xshooter_vis,
                  wht_isis_blue, wht_isis_red

options:
  -h, --help      show this help message and exit
  --force_update  Force download of GitHub file (default: False)

pypeit_install_telluric

When needed, atmospheric model grids will be download automatically, but given the size of these files and your downlink speed, this may take some time. To install the grid independent of a reduction, run the pypeit_install_telluric script, calling the filename of the grid required. For example, if you needed the file TelFit_MaunaKea_3100_26100_R200000.fits, you would execute:

$ pypeit_install_telluric TelFit_MaunaKea_3100_26100_R200000.fits

The script usage can be displayed by calling the script with the -h option:

$ pypeit_install_telluric -h
usage: pypeit_install_telluric [-h] [--force_update] [--local_file]
                               files [files ...]

Script to download/install PypeIt telluric files

positional arguments:
  files           Filename(s) of the TelFits files to be downloaded from the
                  Cloud and installed in the PypeIt cache

options:
  -h, --help      show this help message and exit
  --force_update  Force download of latest version of the telluric grid
                  (default: False)
  --local_file    This is a local file (downloaded or created) to be installed
                  in the cache (default: False)

pypeit_install_ql_calibs

After downloading the QL_CALIB directory for use with the quick-look scripts, this script “installs” the files by creating a symlink to it within the PypeIt code base.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_install_ql_calibs -h
usage: pypeit_install_ql_calibs [-h] [--zip ZIP | --ql_path QL_PATH]
                                [--odir ODIR] [--rmzip]

Script to install PypeIt QL calibration files

options:
  -h, --help         show this help message and exit
  --zip ZIP          Zip file of the full QL_CALIB directory downloaded from the
                     PypeIt Google Drive (default: None)
  --ql_path QL_PATH  An existing directory to symlink as the QL_CALIB directory.
                     (default: None)
  --odir ODIR        The directory in which to extract the zip file. Ignored if
                     a direct path is provided using --ql_path. (default:
                     current working directory)
  --rmzip            Remove the downloaded zip file (default: False)

pypeit_install_linelist

If an instrument-specific arc line list that is not already included in the PypeIt repository is needed for a particular reduction, this script may be used to install a user-generated line list file in the user’s PypeIt cache. See User-Supplied Line Lists.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_install_linelist -h
usage: pypeit_install_linelist [-h] files [files ...]

Script to install user-created arc line lists

positional arguments:
  files       Filename(s) of the line list files to be installed in the PypeIt
              cache

options:
  -h, --help  show this help message and exit

pypeit_install_extinctfile

In the event of doing flux calibration for data from an observatory without an included extinction file in the PypeIt repository, this script may be used to install a user-supplied extinction file in the user’s PypeIt cache. See Extinction Correction.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_install_extinctfile -h
usage: pypeit_install_extinctfile [-h] files [files ...]

Script to install user-created extinction file

positional arguments:
  files       Filename(s) of the extinction file(s) to be installed in the
              PypeIt cache

options:
  -h, --help  show this help message and exit

pypeit_c_enabled

This is a simple script to check of the compiled C code used by PypeIt was successfully installed. The script takes no arguments and reports success if the C libraries were successfully imported.

pypeit_chk_plugins

This is a simple script to check if all ginga plugins are successfully installed. The script takes no arguments.

pypeit_version

This simply prints the PypeIt version you have installed.


Core Processing Scripts

The core data processing scripts provided by PypeIt perform the standard data reductions expected for all spectrographs. These include basic image processing, slit identification, wavelength calibration, flat-fielding, sky-subtraction, and 1D object extraction.

pypeit_chk_for_calibs

This script, which is similar to pypeit_setup, examines a set of files for an input spectrograph and scans for the standard calibrations. It raises warnings when these are not found.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_chk_for_calibs -h
usage: pypeit_chk_for_calibs [-h] [-s SPECTROGRAPH] [-e EXTENSION]
                             [--save_setups]
                             root

Script to check for calibrations

positional arguments:
  root                  File path+root, e.g. /data/Kast/b

options:
  -h, --help            show this help message and exit
  -s SPECTROGRAPH, --spectrograph SPECTROGRAPH
                        A valid spectrograph identifier: bok_bc,
                        gemini_flamingos1, gemini_flamingos2,
                        gemini_gmos_north_e2v, gemini_gmos_north_ham,
                        gemini_gmos_north_ham_ns, gemini_gmos_south_ham,
                        gemini_gnirs_echelle, gemini_gnirs_ifu, gtc_maat,
                        gtc_osiris, gtc_osiris_plus, jwst_nircam, jwst_nirspec,
                        keck_deimos, keck_esi, keck_hires, keck_kcrm, keck_kcwi,
                        keck_lris_blue, keck_lris_blue_orig, keck_lris_red,
                        keck_lris_red_mark4, keck_lris_red_orig, keck_mosfire,
                        keck_nires, keck_nirspec_high, keck_nirspec_high_old,
                        keck_nirspec_low, lbt_luci1, lbt_luci2, lbt_mods1b,
                        lbt_mods1r, lbt_mods2b, lbt_mods2r, ldt_deveny,
                        magellan_fire, magellan_fire_long, magellan_mage,
                        mdm_modspec, mdm_osmos_mdm4k, mdm_osmos_r4k,
                        mmt_binospec, mmt_bluechannel, mmt_mmirs, not_alfosc,
                        not_alfosc_vert, ntt_efosc2, p200_dbsp_blue,
                        p200_dbsp_red, p200_tspec, shane_kast_blue,
                        shane_kast_red, shane_kast_red_ret, soar_goodman_blue,
                        soar_goodman_red, tng_dolores, vlt_fors2, vlt_sinfoni,
                        vlt_xshooter_nir, vlt_xshooter_uvb, vlt_xshooter_vis,
                        wht_isis_blue, wht_isis_red (default: None)
  -e EXTENSION, --extension EXTENSION
                        File extension; compression indicators (e.g. .gz) not
                        required. (default: .fits)
  --save_setups         If not toggled, remove setup_files/ folder and its
                        files. (default: False)

A typical call is:

pypeit_chk_calibs /PypeIt-development-suite/RAW_DATA/not_alfosc/grism4/ALDc2 -s not_alfosc

After a running stream of detailed notes, it prints a table of results to the screen; e.g.:

setups pass     scifiles
------ -------- ---------------
     A False    ALDc200205.fits
  None True

pypeit_obslog

The pypeit_obslog script allows you to see a simple listing of the data files in a given directory (or directories) and the metadata that PypeIt will pull from their headers. See pypeit_obslog for details.

pypeit_setup

This is used to setup PypeIt for data reduction, including writing the automatically generated pypeit file that you will likely need to edit by hand. See pypeit_setup for details.

run_pypeit

This is the main executable for PypeIt for its core end-to-end data processing. See run_pypeit for details.

pypeit_trace_edges

This isolates the slit-edge tracing to a stand-alone script that can be used to troubleshoot issues before executing run_pypeit. See pypeit_trace_edges.

pypeit_compare_sky

You may find that the default sky models used for your spectrograph are not the best suited for your data. If so, this script allows you to plot a sky spectrum extracted from your data against any of the sky models in the PypeIt archive; see Alternate sky models.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_compare_sky -h
usage: pypeit_compare_sky [-h] [--exten EXTEN] [--optimal]
                          [--scale_user SCALE_USER]
                          file skyfile

Compare the extracted sky spectrum against an archived sky model maintained by
PypeIt.

positional arguments:
  file                  spec1d Spectral file
  skyfile               Archived PypeIt sky file (e.g. paranal_sky.fits)

options:
  -h, --help            show this help message and exit
  --exten EXTEN         FITS extension (default: None)
  --optimal             Show Optimal? Default is boxcar (default: False)
  --scale_user SCALE_USER
                        Scale user spectrum by a factor (default: 1.0)

pypeit_qa_html

Deprecated?

This script constructs the QA html files. This should be done by default at the end of the run_pypeit execution.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_qa_html -h
usage: pypeit_qa_html [-h] [--qapath QAPATH] pypeit_file type

Script to build HTML files for PYPIT QA.

positional arguments:
  pypeit_file      PYPIT file
  type             QA Type (MF, exp, all)

options:
  -h, --help       show this help message and exit
  --qapath QAPATH  Path the QA folder including QA/) (default: QA/)

Quick-look Scripts

PypeIt provides a script for faster, less robust data reductions for quick-look assessments of the data.

pypeit_ql

This script performs a boxcar (only) extraction of a long- or multi-slit observation taken with one of PypeIt’s spectrographs; see Quick-Look Reductions for full details.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_ql -h
usage: pypeit_ql [-h] [--raw_files RAW_FILES [RAW_FILES ...]]
                 [--raw_path RAW_PATH] [--sci_files SCI_FILES [SCI_FILES ...]]
                 [--redux_path REDUX_PATH] [--parent_calib_dir PARENT_CALIB_DIR]
                 [--setup_calib_dir SETUP_CALIB_DIR] [--clear_science]
                 [--calibs_only] [--overwrite_calibs] [--det DET [DET ...]]
                 [--slitspatnum SLITSPATNUM] [--maskID MASKID]
                 [--boxcar_radius BOXCAR_RADIUS] [--snr_thresh SNR_THRESH]
                 [--ignore_std] [--skip_display] [--coadd2d]
                 [--only_slits ONLY_SLITS [ONLY_SLITS ...]] [--offsets OFFSETS]
                 [--weights WEIGHTS] [--spec_samp_fact SPEC_SAMP_FACT]
                 [--spat_samp_fact SPAT_SAMP_FACT] [--try_old]
                 spectrograph

Script to produce quick-look PypeIt reductions

positional arguments:
  spectrograph          A valid spectrograph identifier: bok_bc,
                        gemini_flamingos1, gemini_flamingos2,
                        gemini_gmos_north_e2v, gemini_gmos_north_ham,
                        gemini_gmos_north_ham_ns, gemini_gmos_south_ham,
                        gemini_gnirs_echelle, gemini_gnirs_ifu, gtc_maat,
                        gtc_osiris, gtc_osiris_plus, jwst_nircam, jwst_nirspec,
                        keck_deimos, keck_esi, keck_hires, keck_kcrm, keck_kcwi,
                        keck_lris_blue, keck_lris_blue_orig, keck_lris_red,
                        keck_lris_red_mark4, keck_lris_red_orig, keck_mosfire,
                        keck_nires, keck_nirspec_high, keck_nirspec_high_old,
                        keck_nirspec_low, lbt_luci1, lbt_luci2, lbt_mods1b,
                        lbt_mods1r, lbt_mods2b, lbt_mods2r, ldt_deveny,
                        magellan_fire, magellan_fire_long, magellan_mage,
                        mdm_modspec, mdm_osmos_mdm4k, mdm_osmos_r4k,
                        mmt_binospec, mmt_bluechannel, mmt_mmirs, not_alfosc,
                        not_alfosc_vert, ntt_efosc2, p200_dbsp_blue,
                        p200_dbsp_red, p200_tspec, shane_kast_blue,
                        shane_kast_red, shane_kast_red_ret, soar_goodman_blue,
                        soar_goodman_red, tng_dolores, vlt_fors2, vlt_sinfoni,
                        vlt_xshooter_nir, vlt_xshooter_uvb, vlt_xshooter_vis,
                        wht_isis_blue, wht_isis_red

options:
  -h, --help            show this help message and exit
  --raw_files RAW_FILES [RAW_FILES ...]
                        Either a PypeIt-formatted input file with the list of
                        raw images to process and the relevant path, or a space-
                        separated list of the filenames (e.g., "img1.fits
                        img2.fits"). For the latter entry mode, the path
                        containing the files is set using --raw_path. (default:
                        None)
  --raw_path RAW_PATH   Directory with the raw files to process. Ignored if a
                        PypeIt-formatted file is provided using the --rawfiles
                        option. (default: current working directory)
  --sci_files SCI_FILES [SCI_FILES ...]
                        A space-separated list of raw file names that are
                        science exposures. These files must *also* be in the
                        list of raw files. Use of this option overrides the
                        automated PypeIt frame typing. Should only be used of
                        automatic frame typing fails or is undesirable.
                        (default: None)
  --redux_path REDUX_PATH
                        Path for the QL reduction outputs. (default: current
                        working directory)
  --parent_calib_dir PARENT_CALIB_DIR
                        Directory with/for calibrations for *all* instrument
                        configurations/setups. If provided, the data for your
                        instrument configuration will be placed or pulled from a
                        relevant sub-directory. If None, the redux_path is used.
                        (default: None)
  --setup_calib_dir SETUP_CALIB_DIR
                        Directory with/for calibrations specific to your
                        instrument configuration/setup. Use of this option
                        circumvents the automated naming system for the
                        configuration/setup sub-directories. If None, the code
                        will try to find relevant calibrations in the
                        parent_calib_dir. If no calibrations exist in that
                        directory that match the instrument setup/configuration
                        of the provided data, the code will construct new
                        calibrations (assuming relevant raw files are provided).
                        (default: None)
  --clear_science       Remove the existing output science directories to force
                        a fresh reduction. If False, any existing directory
                        structure will remain, and any alterations to existing
                        science files will follow the normal behavior of
                        run_pypeit. (default: False)
  --calibs_only         Reduce only the calibrations? (default: False)
  --overwrite_calibs    Re-process and overwrite any existing calibration files.
                        (default: False)
  --det DET [DET ...]   A space-separated set of detectors or detector mosaics
                        to reduce. By default, *all* detectors or default
                        mosaics for this instrument will be reduced. Detectors
                        in a mosaic must be a mosaic "allowed" by PypeIt and
                        should be provided as comma-separated integers (with no
                        spaces). For example, to separately reduce detectors 1
                        and 5 for Keck/DEIMOS, you would use --det 1 5; to
                        reduce mosaics made up of detectors 1,5 and 3,7, you
                        would use --det 1,5 3,7 (default: None)
  --slitspatnum SLITSPATNUM
                        Reduce the slit(s) as specified by the slitspatnum
                        value(s) (default: None)
  --maskID MASKID       Reduce the slit(s) as specified by the maskID value(s)
                        (default: None)
  --boxcar_radius BOXCAR_RADIUS
                        Set the radius for the boxcar extraction in arcseconds
                        (default: None)
  --snr_thresh SNR_THRESH
                        Change the default S/N threshold used during source
                        detection (default: None)
  --ignore_std          If standard star observations are automatically
                        detected, ignore those frames. Otherwise, they are
                        included with the reduction of the science frames.
                        (default: False)
  --skip_display        Run the quicklook without displaying any results.
                        (default: True)
  --coadd2d             Perform default 2D coadding. (default: False)
  --only_slits ONLY_SLITS [ONLY_SLITS ...]
                        If coadding, only coadd this space-separated set of
                        slits. If not provided, all slits are coadded. (default:
                        None)
  --offsets OFFSETS     If coadding, spatial offsets to apply to each image; see
                        the [coadd2d][offsets] parameter. Options are restricted
                        here to either maskdef_offsets or auto. If not
                        specified, the (spectrograph-specific) default is used.
                        (default: None)
  --weights WEIGHTS     If coadding, weights used to coadd images; see the
                        [coadd2d][weights] parameter. Options are restricted
                        here to either uniform or auto. If not specified, the
                        (spectrograph-specific) default is used. (default: None)
  --spec_samp_fact SPEC_SAMP_FACT
                        If coadding, adjust the wavelength grid sampling by this
                        factor. For a finer grid, set value to <1.0; for coarser
                        sampling, set value to >1.0). (default: 1.0)
  --spat_samp_fact SPAT_SAMP_FACT
                        If coadding, adjust the spatial grid sampling by this
                        factor. For a finer grid, set value to <1.0; for coarser
                        sampling, set value to >1.0). (default: 1.0)
  --try_old             Attempt to load old datamodel versions. A crash may
                        ensue.. (default: False)

Further Processing Scripts

PypeIt separates its Core Processing Scripts from subsequent processing steps, like flux calibration and coadding. The scripts that focus on the latter are as follows.

pypeit_sensfunc

Provided observations of a standard star, this script is used to create a sensitivity function of your observations given the known fluxes of the observed standard. See Fluxing and, specifically, pypeit_sensfunc.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_sensfunc -h
usage: pypeit_sensfunc [-h] [--algorithm {UVIS,IR}] [--multi MULTI] [-o OUTFILE]
                       [-s SENS_FILE] [-f FLATFILE] [--debug]
                       [--par_outfile PAR_OUTFILE] [-v VERBOSITY]
                       spec1dfile

Compute a sensitivity function

positional arguments:
  spec1dfile            spec1d file for the standard that will be used to
                        compute the sensitivity function

options:
  -h, --help            show this help message and exit
  --algorithm {UVIS,IR}
                        Override the default algorithm for computing the
                        sensitivity function.  Note that it is not possible to
                        set --algorithm and simultaneously use a .sens file with
                        the --sens_file option. If you are using a .sens file,
                        set the algorithm there via:

                            [sensfunc]
                                 algorithm = IR

                        The algorithm options are:

                        UVIS = Should be used for data with lambda < 7000A.  No
                        detailed model of telluric absorption but corrects for
                        atmospheric extinction.

                        IR = Should be used for data with lambbda > 7000A.
                        Performs joint fit for sensitivity function and telluric
                        absorption using HITRAN models.

  --multi MULTI         List of detector numbers to splice together for
                        instruments with multiple detectors arranged in the
                        spectral direction, e.g. --multi = '3,7'.  Note that it
                        is not possible to set --multi and simultaneously use a
                        .sens file with the --sens_file option.  If you are
                        using a .sens file, set the multi_spec_det param there
                        via:

                            [sensfunc]
                                multi_spec_det = 3,7

  -o OUTFILE, --outfile OUTFILE
                        Output file for sensitivity function. If not specified,
                        the sensitivity function will be written out to a
                        standard filename in the current working directory, i.e.
                        if the standard spec1d file is named
                        spec1d_b24-Feige66_KASTb_foo.fits the sensfunc will be
                        written to sens_b24-Feige66_KASTb_foo.fits. A QA file
                        will also be written as
                        sens_spec1d_b24-Feige66_KASTb_foo_QA.pdf and a file
                        showing throughput plots to
                        sens_spec1d_b24-Feige66_KASTb_foo_throughput.pdf. The
                        same extensions for QA and throughput will be used if
                        outfile is provided but with .fits trimmed off if it is
                        in the filename.
  -s SENS_FILE, --sens_file SENS_FILE
                        Configuration file with sensitivity function parameters
  -f FLATFILE, --flatfile FLATFILE
                        Use the flat file for computing the sensitivity
                        function.  Note that it is not possible to set
                        --flatfile and simultaneously use a .sens file with the
                        --sens_file option. If you are using a .sens file, set
                        the flatfile there via e.g.:

                            [sensfunc]
                                 flatfile = Calibrations/Flat_A_0_DET01.fits

                        Where Flat_A_0_DET01.fits is the flat file in your
                        Calibrations directory
  --debug               show debug plots?
  --par_outfile PAR_OUTFILE
                        Name of output file to save the parameters used by the
                        fit
  -v VERBOSITY, --verbosity VERBOSITY
                        Verbosity level between 0 [none] and 2 [all]. Default:
                        1. Level 2 writes a log with filename sensfunc_YYYYMMDD-
                        HHMM.log

pypeit_flux_setup

Once you have a set of 1D object spectra and a sensitivity function, this script helps you create the necessary input file to perform the flux calibration, 1d coadding, and telluric correction. See Fluxing (specifically, Applying the PypeIt Sensitivity Function), Coadd 1D Spectra, and Telluric correction for details.

Note you will need to hand edit the files generated by this script:

  • Double check the fluxing pypeit file (ending in .flux) to make sure that the correct sensitivity function files were found by the script, and were matched with the right spec1d files. This is in the section between flux read and flux end.

  • Remove unwanted spec1d files from the fluxing file.

  • The coadding pypeit file (ending in .coadd1d) includes all objects extracted from your main reduction, so you need to pick the ones you are interested in and remove all others in the coadding pypeit file (between coadd1d read and coadd1d end).

  • For echelle spectrographs, double check that the coadding pypeit file has the sensitivity function files matched to the correct spec1d files, and that the files have been correctly separated into different setups.

  • Add any additional configuration parameters if needed; see User-level Parameters.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_flux_setup -h
usage: pypeit_flux_setup [-h] [--name NAME] [--objmodel {qso,star,poly}]
                         paths [paths ...]

Setup configuration files to perform flux calibration, 1D coadding, and telluric
correction.

positional arguments:
  paths                 One or more paths for Science folders or sensitivity
                        functions. Sensitivity functions must start with 'sens_'
                        to be detected.

options:
  -h, --help            show this help message and exit
  --name NAME           The base name to use for the output files. Defaults to
                        the instrument name is used.
  --objmodel {qso,star,poly}
                        science object model used in the telluric fitting. The
                        options are:

                        qso = For quasars. You might need to set redshift,
                        bal_wv_min_max in the tell file.

                        star = For stars. You need to set star_type, star_ra,
                        star_dec, and star_mag in the tell_file.

                        poly = For other type object, You might need to set
                        fit_wv_min_max, and norder in the tell_file.

pypeit_flux_calib

Once you have a set of 1D object spectra and a sensitivity function, this script applies the flux calibration to your object spectra provided the necessary input file. See Fluxing and, specifically, Applying the PypeIt Sensitivity Function.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_flux_calib -h
usage: pypeit_flux_calib [-h] [--par_outfile] [-v VERBOSITY] [--try_old]
                         flux_file

Flux calibrate 1D spectra produced by PypeIt

positional arguments:
  flux_file             File to guide fluxing process.  This file must have the
                        following format:

                        flux read
                             filename | sensfile
                          spec1dfile1 | sensfile1
                          spec1dfile2 |
                             ...
                        flux end

                        OR

                        flux read
                             filename | sensfile
                          spec1dfile1 | sensfile1
                          spec1dfile2 | sensfile2
                          spec1dfile3 | sensfile3
                             ...
                        flux end

                        OR

                        [fluxcalib]
                          use_archived_sens = True
                        flux read
                             filename
                          spec1dfile1
                          spec1dfile2
                          spec1dfile3
                             ...
                        flux end

                        That is, you must specify either a sensfile for all
                        spec1dfiles on the first line, specify one sensfile for
                        each spec1dfile, or specify no sensfiles and use an
                        archived one.
                        Archived sensfiles are available for the following
                        spectrographs: keck_deimos


options:
  -h, --help            show this help message and exit
  --par_outfile         Output to save the parameters
  -v VERBOSITY, --verbosity VERBOSITY
                        Verbosity level between 0 [none] and 2 [all]. Default:
                        1. Level 2 writes a log with filename
                        flux_calib_YYYYMMDD-HHMM.log
  --try_old             Attempt to load old datamodel versions. A crash may
                        ensue..

pypeit_coadd_1dspec

This script coadds flux-calibrated 1D spectra; see Coadd 1D Spectra.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_coadd_1dspec -h
usage: pypeit_coadd_1dspec [-h] [--debug] [--show] [--par_outfile PAR_OUTFILE]
                           [-v VERBOSITY]
                           coadd1d_file

Coadd 1D spectra produced by PypeIt

positional arguments:
  coadd1d_file          File to guide coadding process.

                        ------------------------
                               MultiSlit
                        ------------------------

                        For coadding Multislit spectra the file must have the
                        following format (see docs for further details including
                        the use of paths):

                        [coadd1d]
                           coaddfile='output_filename.fits' # Optional

                           coadd1d read
                                filename | obj_id
                             spec1dfile1 | objid1
                             spec1dfile2 | objid2
                             spec1dfile3 | objid3
                                ...
                           coadd1d end

                         OR the coadd1d read/end block can look like

                          coadd1d read
                                filename | obj_id
                             spec1dfile1 | objid
                             spec1dfile2 |
                             spec1dfile3 |
                             ...
                          coadd1d end

                        That is the coadd1d block must be a two column list of
                        spec1dfiles and objids, but you can specify only a
                        single objid for all spec1dfiles on the first line

                        Where:

                        spec1dfile: full path to a PypeIt spec1dfile

                        objid: the object identifier. To determine the objids
                        inspect the spec1d_*.txt files or run pypeit_show_1dspec
                        spec1dfile --list

                        ------------------------
                                 Echelle
                        ------------------------

                        For coadding Echelle spectra the file must have the
                        following format (see docs for further details):

                        [coadd1d]
                           coaddfile='output_filename.fits' # Optional

                           coadd1d read
                                filename | obj_id | sensfile  | setup_id
                             spec1dfile1 | objid1 | sensfile1 | setup_id1
                             spec1dfile2 | objid2 | sensfile2 | setup_id2
                             spec1dfile3 | objid3 | sensfile3 | setup_id3
                                ...
                           coadd1d end

                         OR the coadd1d read/end block can look like

                          coadd1d read
                                filename | obj_id | sensfile  | setup_id
                             spec1dfile1 | objid1 | sensfile  | setup_id
                             spec1dfile2 |        |           |
                             spec1dfile3 |        |           |
                                ...
                           coadd1d end

                        That is the coadd1d block is a four column list of
                        spec1dfiles, objids, sensitivity function files, and
                        setup_ids, but you can specify only a single objid,
                        sensfile, and setup_id for all spec1dfiles on the first
                        line

                        Here:

                        spec1dfile: full path to a PypeIt spec1dfile

                        objid: the object identifier (see details above)

                        sensfile: full path to a PypeIt sensitivity function
                        file for the echelle setup in question

                        setup_id: string identifier for the echelle setup in
                        question, i.e. 'VIS', 'NIR', or 'UVB'

                        If the coaddfile is not given the output file will be
                        placed in the same directory as the first spec1d file.


options:
  -h, --help            show this help message and exit
  --debug               show debug plots?
  --show                show QA during coadding process
  --par_outfile PAR_OUTFILE
                        Output to save the parameters
  -v VERBOSITY, --verbosity VERBOSITY
                        Verbosity level between 0 [none] and 2 [all]. Default:
                        1. Level 2 writes a log with filename
                        coadd_1dspec_YYYYMMDD-HHMM.log

pypeit_tellfit

This script performs telluric corrections for flux-calibrated, coadded 1D spectra; see Telluric correction.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_tellfit -h
usage: pypeit_tellfit [-h] [--objmodel {qso,star,poly}] [-r REDSHIFT]
                      [-g TELL_GRID] [-p PCA_FILE] [-t TELL_FILE] [--debug]
                      [--plot] [--par_outfile PAR_OUTFILE] [-v VERBOSITY]
                      [--chk_version]
                      spec1dfile

Telluric correct a spectrum

positional arguments:
  spec1dfile            spec1d or coadd file that will be used for telluric
                        correction.

options:
  -h, --help            show this help message and exit
  --objmodel {qso,star,poly}
                        science object model used in the fitting. The options
                        are:

                        qso = For quasars. You might need to set redshift,
                        bal_wv_min_max in the tell file.

                        star = For stars. You need to set star_type, star_ra,
                        star_dec, and star_mag in the tell_file.

                        poly = For other type object, You might need to set
                        fit_wv_min_max, and norder in the tell_file.

  -r REDSHIFT, --redshift REDSHIFT
                        Specify redshift. Used with the --objmodel qso option
                        above.
  -g TELL_GRID, --tell_grid TELL_GRID
                        Telluric grid. You should download the giant grid file
                        to the pypeit/data/telluric folder. It should only be
                        passed if you want to overwrite the default tell_grid
                        that is set via each spectrograph file.
  -p PCA_FILE, --pca_file PCA_FILE
                        Quasar PCA fits file with full path. The default file
                        (qso_pca_1200_3100.fits) is stored in the
                        pypeit/data/telluric folder. If you change the fits
                        file, make sure to set the pca_lower and pca_upper in
                        the tell_file to specify the wavelength coverage of your
                        model. The defaults are pca_lower=1220. and
                        pca_upper=3100.
  -t TELL_FILE, --tell_file TELL_FILE
                        Configuration file to change default telluric
                        parameters.  Note that the parameters in this file will
                        be overwritten if you set argument in your terminal.
                        The --tell_file option requires a .tell file with the
                        following format:

                            [telluric]
                                 objmodel = qso
                                 redshift = 7.6
                                 bal_wv_min_max = 10825,12060
                        OR
                            [telluric]
                                 objmodel = star
                                 star_type = A0
                                 star_mag = 8.
                        OR
                            [telluric]
                                 objmodel = poly
                                 polyorder = 3
                                 fit_wv_min_max = 9000.,9500.

  --debug               show debug plots?
  --plot                Show the telluric corrected spectrum
  --par_outfile PAR_OUTFILE
                        Name of output file to save the parameters used by the
                        fit
  -v VERBOSITY, --verbosity VERBOSITY
                        Verbosity level between 0 [none] and 2 [all]. Default:
                        1. Level 2 writes a log with filename tellfit_YYYYMMDD-
                        HHMM.log
  --chk_version         Ensure the datamodels are from the current PypeIt
                        version. By default (consistent with previous
                        functionality) this is not enforced and crashes may
                        ensue ...

pypeit_collate_1d

This is a tool to help organize spectra in multiple spec1d files, group them by source, and flux/coadd them. See Collating 1D Spectra.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_collate_1d -h
usage: pypeit_collate_1d [-h] [--spec1d_files [SPEC1D_FILES ...]]
                         [--par_outfile PAR_OUTFILE] [--outdir OUTDIR]
                         [--spec1d_outdir SPEC1D_OUTDIR] [--tolerance TOLERANCE]
                         [--match_using MATCH_USING] [--dry_run] [--ignore_flux]
                         [--flux] [--exclude_slit_bm EXCLUDE_SLIT_BM]
                         [--exclude_serendip] [--wv_rms_thresh WV_RMS_THRESH]
                         [--refframe {observed,heliocentric,barycentric}]
                         [--chk_version] [-v VERBOSITY]
                         [input_file]

Flux/Coadd multiple 1d spectra from multiple nights and prepare a directory for
the KOA.

positional arguments:
  input_file            (Optional) File for guiding the collate process.
                        Parameters in this file are overidden by the command
                        line. The file must have the following format:

                        [collate1d]
                          tolerance             <tolerance>
                          outdir                <directory to place output files>
                          spec1d_outdir         <directory to place modified spec1ds, if any>
                          exclude_slit_trace_bm <slit types to exclude>
                          exclude_serendip      If set serendipitous objects are skipped.
                          match_using           Whether to match using "pixel" or
                                                "ra/dec"
                          dry_run               If set the matches are displayed
                                                without any processing
                          flux                  Flux calibrate using archived sensfuncs.
                          ignore_flux           Ignore any flux calibration information in
                                                spec1d files.
                          wv_rms_thresh         If set, any objects with a wavelength rms > than the input
                                                value are skipped, else all wavelength rms values are accepted.
                          refframe              Perform reference frame correction prior to coadding.
                                                Options are ['observed', 'heliocentric', 'barycentric']. Defaults to None.

                        spec1d read
                        <path to spec1d files, wildcards allowed>
                        ...
                        end

options:
  -h, --help            show this help message and exit
  --spec1d_files [SPEC1D_FILES ...]
                        One or more spec1d files to flux/coadd/archive. Can
                        contain wildcards
  --par_outfile PAR_OUTFILE
                        Output to save the parameters
  --outdir OUTDIR       The path where all coadded output files and report files
                        will be placed. Defaults to the current directory.
  --spec1d_outdir SPEC1D_OUTDIR
                        The path where all modified spec1d files are placed.
                        These are only created if flux calibration or refframe
                        correction are asked for. Defaults to overwriting
                        existing spec1ds.
  --tolerance TOLERANCE
                        The tolerance used when comparing the coordinates of
                        objects. If two objects are within this distance from
                        each other, they are considered the same object. If
                        match_using is 'ra/dec' (the default) this is an angular
                        distance. The defaults units are arcseconds but other
                        units supported by astropy.coordinates.Angle can be used
                        (`e.g.`, '0.003d' or '0h1m30s'). If match_using is
                        'pixel' this is a float.
  --match_using MATCH_USING
                        Determines how 1D spectra are matched as being the same
                        object. Must be either 'pixel' or 'ra/dec'.
  --dry_run             If set, the script will display the matching File and
                        Object Ids but will not flux, coadd or archive.
  --ignore_flux         If set, the script will only coadd non-fluxed spectra
                        even if flux data is present. Otherwise fluxed spectra
                        are coadded if all spec1ds have been fluxed calibrated.
  --flux                If set, the script will flux calibrate using archived
                        sensfuncs before coadding.
  --exclude_slit_bm EXCLUDE_SLIT_BM
                        A list of slit trace bitmask bits that should be
                        excluded. Comma separated.
  --exclude_serendip    Whether to exclude SERENDIP objects from collating.
  --wv_rms_thresh WV_RMS_THRESH
                        If set, any objects with a wavelength RMS > this value
                        are skipped, else all wavelength RMS values are
                        accepted.
  --refframe {observed,heliocentric,barycentric}
                        Perform reference frame correction prior to coadding.
                        Options are: observed, heliocentric, barycentric
  --chk_version         If True enforce strict PypeIt version checking to ensure
                        that all files were created with the current version of
                        PypeIt. If set to False, the code will attempt to read
                        out-of-date files and keep going. Beware (!!) that this
                        can lead to unforeseen bugs that either cause the code
                        to crash or lead to erroneous results. I.e., you really
                        need to know what you are doing if you set this to
                        False!
  -v VERBOSITY, --verbosity VERBOSITY
                        Verbosity level between 0 [none] and 2 [all]. Default:
                        1. Level 2 writes a log with filename
                        collate_1d_YYYYMMDD-HHMM.log

pypeit_multislit_flexure

This script calculates a flexure correction across multiple detectors, i.e. with an expanded wavelength coverage. Thus far, it has only been developed and fine-tuned for the 1200 line grating of Keck/DEIMOS. See Flexure Correction and, specifically, pypeit_multislit_flexure.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_multislit_flexure -h
usage: pypeit_multislit_flexure [-h] [--clobber] [--debug] flex_file outroot

Calculate and apply flexure corrections for 1D spectra produced by PypeIt.

positional arguments:
  flex_file   File to guide flexure corrections for this multi-slit mode.  This
              file must have the following format:

              flexure read
                filename
                spec1dfile1
                spec1dfile2
                   ...
              flexure end


  outroot     Output fileroot for the flexure fits saved as FITS.

options:
  -h, --help  show this help message and exit
  --clobber   Clobber output files
  --debug     show debug plots?

pypeit_setup_coadd2d

This is used to setup a coadd2d file for performing 2D coadds; see Coadd 2D Spectra.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_setup_coadd2d -h
usage: pypeit_setup_coadd2d [-h]
                            (-f PYPEIT_FILE | -d SCIENCE_DIR [SCIENCE_DIR ...])
                            [--keep_par] [--obj OBJ [OBJ ...]]
                            [--det DET [DET ...]]
                            [--only_slits ONLY_SLITS [ONLY_SLITS ...]]
                            [--exclude_slits EXCLUDE_SLITS [EXCLUDE_SLITS ...]]
                            [--spat_toler SPAT_TOLER] [--offsets OFFSETS]
                            [--weights WEIGHTS]

Prepare a configuration file for performing 2D coadds

options:
  -h, --help            show this help message and exit
  -f PYPEIT_FILE, --pypeit_file PYPEIT_FILE
                        PypeIt reduction file (default: None)
  -d SCIENCE_DIR [SCIENCE_DIR ...], --science_dir SCIENCE_DIR [SCIENCE_DIR ...]
                        One or more directories with spec2d files to stack (use
                        wildcard to specify multiple directories). (default:
                        None)
  --keep_par            Propagate all parameters from the pypeit file to the
                        coadd2d file(s). If not set, only the required
                        parameters and their default values are included in the
                        output file(s). (default: True)
  --obj OBJ [OBJ ...]   Limit the coadd2d files created to observations of the
                        specified target. If not provided, a coadd2D file is
                        written for each target found in the science directory.
                        The target names are included in the PypeIt spec2d file
                        names.For example, the target for spec2d file "spec2d_cN
                        20170331S0216-pisco_GNIRS_20170331T085412.181.fits" is
                        "pisco". (default: None)
  --det DET [DET ...]   A space-separated set of detectors or detector mosaics
                        to coadd. By default, *all* detectors or default mosaics
                        for this instrument will be coadded. Detectors in a
                        mosaic must be a mosaic "allowed" by PypeIt and should
                        be provided as comma-separated integers (with no
                        spaces). For example, to separately coadd detectors 1
                        and 5 for Keck/DEIMOS, you would use --det 1 5; to coadd
                        mosaics made up of detectors 1,5 and 3,7, you would use
                        --det 1,5 3,7 (default: None)
  --only_slits ONLY_SLITS [ONLY_SLITS ...]
                        A space-separated set of slits to coadd. Example syntax
                        for argument is DET01:175,DET02:205 or MSC02:2234. If
                        not provided, all slits are coadded. If both --det and
                        --only_slits are provided, --det will be ignored. This
                        and --exclude_slits are mutually exclusive. If both are
                        provided, --only_slits takes precedence. (default: None)
  --exclude_slits EXCLUDE_SLITS [EXCLUDE_SLITS ...]
                        A space-separated set of slits to exclude in the
                        coaddition. This and --only_slits are mutually
                        exclusive. If both are provided, --only_slits takes
                        precedence. (default: None)
  --spat_toler SPAT_TOLER
                        Desired tolerance in spatial pixel used to identify
                        slits in different exposures. If not provided, the
                        default value for the specific instrument/configuration
                        is used. (default: None)
  --offsets OFFSETS     Spatial offsets to apply to each image; see the
                        [coadd2d][offsets] parameter. Options are restricted
                        here to either maskdef_offsets or auto. If not
                        specified, the (spectrograph-specific) default is used.
                        Other options exist but must be entered by directly
                        editing the coadd2d file. (default: None)
  --weights WEIGHTS     Weights used to coadd images; see the [coadd2d][weights]
                        parameter. Options are restricted here to either uniform
                        or auto. If not specified, the (spectrograph-specific)
                        default is used. Other options exist but must be entered
                        by directly editing the coadd2d file. (default: None)

pypeit_coadd_2dspec

This script combines 2D spectral output from run_pypeit for multiple observations of the same (set of) target(s). See Coadd 2D Spectra.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_coadd_2dspec -h
usage: pypeit_coadd_2dspec [-h] [--show] [--debug_offsets] [--peaks]
                           [--basename BASENAME] [--debug] [-v VERBOSITY]
                           [--spec_samp_fact SPEC_SAMP_FACT]
                           [--spat_samp_fact SPAT_SAMP_FACT]
                           coadd2d_file

Coadd 2D spectra produced by PypeIt

positional arguments:
  coadd2d_file          File to guide 2d coadds

options:
  -h, --help            show this help message and exit
  --show                Show the reduction steps. Equivalent to the -s option
                        when running pypeit. (default: False)
  --debug_offsets       Show QA plots useful for debugging automatic offset
                        determination (default: False)
  --peaks               Show the peaks found by the object finding algorithm.
                        (default: False)
  --basename BASENAME   Basename of files to save the parameters, spec1d, and
                        spec2d (default: None)
  --debug               show debug plots? (default: False)
  -v VERBOSITY, --verbosity VERBOSITY
                        Verbosity level between 0 [none] and 2 [all]. Default:
                        1. Level 2 writes a log with filename
                        coadd_2dspec_YYYYMMDD-HHMM.log (default: 1)
  --spec_samp_fact SPEC_SAMP_FACT
                        Make the wavelength grid finer (spec_samp_fact < 1.0) or
                        coarser (spec_samp_fact > 1.0) by this sampling factor,
                        i.e. units of spec_samp_fact are pixels. (default: 1.0)
  --spat_samp_fact SPAT_SAMP_FACT
                        Make the spatial grid finer (spat_samp_fact < 1.0) or
                        coarser (spat_samp_fact > 1.0) by this sampling factor,
                        i.e. units of spat_samp_fact are pixels. (default: 1.0)

pypeit_coadd_datacube

This script combines 2D spectral output from run_pypeit for multiple IFU observations of the same (set of) target(s) into a 3D datacube. See Coadd 3D Spectra.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_coadd_datacube -h
usage: pypeit_coadd_datacube [-h] [--det DET] [-o] [-v VERBOSITY] file

Read in an array of spec2D files and convert them into a datacube

positional arguments:
  file                  filename.coadd3d file

options:
  -h, --help            show this help message and exit
  --det DET             Detector (default: 1)
  -o, --overwrite       Overwrite any existing files/directories (default:
                        False)
  -v VERBOSITY, --verbosity VERBOSITY
                        Verbosity level between 0 [none] and 2 [all]. Default:
                        1. Level 2 writes a log with filename
                        coadd_datacube_YYYYMMDD-HHMM.log (default: 1)

Inspection Scripts

PypeIt provides numerous scripts for helping you inspect its outputs, mostly by loading and displaying the data in a ginga viewer. The provided scripts are as follows.

pypeit_view_fits

This is a simple, general-purpose wrapper to the ginga image viewer that allows you to open and view both raw and processed files.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_view_fits -h
usage: pypeit_view_fits [-h] [--list] [--proc] [--bkg_file BKG_FILE]
                        [--exten EXTEN] [--det [DET ...]] [--chname CHNAME]
                        [--showmask] [--embed]
                        spectrograph file

View FITS files with ginga

positional arguments:
  spectrograph         A valid spectrograph identifier: bok_bc,
                       gemini_flamingos1, gemini_flamingos2,
                       gemini_gmos_north_e2v, gemini_gmos_north_ham,
                       gemini_gmos_north_ham_ns, gemini_gmos_south_ham,
                       gemini_gnirs_echelle, gemini_gnirs_ifu, gtc_maat,
                       gtc_osiris, gtc_osiris_plus, jwst_nircam, jwst_nirspec,
                       keck_deimos, keck_esi, keck_hires, keck_kcrm, keck_kcwi,
                       keck_lris_blue, keck_lris_blue_orig, keck_lris_red,
                       keck_lris_red_mark4, keck_lris_red_orig, keck_mosfire,
                       keck_nires, keck_nirspec_high, keck_nirspec_high_old,
                       keck_nirspec_low, lbt_luci1, lbt_luci2, lbt_mods1b,
                       lbt_mods1r, lbt_mods2b, lbt_mods2r, ldt_deveny,
                       magellan_fire, magellan_fire_long, magellan_mage,
                       mdm_modspec, mdm_osmos_mdm4k, mdm_osmos_r4k,
                       mmt_binospec, mmt_bluechannel, mmt_mmirs, not_alfosc,
                       not_alfosc_vert, ntt_efosc2, p200_dbsp_blue,
                       p200_dbsp_red, p200_tspec, shane_kast_blue,
                       shane_kast_red, shane_kast_red_ret, soar_goodman_blue,
                       soar_goodman_red, tng_dolores, vlt_fors2, vlt_sinfoni,
                       vlt_xshooter_nir, vlt_xshooter_uvb, vlt_xshooter_vis,
                       wht_isis_blue, wht_isis_red
  file                 FITS file

options:
  -h, --help           show this help message and exit
  --list               List the extensions only? (default: False)
  --proc               Process the image (i.e. orient, overscan subtract,
                       multiply by gain) using pypeit.images.buildimage.
                       (default: False)
  --bkg_file BKG_FILE  FITS file to be subtracted from the image in file.--proc
                       must be set in order for this option to work. (default:
                       None)
  --exten EXTEN        Show a FITS extension in the raw file. Note --proc and
                       --mosaic will not work with this option. (default: None)
  --det [DET ...]      Detector(s) to show. If more than one, the list of
                       detectors, i.e. --det 4 8 to show detectors 4 and 8. This
                       combination must be one of the allowed mosaics hard-coded
                       for the selected spectrograph. Using "mosaic" for
                       gemini_gmos, keck_deimos, or keck_lris will show the
                       mosaic of all detectors. (default: 1)
  --chname CHNAME      Name of Ginga tab (default: Image)
  --showmask           Overplot masked pixels (default: False)
  --embed              Upon completion embed in ipython shell (default: False)

pypeit_chk_alignments

This script simply shows the Alignments file for visual inspection; see Alignment.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_chk_alignments -h
usage: pypeit_chk_alignments [-h] [--chname CHNAME] [--try_old] file

Display Alignment image and the trace data

positional arguments:
  file             PypeIt Alignment file [e.g. Alignment_A_1_DET01.fits]

options:
  -h, --help       show this help message and exit
  --chname CHNAME  Channel name for image in Ginga (default: Alignments)
  --try_old        Attempt to load old datamodel versions. A crash may ensue..
                   (default: False)

pypeit_chk_edges

Inspect the slit/order edges identified by PypeIt in a ginga window. See Slit Tracing.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_chk_edges -h
usage: pypeit_chk_edges [-h] [--slits_file SLITS_FILE] [--mpl] [--try_old]
                        trace_file

Display trace image and edge traces

positional arguments:
  trace_file            PypeIt Edges file [e.g. Edges_A_0_DET01.fits.gz]

options:
  -h, --help            show this help message and exit
  --slits_file SLITS_FILE
                        PypeIt Slits file [e.g. Slits_A_1_01.fits]. If this file
                        does not exist or is not provided, PypeIt will attempt
                        to read the default file name (in the Calibrations
                        directory). Ignored if plotting using a matplotlib
                        window instead of ginga. (default: None)
  --mpl                 Use a matplotlib window instead of ginga to show the
                        trace (default: False)
  --try_old             Attempt to load old datamodel versions. A crash may
                        ensue.. (default: False)

pypeit_parse_slits

This script prints a simple summary of the state of the reduction for all of the slits in a given Spec2D Output or Slits file. Here is a standard call:

pypeit_parse_slits spec2d_d0315_45929-agsmsk_DEIMOS_2018Mar15T124523.587.fits

And the output to screen will look like:

================ DET 04 ======================
SpatID  MaskID  Flags
0021    958445    None
0073    958470    None
0143    958434    None
0212    958458    None
0278    958410    None
0479    958400    None
1257    958466    None
1352    958392    BOXSLIT
1413    958396    None
1492    958403    None
1568    958457    None
1640    958405    None
1725    958435    None
1818    958422    None
1880    958390    BOXSLIT
1984    958393    BOXSLIT

The MaskID will be populated only if the instrument includes mask design (e.g. Keck/DEIMOS). The Flags column describes failure modes or reasons why the slit was not reduced. None is the preferred state for a science slit.

pypeit_chk_wavecalib

This script prints a set of simple wavelength calibration diagnostics for all of the slits in a given Spec2D Output or WaveCalib file. See pypeit_chk_wavecalib for more details. Standard command-line calls are:

pypeit_chk_wavecalib Science/spec2d_DE.20100913.22358-CFHQS1_DEIMOS_20100913T061231.334.fits

or:

pypeit_chk_wavecalib Calibrations/WaveCalib_A_1_DET07.fits

The script usage can be displayed by calling the script with the -h option:

$ pypeit_chk_wavecalib -h
usage: pypeit_chk_wavecalib [-h] [--try_old] input_file [input_file ...]

Print QA on Wavelength Calib to the screen

positional arguments:
  input_file  One or more PypeIt WaveCalib file [e.g. WaveCalib_A_1_DET01.fits]
              or spec2d file

options:
  -h, --help  show this help message and exit
  --try_old   Attempt to load old datamodel versions. A crash may ensue..
              (default: False)

pypeit_show_wvcalib

Allows the user to plot the calibrated arc spectrum for a given slit/order. This is primarily useful for generating new wavelength solutions. Here is a standard call:

pypeit_show_wvcalib WaveCalib_A_1_DET01.fits 17 --is_order  # for magellan_mage

This launches a matplotlib GUI plot of Order=17 for the magellan_mage spectrograph.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_show_wvcalib -h
usage: pypeit_show_wvcalib [-h] [--slit_file SLIT_FILE] [--is_order] [--try_old]
                           file slit_order

Show the result of wavelength calibration

positional arguments:
  file                  WaveCalib file
  slit_order            Slit or Order number

options:
  -h, --help            show this help message and exit
  --slit_file SLIT_FILE
                        Slit file (default: None)
  --is_order            Input slit/order is an order (default: False)
  --try_old             Attempt to load old datamodel versions. A crash may
                        ensue.. (default: False)

pypeit_show_arxiv

This script simply plots the selected archive arc spectrum from PypeIt’s pypeit/data/arc_liens/reid_arxiv directory.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_show_arxiv -h
usage: pypeit_show_arxiv [-h] [--det DET] file

Show an archived arc spectrum located in pypeit/data/arc_liens/reid_arxiv

positional arguments:
  file        Arxiv filename, e.g. gemini_gmos_r831_ham.fits

options:
  -h, --help  show this help message and exit
  --det DET   Detector number (default: 1)

pypeit_chk_tilts

This script displays Tiltimg and 2D fitted tilts in a ginga viewer or matplotlib window, allowing to assess the quality of the tilts calibration. See pypeit_chk_tilts for more details.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_chk_tilts -h
usage: pypeit_chk_tilts [-h] [--mpl] [--show_traces] [--try_old] file

Display Tiltimg image and 2D fitted tilts in Ginga viewer or Matplotlib window.
Tiltimg file must be in the same directory as Tilts.

positional arguments:
  file           PypeIt Tilts file [e.g. Tilt_A_1_01.fits]

options:
  -h, --help     show this help message and exit
  --mpl          Use a matplotlib window instead of ginga to show the tilts.
                 Faster plotting. (default: False)
  --show_traces  Show the traced tilts. This slows down the plotting (mostly in
                 Ginga). If not set, only the fitted, masked and rejected in the
                 fit tilts are shown. (default: False)
  --try_old      Attempt to load old datamodel versions. A crash may ensue..
                 (default: False)

pypeit_chk_flats

Inspect the flat field images produced by PypeIt in a RC Ginga window. This includes the stacked ‘raw’ image, the pixel flat, the illumination flat, and the flat model.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_chk_flats -h
usage: pypeit_chk_flats [-h] [--type TYPE] [--try_old] file

Display flat images in Ginga viewer

positional arguments:
  file         PypeIt Flat file [e.g. Flat_A_1_DET01.fits]

options:
  -h, --help   show this help message and exit
  --type TYPE  Which flats to display. Must be one of: pixel, illum, all
               (default: all)
  --try_old    Attempt to load old datamodel versions. A crash may ensue..
               (default: False)

pypeit_show_2dspec

This script displays the sky-subtracted 2D image for a single detector in a ginga RC viewer. See pypeit_show_2dspec.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_show_2dspec -h
usage: pypeit_show_2dspec [-h] [--list] [--det DET] [--spat_id SPAT_ID]
                          [--maskID MASKID] [--showmask [SHOWMASK ...]]
                          [--removetrace] [--embed] [--ignore_extract_mask]
                          [--channels CHANNELS] [--prefix PREFIX] [--no_clear]
                          [-v VERBOSITY] [--try_old]
                          file

Display sky subtracted, spec2d image in a ginga viewer.

positional arguments:
  file                  Path to a PypeIt spec2d file

options:
  -h, --help            show this help message and exit
  --list                List the extensions only? (default: False)
  --det DET             Detector name or number. If a number, the name is
                        constructed assuming the reduction is for a single
                        detector. If a string, it must match the name of the
                        detector object (e.g., DET01 for a detector, MSC01 for a
                        mosaic). (default: 1)
  --spat_id SPAT_ID     Restrict plotting to this slit (PypeIt ID notation)
                        (default: None)
  --maskID MASKID       Restrict plotting to this maskID (default: None)
  --showmask [SHOWMASK ...]
                        Include a channel showing the mask. If no arguments are
                        provided, the mask bit values are provided directly. You
                        can also specify one or more mask flags used to
                        construct an image identifying which pixels are flagged
                        by any of these issues. E.g., to show pixels flagged by
                        the instrument specific bad-pixel mask or cosmic arrays,
                        use --showmask BPM CR . See
                        https://pypeit.readthedocs.io/en/release/out_masks.html
                        for the list of flags. (default: None)
  --removetrace         Do not overplot traces in the skysub, sky_resid, and
                        resid channels (default: False)
  --embed               Upon completion embed in ipython shell (default: False)
  --ignore_extract_mask
                        Ignore the extraction mask (default: False)
  --channels CHANNELS   Only show a subset of the channels (0-indexed), e.g. 1,3
                        (default: None)
  --prefix PREFIX       Channel name prefix [lets you display more than one set]
                        (default: )
  --no_clear            Do *not* clear all existing tabs (default: True)
  -v VERBOSITY, --verbosity VERBOSITY
                        Verbosity level between 0 [none] and 2 [all] (default:
                        1)
  --try_old             Attempt to load old datamodel versions. A crash may
                        ensue.. (default: False)

pypeit_chk_noise_2dspec

Script to view the \(chi\) distribution of the residuals for a processed slit (or order) of the 2D image. Both the sky and object model are subtracted.

Ideally, one sees an image without structure and that the chi values are unit Gaussian distributed.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_chk_noise_2dspec -h
usage: pypeit_chk_noise_2dspec [-h] [--det DET] [--z [Z ...]]
                               [--maskdef_id MASKDEF_ID] [--pypeit_id PYPEIT_ID]
                               [--pad PAD] [--aspect_ratio ASPECT_RATIO]
                               [--wavemin WAVEMIN] [--wavemax WAVEMAX]
                               [--mode MODE] [--list] [--try_old]
                               [files ...]

Examine the noise in a PypeIt slit/order

positional arguments:
  files                 PypeIt spec2d file(s) (default: None)

options:
  -h, --help            show this help message and exit
  --det DET             Detector name or number. If a number, the name is
                        constructed assuming the reduction is for a single
                        detector. If a string, it must match the name of the
                        detector object (e.g., DET01 for a detector, MSC01 for a
                        mosaic). (default: 1)
  --z [Z ...]           Object redshift (default: None)
  --maskdef_id MASKDEF_ID
                        MASKDEF_ID of the slit that you want to plot. If
                        maskdef_id is not provided, nor a pypeit_id, all the 2D
                        spectra in the file(s) will be plotted. (default: None)
  --pypeit_id PYPEIT_ID
                        PypeIt ID of the slit that you want to plot. If
                        pypeit_id is not provided, nor a maskdef_id, all the 2D
                        spectra in the file(s) will be plotted. (default: None)
  --pad PAD             Padding for the selected slit. Negative value will trim.
                        (default: -5)
  --aspect_ratio ASPECT_RATIO
                        Aspect ratio when plotting the spec2d (default: 3)
  --wavemin WAVEMIN     Wavelength min. This is for selecting a region of the
                        spectrum to analyze. (default: None)
  --wavemax WAVEMAX     Wavelength max. This is for selecting a region of the
                        spectrum to analyze. (default: None)
  --mode MODE           Options are: [plot, save, print]. "plot" will open a
                        plot in a mpl window. "save" will create a folder called
                        spec2d*_noisecheck where all the relevant plots will be
                        placed. "print" will cause the check noise values to be
                        printed in the terminal. (default: plot)
  --list                List the extensions only? (default: False)
  --try_old             Attempt to load old datamodel versions. A crash may
                        ensue.. (default: False)

Here is an example from the Dev Suite:

pypeit_chk_noise_2dspec spec2d_s190519_0067-J1450+3302_NIRES_20190519T095152.165.fits --pypeit_id 6

pypeit_show_1dspec

This script loads a 1D spectrum file from PypeIt and launches a GUI from the linetools package for inspection; see pypeit_show_1dspec.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_show_1dspec -h
usage: pypeit_show_1dspec [-h] [--list] [--exten EXTEN] [--obj OBJ]
                          [--extract EXTRACT] [--flux] [-m]
                          file

Show a 1D spectrum

positional arguments:
  file               Spectral file

options:
  -h, --help         show this help message and exit
  --list             List the extensions only? (default: False)
  --exten EXTEN      FITS extension (default: 1)
  --obj OBJ          Object name in lieu of extension, e.g.
                     SPAT0424-SLIT0000-DET01 (default: None)
  --extract EXTRACT  Extraction method. Default is OPT. ['BOX', 'OPT'] (default:
                     OPT)
  --flux             Show fluxed spectrum? (default: False)
  -m, --unmasked     Only show unmasked data. (default: True)

pypeit_chk_noise_1dspec

Script to view the \(\chi\) distribution of the residuals for a processed spectrum. This makes most sense if restricted to a region of the spectrum without signal.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_chk_noise_1dspec -h
usage: pypeit_chk_noise_1dspec [-h] [--fileformat FILEFORMAT]
                               [--extraction EXTRACTION] [--ploterr] [--step]
                               [--z [Z ...]] [--maskdef_objname MASKDEF_OBJNAME]
                               [--pypeit_name PYPEIT_NAME] [--wavemin WAVEMIN]
                               [--wavemax WAVEMAX] [--plot_or_save PLOT_OR_SAVE]
                               [--try_old]
                               [files ...]

Examine the noise in a PypeIt spectrum

positional arguments:
  files                 PypeIt spec1d file(s) (default: None)

options:
  -h, --help            show this help message and exit
  --fileformat FILEFORMAT
                        Is this coadd1d or spec1d? (default: spec1d)
  --extraction EXTRACTION
                        If spec1d, which extraction? opt or box (default: opt)
  --ploterr             Plot noise spectrum (default: False)
  --step                Use `steps-mid` as linestyle (default: False)
  --z [Z ...]           Object redshift (default: None)
  --maskdef_objname MASKDEF_OBJNAME
                        MASKDEF_OBJNAME of the target that you want to plot. If
                        maskdef_objname is not provided, nor a pypeit_name, all
                        the 1D spectra in the file(s) will be plotted. (default:
                        None)
  --pypeit_name PYPEIT_NAME
                        PypeIt name of the target that you want to plot. If
                        pypeit_name is not provided, nor a maskdef_objname, all
                        the 1D spectra in the file(s) will be plotted. (default:
                        None)
  --wavemin WAVEMIN     Wavelength min. This is for selecting a region of the
                        spectrum to analyze. (default: None)
  --wavemax WAVEMAX     Wavelength max.This is for selecting a region of the
                        spectrum to analyze. (default: None)
  --plot_or_save PLOT_OR_SAVE
                        Do you want to save to disk or open a plot in a mpl
                        window. If you choose save, a folder called
                        spec1d*_noisecheck will be created and all the relevant
                        plot will be placed there. (default: plot)
  --try_old             Attempt to load old datamodel versions. A crash may
                        ensue.. (default: False)

Here is an example from the Dev Suite:

pypeit_chk_noise_1dspec Science/spec1d_d0225_0054-16045h_DEIMOS_20190225T145727.158.fits

Interactive Scripts

PypeIt provides a few interactive GUI scripts for specific parts of the data reduction. These are never run as a part of an execution of run_pypeit. Instead, they produce files or parameters that ensure run_pypeit is successful.

pypeit_identify

This script provides an interactive GUI used for hands-on wavelength calibration. See Wavelength Calibration and, specifically, the By-Hand Approach.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_identify -h
usage: pypeit_identify [-h] [--lamps LAMPS] [-s] [--wmin WMIN] [--wmax WMAX]
                       [--slits SLITS] [-m] [-n] [--det DET] [--rmstol RMSTOL]
                       [--fwhm FWHM] [--sigdetect SIGDETECT] [--pixtol PIXTOL]
                       [--linear] [--force_save] [--rescale_resid]
                       [-v VERBOSITY] [--try_old]
                       arc_file slits_file

Launch PypeIt pypeit_identify tool, display extracted Arc, and load linelist.

positional arguments:
  arc_file              PypeIt Arc file
  slits_file            PypeIt Slits file

options:
  -h, --help            show this help message and exit
  --lamps LAMPS         Comma separated list of calibration lamps (no spaces)
                        (default: None)
  -s, --solution        Load a wavelength solution from the arc_file (if it
                        exists) (default: False)
  --wmin WMIN           Minimum wavelength range (default: 3000.0)
  --wmax WMAX           Maximum wavelength range (default: 50000.0)
  --slits SLITS         Which slit to load for wavelength calibration. Format
                        should be [0,1,...] for multiple slits, 0 for only one
                        slit. If creating a new WaveCalib with the -n flag, this
                        is not necessary. (default: 0)
  -m, --multi           Set this flag to create wavelength solutions for muliple
                        slits (default: False)
  -n, --new_sol         Set this flag to construct a new WaveCalib file, rather
                        than using the exising one (default: False)
  --det DET             Detector index (default: 1)
  --rmstol RMSTOL       RMS tolerance (default: 0.1)
  --fwhm FWHM           FWHM for line finding (default: 4.0)
  --sigdetect SIGDETECT
                        sigma detection for line finding (default: None)
  --pixtol PIXTOL       Pixel tolerance for Auto IDs (default: 0.1)
  --linear              Show the spectrum in linear (rather than log) scale
                        (default: False)
  --force_save          Save the solutions, despite the RMS (default: False)
  --rescale_resid       Rescale the residual plot to include all points?
                        (default: False)
  -v VERBOSITY, --verbosity VERBOSITY
                        Verbosity level between 0 [none] and 2 [all]. Default:
                        1. Level 2 writes a log with filename identify_YYYYMMDD-
                        HHMM.log (default: 1)
  --try_old             Attempt to load old datamodel versions. A crash may
                        ensue.. (default: False)

pypeit_skysub_regions

This script provides an interactive GUI used to define bespoke sky regions for each slit. See Sky Subtraction and, specifically, Interactively defining the sky regions.

The script usage can be displayed by calling the script with the -h option:

$ pypeit_skysub_regions -h
usage: pypeit_skysub_regions [-h] [--det DET] [-o] [-i] [-f] [-s] [-v VERBOSITY]
                             [--try_old]
                             file

Display a spec2d frame and interactively define the sky regions using a GUI. Run
in the same folder as your .pypeit file

positional arguments:
  file                  spec2d file

options:
  -h, --help            show this help message and exit
  --det DET             Detector (default: 1)
  -o, --overwrite       Overwrite any existing files/directories (default:
                        False)
  -i, --initial         Use initial slit edges? (default: False)
  -f, --flexure         Use flexure corrected slit edges? (default: False)
  -s, --standard        List standard stars as well? (default: False)
  -v VERBOSITY, --verbosity VERBOSITY
                        Verbosity level between 0 [none] and 2 [all]. Default:
                        1. Level 2 writes a log with filename
                        skysub_regions_YYYYMMDD-HHMM.log (default: 1)
  --try_old             Attempt to load old datamodel versions. A crash may
                        ensue.. (default: False)

Developer Scripts

The following are developer-only scripts and can safely be ignored:

  • pypeit_lowrdx_skyspec

  • pypeit_clean

  • pypeit_cp_spec1d