Calibration files

doc/DESI_SPECTRO_REDUX/SPECPROD/calibnight/NIGHT/biasnight-CAMERA-NIGHT.rst

@@ -2,9 +2,7 @@
 biasnight-CAMERA-NIGHT.fits
 ===========================
 
-:Summary: *This section should be filled in with a high-level description of
-    this file. In general, you should remove or replace the emphasized text
-    (\*this text is emphasized\*) in this document.*
+:Summary: Master bias frame for the preprocessing of the night data
 :Naming Convention: ``biasnight-CAMERA-NIGHT.fits.gz``, where ``CAMERA`` is
     *e.g.*, "b0", "r5", etc. and ``NIGHT`` is the observation night in
     YYYYMMDD format.
@@ -17,7 +15,7 @@ Contents
 ====== ======= ===== ===================
 Number EXTNAME Type  Contents
 ====== ======= ===== ===================
-HDU0_  BIAS    IMAGE *Brief Description*
+HDU0_  BIAS    IMAGE bias image
 ====== ======= ===== ===================
 
 
@@ -29,7 +27,8 @@ HDU0
 
 EXTNAME = BIAS
 
-*Summarize the contents of this HDU.*
+2D image with the master bias to subtract to the raw images of the night.
+
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~

doc/DESI_SPECTRO_REDUX/SPECPROD/calibnight/NIGHT/biasnighttest-CAMERA-NIGHT.rst

@@ -19,7 +19,7 @@ Contents
 ====== ======= ===== ===================
 Number EXTNAME Type  Contents
 ====== ======= ===== ===================
-HDU0_  BIAS    IMAGE *Brief Description*
+HDU0_  BIAS    IMAGE bias image
 ====== ======= ===== ===================
 
 
@@ -31,7 +31,7 @@ HDU0
 
 EXTNAME = BIAS
 
-*Summarize the contents of this HDU.*
+2D image with the master bias to subtract to the raw images of the night.
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~

doc/DESI_SPECTRO_REDUX/SPECPROD/calibnight/NIGHT/fiberflatnight-CAMERA-NIGHT.rst

@@ -34,7 +34,7 @@ HDU0
 
 EXTNAME = FIBERFLAT
 
-Relative fiber-to-fiber variation.  Corrected flux = original flux / fiberflat.
+Fiber flat field correction to homogeneize the response among fibers of the same camera, for each wavelength. 2D array of dimension [nspec, nwave]. nspec is the number of fibers per camera. nwave in the length of the wavelength array. The fiber flat field of all fibers share the same wavelength grid (given in HDU WAVELENGTH). This file is the fiber flat derived from a series of flat field exposures. It is the one used for the science observations during the night.
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -444,7 +444,7 @@ HDU1
 
 EXTNAME = IVAR
 
-Inverse variance of fiberflat.
+Inverse variance (1/sigma^2) of the fiber flat field in HDU0.
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -470,8 +470,7 @@ HDU2
 
 EXTNAME = MASK
 
-Mask of fiberflat (0=good).
-
+Mask of the fiberflat; 0=good. See the :doc:`bitmask documentation </bitmasks>` page for the definition of the bits.
 Prior to desispec/0.24.0 and software release 18.9, the MASK HDU was compressed.
 
 Required Header Keywords
@@ -499,7 +498,8 @@ HDU3
 
 EXTNAME = MEANSPEC
 
-Average continuum lamp spectrum.
+Average flat lamp spectrum of fibers in this camera frame. The fiber flat field is in first approximation the ratio of the measured spectra to this mean spectrum (in practice we use a deconvolved mean spectrum and reconvolve it with the resolution of each fiber). The units are electrons per Angstrom.
+
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -524,7 +524,7 @@ HDU4
 
 EXTNAME = WAVELENGTH
 
