Skip to content

Commit

Permalink
Merge branch 'main' into fiberassign
Browse files Browse the repository at this point in the history 
* main:
  add note about complete rebuild
  update change log
  improve description of FIBER_FRACFLUX_ELG_GFA
  Fix indents and newline to resolve Sphinx issues
  Add file description for exposures-SPECPROD
  Add descriptions for top level exposures and tiles table files
  restore the SV1/SV3 bitmask columns
  update the changes docs
  populate the data model for the zmtl files; also add a note to the target files about how DESI_TARGET can be SVX_DESI_TARGET
  • Loading branch information
@weaverba137
weaverba137 committed Jun 16, 2022
2 parents 41f9304 + a1102a3 commit df8b1b5
Show file tree
Hide file tree
Showing 6 changed files with 225 additions and 184 deletions.
212 changes: 112 additions & 100 deletions doc/DESI_SPECTRO_REDUX/SPECPROD/exposures-SPECPROD.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,12 @@
exposures-SPECPROD.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: File containing metadata about individual DESI exposures. There are two tables.
The first is per-exposure and the second is per-camera per-exposure. The per-exposure table
includes observational information as well as derived quantities
estimating the observational depth for each target class, quoted
in seconds of effective, idealized observing time. The second provides similar information on
a per-camera basis.
:Naming Convention: ``exposures-{SPECPROD}.fits``, where ``{SPECPROD}`` is the
official name of the full reduction, *e.g.* ``everest``.
:Regex: ``exposures-[a-z0-9_-]+\.fits``
Expand All @@ -16,9 +19,9 @@ Contents
====== ========= ======== ===================
Number EXTNAME Type Contents
====== ========= ======== ===================
HDU0_ IMAGE *Brief Description*
HDU1_ EXPOSURES BINTABLE *Brief Description*
HDU2_ FRAMES BINTABLE *Brief Description*
HDU0_ IMAGE Empty
HDU1_ EXPOSURES BINTABLE Per-exposure metadata
HDU2_ FRAMES BINTABLE Per-camera per-exposure metadata
====== ========= ======== ===================


Expand All @@ -28,8 +31,6 @@ FITS Header Units
HDU0
----

*Summarize the contents of this HDU.*

This HDU has no non-standard required keywords.

Empty HDU.
Expand All @@ -39,7 +40,10 @@ HDU1

EXTNAME = EXPOSURES

*Summarize the contents of this HDU.*
Binary table containing metadata about individual DESI exposures. This
includes observational information as well as derived quantities
estimating the observational depth for each target class, quoted
in seconds of effective, idealized observing time.

Required Header Keywords
~~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -51,77 +55,83 @@ Required Header Keywords
====== ============= ==== =====================
KEY Example Value Type Comment
====== ============= ==== =====================
NAXIS1 337 int length of dimension 1
NAXIS2 3912 int length of dimension 2
NAXIS1 337 int Number of columns
NAXIS2 3912 int Number of exposure rows
====== ============= ==== =====================

Required Data Table Columns
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. rst-class:: columns

