******************** Calibration Products ******************** The APOGEE pipeline has a number of calibration products that it uses for the processing. There are master/super calibration products that are made every year or so, and daily calibration products that are made every day. The ``makecal.pro`` program can be used to make all of these calibration files. Master Calibrations =================== There is a master list of calibration products for each APOGEE instrument, e.g. `apogee-n.par `_ for APO. This specifies the type, name and files to use to generate a given master calibration product. Dark ---- The master dark files correct for any dark current including any time dependence. Therefore, they are kept as 3D data cubes. A sequence of ~30 100 read darks are used to generate these. The master darks are remade roughly every few years. The ``apDark`` files are made by ``mkdark.pro``. Flat ---- The master flat files are used to correct for any pixel-to-pixel quantum efficiency (QE) variations. They are made using a sequence of ~30 internal LED exposures and stacked. Note that currently the large scale structure is difficult to remove and is left in the master flat (see `Flux Calibration `_ for more details). The master flats are remade roughly every few years. The ``apFlat`` files are made by ``mkflat.pro``. BPM --- The master bad pixel mask (BPM) files are used to mask bad pixels. Information from the master apDark and apFlat calibration products are used to determine which pixels should be considered "bad". The master BPMs are remade roughly every few years. The ``apBPM`` files are made by ``mkbpm.pro``. Detector -------- The detector file contains the read noise, gain, and linearity terms for each 512x2048 "quadrant" of a single APOGEE detector. Note, currently the linearity correction is not used. The master detector file is only made very rarely. The ``apDetector`` files are are made by ``mkdet.pro``. Linearity --------- The linearity terms are determined by using an up-the-ramp datacube of an internal LED exposure. Note, currently the linearity correction is not used. The ``apLinearity`` files are made by ``mklinearity.pro``. Persistance ----------- The persistence calibration file is generated from a flat and dark exposures. It it used to flag pixels that suffer from "superpersistence". The ``apPersist`` files are made by ``mkpersist.pro``. Persistance Model ----------------- The persistence model calibration file was generated with special software written by Duy Nguyen and special exposure sequences with an internal lamp exposure followed by many hours of darks to measure the persistence. The pipeline uses these model files to attempt to correct for the superpersistence effect, with some moderate success. These were only generated once for the green and blue detectors. Littrow ------- The "Littrow ghost" (described in `Burgh et al. (2007) `_ is an optical effect of a spectrograph operating in Littrow configuration (the diffracted beam is back-reflected into the direction of the incident beam). From Wilson et al. 2019:: This ghost is formed by dispersed light that is reflected backwards into the camera by the detector arrays and then reflectively recombined by the VPH grating into zeroth order (white light) and finally reimaged by the camera on the detector arrays at the location of the Littrow wavelength. A domeflat or quartzflat exposure is used to determine the pixels affected by the Littrow ghost. The Littrow calibration product is used to flag pixels during the reduction process. The master littrow files are only made very rarely. The ``apLittrow`` files are made by ``mklittrow.pro``. LSF --- Line Spread Function calibration file is generated by fitting an analytical (slowly spatially varying Gauss-Hermite polynomials) line models to the airglow emission lines in a "sky flat" (all fibers on sky) exposure. The LSF files are generated roughly every couple of years especially after any instrument maintenance. The ``apLSF`` files are made by ``mklsf.pro``. Daily Calibrations ================== Daily calibration products do not need to be specified in the master calibration list. PSF --- The PSF calibration files are made from either domeflat or quartzflat exposures. The traces of the fibers are determined and Gaussians are fit to each fiber/column. Empirical profiles are produced and saved in the ``apEPSF`` files. The information is used to help in the spectral extraction process in ``ap2D``. The ``apPSF/apEPSF/apETrace`` files are made by ``mkpsf.pro``. Flux ---- The flux calibration files are generated by smoothing domeflat exposures. They correct for fiber-to-fiber throughput and spectral response variations. See `Flux Calibration `_ for more information on the APOGEE flux calibration. The ``apFlux`` files are made by ``mkflux.pro``. Wave ---- Daily wavelength solutions are made using generally a single ThArNe and UNe arclamp exposures. This identifies and fits Gaussians to all of the lines and fits a ~5th order polynomial (plus detector offsets) to the lines for all three chips and each fiber. The ``apWave` files are made by ``apwave.pro``. DailyWave --------- A wavelength solution is generated by fitting many arclamp exposures simultaneously allowing for dither shifts between each group. Arc lamp exposures are selected from +/-3 days which ends up being roughly 60 exposures. The ``apWave-?-MJD.fits`` files are made by ``mkdailywave.pro``. FPI --- The daily FPI calibration product is generated using a full-frame (all 300 fibers) FPI exposure and a set of ThArNe and UNe arclamps taken at the exact same dither position (with no dithers in between). Arclamps taken over the last week are also used included to better constrain the wavelength solution. This is then used to determine the wavelengths for all lines in the FPI exposure. The wavelengths of each unique FPI line are determined by averaging over the values of the 300 fibers. These average FPI wavelength values are then used to redetermine the wavelength solution for each fiber with high precision. The ``apWaveFPI`` files are made by ``mkfpi.pro`. Telluric -------- A separate set of files, ``apTelluric``, are used by the pipeline, but they aren't officially calibration products. They are more mostly a time-saving device. They are generated by convolving the telluric models for CH4, CO2 and H2O by a particular LSF calibration product and later used during the telluric correction process. The convolving is performed automatically (as needed) when ap1dvisit.pro is run using ``aptelluric_convolve.pro``.