-Wavelengths in Angstroms at which the fiberflat is measured.
+Wavelength grid in Angstrom used by this fiber flat field. Note that contrary to the science frame, this wavelength array is in the observer frame. In consequence, one has to first convert its wavelength to the solar barycenter frame before using this data to flat field a science exposure. See the frame :ref:`WAVELENGTH documentation <frame-hdu3-wavelength>` for more details.
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -549,7 +549,7 @@ HDU5
 
 EXTNAME = FIBERMAP
 
-The fibermap HDU copied from other files.
+Fibermap with information about the fiber status.
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~

doc/DESI_SPECTRO_REDUX/SPECPROD/calibnight/NIGHT/psfnight-CAMERA-NIGHT.rst

@@ -16,9 +16,9 @@ Contents
 ====== ======= ======== ===================
 Number EXTNAME Type     Contents
 ====== ======= ======== ===================
-HDU0_  XTRACE  IMAGE    *Brief Description*
-HDU1_  YTRACE  IMAGE    *Brief Description*
-HDU2_  PSF     BINTABLE *Brief Description*
+HDU0_  XTRACE  IMAGE    Legendre coefficient of the fiber trace X CCD coordinates
+HDU1_  YTRACE  IMAGE    Legendre coefficient of the fiber trace Y CCD coordinates
+HDU2_  PSF     BINTABLE Table with PSF shape parameters
 ====== ======= ======== ===================
 
 
@@ -30,7 +30,13 @@ HDU0
 
 EXTNAME = XTRACE
 
-*Summarize the contents of this HDU.*
+Encodes the X coordinate of the fiber traces in the CCD.
+X is in units of pixels, along the cross-dispersion axis (perpendicular to the fiber traces) and increases with increasing fiber number.
+
+XTRACE is a 2D array of size [nfiber,ncoef]. Each row contains the Legendre polynomial coefficients for a fiber trace.
+The polynomial applies to a reduced wavelength = (2*wavelength-(WAVEMIN+WAVEMAX))/(WAVEMAX-WAVEMIN) where
+WAVEMIN and WAVEMAX are header keywords.
+
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -59,7 +65,13 @@ HDU1
 
 EXTNAME = YTRACE
 
-*Summarize the contents of this HDU.*
+Encodes the Y coordinate of the fiber traces in the CCD.
+Y is in units of pixels, along the dispersion axis and increases with increasing wavelength.
+
+YTRACE is a 2D array of size [nfiber,ncoef]. Each row contains the Legendre polynomial coefficients for a fiber trace.
+The polynomial applies to a reduced wavelength = (2*wavelength-(WAVEMIN+WAVEMAX))/(WAVEMAX-WAVEMIN) where
+WAVEMIN and WAVEMAX are header keywords.
+
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -86,7 +98,33 @@ HDU2
 
 EXTNAME = PSF
 