====================== ======== ===== ===========
Name Type Units Description
====================== ======== ===== ===========
NIGHT int32
EXPID int32
TILEID int32
TILERA float64
TILEDEC float64
MJD float64
SURVEY char[7]
PROGRAM char[6]
FAPRGRM char[*]
FAFLAVOR char[*]
EXPTIME float64
EFFTIME_SPEC float64
GOALTIME float64
GOALTYPE char[6]
MINTFRAC float64
AIRMASS float32
EBV float32
SEEING_ETC float64
EFFTIME_ETC float64
TSNR2_ELG float32
TSNR2_QSO float32
TSNR2_LRG float32
TSNR2_LYA float64
TSNR2_BGS float32
TSNR2_GPBDARK float32
TSNR2_GPBBRIGHT float32
TSNR2_GPBBACKUP float32
LRG_EFFTIME_DARK float32
ELG_EFFTIME_DARK float32
BGS_EFFTIME_BRIGHT float32
LYA_EFFTIME_DARK float64
GPB_EFFTIME_DARK float32
GPB_EFFTIME_BRIGHT float32
GPB_EFFTIME_BACKUP float32
TRANSPARENCY_GFA float64
SEEING_GFA float64
FIBER_FRACFLUX_GFA float64
FIBER_FRACFLUX_ELG_GFA float64
FIBER_FRACFLUX_BGS_GFA float64
FIBERFAC_GFA float64
FIBERFAC_ELG_GFA float64
FIBERFAC_BGS_GFA float64
AIRMASS_GFA float64
SKY_MAG_AB_GFA float64
SKY_MAG_G_SPEC float64
SKY_MAG_R_SPEC float64
SKY_MAG_Z_SPEC float64
EFFTIME_GFA float64
EFFTIME_DARK_GFA float64
EFFTIME_BRIGHT_GFA float64
EFFTIME_BACKUP_GFA float64
====================== ======== ===== ===========
====================== ======== ====== ===========
Name Type Units Description
====================== ======== ====== ===========
NIGHT int32 Observing night
EXPID int32 DESI Exposure number
TILEID int32 DESI Tile ID
TILERA float64 deg RA of tile given in fiberassign file
TILEDEC float64 deg DEC of tile given in fiberassign fileDEC of tile given in fiberassign file
MJD float64 Modified Julian Date when shutter was opened for this exposure.
SURVEY char[7] Survey name
PROGRAM char[6] Program name
FAPRGRM char[*] Fiberassign program name
FAFLAVOR char[*] Fiberassign flavor name
EXPTIME float64 s Length of time shutter was open.
EFFTIME_SPEC float64 s Effective exposure time for nominal conditions derived from the TSNR2 fits to the spectroscopy
GOALTIME float64 s Goal for total effective exposure time for the tile
GOALTYPE char[6] The intended observing conditions for the tile
MINTFRAC float64 Minimum fraction of GOALTIME acceptable for considering a tile complete
AIRMASS float32 Average airmass during this exposure.
EBV float32 Galactic extinction E(B-V) reddening from SFD98_
SEEING_ETC float64 arcsec Average FWHM atmospheric seeing during this exposure as measured by ETC.
EFFTIME_ETC float64 s Effective exposure time for nominal conditions inferred from ETC data
TSNR2_ELG float32 ELG template (S/N)^2 summed over B,R,Z
TSNR2_QSO float32 QSO template (S/N)^2 summed over B,R,Z
TSNR2_LRG float32 LRG template (S/N)^2 summed over B,R,Z
TSNR2_LYA float64 LYA template (S/N)^2 summed over B,R,Z
TSNR2_BGS float32 BGS template (S/N)^2 summed over B,R,Z
TSNR2_GPBDARK float32 GPBDARK template (S/N)^2 summed over B,R,Z
TSNR2_GPBBRIGHT float32 GPBBRIGHT template (S/N)^2 summed over B,R,Z
TSNR2_GPBBACKUP float32 GPBBACKUP template (S/N)^2 summed over B,R,Z
LRG_EFFTIME_DARK float32 s Effective exposure time for nominal dark conditions inferred for LRG targets
ELG_EFFTIME_DARK float32 s Effective exposure time for nominal dark conditions inferred for ELG targets
BGS_EFFTIME_BRIGHT float32 s Effective exposure time for nominal bright conditions inferred for BGS targets
LYA_EFFTIME_DARK float64 s Effective exposure time for nominal dark conditions inferred for LYA targets
GPB_EFFTIME_DARK float32 s Effective exposure time for nominal dark conditions inferred for GPB targets
GPB_EFFTIME_BRIGHT float32 s Effective exposure time for nominal bright conditions inferred for GPB targets
GPB_EFFTIME_BACKUP float32 s Effective exposure time for nominal backup conditions inferred for GPB targets
TRANSPARENCY_GFA float64 Average airmass during this exposure as measured by GFA.
SEEING_GFA float64 arcsec Average FWHM atmospheric seeing during this exposure as measured by GFA.
FIBER_FRACFLUX_GFA float64 Fraction of the flux entering the fiber relative to nominal 1.1" seeing using the PSF inferred from the GFAs
FIBER_FRACFLUX_ELG_GFA float64 Fraction of the flux entering the fiber relative to nominal 1.1" seeing using the PSF inferred from the GFAs for a source with an ELG profile (0.45" exponential galaxy profile)
FIBER_FRACFLUX_BGS_GFA float64 Fraction of the flux entering the fiber relative to nominal 1.1" seeing using the PSF inferred from the GFAs for a source with a BGS profile (deV profile, half light radius of 1.5")
FIBERFAC_GFA float64 Fraction of light entering a fiber relative to expectations for 1.1" seeing, transparency 1, for an object with a PSF profile, measured by comparing the flux integrated over a 107 micron diameter circle on the GFA images centered at the PlateMaker expectations for where stars should land.
FIBERFAC_ELG_GFA float64 Same as FIBERFAC_GFA except for an ELG profile
FIBERFAC_BGS_GFA float64 Same as FIBERFAC_GFA except for a BGS profile
AIRMASS_GFA float64 Average airmass during this exposure as measured by GFA.
SKY_MAG_AB_GFA float64 Sky background in the GFA passband, measured from the GFA backgrounds.
SKY_MAG_G_SPEC float64 Sky background measured in the spectroscopy integrated over the DECam g passband, AB mags.
SKY_MAG_R_SPEC float64 Sky background measured in the spectroscopy integrated over the DECam r passband, AB mags.
SKY_MAG_Z_SPEC float64 Sky background measured in the spectroscopy integrated over the DECam z passband, AB mags.
EFFTIME_GFA float64 s Effective exposure time for nominal conditions inferred from GFA data
EFFTIME_DARK_GFA float64 s Effective exposure time for nominal dark conditions inferred from GFA data
EFFTIME_BRIGHT_GFA float64 s Effective exposure time for nominal bright conditions inferred from GFA data
EFFTIME_BACKUP_GFA float64 s Effective exposure time for nominal backup conditions inferred from GFA data
====================== ======== ====== ===========

