.. _DataBitFields:

NEID Data Bitfields
===================

Overview
--------

Beginning in v1.2.0, the NEID DRP uses bitfields contained in header
keywords DQLEVEL0, DQLEVEL1, DQLEVEL2 to compactly provide information
about the data that may be useful to end users.  This data is packaged
as a series of nested bit-fields, as defined below, and stored in the
header as an *int*. Each field contains up to 64 bits, although many
will be unpopulated (i.e., 0).

Each byte is dedicated to a specific DRP subsystem, and the 2
least-significant-bits of each byte contain rollup assessments of the
data in the following 6 bits.

The least-significant-byte contains rollup information from the other
bytes. Bits 0-1 contain an overall data quality assessment, as
follows:

* 0: Pass
* 1: Warn
* 2: Fail

Bits not listed in the below tables are reserved for future use.

DQLEVEL0
--------

Not currently used


DQLEVEL1
--------

+------+-------+----------------------------------------------------------+
| Byte | Bit   | Description                                              |
+======+=======+==========================================================+
| 0    | 0-1   | **Overall Level 1 Summary Assessment**                   |
|      |       |  | 0: Pass                                               |
|      |       |  | 1: Warning                                            |
|      |       |  | 1: Rejected                                           |
+------+-------+----------------------------------------------------------+
+------+-------+----------------------------------------------------------+
| 1    |       | **Manual Assessment Bits**                               |
+------+-------+----------------------------------------------------------+
| 1    | 8-9   | Summary Assessment                                       |
|      |       |  | 0: No known faults                                    |
|      |       |  | 1: Data warning                                       |
|      |       |  | 2: Data rejected                                      |
+------+-------+----------------------------------------------------------+
| 1    | 10-15 | Assessment Flag (from manual assessment masterfile)      |
|      |       |  | 0: No flags specific                                  |
|      |       |  | 1-15: Header fault description                        |
|      |       |  |  1: Major header telemetry fault                      |
|      |       |  | 16-32: Image fault description                        |
|      |       |  | 33-47: Instrument/Port fault description              |
|      |       |  |  33: CFB camera fault                                 |
|      |       |  | 48-63: Other fault description                        |
|      |       |  |  48: Telescope summer shutdown                        |
|      |       |  |  49: Telescope engineering                            |
|      |       |  |  50: Shared Risk - General                            |
|      |       |  |  51: Shared Risk - Commissioning                      |
|      |       |  |  52: Shared Risk - Contreras Fire Restart             |
|      |       |  |  54: Etalon stabilizing (possible unreliable wavecal) |
|      |       |  |  54: LFC fault (possible unreliable wavecal)          |
|      |       |  |  58: Solar telescope fault - cable wrap fail, bad RVs |
|      |       |  |  59: Solar eclipse                                    |
|      |       |  |  60: Wrong star was observed                          |
+------+-------+----------------------------------------------------------+
+------+-------+----------------------------------------------------------+
| 2    |       | **Automated Hardware Assessment**                        |
+------+-------+----------------------------------------------------------+
| 2    | 16-17 | Summary Assessment                                       |
+------+-------+----------------------------------------------------------+
| 2    | 18    | Port illumination failure                                |
+------+-------+----------------------------------------------------------+
| 2    | 19    | Calibration illumination failure                         |
+------+-------+----------------------------------------------------------+
+------+-------+----------------------------------------------------------+
| 3    |       | **Run Information/Manifest**                             |
+------+-------+----------------------------------------------------------+
| 3    | 24-25 | Summary Assessment (based on OBSTYPE)                    |
|      |       |  | 0: Sci, Cal, Eng                                      |
|      |       |  | 1: Tst                                                |
+------+-------+----------------------------------------------------------+
| 3    | 26-27 | Specific Observation Type (Header Keyword OBSTYPE)       |
|      |       |  | 0: Sci                                                |
|      |       |  | 1: Cal                                                |
|      |       |  | 2: Eng                                                |
|      |       |  | 3: Tst                                                |
+------+-------+----------------------------------------------------------+
+------+-------+----------------------------------------------------------+
| 4    |       | **CCD Image Processing Assessment**                      |
+------+-------+----------------------------------------------------------+
| 4    | 32-33 | Summary Assessment                                       |
+------+-------+----------------------------------------------------------+
| 4    | 34    | Bias contamination                                       |
|      |       |  | 0: Pass                                               |
|      |       |  | 1: Fail                                               |
+------+-------+----------------------------------------------------------+
+------+-------+----------------------------------------------------------+
| 5    |       | **Extraction**                                           |
+------+-------+----------------------------------------------------------+
| 5    | 40-41 | Summary Assessment                                       |
+------+-------+----------------------------------------------------------+
| 5    | 42    | Signal-to-noise Threshold (>= 80% of Requested)          |
|      |       |  | 0: Pass                                               |
|      |       |  | 1: Fail                                               |
+------+-------+----------------------------------------------------------+
+------+-------+----------------------------------------------------------+
| 6    |       | **Wavelength Calibration**                               |
+------+-------+----------------------------------------------------------+
| 6    | 48-49 | Summary Assessment                                       |
|      |       |  | 0: WAVECAL = LFCplusThAr AND DRIFTFUN = dailymodel0   |
|      |       |  | 1: Otherwise                                          |
+------+-------+----------------------------------------------------------+
| 6    | 50    | Wavelength Calibration Mode (Header Keyword WAVECAL)     |
|      |       |  | 0: LFConly                                            |
|      |       |  | 1: LFCplus ThAr                                       |
+------+-------+----------------------------------------------------------+
| 6    | 51    | Session Drift Correction Model (Header Keyword DRIFTFUN) |
|      |       |  | 0: Master                                             |
|      |       |  | 1: Constant                                           |
|      |       |  | 2: Linear                                             |
|      |       |  | 3: Simultaneous                                       |
|      |       |  | 4: DailyModel0                                        |
+------+-------+----------------------------------------------------------+
|      |       |                                                          |
+------+-------+----------------------------------------------------------+


DQLEVEL2
--------

+------+-------+-------------------------------------+
| Byte | Bit   | Description                         |
+======+=======+=====================================+
| 2    |       | **Telluric Model**                  |
+------+-------+-------------------------------------+
| 2    | 16-17 | Summary Assessment                  |
+------+-------+-------------------------------------+
| 2    | 18    | Preciptable water vapor fit status: |
|      |       |  | 0: Succeeded                     |
|      |       |  | 1: Failed                        |
+------+-------+-------------------------------------+

*Last Updated, 2025-02-18, DMK*