-*Summarize the contents of this HDU.*
+Binary table with the PSF shape parameters encoded as Legendre polynomials of wavelength, per fiber.
+
+Each row of the table addresses a parameter. The column PARAM provides its name. The column COEFF contains a 2D array of size [nfiber,ncoef] with its associated Legendre polynomial coefficients.
+
+As for XTRACE and YTRACE, each row of the COEFF array provided the Legendre coefficients of a fiber. The polynomial applies to the reduced wavelength = (2*wavelength-(WAVEMIN+WAVEMAX))/(WAVEMAX-WAVEMIN) where WAVEMIN and WAVEMAX are header keywords.
+
+The additional columns LEGDEGX and LEGDEGW are the degrees along the cross-dispersion and dispersion axes used during the fit.
+
+This format can apply to several PSF models. For the one currently used in DESI, based on Gauss-Hermite polynomials, the parameters are the following:
+ - 'GHSIGX' Gauss-Hermite Gaussian sigma along X
+ - 'GHSIGY' Gauss-Hermite Gaussian sigma along Y
+ - 'GH-I-J' with I and J in the range 0 to 6: Gauss-Hermite polynomial coefficient of degree I along X and J along Y
+ - 'TAILAMP' PSF tail amplitude
+ - 'TAILCORE' PSF tail core size
+ - 'TAILXSCA' relative scaling along X
+ - 'TAILYSCA' relative scaling along Y
+ - 'TAILINDE' PSF tail asymptotic power law index
+ - 'BUNDLE' Index of fiber bundle (or fiber block)
+ - 'STATUS' Not used currently (values = 0)
+ - 'CONT' Value of continuum at this fiber and wavelength
+
+PSF(X,Y) = PSF_CORE(X,Y) + PSF_TAIL(X,Y)
+
+PSF_CORE(X,Y) = [ SUM_ij (GH-i-j)*HERM(i,X/GHSIGX)*HERM(j,Y/GHSIGY)*GAUS(X,GHSIGX)*GAUS(Y,GHSIGY)
+
+PSF_TAIL(X,Y) = TAILAMP*R^2/(TAILCORE^2+R^2)^(1+TAILINDE/2) with R^2=(X/TAILXSCA)^2+(Y/TAILYSCA)^2')
+
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~

doc/DESI_SPECTRO_REDUX/SPECPROD/exposures/NIGHT/EXPID/cframe-CAMERA-EXPID.rst

@@ -17,8 +17,8 @@ Contents
 ====== ========== ======== ======================================
 Number EXTNAME    Type     Contents
 ====== ========== ======== ======================================
-HDU0_  FLUX       IMAGE    Flux, erg/s/cm2/A
-HDU1_  IVAR       IMAGE    Inverse variance, ``(erg/s/cm2/A)^-2``
+HDU0_  FLUX       IMAGE    Flux, 10^{-17} erg/s/cm2/A
+HDU1_  IVAR       IMAGE    Inverse variance, (10^{-17} erg/s/cm2/A)^-2
 HDU2_  MASK       IMAGE    Mask (0 = good)
 HDU3_  WAVELENGTH IMAGE    wavelength in Angstrom
 HDU4_  RESOLUTION IMAGE    Resolution Matrix
@@ -36,7 +36,9 @@ HDU0
 
 EXTNAME = FLUX
 
-Calibrated spectral flux in 1e-17 erg / (s cm2 Angstrom).
+2D array of calibrated spectral flux of dimension [nspec, nwave] in units of 1e-17 erg / (s cm2 Angstrom). nspec is the number of fibers per camera. nwave in the length of the wavelength array. The spectra of all fibers share the same
+wavelength grid (given in HDU WAVELENGTH). cframe.flux = ( frame.flux / flatfield - sky ) / fluxcalib.
+This calibration of the total flux is valid for point sources only. For extended sources, one may consider the 'fiber flux', which is the flux one would collect in a 1.5 arcsec diameter aperture centered on the object when observed with a 1 arcsec FWHM Gaussian seeing. The 'fiber flux' can be obtained by multiplying the flux array of each fiber by the corresponding entry in fibermap table column 'PSF_TO_FIBER_SPECFLUX'. This is the quantity to use for comparison with the photometric FIBERFLUX values given for several band passes in the fibermap.
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -613,7 +615,8 @@ HDU1
 
 EXTNAME = IVAR
 
-Inverse variance of flux (*i.e.* ``error**-2``).
+Inverse variance of flux (1/sigma^2) in units of (10^{-17} erg/s/cm2/A)^-2.
+Uncertainties comprise statistical uncertainties from the error propagation of the initial CCD pixel variance, the calibration uncertainties, plus an additional term on bright sky lines to account for the imperfect sky subtraction.
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -638,8 +641,7 @@ HDU2
 
 EXTNAME = MASK
 
-Mask of spectra; 0=good.
-
+Mask of spectral data; 0=good. See the :doc:`bitmask documentation </bitmasks>` page for the definition of the bits.
 Prior to desispec/0.24.0 and software release 18.9, the MASK HDU was compressed.
 
 TODO: add documentation link to what bits mean what.
@@ -669,7 +671,7 @@ HDU3
 
 EXTNAME = WAVELENGTH
 
-Wavelengths at which flux is measured.
+1D array of wavelengths. See the frame :ref:`WAVELENGTH documentation <frame-hdu3-wavelength>` for more details.
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -694,9 +696,8 @@ HDU4
 
 EXTNAME = RESOLUTION
 
-Diagonal elements of convolution matrix describing spectral resolution.
+Resolution matrix stored as a 3D sparse matrix. the frame :ref:`RESOLUTION documentation <frame-hdu4-resolution>` for more details.
 
-TODO: add code example for using this.
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -722,7 +723,7 @@ HDU5
 
 EXTNAME = FIBERMAP
 
-Fibermap of what targets were assigned to what fibers.
+Fibermap information combining fiberassign request with actual fiber locations. See also the :doc:`fibermap documentation </DESI_SPECTRO_REDUX/SPECPROD/preproc/NIGHT/EXPID/fibermap-EXPID>` page.
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~

doc/DESI_SPECTRO_REDUX/SPECPROD/exposures/NIGHT/EXPID/fiberflat-CAMERA-EXPID.rst

@@ -33,7 +33,7 @@ HDU0
 
 EXTNAME = FIBERFLAT
 
-Mean fiberflat.
+Fiber flat field correction to homogeneize the response among fibers of the same camera, for each wavelength. 2D array of dimension [nspec, nwave]. nspec is the number of fibers per camera. nwave in the length of the wavelength array. The fiber flat field of all fibers share the same wavelength grid (given in HDU WAVELENGTH). This file is the fiber flat derived for the flat exposure EXPID. It is an intermediate file used as input for the nightly fiber flat.
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -445,7 +445,7 @@ HDU1
 
 EXTNAME = IVAR
 
-Inverse variance of the fiberflat.
+Inverse variance (1/sigma^2) of the fiber flat field in HDU0.
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -471,8 +471,7 @@ HDU2
 
 EXTNAME = MASK
 
-Mask of the fiberflat; 0=good.
-
+Mask of the fiberflat; 0=good. See the :doc:`bitmask documentation </bitmasks>` page for the definition of the bits.
 Prior to desispec/0.24.0 and software release 18.9, the MASK HDU was compressed.
 
 Required Header Keywords
@@ -500,8 +499,7 @@ HDU3
 
 EXTNAME = MEANSPEC
 
-Average flat lamp spectrum of fibers in this frame.  Fiberflat is relative
-to this mean spectrum.
+Average flat lamp spectrum of fibers in this camera frame. The fiber flat field is in first approximation the ratio of the measured spectra to this mean spectrum (in practice we use a deconvolved mean spectrum and reconvolve it with the resolution of each fiber). The units are electrons per Angstrom.
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -526,7 +524,7 @@ HDU4
 
 EXTNAME = WAVELENGTH
 
-Wavelength grid in Angstroms used by this fiberflat.
+Wavelength grid in Angstrom used by this fiber flat field. Note that contrary to the science frame, this wavelength array is in the observer frame. In consequence, one has to first convert its wavelength to the solar barycenter frame before using this data to flat field a science exposure. See the frame :ref:`WAVELENGTH documentation <frame-hdu3-wavelength>` for more details.
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -551,7 +549,7 @@ HDU5
 
 EXTNAME = FIBERMAP
 
-Fibermap of what targets were assigned to what fibers.
+Fibermap with information about the fiber status.
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~

doc/DESI_SPECTRO_REDUX/SPECPROD/exposures/NIGHT/EXPID/fiberflatexp-CAMERA-EXPID.rst

@@ -1,10 +1,8 @@
-============
-fiberflatexp
-============
+==============================
+fiberflatexp-CAMERA-EXPID.fits
+==============================
 
-:Summary: *This section should be filled in with a high-level description of
-    this file. In general, you should remove or replace the emphasized text
-    (\*this text is emphasized\*) in this document.*
+:Summary: This file contains the fiberflat to use for a specific exposure such that newflux = rawflux/fiberflat.
 :Naming Convention: ``fiberflatexp-{CAMERA}-{EXPID}.fits``, where ``{camera}`` is the camera
     name (*e.g.* b0, r1, z9) and ``{EXPID}`` is the zero padded 8-digit exposure ID.
 :Regex: ``fiberflatexp-[brz][0-9]-[0-9]{8}\.fits``
@@ -33,7 +31,7 @@ HDU0
 
 EXTNAME = FIBERFLAT
 
-*Summarize the contents of this HDU.*
+Fiber flat field correction to homogeneize the response among fibers of the same camera, for each wavelength. 2D array of dimension [nspec, nwave]. nspec is the number of fibers per camera. nwave in the length of the wavelength array. The fiber flat field of all fibers share the same wavelength grid (given in HDU WAVELENGTH). This file is valid for a specific exposure as it comprises a correction based on the humidity in the spectrograph enclosure.
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -448,7 +446,7 @@ HDU1
 
 EXTNAME = IVAR
 
-*Summarize the contents of this HDU.*
+Inverse variance (1/sigma^2) of the fiber flat field in HDU0.
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -474,7 +472,8 @@ HDU2
 
 EXTNAME = MASK
 
-*Summarize the contents of this HDU.*
+Mask of the fiberflat; 0=good. See the :doc:`bitmask documentation </bitmasks>` page for the definition of the bits.
+Prior to desispec/0.24.0 and software release 18.9, the MASK HDU was compressed.
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -501,7 +500,7 @@ HDU3
 
 EXTNAME = MEANSPEC
 
-*Summarize the contents of this HDU.*
+Average flat lamp spectrum of fibers in this camera frame. The fiber flat field is in first approximation the ratio of the measured spectra to this mean spectrum (in practice we use a deconvolved mean spectrum and reconvolve it with the resolution of each fiber). The units are electrons per Angstrom.
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -526,7 +525,7 @@ HDU4
 
 EXTNAME = WAVELENGTH
 
-*Summarize the contents of this HDU.*
+Wavelength grid in Angstrom used by this fiber flat field. Note that contrary to the science frame, this wavelength array is in the observer frame. In consequence, one has to first convert its wavelength to the solar barycenter frame before using this data to flat field a science exposure. See the frame :ref:`WAVELENGTH documentation <frame-hdu3-wavelength>` for more details.
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -551,7 +550,7 @@ HDU5
 
 EXTNAME = FIBERMAP
 
-*Summarize the contents of this HDU.*
+Fibermap with information about the fiber status.
 
 Required Header Keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~

doc/DESI_SPECTRO_REDUX/SPECPROD/exposures/NIGHT/EXPID/fit-psf-CAMERA-EXPID.rst

@@ -9,9 +9,9 @@ fit-psf-CAMERA-EXPID.fits
 :Regex: ``fit-psf-[brz][0-9]-[0-9]{8}(_[0-9][0-9]|)\.fits``
 :File Type: FITS, 998 KB
 
-See :doc:`psfnight <../../../calibnight/NIGHT/psfnight-CAMERA-NIGHT>`.
+See the :doc:`psfnight-CAMERA-NIGHT documentation <../../../calibnight/NIGHT/psfnight-CAMERA-NIGHT>` for a description of the PSF file content.
 
-Arc exposures have 4 different PSF files per camera:
+Four different PSF files are written per camera for each arc lamp exposure:
 
 1. :doc:`shifted-input-psf-CAMERA-EXPID.fits <shifted-input-psf-CAMERA-EXPID>`:
    Input PSF with spectral trace coordinates and wavelength calibration