.. _SFD98: https://ui.adsabs.harvard.edu/abs/1998ApJ...500..525S/abstract

HDU2
----

EXTNAME = FRAMES

*Summarize the contents of this HDU.*
Binary table containing metadata about individual DESI exposures per camera. This
includes observational information as well as derived quantities
estimating the observational depth for each target class, quoted
as TSNR2_*. TSNR2_* can be converted to EFFTIME using the desispec_ function
*desispec.tsnr.tsnr2_to_efftime(tsnr2,target_type)*.

Required Header Keywords
~~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -133,46 +143,48 @@ Required Header Keywords
====== ============= ==== =====================
KEY Example Value Type Comment
====== ============= ==== =====================
NAXIS1 167 int length of dimension 1
NAXIS2 111720 int length of dimension 2
NAXIS1 167 int Number of columns
NAXIS2 111720 int Number of per-camera per-exposure rows
====== ============= ==== =====================

Required Data Table Columns
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. rst-class:: keywords

=============== ======== ===== ===========
Name Type Units Description
=============== ======== ===== ===========
NIGHT int32
EXPID int32
TILEID int32
TILERA float64
TILEDEC float64
MJD float64
EXPTIME float32
AIRMASS float32
EBV float32
SEEING_ETC float64
EFFTIME_ETC float64
CAMERA char[2]
TSNR2_GPBDARK float32
TSNR2_ELG float32
TSNR2_GPBBRIGHT float32
TSNR2_LYA float64
TSNR2_BGS float32
TSNR2_GPBBACKUP float32
TSNR2_QSO float32
TSNR2_LRG float32
SURVEY char[7]
GOALTYPE char[6]
FAPRGRM char[*]
FAFLAVOR char[*]
MINTFRAC float64
GOALTIME float64
=============== ======== ===== ===========

=============== ======== ====== ===========
Name Type Units Description
=============== ======== ====== ===========
NIGHT int32 Observing night
EXPID int32 DESI Exposure number
TILEID int32 DESI Tile ID
TILERA float64 deg RA of tile given in fiberassign file
TILEDEC float64 deg DEC of tile given in fiberassign file
MJD float64 Modified Julian Date when shutter was opened for this exposure.
EXPTIME float32 s Length of time shutter was open.
AIRMASS float32 Average airmass during this exposure.
EBV float32 Galactic extinction E(B-V) reddening from SFD98_
SEEING_ETC float64 arcsec Average FWHM atmospheric seeing during this exposure as measured by ETC.
EFFTIME_ETC float64 s Effective exposure time for nominal conditions derived from exposure ETC data
CAMERA char[2] Camera identifier. Passband and SPECGRPH ([brz][0-9]).
TSNR2_GPBDARK float32 GPBDARK template (S/N)^2 summed over B,R,Z
TSNR2_ELG float32 ELG template (S/N)^2 summed over B,R,Z
TSNR2_GPBBRIGHT float32 GPBBRIGHT template (S/N)^2 summed over B,R,Z
TSNR2_LYA float64 LYA template (S/N)^2 summed over B,R,Z
TSNR2_BGS float32 BGS template (S/N)^2 summed over B,R,Z
TSNR2_GPBBACKUP float32 GPBBACKUP template (S/N)^2 summed over B,R,Z
TSNR2_QSO float32 QSO template (S/N)^2 summed over B,R,Z
TSNR2_LRG float32 LRG template (S/N)^2 summed over B,R,Z
SURVEY char[7] Survey name
GOALTYPE char[6] The intended observing conditions for the tile
FAPRGRM char[*] PROGRAM in fiberassign file
FAFLAVOR char[*] FLAVOR in fiberassign file
MINTFRAC float64 Minimum fraction of GOALTIME acceptable for considering a tile complete
GOALTIME float64 s Goal for total effective exposure time for the tile
=============== ======== ====== ===========

