diff --git a/doc/api/pypeit.scripts.extract_datacube.rst b/doc/api/pypeit.scripts.extract_datacube.rst new file mode 100644 index 0000000000..49f3a9d13e --- /dev/null +++ b/doc/api/pypeit.scripts.extract_datacube.rst @@ -0,0 +1,8 @@ +pypeit.scripts.extract\_datacube module +======================================= + +.. automodule:: pypeit.scripts.extract_datacube + :members: + :private-members: + :undoc-members: + :show-inheritance: diff --git a/doc/api/pypeit.scripts.rst b/doc/api/pypeit.scripts.rst index 38fbcf5584..9709614544 100644 --- a/doc/api/pypeit.scripts.rst +++ b/doc/api/pypeit.scripts.rst @@ -26,6 +26,7 @@ Submodules pypeit.scripts.compare_sky pypeit.scripts.compile_wvarxiv pypeit.scripts.edge_inspector + pypeit.scripts.extract_datacube pypeit.scripts.flux_calib pypeit.scripts.flux_setup pypeit.scripts.identify diff --git a/doc/coadd3d.rst b/doc/coadd3d.rst index 5651dd0ee2..4e16390484 100644 --- a/doc/coadd3d.rst +++ b/doc/coadd3d.rst @@ -155,7 +155,7 @@ There are several recommended steps of the coadd3d process that can be run separ pypeit_sensfunc spec1d_StandardStarName.fits -o sens_StandardStarName.fits - For further details, see :doc:`_sensitivity_function`. + For further details, see :ref:`sensitivity_function`. #. Step 4 - Generate a datacube of the science exposures. This is done by running the following command: @@ -164,7 +164,7 @@ There are several recommended steps of the coadd3d process that can be run separ pypeit_coadd_datacube ScienceName.coadd3d -o Note that you will need to specify the sensitivity function file using the ``sensfile`` option in the - :doc:`coadd3d_file` file. For further details, see :ref:`coadd3d_fluxing`. + :ref:`coadd3d_file` file. For further details, see :ref:`coadd3d_fluxing`. Combination options =================== @@ -239,7 +239,7 @@ If you would like to flux calibrate your datacube, you need to produce your standard star datacube first. Then extract the spectrum of the standard star using the ``pypeit_extract_datacube`` script. This will produce a ``spec1d`` file that you will need to use to generate a -sensitivity function in the usual way (see :doc:`_sensitivity_function`). +sensitivity function in the usual way (see :ref:`sensitivity_function`). Then, when generating the datacube of the science frame you must include the name of the sensitivity function in your ``coadd3d`` file as follows: @@ -289,7 +289,7 @@ then you can specify the ``skysub_frame`` in the ``spec2d`` block of the above. If you have dedicated sky frames, then it is generally recommended to reduce these frames as if they are regular science frames, but add the following keyword arguments at the top of your -:doc:`coadd3d_file`: +:ref:`coadd3d_file`: .. code-block:: ini diff --git a/doc/help/pypeit_extract_datacube.rst b/doc/help/pypeit_extract_datacube.rst new file mode 100644 index 0000000000..f4b16eab69 --- /dev/null +++ b/doc/help/pypeit_extract_datacube.rst @@ -0,0 +1,29 @@ +.. code-block:: console + + $ pypeit_extract_datacube -h + usage: pypeit_extract_datacube [-h] [-e EXT_FILE] [-s SAVE] [-o] + [-b BOXCAR_RADIUS] [-v VERBOSITY] + file + + Read in a datacube, extract a spectrum of a point source,and save it as a spec1d + file. + + positional arguments: + file spec3d.fits DataCube file + + options: + -h, --help show this help message and exit + -e EXT_FILE, --ext_file EXT_FILE + Configuration file with extraction parameters (default: + None) + -s SAVE, --save SAVE Output spec1d filename (default: None) + -o, --overwrite Overwrite any existing files/directories (default: + False) + -b BOXCAR_RADIUS, --boxcar_radius BOXCAR_RADIUS + Radius of the circular boxcar (in arcseconds) to use for + the extraction. (default: None) + -v VERBOSITY, --verbosity VERBOSITY + Verbosity level between 0 [none] and 2 [all]. Default: + 1. Level 2 writes a log with filename + extract_datacube_YYYYMMDD-HHMM.log (default: 1) + \ No newline at end of file diff --git a/doc/help/pypeit_sensfunc.rst b/doc/help/pypeit_sensfunc.rst index 3a5b008e28..8eb7d65e05 100644 --- a/doc/help/pypeit_sensfunc.rst +++ b/doc/help/pypeit_sensfunc.rst @@ -62,11 +62,13 @@ -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.: + Use a flat calibration file to compute the blaze + function when generating the sensitivity function. This + is helpful to account for small scale undulations in 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 diff --git a/doc/include/class_datamodel_pypeitimage.rst b/doc/include/class_datamodel_pypeitimage.rst index 1f21b5588b..9008ab7bc3 100644 --- a/doc/include/class_datamodel_pypeitimage.rst +++ b/doc/include/class_datamodel_pypeitimage.rst @@ -10,6 +10,7 @@ Attribute Type ``det_img`` `numpy.ndarray`_ `numpy.integer`_ If a detector mosaic, this image provides the detector that contributed to each pixel. ``detector`` :class:`~pypeit.images.detector_container.DetectorContainer`, :class:`~pypeit.images.mosaic.Mosaic` The detector (see :class:`~pypeit.images.detector_container.DetectorContainer`) or mosaic (see :class:`~pypeit.images.mosaic.Mosaic`) parameters ``exptime`` int, float Effective exposure time (s) +``filename`` str Filename for the image ``fullmask`` :class:`~pypeit.images.imagebitmask.ImageBitMaskArray` Image mask ``image`` `numpy.ndarray`_ `numpy.floating`_ Primary image data ``img_scale`` `numpy.ndarray`_ `numpy.floating`_ Image count scaling applied (e.g., 1/flat-field) diff --git a/doc/include/keck_deimos.sorted.rst b/doc/include/keck_deimos.sorted.rst index 4e41db2257..828519122f 100644 --- a/doc/include/keck_deimos.sorted.rst +++ b/doc/include/keck_deimos.sorted.rst @@ -12,17 +12,17 @@ filename | frametype | ra | dec | target | dispname | decker | binning | mjd | airmass | exptime | dispangle | amp | filter1 | lampstat01 | dateobs | utc | frameno | calib DE.20170527.06713.fits | arc,tilt | 57.99999999999999 | 45.0 | DOME PHLAT | 830G | LongMirr | 1,1 | 57900.077631 | 1.41291034 | 1.0 | 8099.98291016 | SINGLE:B | OG550 | Kr Xe Ar Ne | 2017-05-27 | 01:51:53.87 | 30 | 0 d0527_0030.fits.gz | arc,tilt | 57.99999999999999 | 45.0 | DOME PHLAT | 830G | LongMirr | 1,1 | 57900.077631 | 1.41291034 | 1.0 | 8099.98291016 | SINGLE:B | OG550 | Kr Xe Ar Ne | 2017-05-27 | 01:51:53.87 | 30 | 0 - DE.20170527.06790.fits | pixelflat,illumflat,trace | 57.99999999999999 | 45.0 | DOME PHLAT | 830G | LongMirr | 1,1 | 57900.07851 | 1.41291034 | 4.0 | 8099.98291016 | SINGLE:B | OG550 | Qz | 2017-05-27 | 01:53:10.93 | 31 | 0 d0527_0031.fits.gz | pixelflat,illumflat,trace | 57.99999999999999 | 45.0 | DOME PHLAT | 830G | LongMirr | 1,1 | 57900.07851 | 1.41291034 | 4.0 | 8099.98291016 | SINGLE:B | OG550 | Qz | 2017-05-27 | 01:53:10.93 | 31 | 0 - d0527_0032.fits.gz | pixelflat,illumflat,trace | 57.99999999999999 | 45.0 | DOME PHLAT | 830G | LongMirr | 1,1 | 57900.079356 | 1.41291034 | 4.0 | 8099.98291016 | SINGLE:B | OG550 | Qz | 2017-05-27 | 01:54:24.03 | 32 | 0 + DE.20170527.06790.fits | pixelflat,illumflat,trace | 57.99999999999999 | 45.0 | DOME PHLAT | 830G | LongMirr | 1,1 | 57900.07851 | 1.41291034 | 4.0 | 8099.98291016 | SINGLE:B | OG550 | Qz | 2017-05-27 | 01:53:10.93 | 31 | 0 DE.20170527.06864.fits | pixelflat,illumflat,trace | 57.99999999999999 | 45.0 | DOME PHLAT | 830G | LongMirr | 1,1 | 57900.079356 | 1.41291034 | 4.0 | 8099.98291016 | SINGLE:B | OG550 | Qz | 2017-05-27 | 01:54:24.03 | 32 | 0 - DE.20170527.06936.fits | pixelflat,illumflat,trace | 57.99999999999999 | 45.0 | DOME PHLAT | 830G | LongMirr | 1,1 | 57900.080211 | 1.41291034 | 4.0 | 8099.98291016 | SINGLE:B | OG550 | Qz | 2017-05-27 | 01:55:36.93 | 33 | 0 + d0527_0032.fits.gz | pixelflat,illumflat,trace | 57.99999999999999 | 45.0 | DOME PHLAT | 830G | LongMirr | 1,1 | 57900.079356 | 1.41291034 | 4.0 | 8099.98291016 | SINGLE:B | OG550 | Qz | 2017-05-27 | 01:54:24.03 | 32 | 0 d0527_0033.fits.gz | pixelflat,illumflat,trace | 57.99999999999999 | 45.0 | DOME PHLAT | 830G | LongMirr | 1,1 | 57900.080211 | 1.41291034 | 4.0 | 8099.98291016 | SINGLE:B | OG550 | Qz | 2017-05-27 | 01:55:36.93 | 33 | 0 + DE.20170527.06936.fits | pixelflat,illumflat,trace | 57.99999999999999 | 45.0 | DOME PHLAT | 830G | LongMirr | 1,1 | 57900.080211 | 1.41291034 | 4.0 | 8099.98291016 | SINGLE:B | OG550 | Qz | 2017-05-27 | 01:55:36.93 | 33 | 0 DE.20170527.37601.fits | science | 261.0363749999999 | 19.028166666666667 | P261_OFF | 830G | LongMirr | 1,1 | 57900.435131 | 1.03078874 | 1200.0 | 8099.98291016 | SINGLE:B | OG550 | Off | 2017-05-27 | 10:26:41.61 | 80 | 0 - DE.20170527.38872.fits | science | 261.0363749999999 | 19.028166666666667 | P261_OFF | 830G | LongMirr | 1,1 | 57900.449842 | 1.01267696 | 1200.0 | 8099.98291016 | SINGLE:B | OG550 | Off | 2017-05-27 | 10:47:52.92 | 81 | 0 d0527_0081.fits.gz | science | 261.0363749999999 | 19.028166666666667 | P261_OFF | 830G | LongMirr | 1,1 | 57900.449842 | 1.01267696 | 1200.0 | 8099.98291016 | SINGLE:B | OG550 | Off | 2017-05-27 | 10:47:52.92 | 81 | 0 - d0527_0083.fits.gz | science | 261.0362916666666 | 19.028888888888886 | P261_OFF | 830G | LongMirr | 1,1 | 57900.483427 | 1.00093023 | 1200.0 | 8099.98291016 | SINGLE:B | OG550 | Off | 2017-05-27 | 11:36:15.35 | 83 | 0 + DE.20170527.38872.fits | science | 261.0363749999999 | 19.028166666666667 | P261_OFF | 830G | LongMirr | 1,1 | 57900.449842 | 1.01267696 | 1200.0 | 8099.98291016 | SINGLE:B | OG550 | Off | 2017-05-27 | 10:47:52.92 | 81 | 0 DE.20170527.41775.fits | science | 261.0362916666666 | 19.028888888888886 | P261_OFF | 830G | LongMirr | 1,1 | 57900.483427 | 1.00093023 | 1200.0 | 8099.98291016 | SINGLE:B | OG550 | Off | 2017-05-27 | 11:36:15.35 | 83 | 0 + d0527_0083.fits.gz | science | 261.0362916666666 | 19.028888888888886 | P261_OFF | 830G | LongMirr | 1,1 | 57900.483427 | 1.00093023 | 1200.0 | 8099.98291016 | SINGLE:B | OG550 | Off | 2017-05-27 | 11:36:15.35 | 83 | 0 DE.20170527.43045.fits | science | 261.0362916666666 | 19.028888888888886 | P261_OFF | 830G | LongMirr | 1,1 | 57900.498135 | 1.00838805 | 1200.0 | 8099.98291016 | SINGLE:B | OG550 | Off | 2017-05-27 | 11:57:25.35 | 84 | 0 DE.20170527.44316.fits | science | 261.0362916666666 | 19.028888888888886 | P261_OFF | 830G | LongMirr | 1,1 | 57900.512854 | 1.02377681 | 1200.0 | 8099.98291016 | SINGLE:B | OG550 | Off | 2017-05-27 | 12:18:36.71 | 85 | 0 DE.20170527.53184.fits | science | 349.99316666666664 | -5.16575 | Feige 110 | 830G | LongMirr | 1,1 | 57900.615484 | 1.42505162 | 45.0 | 8099.98291016 | SINGLE:B | OG550 | Off | 2017-05-27 | 14:46:24.88 | 93 | 0 diff --git a/doc/pypeit_par.rst b/doc/pypeit_par.rst index d8a7b4a747..ebbc746b52 100644 --- a/doc/pypeit_par.rst +++ b/doc/pypeit_par.rst @@ -308,32 +308,33 @@ FlatFieldPar Keywords Class Instantiation: :class:`~pypeit.par.pypeitpar.FlatFieldPar` -========================== ================= ================================= =========== ================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================ -Key Type Options Default Description -========================== ================= ================================= =========== ================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================ -``fit_2d_det_response`` bool .. False Set this variable to True if you want to compute and account for the detector response in the flatfield image. Note that ``detector response`` refers to pixel sensitivity variations that primarily depend on (x,y) detector coordinates. In most cases, the default 2D bspline is sufficient to account for detector response (i.e. set this parameter to False). Note that this correction will _only_ be performed for the spectrographs that have a dedicated response correction implemented. Currently,this correction is only implemented for Keck+KCWI. -``illum_iter`` int .. 0 The number of rejection iterations to perform when constructing the slit-illumination profile. No rejection iterations are performed if 0. WARNING: Functionality still being tested. -``illum_rej`` int, float .. 5.0 The sigma threshold used in the rejection iterations used to refine the slit-illumination profile. Rejection iterations are only performed if ``illum_iter > 0``. -``method`` str ``bspline``, ``skip`` ``bspline`` Method used to flat field the data; use skip to skip flat-fielding. Options are: None, bspline, skip -``pixelflat_file`` str .. .. Filename of the image to use for pixel-level field flattening -``pixelflat_max_wave`` int, float .. .. All values of the normalized pixel flat are set to 1 for wavelengths above this value. -``pixelflat_min_wave`` int, float .. .. All values of the normalized pixel flat are set to 1 for wavelengths below this value. -``rej_sticky`` bool .. False Propagate the rejected pixels through the stages of the flat-field fitting (i.e, from the spectral fit, to the spatial fit, and finally to the 2D residual fit). If False, pixels rejected in each stage are included in each subsequent stage. -``saturated_slits`` str ``crash``, ``mask``, ``continue`` ``crash`` Behavior when a slit is encountered with a large fraction of saturated pixels in the flat-field. The options are: 'crash' - Raise an error and halt the data reduction; 'mask' - Mask the slit, meaning no science data will be extracted from the slit; 'continue' - ignore the flat-field correction, but continue with the reduction. -``slit_illum_finecorr`` bool .. True If True, a fine correction to the spatial illumination profile will be performed. The fine correction is a low order 2D polynomial fit to account for a gradual change to the spatial illumination profile as a function of wavelength. -``slit_illum_pad`` int, float .. 5.0 The number of pixels to pad the slit edges when constructing the slit-illumination profile. Single value applied to both edges. -``slit_illum_ref_idx`` int .. 0 The index of a reference slit (0-indexed) used for estimating the relative spectral sensitivity (or the relative blaze). This parameter is only used if ``slit_illum_relative = True``. -``slit_illum_relative`` bool .. False Generate an image of the relative spectral illumination for a multi-slit setup. If you set ``use_specillum = True`` for any of the frames that use the flatfield model, this *must* be set to True. Currently, this is only used for SlicerIFU reductions. -``slit_illum_smooth_npix`` int .. 10 The number of pixels used to determine smoothly varying relative weights is given by ``nspec/slit_illum_smooth_npix``, where nspec is the number of spectral pixels. -``slit_trim`` int, float, tuple .. 3.0 The number of pixels to trim each side of the slit when selecting pixels to use for fitting the spectral response function. Single values are used for both slit edges; a two-tuple can be used to trim the left and right sides differently. -``spat_samp`` int, float .. 5.0 Spatial sampling for slit illumination function. This is the width of the median filter in pixels used to determine the slit illumination function, and thus sets the minimum scale on which the illumination function will have features. -``spec_samp_coarse`` int, float .. 50.0 bspline break point spacing in units of pixels for 2-d bspline-polynomial fit to flat field image residuals. This should be a large number unless you are trying to fit a sky flat with lots of narrow spectral features. -``spec_samp_fine`` int, float .. 1.2 bspline break point spacing in units of pixels for spectral fit to flat field blaze function. -``tweak_slits`` bool .. True Use the illumination flat field to tweak the slit edges. This will work even if illumflatten is set to False -``tweak_slits_maxfrac`` float .. 0.1 If tweak_slit is True, this sets the maximum fractional amount (of a slits width) allowed for trimming each (i.e. left and right) slit boundary, i.e. the default is 10% which means slits would shrink or grow by at most 20% (10% on each side) -``tweak_slits_thresh`` float .. 0.93 If tweak_slits is True, this sets the illumination function threshold used to tweak the slit boundaries based on the illumination flat. It should be a number less than 1.0 -``twod_fit_npoly`` int .. .. Order of polynomial used in the 2D bspline-polynomial fit to flat-field image residuals. The code determines the order of these polynomials to each slit automatically depending on the slit width, which is why the default is None. Alter this paramter at your own risk! -========================== ================= ================================= =========== ================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================ +========================== ================= ================================= ============= ================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================ +Key Type Options Default Description +========================== ================= ================================= ============= ================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================ +``fit_2d_det_response`` bool .. False Set this variable to True if you want to compute and account for the detector response in the flatfield image. Note that ``detector response`` refers to pixel sensitivity variations that primarily depend on (x,y) detector coordinates. In most cases, the default 2D bspline is sufficient to account for detector response (i.e. set this parameter to False). Note that this correction will _only_ be performed for the spectrographs that have a dedicated response correction implemented. Currently,this correction is only implemented for Keck+KCWI. +``illum_iter`` int .. 0 The number of rejection iterations to perform when constructing the slit-illumination profile. No rejection iterations are performed if 0. WARNING: Functionality still being tested. +``illum_rej`` int, float .. 5.0 The sigma threshold used in the rejection iterations used to refine the slit-illumination profile. Rejection iterations are only performed if ``illum_iter > 0``. +``method`` str ``bspline``, ``skip`` ``bspline`` Method used to flat field the data; use skip to skip flat-fielding. Options are: None, bspline, skip +``pixelflat_file`` str .. .. Filename of the image to use for pixel-level field flattening +``pixelflat_max_wave`` int, float .. .. All values of the normalized pixel flat are set to 1 for wavelengths above this value. +``pixelflat_min_wave`` int, float .. .. All values of the normalized pixel flat are set to 1 for wavelengths below this value. +``rej_sticky`` bool .. False Propagate the rejected pixels through the stages of the flat-field fitting (i.e, from the spectral fit, to the spatial fit, and finally to the 2D residual fit). If False, pixels rejected in each stage are included in each subsequent stage. +``saturated_slits`` str ``crash``, ``mask``, ``continue`` ``crash`` Behavior when a slit is encountered with a large fraction of saturated pixels in the flat-field. The options are: 'crash' - Raise an error and halt the data reduction; 'mask' - Mask the slit, meaning no science data will be extracted from the slit; 'continue' - ignore the flat-field correction, but continue with the reduction. +``slit_illum_finecorr`` bool .. True If True, a fine correction to the spatial illumination profile will be performed. The fine correction is a low order 2D polynomial fit to account for a gradual change to the spatial illumination profile as a function of wavelength. +``slit_illum_pad`` int, float .. 5.0 The number of pixels to pad the slit edges when constructing the slit-illumination profile. Single value applied to both edges. +``slit_illum_ref_idx`` int .. 0 The index of a reference slit (0-indexed) used for estimating the relative spectral sensitivity (or the relative blaze). This parameter is only used if ``slit_illum_relative = True``. +``slit_illum_relative`` bool .. False Generate an image of the relative spectral illumination for a multi-slit setup. If you set ``use_specillum = True`` for any of the frames that use the flatfield model, this *must* be set to True. Currently, this is only used for SlicerIFU reductions. +``slit_illum_smooth_npix`` int .. 10 The number of pixels used to determine smoothly varying relative weights is given by ``nspec/slit_illum_smooth_npix``, where nspec is the number of spectral pixels. +``slit_trim`` int, float, tuple .. 3.0 The number of pixels to trim each side of the slit when selecting pixels to use for fitting the spectral response function. Single values are used for both slit edges; a two-tuple can be used to trim the left and right sides differently. +``spat_samp`` int, float .. 5.0 Spatial sampling for slit illumination function. This is the width of the median filter in pixels used to determine the slit illumination function, and thus sets the minimum scale on which the illumination function will have features. +``spec_samp_coarse`` int, float .. 50.0 bspline break point spacing in units of pixels for 2-d bspline-polynomial fit to flat field image residuals. This should be a large number unless you are trying to fit a sky flat with lots of narrow spectral features. +``spec_samp_fine`` int, float .. 1.2 bspline break point spacing in units of pixels for spectral fit to flat field blaze function. +``tweak_method`` str ``threshold``, ``gradient`` ``threshold`` Method used to tweak the slit edges (when "tweak_slits" is set to True). Options include: threshold, gradient. The "threshold" method determines when the left and right slit edges fall below a threshold relative to the peak illumination. The "gradient" method determines where the gradient is the highest at the left and right slit edges. This method performs better when there is systematic vignetting in the spatial direction. +``tweak_slits`` bool .. True Use the illumination flat field to tweak the slit edges. This will work even if illumflatten is set to False +``tweak_slits_maxfrac`` float .. 0.1 If tweak_slit is True, this sets the maximum fractional amount (of a slits width) allowed for trimming each (i.e. left and right) slit boundary, i.e. the default is 10% which means slits would shrink or grow by at most 20% (10% on each side) +``tweak_slits_thresh`` float .. 0.93 If tweak_slits is True, this sets the illumination function threshold used to tweak the slit boundaries based on the illumination flat. It should be a number less than 1.0 +``twod_fit_npoly`` int .. .. Order of polynomial used in the 2D bspline-polynomial fit to flat-field image residuals. The code determines the order of these polynomials to each slit automatically depending on the slit width, which is why the default is None. Alter this paramter at your own risk! +========================== ================= ================================= ============= ================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================ ---- @@ -345,77 +346,78 @@ EdgeTracePar Keywords Class Instantiation: :class:`~pypeit.par.pypeitpar.EdgeTracePar` -=========================== ================ =========================================== ============== ====================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== -Key Type Options Default Description -=========================== ================ =========================================== ============== ====================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== -``add_missed_orders`` bool .. False For any Echelle spectrograph (fixed-format or otherwise), attempt to add orders that have been missed by the automated edge tracing algorithm. For *fixed-format* Echelles, this is based on the expected positions on on the detector. Otherwise, the detected orders are modeled and roughly used to predict the locations of missed orders; see additional parameters ``order_width_poly``, ``order_gap_poly``, and ``order_spat_range``. -``add_predict`` str .. ``nearest`` Sets the method used to predict the shape of the left and right traces for a user-defined slit inserted. Options are (1) ``straight`` inserts traces with a constant spatial pixels position, (2) ``nearest`` inserts traces with a form identical to the automatically identified trace at the nearest spatial position to the inserted slit, or (3) ``pca`` uses the PCA decomposition to predict the shape of the traces. -``add_slits`` str, list .. .. Add one or more user-defined slits. The syntax to define a slit to add is: 'det:spec:spat_left:spat_right' where det=detector, spec=spectral pixel, spat_left=spatial pixel of left slit boundary, and spat_righ=spatial pixel of right slit boundary. For example, '2:2000:2121:2322,3:2000:1201:1500' will add a slit to detector 2 passing through spec=2000 extending spatially from 2121 to 2322 and another on detector 3 at spec=2000 extending from 1201 to 1500. -``auto_pca`` bool .. True During automated tracing, attempt to construct a PCA decomposition of the traces. When True, the edge traces resulting from the initial detection, centroid refinement, and polynomial fitting must meet a set of criteria for performing the pca; see :func:`pypeit.edgetrace.EdgeTraceSet.can_pca`. If False, the ``sync_predict`` parameter *cannot* be set to ``pca``; if it is not, the value is set to ``nearest`` and a warning is issued when validating the parameter set. -``bound_detector`` bool .. False When the code is ready to synchronize the left/right trace edges, the traces should have been constructed, vetted, and cleaned. This can sometimes lead to *no* valid traces. This parameter dictates what to do next. If ``bound_detector`` is True, the code will artificially add left and right edges that bound the detector; if False, the code identifies the slit-edge tracing as being unsuccessful, warns the user, and ends gracefully. Note that setting ``bound_detector`` to True is needed for some long-slit data where the slit edges are, in fact, beyond the edges of the detector. -``clip`` bool .. True Remove traces flagged as bad, instead of only masking them. This is currently only used by :func:`~pypeit.edgetrace.EdgeTraceSet.centroid_refine`. -``det_buffer`` int .. 5 The minimum separation between the detector edges and a slit edge for any added edge traces. Must be positive. -``det_min_spec_length`` int, float .. 0.33 The minimum spectral length (as a fraction of the detector size) of a trace determined by direct measurements of the detector data (as opposed to what should be included in any modeling approach; see fit_min_spec_length). -``dlength_range`` int, float .. .. Similar to ``minimum_slit_dlength``, but constrains the *fractional* change in the slit length as a function of wavelength. For example, a value of 0.2 means that slit length should not vary more than 20%as a function of wavelength. -``edge_detect_clip`` int, float .. .. Sigma clipping level for peaks detected in the collapsed, Sobel-filtered significance image. -``edge_thresh`` int, float .. 20.0 Threshold for finding edges in the Sobel-filtered significance image. -``exclude_regions`` list, str .. .. User-defined regions to exclude from the slit tracing. To set this parameter, the text should be a comma separated list of pixel ranges (in the x direction) to be excluded and the detector number. For example, the following string 1:0:20,1:300:400 would select two regions in det=1 between pixels 0 and 20 and between 300 and 400. -``filt_iter`` int .. 0 Number of median-filtering iterations to perform on sqrt(trace) image before applying to Sobel filter to detect slit/order edges. -``fit_function`` str ``polynomial``, ``legendre``, ``chebyshev`` ``legendre`` Function fit to edge measurements. Options are: polynomial, legendre, chebyshev -``fit_maxdev`` int, float .. 5.0 Maximum deviation between the fitted and measured edge position for rejection in spatial pixels. -``fit_maxiter`` int .. 25 Maximum number of rejection iterations during edge fitting. -``fit_min_spec_length`` float .. 0.6 Minimum unmasked spectral length of a traced slit edge to use in any modeling procedure (polynomial fitting or PCA decomposition). -``fit_niter`` int .. 1 Number of iterations of re-measuring and re-fitting the edge data; see :func:`~pypeit.core.trace.fit_trace`. -``fit_order`` int .. 5 Order of the function fit to edge measurements. -``follow_span`` int .. 20 In the initial connection of spectrally adjacent edge detections, this sets the number of previous spectral rows to consider when following slits forward. -``fwhm_gaussian`` int, float .. 3.0 The `fwhm` parameter to use when using Gaussian weighting in :func:`~pypeit.core.trace.fit_trace` when refining the PCA predictions of edges. See description :func:`~pypeit.core.trace.peak_trace`. -``fwhm_uniform`` int, float .. 3.0 The `fwhm` parameter to use when using uniform weighting in :func:`~pypeit.core.trace.fit_trace` when refining the PCA predictions of edges. See description of :func:`~pypeit.core.trace.peak_trace`. -``gap_offset`` int, float .. 5.0 Offset (pixels) used for the slit edge gap width when inserting slit edges (see `sync_center`) or when nudging predicted slit edges to avoid slit overlaps. This should be larger than `minimum_slit_gap` when converted to arcseconds. -``left_right_pca`` bool .. False Construct a PCA decomposition for the left and right traces separately. This can be important for cross-dispersed echelle spectrographs (e.g., Keck-NIRES) -``length_range`` int, float .. .. Allowed range in slit length compared to the median slit length. For example, a value of 0.3 means that slit lengths should not vary more than 30%. Relatively shorter or longer slits are masked or clipped. Most useful for echelle or multi-slit data where the slits should have similar or identical lengths. -``maskdesign_filename`` str, list .. .. Mask design info contained in this file or files (comma separated) -``maskdesign_maxsep`` int, float .. 50 Maximum allowed offset in pixels between the slit edges defined by the slit-mask design and the traced edges. -``maskdesign_sigrej`` int, float .. 3 Number of sigma for sigma-clipping rejection during slit-mask design matching. -``maskdesign_step`` int, float .. 1 Step in pixels used to generate a list of possible offsets (within +/- `maskdesign_maxsep`) between the slit edges defined by the mask design and the traced edges. -``match_tol`` int, float .. 3.0 Same-side slit edges below this separation in pixels are considered part of the same edge. -``max_nudge`` int, float .. .. If parts of any (predicted) trace fall off the detector edge, allow them to be nudged away from the detector edge up to and including this maximum number of pixels. If None, no limit is set; otherwise should be 0 or larger. -``max_shift_abs`` int, float .. 0.5 Maximum spatial shift in pixels between an input edge location and the recentroided value. -``max_shift_adj`` int, float .. 0.15 Maximum spatial shift in pixels between the edges in adjacent spectral positions. -``max_spat_error`` int, float .. .. Maximum error in the spatial position of edges in pixels. -``minimum_slit_dlength`` int, float .. .. Minimum *change* in the slit length (arcsec) as a function of wavelength in arcsec. This is mostly meant to catch cases when the polynomial fit to the detected edges becomes ill-conditioned (e.g., when the slits run off the edge of the detector) and leads to wild traces. If reducing the order of the polynomial (``fit_order``) does not help, try using this to remove poorly constrained slits. -``minimum_slit_gap`` int, float .. .. Minimum slit gap in arcsec. Gaps between slits are determined by the median difference between the right and left edge locations of adjacent slits. Slits with small gaps are merged by removing the intervening traces.If None, no minimum slit gap is applied. This should be smaller than `gap_offset` when converted to pixels. -``minimum_slit_length`` int, float .. .. Minimum slit length in arcsec. Slit lengths are determined by the median difference between the left and right edge locations for the unmasked trace locations. This is used to identify traces that are *erroneously* matched together to form slits. Short slits are expected to be ignored or removed (see ``clip``). If None, no minimum slit length applied. -``minimum_slit_length_sci`` int, float .. .. Minimum slit length in arcsec for a science slit. Slit lengths are determined by the median difference between the left and right edge locations for the unmasked trace locations. Used in combination with ``minimum_slit_length``, this parameter is used to identify box or alignment slits; i.e., those slits that are shorter than ``minimum_slit_length_sci`` but larger than ``minimum_slit_length`` are box/alignment slits. Box slits are *never* removed (see ``clip``), but no spectra are extracted from them. If None, no minimum science slit length is applied. -``niter_gaussian`` int .. 6 The number of iterations of :func:`~pypeit.core.trace.fit_trace` to use when using Gaussian weighting. -``niter_uniform`` int .. 9 The number of iterations of :func:`~pypeit.core.trace.fit_trace` to use when using uniform weighting. -``order_gap_poly`` int .. 3 Order of the Legendre polynomial used to model the spatial gap between orders as a function of the order spatial position. See ``add_missed_orders``. -``order_match`` int, float .. .. Orders for *fixed-format* echelle spectrographs are always matched to a predefined expectation for the number of orders found and their relative placement in the detector. This sets the tolerance allowed for matching identified "slits" to echelle orders. Must be relative to the fraction of the detector spatial scale (i.e., a value of 0.05 means that the order locations must be within 5% of the expected value). If None, no limit is used. -``order_offset`` int, float .. .. Orders for *fixed-format* echelle spectrographs are always matched to a predefined expectation for the number of orders found and their relative placement in the detector. This sets the offset to introduce to the expected order positions to improve the match for this specific data. This is an additive offset to the measured slit positions; i.e., this should minimize the difference between the expected order positions and ``self.slit_spatial_center() + offset``. Must be in the fraction of the detector spatial scale. If None, no offset is applied. -``order_spat_range`` list .. .. The spatial range of the detector/mosaic over which to predict order locations. If None, the full detector/mosaic range is used. See ``add_missed_orders``. -``order_width_poly`` int .. 2 Order of the Legendre polynomial used to model the spatial width of each order as a function of spatial pixel position. See ``add_missed_orders``. -``overlap`` bool .. False Assume slits identified as abnormally short are actually due to overlaps between adjacent slits/orders. If set to True, you *must* have also used ``length_range`` to identify left-right edge pairs that have an abnormally short separation. For those short slits, the code attempts to convert the short slits into slit gaps. This is particularly useful for blue orders in Keck-HIRES data. -``pad`` int .. 0 Integer number of pixels to consider beyond the slit edges when selecting pixels that are 'on' the slit. -``pca_function`` str ``polynomial``, ``legendre``, ``chebyshev`` ``polynomial`` Type of function fit to the PCA coefficients for each component. Options are: polynomial, legendre, chebyshev -``pca_maxiter`` int .. 25 Maximum number of rejection iterations when fitting the PCA coefficients. -``pca_maxrej`` int .. 1 Maximum number of PCA coefficients rejected during a given fit iteration. -``pca_min_edges`` int .. 4 Minimum number of edge traces required to perform a PCA decomposition of the trace form. If left_right_pca is True, this minimum applies to the number of left and right traces separately. -``pca_n`` int .. .. The number of PCA components to keep, which must be less than the number of detected traces. If not provided, determined by calculating the minimum number of components required to explain a given percentage of variance in the edge data; see `pca_var_percent`. -``pca_order`` int .. 2 Order of the function fit to the PCA coefficients. -``pca_sigrej`` int, float, list .. 2.0, 2.0 Sigma rejection threshold for fitting PCA components. Individual numbers are used for both lower and upper rejection. A list of two numbers sets these explicitly (e.g., [2., 3.]). -``pca_var_percent`` int, float .. 99.8 The percentage (i.e., not the fraction) of the variance in the edge data accounted for by the PCA used to truncate the number of PCA coefficients to keep (see `pca_n`). Ignored if `pca_n` is provided directly. -``rm_slits`` str, list .. .. Remove one or more user-specified slits. The syntax used to define a slit to remove is: 'det:spec:spat' where det=detector, spec=spectral pixel, spat=spatial pixel. For example, '2:2000:2121,3:2000:1500' will remove the slit on detector 2 that contains pixel (spat,spec)=(2000,2121) and on detector 3 that contains pixel (2000,2121). -``smash_range`` list .. 0.0, 1.0 Range of the slit in the spectral direction (in fractional units) to smash when searching for slit edges. If the spectrum covers only a portion of the image, use that range. -``sobel_enhance`` int .. 0 Enhance the sobel filtering? A value of 0 will not enhance the sobel filtering. Any other value > 0 will sum the sobel values. For example, a value of 3 will combine the sobel values for the 3 nearest pixels. This is useful when a slit edge is poorly defined (e.g. vignetted). -``sobel_mode`` str ``nearest``, ``constant`` ``nearest`` Mode for Sobel filtering. Default is 'nearest'; note we find'constant' works best for DEIMOS. -``sync_center`` str ``median``, ``nearest``, ``gap`` ``median`` Mode to use for determining the location of traces to insert. Use `median` to use the median of the matched left and right edge pairs, `nearest` to use the length of the nearest slit, or `gap` to offset by a fixed gap width from the next slit edge. -``sync_predict`` str ``pca``, ``nearest``, ``auto`` ``pca`` Mode to use when predicting the form of the trace to insert. Use `pca` to use the PCA decomposition, `nearest` to reproduce the shape of the nearest trace, or `auto` to let PypeIt decide which mode to use between `pca` and `nearest`. In general, it will first try `pca`, and if that is not possible, it will use `nearest`. -``sync_to_edge`` bool .. True If adding a first left edge or a last right edge, ignore `center_mode` for these edges and place them at the edge of the detector (with the relevant shape). -``trace_median_frac`` int, float .. .. After detection of peaks in the rectified Sobel-filtered image and before refitting the edge traces, the rectified image is median filtered with a kernel width of `trace_median_frac*nspec` along the spectral dimension. -``trace_rms_tol`` int, float .. .. After retracing edges using peaks detected in the rectified and collapsed image, the RMS difference (in pixels) between the original and refit traces are calculated. This sets the upper limit of the RMS for traces that will be removed. If None, no limit is set and all new traces are kept. -``trace_thresh`` int, float .. .. After rectification and median filtering of the Sobel-filtered image (see `trace_median_frac`), values in the median-filtered image *below* this threshold are masked in the refitting of the edge trace data. If None, no masking applied. -``trim_spec`` list .. .. User-defined truncation of all slits in the spectral direction.Should be two integers, e.g. 100,150 trims 100 pixels from the short wavelength end and 150 pixels from the long wavelength end of the spectral axis of the detector. -``use_maskdesign`` bool .. False Use slit-mask designs to identify slits. -=========================== ================ =========================================== ============== ====================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== +=========================== ================ =========================================== ============== =================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== +Key Type Options Default Description +=========================== ================ =========================================== ============== =================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== +``add_missed_orders`` bool .. False For any Echelle spectrograph (fixed-format or otherwise), attempt to add orders that have been missed by the automated edge tracing algorithm. For *fixed-format* Echelles, this is based on the expected positions on on the detector. Otherwise, the detected orders are modeled and roughly used to predict the locations of missed orders; see additional parameters ``order_width_poly``, ``order_gap_poly``, and ``order_spat_range``. +``add_predict`` str .. ``nearest`` Sets the method used to predict the shape of the left and right traces for a user-defined slit inserted. Options are (1) ``straight`` inserts traces with a constant spatial pixels position, (2) ``nearest`` inserts traces with a form identical to the automatically identified trace at the nearest spatial position to the inserted slit, or (3) ``pca`` uses the PCA decomposition to predict the shape of the traces. +``add_slits`` str, list .. .. Add one or more user-defined slits. The syntax to define a slit to add is: 'det:spec:spat_left:spat_right' where det=detector, spec=spectral pixel, spat_left=spatial pixel of left slit boundary, and spat_righ=spatial pixel of right slit boundary. For example, '2:2000:2121:2322,3:2000:1201:1500' will add a slit to detector 2 passing through spec=2000 extending spatially from 2121 to 2322 and another on detector 3 at spec=2000 extending from 1201 to 1500. +``auto_pca`` bool .. True During automated tracing, attempt to construct a PCA decomposition of the traces. When True, the edge traces resulting from the initial detection, centroid refinement, and polynomial fitting must meet a set of criteria for performing the pca; see :func:`pypeit.edgetrace.EdgeTraceSet.can_pca`. If False, the ``sync_predict`` parameter *cannot* be set to ``pca``; if it is not, the value is set to ``nearest`` and a warning is issued when validating the parameter set. +``bound_detector`` bool .. False When the code is ready to synchronize the left/right trace edges, the traces should have been constructed, vetted, and cleaned. This can sometimes lead to *no* valid traces. This parameter dictates what to do next. If ``bound_detector`` is True, the code will artificially add left and right edges that bound the detector; if False, the code identifies the slit-edge tracing as being unsuccessful, warns the user, and ends gracefully. Note that setting ``bound_detector`` to True is needed for some long-slit data where the slit edges are, in fact, beyond the edges of the detector. +``clip`` bool .. True Remove traces flagged as bad, instead of only masking them. This is currently only used by :func:`~pypeit.edgetrace.EdgeTraceSet.centroid_refine`. +``det_buffer`` int .. 5 The minimum separation between the detector edges and a slit edge for any added edge traces. Must be positive. +``det_min_spec_length`` int, float .. 0.33 The minimum spectral length (as a fraction of the detector size) of a trace determined by direct measurements of the detector data (as opposed to what should be included in any modeling approach; see fit_min_spec_length). +``dlength_range`` int, float .. .. Similar to ``minimum_slit_dlength``, but constrains the *fractional* change in the slit length as a function of wavelength. For example, a value of 0.2 means that slit length should not vary more than 20%as a function of wavelength. +``edge_detect_clip`` int, float .. .. Sigma clipping level for peaks detected in the collapsed, Sobel-filtered significance image. +``edge_thresh`` int, float .. 20.0 Threshold for finding edges in the Sobel-filtered significance image. +``exclude_regions`` list, str .. .. User-defined regions to exclude from the slit tracing. To set this parameter, the text should be a comma separated list of pixel ranges (in the x direction) to be excluded and the detector number. For example, the following string 1:0:20,1:300:400 would select two regions in det=1 between pixels 0 and 20 and between 300 and 400. +``filt_iter`` int .. 0 Number of median-filtering iterations to perform on sqrt(trace) image before applying to Sobel filter to detect slit/order edges. +``fit_function`` str ``polynomial``, ``legendre``, ``chebyshev`` ``legendre`` Function fit to edge measurements. Options are: polynomial, legendre, chebyshev +``fit_maxdev`` int, float .. 5.0 Maximum deviation between the fitted and measured edge position for rejection in spatial pixels. +``fit_maxiter`` int .. 25 Maximum number of rejection iterations during edge fitting. +``fit_min_spec_length`` float .. 0.6 Minimum unmasked spectral length of a traced slit edge to use in any modeling procedure (polynomial fitting or PCA decomposition). +``fit_niter`` int .. 1 Number of iterations of re-measuring and re-fitting the edge data; see :func:`~pypeit.core.trace.fit_trace`. +``fit_order`` int .. 5 Order of the function fit to edge measurements. +``follow_span`` int .. 20 In the initial connection of spectrally adjacent edge detections, this sets the number of previous spectral rows to consider when following slits forward. +``fwhm_gaussian`` int, float .. 3.0 The `fwhm` parameter to use when using Gaussian weighting in :func:`~pypeit.core.trace.fit_trace` when refining the PCA predictions of edges. See description :func:`~pypeit.core.trace.peak_trace`. +``fwhm_uniform`` int, float .. 3.0 The `fwhm` parameter to use when using uniform weighting in :func:`~pypeit.core.trace.fit_trace` when refining the PCA predictions of edges. See description of :func:`~pypeit.core.trace.peak_trace`. +``gap_offset`` int, float .. 5.0 Offset (pixels) used for the slit edge gap width when inserting slit edges (see `sync_center`) or when nudging predicted slit edges to avoid slit overlaps. This should be larger than `minimum_slit_gap` when converted to arcseconds. +``left_right_pca`` bool .. False Construct a PCA decomposition for the left and right traces separately. This can be important for cross-dispersed echelle spectrographs (e.g., Keck-NIRES) +``length_range`` int, float .. .. Allowed range in slit length compared to the median slit length. For example, a value of 0.3 means that slit lengths should not vary more than 30%. Relatively shorter or longer slits are masked or clipped. Most useful for echelle or multi-slit data where the slits should have similar or identical lengths. +``maskdesign_filename`` str, list .. .. Mask design info contained in this file or files (comma separated) +``maskdesign_maxsep`` int, float .. 50 Maximum allowed offset in pixels between the slit edges defined by the slit-mask design and the traced edges. +``maskdesign_sigrej`` int, float .. 3 Number of sigma for sigma-clipping rejection during slit-mask design matching. +``maskdesign_step`` int, float .. 1 Step in pixels used to generate a list of possible offsets (within +/- `maskdesign_maxsep`) between the slit edges defined by the mask design and the traced edges. +``match_tol`` int, float .. 3.0 Same-side slit edges below this separation in pixels are considered part of the same edge. +``max_nudge`` int, float .. .. If parts of any (predicted) trace fall off the detector edge, allow them to be nudged away from the detector edge up to and including this maximum number of pixels. If None, no limit is set; otherwise should be 0 or larger. +``max_overlap`` float .. .. When adding missing echelle orders based on where existing orders are found, the prediction can yield overlapping orders. The edges of these orders are adjusted to eliminate the overlap, and orders can be added up over the spatial range of the detector set by ``order_spate_range``. If this value is None, orders are added regardless of how much they overlap. If not None, this defines the maximum fraction of an order spatial width that can overlap with other orders. For example, if ``max_overlap=0.5``, any order that overlaps its neighboring orders by more than 50% will not be added as a missing order. +``max_shift_abs`` int, float .. 0.5 Maximum spatial shift in pixels between an input edge location and the recentroided value. +``max_shift_adj`` int, float .. 0.15 Maximum spatial shift in pixels between the edges in adjacent spectral positions. +``max_spat_error`` int, float .. .. Maximum error in the spatial position of edges in pixels. +``minimum_slit_dlength`` int, float .. .. Minimum *change* in the slit length (arcsec) as a function of wavelength in arcsec. This is mostly meant to catch cases when the polynomial fit to the detected edges becomes ill-conditioned (e.g., when the slits run off the edge of the detector) and leads to wild traces. If reducing the order of the polynomial (``fit_order``) does not help, try using this to remove poorly constrained slits. +``minimum_slit_gap`` int, float .. .. Minimum slit gap in arcsec. Gaps between slits are determined by the median difference between the right and left edge locations of adjacent slits. Slits with small gaps are merged by removing the intervening traces.If None, no minimum slit gap is applied. This should be smaller than `gap_offset` when converted to pixels. +``minimum_slit_length`` int, float .. .. Minimum slit length in arcsec. Slit lengths are determined by the median difference between the left and right edge locations for the unmasked trace locations. This is used to identify traces that are *erroneously* matched together to form slits. Short slits are expected to be ignored or removed (see ``clip``). If None, no minimum slit length applied. +``minimum_slit_length_sci`` int, float .. .. Minimum slit length in arcsec for a science slit. Slit lengths are determined by the median difference between the left and right edge locations for the unmasked trace locations. Used in combination with ``minimum_slit_length``, this parameter is used to identify box or alignment slits; i.e., those slits that are shorter than ``minimum_slit_length_sci`` but larger than ``minimum_slit_length`` are box/alignment slits. Box slits are *never* removed (see ``clip``), but no spectra are extracted from them. If None, no minimum science slit length is applied. +``niter_gaussian`` int .. 6 The number of iterations of :func:`~pypeit.core.trace.fit_trace` to use when using Gaussian weighting. +``niter_uniform`` int .. 9 The number of iterations of :func:`~pypeit.core.trace.fit_trace` to use when using uniform weighting. +``order_gap_poly`` int .. 3 Order of the Legendre polynomial used to model the spatial gap between orders as a function of the order spatial position. See ``add_missed_orders``. +``order_match`` int, float .. .. Orders for *fixed-format* echelle spectrographs are always matched to a predefined expectation for the number of orders found and their relative placement in the detector. This sets the tolerance allowed for matching identified "slits" to echelle orders. Must be relative to the fraction of the detector spatial scale (i.e., a value of 0.05 means that the order locations must be within 5% of the expected value). If None, no limit is used. +``order_offset`` int, float .. .. Orders for *fixed-format* echelle spectrographs are always matched to a predefined expectation for the number of orders found and their relative placement in the detector. This sets the offset to introduce to the expected order positions to improve the match for this specific data. This is an additive offset to the measured slit positions; i.e., this should minimize the difference between the expected order positions and ``self.slit_spatial_center() + offset``. Must be in the fraction of the detector spatial scale. If None, no offset is applied. +``order_spat_range`` list .. .. The spatial range of the detector/mosaic over which to predict order locations. If None, the full detector/mosaic range is used. See ``add_missed_orders``. +``order_width_poly`` int .. 2 Order of the Legendre polynomial used to model the spatial width of each order as a function of spatial pixel position. See ``add_missed_orders``. +``overlap`` bool .. False Assume slits identified as abnormally short are actually due to overlaps between adjacent slits/orders. If set to True, you *must* have also used ``length_range`` to identify left-right edge pairs that have an abnormally short separation. For those short slits, the code attempts to convert the short slits into slit gaps. This is particularly useful for blue orders in Keck-HIRES data. +``pad`` int .. 0 Integer number of pixels to consider beyond the slit edges when selecting pixels that are 'on' the slit. +``pca_function`` str ``polynomial``, ``legendre``, ``chebyshev`` ``polynomial`` Type of function fit to the PCA coefficients for each component. Options are: polynomial, legendre, chebyshev +``pca_maxiter`` int .. 25 Maximum number of rejection iterations when fitting the PCA coefficients. +``pca_maxrej`` int .. 1 Maximum number of PCA coefficients rejected during a given fit iteration. +``pca_min_edges`` int .. 4 Minimum number of edge traces required to perform a PCA decomposition of the trace form. If left_right_pca is True, this minimum applies to the number of left and right traces separately. +``pca_n`` int .. .. The number of PCA components to keep, which must be less than the number of detected traces. If not provided, determined by calculating the minimum number of components required to explain a given percentage of variance in the edge data; see `pca_var_percent`. +``pca_order`` int .. 2 Order of the function fit to the PCA coefficients. +``pca_sigrej`` int, float, list .. 2.0, 2.0 Sigma rejection threshold for fitting PCA components. Individual numbers are used for both lower and upper rejection. A list of two numbers sets these explicitly (e.g., [2., 3.]). +``pca_var_percent`` int, float .. 99.8 The percentage (i.e., not the fraction) of the variance in the edge data accounted for by the PCA used to truncate the number of PCA coefficients to keep (see `pca_n`). Ignored if `pca_n` is provided directly. +``rm_slits`` str, list .. .. Remove one or more user-specified slits. The syntax used to define a slit to remove is: 'det:spec:spat' where det=detector, spec=spectral pixel, spat=spatial pixel. For example, '2:2000:2121,3:2000:1500' will remove the slit on detector 2 that contains pixel (spat,spec)=(2000,2121) and on detector 3 that contains pixel (2000,2121). +``smash_range`` list .. 0.0, 1.0 Range of the slit in the spectral direction (in fractional units) to smash when searching for slit edges. If the spectrum covers only a portion of the image, use that range. +``sobel_enhance`` int .. 0 Enhance the sobel filtering? A value of 0 will not enhance the sobel filtering. Any other value > 0 will sum the sobel values. For example, a value of 3 will combine the sobel values for the 3 nearest pixels. This is useful when a slit edge is poorly defined (e.g. vignetted). +``sobel_mode`` str ``nearest``, ``constant`` ``nearest`` Mode for Sobel filtering. Default is 'nearest'; note we find'constant' works best for DEIMOS. +``sync_center`` str ``median``, ``nearest``, ``gap`` ``median`` Mode to use for determining the location of traces to insert. Use `median` to use the median of the matched left and right edge pairs, `nearest` to use the length of the nearest slit, or `gap` to offset by a fixed gap width from the next slit edge. +``sync_predict`` str ``pca``, ``nearest``, ``auto`` ``pca`` Mode to use when predicting the form of the trace to insert. Use `pca` to use the PCA decomposition, `nearest` to reproduce the shape of the nearest trace, or `auto` to let PypeIt decide which mode to use between `pca` and `nearest`. In general, it will first try `pca`, and if that is not possible, it will use `nearest`. +``sync_to_edge`` bool .. True If adding a first left edge or a last right edge, ignore `center_mode` for these edges and place them at the edge of the detector (with the relevant shape). +``trace_median_frac`` int, float .. .. After detection of peaks in the rectified Sobel-filtered image and before refitting the edge traces, the rectified image is median filtered with a kernel width of `trace_median_frac*nspec` along the spectral dimension. +``trace_rms_tol`` int, float .. .. After retracing edges using peaks detected in the rectified and collapsed image, the RMS difference (in pixels) between the original and refit traces are calculated. This sets the upper limit of the RMS for traces that will be removed. If None, no limit is set and all new traces are kept. +``trace_thresh`` int, float .. .. After rectification and median filtering of the Sobel-filtered image (see `trace_median_frac`), values in the median-filtered image *below* this threshold are masked in the refitting of the edge trace data. If None, no masking applied. +``trim_spec`` list .. .. User-defined truncation of all slits in the spectral direction.Should be two integers, e.g. 100,150 trims 100 pixels from the short wavelength end and 150 pixels from the long wavelength end of the spectral axis of the detector. +``use_maskdesign`` bool .. False Use slit-mask designs to identify slits. +=========================== ================ =========================================== ============== =================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== ---- @@ -582,21 +584,21 @@ Collate1DPar Keywords Class Instantiation: :class:`~pypeit.par.pypeitpar.Collate1DPar` -========================= =============== ======= =============================== ================================================================================================================================================================================================================================================================================================================================================================================================================== -Key Type Options Default Description -========================= =============== ======= =============================== ================================================================================================================================================================================================================================================================================================================================================================================================================== -``dry_run`` bool .. False If set, the script will display the matching File and Object Ids but will not flux, coadd or archive. -``exclude_serendip`` bool .. False Whether to exclude SERENDIP objects from collating. -``exclude_slit_trace_bm`` list, str .. A list of slit trace bitmask bits that should be excluded. -``flux`` bool .. False If set, the script will flux calibrate using archived sensfuncs before coadding. -``ignore_flux`` bool .. False 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. -``match_using`` str .. ``ra/dec`` Determines how 1D spectra are matched as being the same object. Must be either 'pixel' or 'ra/dec'. -``outdir`` str .. ``/home/dusty/work/PypeIt/doc`` The path where all coadded output files and report files will be placed. -``refframe`` str .. .. Perform reference frame correction prior to coadding. Options are: observed, heliocentric, barycentric -``spec1d_outdir`` str .. .. The path where all modified spec1d files are placed. These are only created if flux calibration or refframe correction are asked for. -``tolerance`` str, float, int .. 1.0 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. -``wv_rms_thresh`` float .. .. If set, any objects with a wavelength RMS > this value are skipped, else all wavelength RMS values are accepted. -========================= =============== ======= =============================== ================================================================================================================================================================================================================================================================================================================================================================================================================== +========================= =============== ======= ============================================ ================================================================================================================================================================================================================================================================================================================================================================================================================== +Key Type Options Default Description +========================= =============== ======= ============================================ ================================================================================================================================================================================================================================================================================================================================================================================================================== +``dry_run`` bool .. False If set, the script will display the matching File and Object Ids but will not flux, coadd or archive. +``exclude_serendip`` bool .. False Whether to exclude SERENDIP objects from collating. +``exclude_slit_trace_bm`` list, str .. A list of slit trace bitmask bits that should be excluded. +``flux`` bool .. False If set, the script will flux calibrate using archived sensfuncs before coadding. +``ignore_flux`` bool .. False 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. +``match_using`` str .. ``ra/dec`` Determines how 1D spectra are matched as being the same object. Must be either 'pixel' or 'ra/dec'. +``outdir`` str .. ``/Users/westfall/Work/packages/pypeit/doc`` The path where all coadded output files and report files will be placed. +``refframe`` str .. .. Perform reference frame correction prior to coadding. Options are: observed, heliocentric, barycentric +``spec1d_outdir`` str .. .. The path where all modified spec1d files are placed. These are only created if flux calibration or refframe correction are asked for. +``tolerance`` str, float, int .. 1.0 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. +``wv_rms_thresh`` float .. .. If set, any objects with a wavelength RMS > this value are skipped, else all wavelength RMS values are accepted. +========================= =============== ======= ============================================ ================================================================================================================================================================================================================================================================================================================================================================================================================== ---- @@ -617,7 +619,7 @@ Key Type Options ``multi_min_SN`` int, float .. 1 Minimum S/N for analyzing sky spectrum for flexure ``spec_maxshift`` int .. 20 Maximum allowed spectral flexure shift in pixels. ``spec_method`` str ``boxcar``, ``slitcen``, ``skip`` ``skip`` Method used to correct for flexure. Use skip for no correction. If slitcen is used, the flexure correction is performed before the extraction of objects (not recommended). Options are: None, boxcar, slitcen, skip -``spectrum`` str .. ``paranal_sky.fits`` Archive sky spectrum to be used for the flexure correction. +``spectrum`` str .. ``paranal_sky.fits`` Archive sky spectrum to be used for the flexure correction. See ``pypeit/data/sky_spec/`` for a list of available sky spectra. If ``model`` is used, a model sky spectrum will be generated using :func:`~pypeit.wavemodel.nearIR_modelsky` and the spectralresolution of the spectrum to be flexure corrected. =================== ========== ======================================================== ==================== ====================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== @@ -649,22 +651,22 @@ ReduxPar Keywords Class Instantiation: :class:`~pypeit.par.pypeitpar.ReduxPar` -====================== ============== ======= =============================== ========================================================================================================================================================================================================================================================================================================================================================================================================== -Key Type Options Default Description -====================== ============== ======= =============================== ========================================================================================================================================================================================================================================================================================================================================================================================================== -``calwin`` int, float .. 0 The window of time in hours to search for calibration frames for a science frame -``chk_version`` bool .. True 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! -``detnum`` int, list .. .. Restrict reduction to a list of detector indices. In case of mosaic reduction (currently only available for Gemini/GMOS and Keck/DEIMOS) ``detnum`` should be a list of tuples of the detector indices that are mosaiced together. E.g., for Gemini/GMOS ``detnum`` would be ``[(1,2,3)]`` and for Keck/DEIMOS it would be ``[(1, 5), (2, 6), (3, 7), (4, 8)]`` -``ignore_bad_headers`` bool .. False Ignore bad headers (NOT recommended unless you know it is safe). -``maskIDs`` str, int, list .. .. Restrict reduction to a set of slitmask IDs Example syntax -- ``maskIDs = 818006,818015`` This must be used with detnum (for now). -``qadir`` str .. ``QA`` Directory relative to calling directory to write quality assessment files. -``quicklook`` bool .. False Run a quick look reduction? This is usually good if you want to quickly reduce the data (usually at the telescope in real time) to get an initial estimate of the data quality. -``redux_path`` str .. ``/home/dusty/work/PypeIt/doc`` Path to folder for performing reductions. Default is the current working directory. -``scidir`` str .. ``Science`` Directory relative to calling directory to write science files. -``slitspatnum`` str, list .. .. Restrict reduction to a set of slit DET:SPAT values (closest slit is used). Example syntax -- slitspatnum = DET01:175,DET01:205 or MSC02:2234 If you are re-running the code, (i.e. modifying one slit) you *must* have the precise SPAT_ID index. -``sortroot`` str .. .. A filename given to output the details of the sorted files. If None, the default is the root name of the pypeit file. If off, no output is produced. -``spectrograph`` str .. .. Spectrograph that provided the data to be reduced. See :ref:`instruments` for valid options. -====================== ============== ======= =============================== ========================================================================================================================================================================================================================================================================================================================================================================================================== +====================== ============== ======= ============================================ ========================================================================================================================================================================================================================================================================================================================================================================================================== +Key Type Options Default Description +====================== ============== ======= ============================================ ========================================================================================================================================================================================================================================================================================================================================================================================================== +``calwin`` int, float .. 0 The window of time in hours to search for calibration frames for a science frame +``chk_version`` bool .. True 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! +``detnum`` int, list .. .. Restrict reduction to a list of detector indices. In case of mosaic reduction (currently only available for Gemini/GMOS and Keck/DEIMOS) ``detnum`` should be a list of tuples of the detector indices that are mosaiced together. E.g., for Gemini/GMOS ``detnum`` would be ``[(1,2,3)]`` and for Keck/DEIMOS it would be ``[(1, 5), (2, 6), (3, 7), (4, 8)]`` +``ignore_bad_headers`` bool .. False Ignore bad headers (NOT recommended unless you know it is safe). +``maskIDs`` str, int, list .. .. Restrict reduction to a set of slitmask IDs Example syntax -- ``maskIDs = 818006,818015`` This must be used with detnum (for now). +``qadir`` str .. ``QA`` Directory relative to calling directory to write quality assessment files. +``quicklook`` bool .. False Run a quick look reduction? This is usually good if you want to quickly reduce the data (usually at the telescope in real time) to get an initial estimate of the data quality. +``redux_path`` str .. ``/Users/westfall/Work/packages/pypeit/doc`` Path to folder for performing reductions. Default is the current working directory. +``scidir`` str .. ``Science`` Directory relative to calling directory to write science files. +``slitspatnum`` str, list .. .. Restrict reduction to a set of slit DET:SPAT values (closest slit is used). Example syntax -- slitspatnum = DET01:175,DET01:205 or MSC02:2234 If you are re-running the code, (i.e. modifying one slit) you *must* have the precise SPAT_ID index. +``sortroot`` str .. .. A filename given to output the details of the sorted files. If None, the default is the root name of the pypeit file. If off, no output is produced. +``spectrograph`` str .. .. Spectrograph that provided the data to be reduced. See :ref:`instruments` for valid options. +====================== ============== ======= ============================================ ========================================================================================================================================================================================================================================================================================================================================================================================================== ---- @@ -706,7 +708,6 @@ Key Type Options ``correct_dar`` bool .. True If True, the data will be corrected for differential atmospheric refraction (DAR). ``dec_max`` float .. .. Maximum DEC to use when generating the WCS. If None, the default is maximum DEC based on the WCS of all spaxels. Units should be degrees. ``dec_min`` float .. .. Minimum DEC to use when generating the WCS. If None, the default is minimum DEC based on the WCS of all spaxels. Units should be degrees. -``grating_corr`` bool .. True This option performs a small correction for the relative blaze function of all input frames that have (even slightly) different grating angles, or if you are flux calibrating your science data with a standard star that was observed with a slightly different setup. ``method`` str ``subpixel``, ``ngp`` ``subpixel`` What method should be used to generate the datacube. There are currently two options: (1) "subpixel" (default) - this algorithm divides each pixel in the spec2d frames into subpixels, and assigns each subpixel to a voxel of the datacube. Flux is conserved, but voxels are correlated, and the error spectrum does not account for covariance between adjacent voxels. See also, spec_subpixel and spat_subpixel. (2) "ngp" (nearest grid point) - this algorithm is effectively a 3D histogram. Flux is conserved, voxels are not correlated, however this option suffers the same downsides as any histogram; the choice of bin sizes can change how the datacube appears. This algorithm takes each pixel on the spec2d frame and puts the flux of this pixel into one voxel in the datacube. Depending on the binning used, some voxels may be empty (zero flux) while a neighboring voxel might contain the flux from two spec2d pixels. Note that all spec2d pixels that contribute to the same voxel are inverse variance weighted (e.g. if two pixels have the same variance, the voxel would be assigned the average flux of the two pixels). ``output_filename`` str .. .. If combining multiple frames, this string sets the output filename of the combined datacube. If combine=False, the output filenames will be prefixed with ``spec3d_*`` ``ra_max`` float .. .. Maximum RA to use when generating the WCS. If None, the default is maximum RA based on the WCS of all spaxels. Units should be degrees. @@ -714,13 +715,13 @@ Key Type Options ``reference_image`` str .. .. White light image of a previously combined datacube. The white light image will be used as a reference when calculating the offsets of the input spec2d files. Ideally, the reference image should have the same shape as the data to be combined (i.e. set the ra_min, ra_max etc. params so they are identical to the reference image). ``save_whitelight`` bool .. False Save a white light image of the combined datacube. The output filename will be given by the "output_filename" variable with a suffix "_whitelight". Note that the white light image collapses the flux along the wavelength axis, so some spaxels in the 2D white light image may have different wavelength ranges. To set the wavelength range, use the "whitelight_range" parameter. If combine=False, the individual spec3d files will have a suffix "_whitelight". ``scale_corr`` str .. .. This option performs a small correction for the relative spectral illumination scale of different spec2D files. Specify the relative path+file to the spec2D file that you would like to use for the relative scaling. If you want to perform this correction, it is best to use the spec2d file with the highest S/N sky spectrum. You should choose the same frame for both the standards and science frames. +``sensfile`` str .. .. Filename of a sensitivity function to use to flux calibrate your datacube. The sensitivity function file will also be used to correct the relative scales of the slits. ``skysub_frame`` str .. ``image`` Set the sky subtraction to be implemented. The default behaviour is to subtract the sky using the model that is derived from each individual image (i.e. set this parameter to "image"). To turn off sky subtraction completely, set this parameter to "none" (all lowercase). Finally, if you want to use a different frame for the sky subtraction, specify the relative path+file to the spec2D file that you would like to use for the sky subtraction. The model fit to the sky of the specified frame will be used. Note, the sky and science frames do not need to have the same exposure time; the sky model will be scaled to the science frame based on the relative exposure time. ``slice_subpixel`` int .. 5 When method=subpixel, slice_subpixel sets the subpixellation scale of each IFU slice. The default option is to divide each slice into 5 sub-slices during datacube creation. See also, spec_subpixel and spat_subpixel. ``slit_spec`` bool .. True If the data use slits in one spatial direction, set this to True. If the data uses fibres for all spaxels, set this to False. ``spat_subpixel`` int .. 5 When method=subpixel, spat_subpixel sets the subpixellation scale of each detector pixel in the spatial direction. The total number of subpixels in each pixel is given by spec_subpixel x spat_subpixel. The default option is to divide each spec2d pixel into 25 subpixels during datacube creation. See also, spec_subpixel and slice_subpixel. ``spatial_delta`` float .. .. The spatial size of each spaxel to use when generating the WCS (in arcsec). If None, the default is set by the spectrograph file. ``spec_subpixel`` int .. 5 When method=subpixel, spec_subpixel sets the subpixellation scale of each detector pixel in the spectral direction. The total number of subpixels in each pixel is given by spec_subpixel x spat_subpixel. The default option is to divide each spec2d pixel into 25 subpixels during datacube creation. See also, spat_subpixel and slice_subpixel. -``standard_cube`` str .. .. Filename of a standard star datacube. This cube will be used to correct the relative scales of the slits, and to flux calibrate the science datacube. ``wave_delta`` float .. .. The wavelength step to use when generating the WCS (in Angstroms). If None, the default is set by the wavelength solution. ``wave_max`` float .. .. Maximum wavelength to use when generating the WCS. If None, the default is maximum wavelength based on the WCS of all spaxels. Units should be Angstroms. ``wave_min`` float .. .. Minimum wavelength to use when generating the WCS. If None, the default is minimum wavelength based on the WCS of all spaxels. Units should be Angstroms. @@ -864,43 +865,44 @@ ProcessImagesPar Keywords Class Instantiation: :class:`~pypeit.par.pypeitpar.ProcessImagesPar` -======================== ================================================ =================================================================== ============================= ============================================================================================================================================================================================================================================================================================================================================================ -Key Type Options Default Description -======================== ================================================ =================================================================== ============================= ============================================================================================================================================================================================================================================================================================================================================================ -``apply_gain`` bool .. True Convert the ADUs to electrons using the detector gain -``clip`` bool .. True Perform sigma clipping when combining. Only used with combine=mean -``comb_sigrej`` float .. .. Sigma-clipping level for when clip=True; Use None for automatic limit (recommended). -``combine`` str ``median``, ``mean`` ``mean`` Method used to combine multiple frames. Options are: median, mean -``dark_expscale`` bool .. False If designated dark frames are used and have a different exposure time than the science frames, scale the counts by the by the ratio in the exposure times to adjust the dark counts for the difference in exposure time. WARNING: You should always take dark frames that have the same exposure time as your science frames, so use this option with care! -``empirical_rn`` bool .. False If True, use the standard deviation in the overscan region to measure an empirical readnoise to use in the noise model. -``grow`` int, float .. 1.5 Factor by which to expand regions with cosmic rays detected by the LA cosmics routine. -``lamaxiter`` int .. 1 Maximum number of iterations for LA cosmics routine. -``mask_cr`` bool .. False Identify CRs and mask them -``n_lohi`` list .. 0, 0 Number of pixels to reject at the lowest and highest ends of the distribution; i.e., n_lohi = low, high. Use None for no limit. -``noise_floor`` float .. 0.0 Impose a noise floor by adding the provided fraction of the bias- and dark-subtracted electron counts to the error budget. E.g., a value of 0.01 means that the S/N of the counts in the image will never be greater than 100. -``objlim`` int, float .. 3.0 Object detection limit in LA cosmics routine -``orient`` bool .. True Orient the raw image into the PypeIt frame -``overscan_method`` str ``chebyshev``, ``polynomial``, ``savgol``, ``median``, ``odd_even`` ``savgol`` Method used to fit the overscan. Options are: chebyshev, polynomial, savgol, median, odd_even Note: Method "polynomial" is identical to "chebyshev"; the former is deprecated and will be removed. -``overscan_par`` int, list .. 5, 65 Parameters for the overscan subtraction. For 'chebyshev' or 'polynomial', set overcan_par = order; for 'savgol', set overscan_par = order, window size ; for 'median', set overscan_par = None or omit the keyword. -``rmcompact`` bool .. True Remove compact detections in LA cosmics routine -``satpix`` str ``reject``, ``force``, ``nothing`` ``reject`` Handling of saturated pixels. Options are: reject, force, nothing -``scattlight`` :class:`~pypeit.par.pypeitpar.ScatteredLightPar` .. `ScatteredLightPar Keywords`_ Scattered light subtraction parameters. -``shot_noise`` bool .. True Use the bias- and dark-subtracted image to calculate and include electron count shot noise in the image processing error budget -``sigclip`` int, float .. 4.5 Sigma level for rejection in LA cosmics routine -``sigfrac`` int, float .. 0.3 Fraction for the lower clipping threshold in LA cosmics routine. -``spat_flexure_correct`` bool .. False Correct slits, illumination flat, etc. for flexure -``spat_flexure_maxlag`` int .. 20 Maximum of possible spatial flexure correction, in pixels -``subtract_continuum`` bool .. False Subtract off the continuum level from an image. This parameter should only be set to True to combine arcs with multiple different lamps. For all other cases, this parameter should probably be False. -``subtract_scattlight`` bool .. False Subtract off the scattered light from an image. This parameter should only be set to True for spectrographs that have dedicated methods to subtract scattered light. For all other cases, this parameter should be False. -``trim`` bool .. True Trim the image to the detector supplied region -``use_biasimage`` bool .. True Use a bias image. If True, one or more must be supplied in the PypeIt file. -``use_darkimage`` bool .. False Subtract off a dark image. If True, one or more darks must be provided. -``use_illumflat`` bool .. True Use the illumination flat to correct for the illumination profile of each slit. -``use_overscan`` bool .. True Subtract off the overscan. Detector *must* have one or code will crash. -``use_pattern`` bool .. False Subtract off a detector pattern. This pattern is assumed to be sinusoidal along one direction, with a frequency that is constant across the detector. -``use_pixelflat`` bool .. True Use the pixel flat to make pixel-level corrections. A pixelflat image must be provied. -``use_specillum`` bool .. False Use the relative spectral illumination profiles to correct the spectral illumination profile of each slit. This is primarily used for slicer IFUs. To use this, you must set ``slit_illum_relative=True`` in the ``flatfield`` parameter set! -======================== ================================================ =================================================================== ============================= ============================================================================================================================================================================================================================================================================================================================================================ +======================== ================================================ =================================================================== ============================= ======================================================================================================================================================================================================================================================================================================================================================================================== +Key Type Options Default Description +======================== ================================================ =================================================================== ============================= ======================================================================================================================================================================================================================================================================================================================================================================================== +``apply_gain`` bool .. True Convert the ADUs to electrons using the detector gain +``clip`` bool .. True Perform sigma clipping when combining. Only used with combine=mean +``comb_sigrej`` float .. .. Sigma-clipping level for when clip=True; Use None for automatic limit (recommended). +``combine`` str ``median``, ``mean`` ``mean`` Method used to combine multiple frames. Options are: median, mean +``correct_nonlinear`` list .. .. Correct for non-linear response of the detector. If None, no correction is performed. If a list, then the list should be the non-linear correction parameter (alpha), where the functional form is given by Ct = Cm (1 + alpha x Cm), with Ct and Cm the true and measured counts. This parameter is usually hard-coded for a given spectrograph, and should otherwise be left as None. +``dark_expscale`` bool .. False If designated dark frames are used and have a different exposure time than the science frames, scale the counts by the by the ratio in the exposure times to adjust the dark counts for the difference in exposure time. WARNING: You should always take dark frames that have the same exposure time as your science frames, so use this option with care! +``empirical_rn`` bool .. False If True, use the standard deviation in the overscan region to measure an empirical readnoise to use in the noise model. +``grow`` int, float .. 1.5 Factor by which to expand regions with cosmic rays detected by the LA cosmics routine. +``lamaxiter`` int .. 1 Maximum number of iterations for LA cosmics routine. +``mask_cr`` bool .. False Identify CRs and mask them +``n_lohi`` list .. 0, 0 Number of pixels to reject at the lowest and highest ends of the distribution; i.e., n_lohi = low, high. Use None for no limit. +``noise_floor`` float .. 0.0 Impose a noise floor by adding the provided fraction of the bias- and dark-subtracted electron counts to the error budget. E.g., a value of 0.01 means that the S/N of the counts in the image will never be greater than 100. +``objlim`` int, float .. 3.0 Object detection limit in LA cosmics routine +``orient`` bool .. True Orient the raw image into the PypeIt frame +``overscan_method`` str ``chebyshev``, ``polynomial``, ``savgol``, ``median``, ``odd_even`` ``savgol`` Method used to fit the overscan. Options are: chebyshev, polynomial, savgol, median, odd_even Note: Method "polynomial" is identical to "chebyshev"; the former is deprecated and will be removed. +``overscan_par`` int, list .. 5, 65 Parameters for the overscan subtraction. For 'chebyshev' or 'polynomial', set overcan_par = order; for 'savgol', set overscan_par = order, window size ; for 'median', set overscan_par = None or omit the keyword. +``rmcompact`` bool .. True Remove compact detections in LA cosmics routine +``satpix`` str ``reject``, ``force``, ``nothing`` ``reject`` Handling of saturated pixels. Options are: reject, force, nothing +``scattlight`` :class:`~pypeit.par.pypeitpar.ScatteredLightPar` .. `ScatteredLightPar Keywords`_ Scattered light subtraction parameters. +``shot_noise`` bool .. True Use the bias- and dark-subtracted image to calculate and include electron count shot noise in the image processing error budget +``sigclip`` int, float .. 4.5 Sigma level for rejection in LA cosmics routine +``sigfrac`` int, float .. 0.3 Fraction for the lower clipping threshold in LA cosmics routine. +``spat_flexure_correct`` bool .. False Correct slits, illumination flat, etc. for flexure +``spat_flexure_maxlag`` int .. 20 Maximum of possible spatial flexure correction, in pixels +``subtract_continuum`` bool .. False Subtract off the continuum level from an image. This parameter should only be set to True to combine arcs with multiple different lamps. For all other cases, this parameter should probably be False. +``subtract_scattlight`` bool .. False Subtract off the scattered light from an image. This parameter should only be set to True for spectrographs that have dedicated methods to subtract scattered light. For all other cases, this parameter should be False. +``trim`` bool .. True Trim the image to the detector supplied region +``use_biasimage`` bool .. True Use a bias image. If True, one or more must be supplied in the PypeIt file. +``use_darkimage`` bool .. False Subtract off a dark image. If True, one or more darks must be provided. +``use_illumflat`` bool .. True Use the illumination flat to correct for the illumination profile of each slit. +``use_overscan`` bool .. True Subtract off the overscan. Detector *must* have one or code will crash. +``use_pattern`` bool .. False Subtract off a detector pattern. This pattern is assumed to be sinusoidal along one direction, with a frequency that is constant across the detector. +``use_pixelflat`` bool .. True Use the pixel flat to make pixel-level corrections. A pixelflat image must be provied. +``use_specillum`` bool .. False Use the relative spectral illumination profiles to correct the spectral illumination profile of each slit. This is primarily used for slicer IFUs. To use this, you must set ``slit_illum_relative=True`` in the ``flatfield`` parameter set! +======================== ================================================ =================================================================== ============================= ======================================================================================================================================================================================================================================================================================================================================================================================== ---- @@ -2031,12 +2033,11 @@ Alterations to the default parameters are: noise_floor = 0.01 use_illumflat = False [[flatfield]] + tweak_method = gradient tweak_slits_thresh = 0.0 tweak_slits_maxfrac = 0.0 slit_trim = 2 slit_illum_finecorr = False - [[slitedges]] - pad = 2 [[tilts]] spat_order = 1 spec_order = 1 @@ -2061,8 +2062,6 @@ Alterations to the default parameters are: [[extraction]] model_full_slit = True skip_extraction = True - [[cube]] - grating_corr = False [flexure] spec_maxshift = 0 [sensfunc] @@ -2152,6 +2151,9 @@ Alterations to the default parameters are: mask_cr = True noise_floor = 0.01 [[flatfield]] + tweak_method = gradient + tweak_slits_thresh = 0.0 + tweak_slits_maxfrac = 0.0 slit_illum_finecorr = False [[wavelengths]] method = full_template @@ -3023,18 +3025,16 @@ Alterations to the default parameters are: noise_floor = 0.01 [[flatfield]] spec_samp_coarse = 20.0 + tweak_method = gradient tweak_slits_thresh = 0.0 tweak_slits_maxfrac = 0.0 slit_illum_relative = True slit_illum_ref_idx = 14 - slit_illum_smooth_npix = 5 - fit_2d_det_response = True [[wavelengths]] fwhm_spat_order = 2 [[slitedges]] edge_thresh = 5 fit_order = 4 - pad = 2 [scienceframe] [[process]] mask_cr = True @@ -3085,16 +3085,18 @@ Alterations to the default parameters are: use_pattern = True [[arcframe]] [[[process]]] + correct_nonlinear = -1.4e-07, -1.4e-07, -1.2e-07, -1.8e-07, use_pixelflat = False use_illumflat = False [[tiltframe]] [[[process]]] + correct_nonlinear = -1.4e-07, -1.4e-07, -1.2e-07, -1.8e-07, use_pixelflat = False use_illumflat = False [[pixelflatframe]] [[[process]]] - combine = median satpix = nothing + correct_nonlinear = -1.4e-07, -1.4e-07, -1.2e-07, -1.8e-07, use_pixelflat = False use_illumflat = False subtract_scattlight = True @@ -3112,6 +3114,7 @@ Alterations to the default parameters are: [[illumflatframe]] [[[process]]] satpix = nothing + correct_nonlinear = -1.4e-07, -1.4e-07, -1.2e-07, -1.8e-07, use_illumflat = False use_pattern = True subtract_scattlight = True @@ -3132,32 +3135,32 @@ Alterations to the default parameters are: [[standardframe]] [[[process]]] mask_cr = True + correct_nonlinear = -1.4e-07, -1.4e-07, -1.2e-07, -1.8e-07, noise_floor = 0.01 use_pattern = True [[flatfield]] spec_samp_coarse = 20.0 spat_samp = 1.0 + tweak_method = gradient tweak_slits_thresh = 0.0 tweak_slits_maxfrac = 0.0 slit_illum_relative = True slit_illum_ref_idx = 14 - slit_illum_smooth_npix = 5 fit_2d_det_response = True [[wavelengths]] fwhm_spat_order = 2 [[slitedges]] edge_thresh = 5 fit_order = 4 - pad = 2 [scienceframe] [[process]] mask_cr = True sigclip = 4.0 objlim = 1.5 + correct_nonlinear = -1.4e-07, -1.4e-07, -1.2e-07, -1.8e-07, noise_floor = 0.01 use_specillum = True use_pattern = True - subtract_scattlight = True [[[scattlight]]] finecorr_method = median [reduce] diff --git a/doc/releases/1.16.1dev.rst b/doc/releases/1.16.1dev.rst index 632725788c..8e33f8e4a0 100644 --- a/doc/releases/1.16.1dev.rst +++ b/doc/releases/1.16.1dev.rst @@ -18,6 +18,10 @@ Dependency Changes Functionality/Performance Improvements and Additions ---------------------------------------------------- +- Added the ``max_overlap`` parameter, which limits the set of new order traces + added, to compensate for orders missed during automated edge-tracing, to those + that have less than a given fractional overlap with adjacent orders. + Instrument-specific Updates --------------------------- diff --git a/pypeit/core/datacube.py b/pypeit/core/datacube.py index 3f9625ba9b..72c075eae9 100644 --- a/pypeit/core/datacube.py +++ b/pypeit/core/datacube.py @@ -223,7 +223,7 @@ def extract_point_source(wave, flxcube, ivarcube, bpmcube, wcscube, exptime, Returns ------- - sobjs : `pypeit.specobjs.SpecObjs`_ + sobjs : :class:`~pypeit.specobjs.SpecObjs` SpecObjs object containing the extracted spectrum """ if whitelight_range is None: diff --git a/pypeit/flatfield.py b/pypeit/flatfield.py index 432ed4d469..6efa7da69d 100644 --- a/pypeit/flatfield.py +++ b/pypeit/flatfield.py @@ -1584,8 +1584,9 @@ def spectral_illumination(self, gpm=None, debug=False): smooth_npix=self.flatpar['slit_illum_smooth_npix'], debug=debug) - def tweak_slit_edges(self, left, right, spat_coo, norm_flat, method='threshold', thresh=0.93, maxfrac=0.1, debug=False): - """ + def tweak_slit_edges(self, left, right, spat_coo, norm_flat, method='threshold', thresh=0.93, + maxfrac=0.1, debug=False): + r""" Tweak the slit edges based on the normalized slit illumination profile. Args: @@ -1607,11 +1608,11 @@ def tweak_slit_edges(self, left, right, spat_coo, norm_flat, method='threshold', method (:obj:`str`, optional): Method to use for tweaking the slit edges. Options are: - 'threshold': Use the threshold to set the slit edge - and then shift it to the left or right based on the - illumination profile. + and then shift it to the left or right based on the + illumination profile. - 'gradient': Use the gradient of the illumination - profile to set the slit edge and then shift it to - the left or right based on the illumination profile. + profile to set the slit edge and then shift it to + the left or right based on the illumination profile. thresh (:obj:`float`, optional): Threshold of the normalized flat profile at which to place the two slit edges. @@ -1637,6 +1638,7 @@ def tweak_slit_edges(self, left, right, spat_coo, norm_flat, method='threshold', - The fraction of the slit that the right edge is shifted to the left - The adjusted right edge + """ # TODO :: Since this is just a wrapper, and not really "core", maybe it should be moved to pypeit.flatfield? # Tweak the edges via the specified method diff --git a/pypeit/images/combineimage.py b/pypeit/images/combineimage.py index 635cb4905d..d93d51a033 100644 --- a/pypeit/images/combineimage.py +++ b/pypeit/images/combineimage.py @@ -22,9 +22,10 @@ class CombineImage: Process and combine detector images. Args: - rawImages (:obj:`list`, :class:`~pypeit.images.pypeitimage.PypeItImage): - Either a single :class:`~pypeit.images.pypeitimage.PypeItImage` object or a list of one or more - of these objects to be combined into a an image. + rawImages (:obj:`list`, :class:`~pypeit.images.pypeitimage.PypeItImage`): + Either a single :class:`~pypeit.images.pypeitimage.PypeItImage` + object or a list of one or more of these objects to be combined into + a an image. par (:class:`~pypeit.par.pypeitpar.ProcessImagesPar`): Parameters that dictate the processing of the images. @@ -36,7 +37,6 @@ class CombineImage: rawImages (:obj:`list`): A list of one or more :class:`~pypeit.images.rawimage.RawImage` objects to be combined. - """ def __init__(self, rawImages, par): if not isinstance(par, pypeitpar.ProcessImagesPar):