.. _SFD98: https://ui.adsabs.harvard.edu/abs/1998ApJ...500..525S/abstract
.. _desispec: https://github.com/desihub/desispec/blob/720153babcf85dd93530252b0c1f631d48edfc0d/py/desispec/tsnr.py#L1140

Notes and Examples
==================
Expand Down
63 changes: 32 additions & 31 deletions doc/DESI_SPECTRO_REDUX/SPECPROD/tiles-SPECPROD.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
tiles-SPECPROD.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: Table containing cumulative observational metadata as well as derived quantities
estimating the observational "depth" for each target class, quoted
in seconds of effective, idealized observing time.
:Naming Convention: ``tiles-{SPECPROD}.fits``, where ``{SPECPROD}`` is the
official name of the full reduction, *e.g.* ``everest``.
:Regex: ``tiles-[a-z0-9_-]+.fits``
Expand All @@ -16,8 +16,8 @@ Contents
====== ================= ======== ===================
Number EXTNAME Type Contents
====== ================= ======== ===================
HDU0_ IMAGE *Brief Description*
HDU1_ TILE_COMPLETENESS BINTABLE *Brief Description*
HDU0_ IMAGE Empty
HDU1_ TILE_COMPLETENESS BINTABLE Per-tile metadata
====== ================= ======== ===================


Expand All @@ -27,8 +27,6 @@ FITS Header Units
HDU0
----

*Summarize the contents of this HDU.*

This HDU has no non-standard required keywords.

Empty HDU.
Expand All @@ -38,7 +36,10 @@ HDU1

EXTNAME = TILE_COMPLETENESS

*Summarize the contents of this HDU.*
Binary table containing metadata about individual DESI tiles. This
includes cumulative observational information as well as derived quantities
estimating the observational "depth" for each target class, quoted
in seconds of effective, idealized observing time.

Required Header Keywords
~~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -62,31 +63,31 @@ Required Data Table Columns
================== ======== ===== ===========
Name Type Units Description
================== ======== ===== ===========
TILEID int32
SURVEY char[20]
PROGRAM char[6]
FAPRGRM char[20]
FAFLAVOR char[20]
NEXP int64
EXPTIME float64
TILERA float64
TILEDEC float64
EFFTIME_ETC float64
EFFTIME_SPEC float64
EFFTIME_GFA float64
GOALTIME float64
OBSSTATUS char[20]
LRG_EFFTIME_DARK float64
ELG_EFFTIME_DARK float64
BGS_EFFTIME_BRIGHT float64
LYA_EFFTIME_DARK float64
GOALTYPE char[20]
MINTFRAC float64
LASTNIGHT int32
TILEID int32 Unique DESI tile ID
SURVEY char[20] Survey name
PROGRAM char[6] Program name
FAPRGRM char[20] PROGRAM in fiberassign file
FAFLAVOR char[20] FLAVOR in fiberassign file
NEXP int64 Number of exposures used in EFFTIME estimates
EXPTIME float64 s Actual exposure time
TILERA float64 deg RA of tile given in fiberassign file
TILEDEC float64 deg DEC of tile given in fiberassign file
EFFTIME_ETC float64 s Effective exposure time for nominal conditions derived from exposure ETC data
EFFTIME_SPEC float64 s Effective exposure time for nominal conditions derived from the TSNR2 fits to the spectroscopy
EFFTIME_GFA float64 s Effective exposure time for nominal conditions derived from exposure GFA data
GOALTIME float64 s Goal for total effective exposure time for the tile
OBSSTATUS char[20] Observing conditions bitmask
LRG_EFFTIME_DARK float64 s Effective exposure time for nominal dark conditions inferred for LRG targets
ELG_EFFTIME_DARK float64 s Effective exposure time for nominal dark conditions inferred for ELG targets
BGS_EFFTIME_BRIGHT float64 s Effective exposure time for nominal bright conditions inferred for BGS targets
LYA_EFFTIME_DARK float64 s Effective exposure time for nominal dark conditions inferred for LYA targets
GOALTYPE char[20] The intended observing conditions for the tile
MINTFRAC float64 Minimum fraction of GOALTIME acceptable for considering a tile complete
LASTNIGHT int32 Most recent night with a good exposure
================== ======== ===== ===========


Notes and Examples
==================

*Add notes and examples here. You can also create links to example files.*
For the definition of OBSCONDITIONS please see the :doc:`bitmask documentation </bitmasks>`
page for the definition of the bits.

0 comments on commit df8b1b5

Please sign in to comment.