# GOME2_L1_radiance

## Variables

The table below lists the variables that are present in the HARP product that results from an ingestion of `GOME2_L1_radiance` data.

field name | type | dimensions | unit | description
--- | --- | --- | --- | ---
datetime | double | {time} | [seconds since 2000-01-01] | time of the measurement at the end of the integration time
orbit_index | int32 |  |  | absolute orbit number
latitude | double | {time} | [degree_north] | center latitude of the measurement
longitude | double | {time} | [degree_east] | center longitude of the measurement
latitude_bounds | double | {time, 4} | [degree_north] | corner latitudes for the ground pixel of the measurement
longitude_bounds | double | {time, 4} | [degree_east] | corner longitudes for the ground pixel of the measurement
wavelength_photon_radiance | double | {time, spectral} | [count/s/cm2/sr/nm] | measured radiances
wavelength | double | {time, spectral} | [nm] | nominal wavelength assignment for each of the detector pixels
integration_time | double | {time, spectral} | [s] | integration time for each pixel
scan_subindex | int8 | {time} |  | relative index (0-15) of this measurement within a scan (forward+backward)
scan_direction_type | int8 | {time} |  | scan direction for each measurement; enumeration values: forward (0), backward (1)
cloud_top_pressure | double | {time} | [hPa] | cloud top pressure
cloud_fraction | double | {time} | [] | cloud fraction
solar_zenith_angle_toa | double | {time} | [degree] | solar zenith angle at top of atmosphere
solar_azimuth_angle_toa | double | {time} | [degree] | solar azimuth angle at top of atmosphere
viewing_zenith_angle_toa | double | {time} | [degree] | viewing zenith angle at top of atmosphere
viewing_azimuth_angle_toa | double | {time} | [degree] | viewing azimuth angle at top of atmosphere
index | int32 | {time} |  | zero-based index of the sample within the source product

## Ingestion options

The table below lists the available ingestion options for `GOME2_L1` products.

option name | legal values | description
--- | --- | ---
band | band-1a, band-1b, band-2a, band-2b, band-3, band-4 | only include data from the specified band (‘band-1a’, ‘band-1b’, ‘band-2a’, ‘band-2b’, ‘band-3’, ‘band-4’); by default data from all bands is retrieved
data | transmission, sun, moon, sun_reference | retrieve the measured radiances (default), the transmission spectra (data=transmission), the sun measurement spectra (data=sun), the moon measurement spectra (data=moon) or the sun reference spectrum (data=sun_reference

This definition is only applicable when: data unset

## Mapping description

The GOME2 spectral data in the GOME2 L1b product is stored inside MDRs. There are separate MDRs for Earthshine, Calibration, Sun, and Moon measurements. In addition there are also ‘Dummy Records’ (DMDR) that can be present when there is lost data in the product. With HARP only Earthshine, Sun, and Moon measurements can be ingested.

Each MDR roughly contains a single scan. However, an MDR does not exactly correspond 1-to-1 with a GOME-2 scan. This is an important fact to be aware of. The real situation is as follows:

Within a single scan (a scan takes 6 seconds) there are 16 Instrument Source Packets (covering 375ms each) coming from the satellite. Each ISP contains at most two readouts (there are two if the integration time for a band is 187.5ms (or 93.75ms)). The problem is that the two readouts of the first ISP of a scan contain the last measurement of the previous scan and the first measurement of the new scan. The second ISP contains data for measurements #2 and #3, the third for #4 and #5, etc. The last measurement of a scan will again be found in the first ISP of the next scan. Instead of shifting the data and grouping all data of a single scan together in a single MDR the Level 1a and Level 1b processors just place the MDR boundary at the start of the first ISP of a scan and terminate the MDR at the end of ISP 16. This means that in Level 1b (but also 1a) products the first measurement in an MDR will always be the last measurement of the previous scan.

Nearly all meta-data for a readout (time, geolocation, viewing/solar angles, etc.) in an MDR are filled taking into account this same shift. This means that for retrieving the geolocation of the first readout of an MDR from the GEO_EARTH_ACTUAL record, one will in fact get the geolocation information of the last backscan pixel of the previous scan. However, the integration time meta-data for the first readout in an MDR is not shifted this way (the GEO_EARTH information is also not shifted, by the way, and just contains the 32 geolocation pixels for the scan). As long as the integration time does not change from one scan to another this won’t impact anything, but the L1 products will contain invalid metadata for the first MDR readout if there is a change of integration time between two consecutive scans. In that case the calculated geolocation, angles, etc. of the first readout are values based on the integration time of the _new_ scan instead of the _old_ scan (e.g. the ground pixel will thus either be too large or too small). The (relative) good news to this is that, if a change in integration time occurs, the last pixel readout of the final scan with the ‘old’ integration time will never be valid and will have undefined values in the product (this is because the instrument prematurely terminates the final readout if a scan configuration change occurs). This means that the readout that has the ‘invalid’ meta-data will never be a valid measurement anyway.

Because of all this, HARP will exercise the following rules during ingestion: 1) the first readout of the first MDR will always be ignored (and you will never see the last readout of the last scan, because it won’t be in the product) 2) the first readout after a change in measurement mode (i.e. earthshine vs. calibration vs. sun vs. moon) will be ignored 3) if a change in integration time occurs (for any of the bands) then the first readout (for all bands) of the next MDR will be ignored 4) if two MDRs are not continuous (i.e. there is a time gap) then the first readout of the second MDR will be ignored

GOME-2 uses 6 bands for the main spectra (1A, 1B, 2A, 2B, 3, and 4). Within a scan each band can have its own integration time. There will be at most 32 readouts per scan (corresponding with an integration time of 187.5ms). If the integration time is 375ms, 750ms, 1.5s, 3s or 6s there will be 16, 8, 4, 2, or 1 measurement(s) respectively for this band in a scan. Some readouts may even cover multiple scans if the integration time is larger than 6s. HARP will combine the data for all bands into a single two-dimensional pixel_readout array and uses a fixed resolution of 187.5ms for the variables. Because bands might have higher integration time this means that for those bands there will be multiple rows in the pixel_readout array for a single readout. Each of those multiple rows will be filled with the same measurement value. This comes down to breaking the measurement up into pieces of 187.5ms (the actual integration time can still be found from the integration_time variable). All meta-data, such as geolocation, angles, etc. will also be ingested for this minimum integration time of 187.5ms and filtering on time and geolocation will also always be performed using the 187.5ms resolution.

If the band configuration changes somewhere during the orbit and a band filter is given, then only detector pixels that are inside the requested band for the duration of the whole orbit will be included. i.e. detector pixels that change band during the orbit will always be excluded when a band filter is given.

The table below details where and how each variable was retrieved from the input product.

field name | mapping description
--- | ---
datetime | path | /MDR[]/Earthshine/RECORD_HEADER/RECORD_START_TIME
description | The record start time is the start time of the scan and thus the start time of the second readout in the MDR. The start time for readout i (0..31) is thus RECORD_START_TIME + (i - 1) * 0.1875 and the time at end of integration time (which is the time that is returned) is RECORD_START_TIME + i * 0.1875
orbit_index | path | /MPHR/ORBIT_START
latitude | condition | CODA product version < 12
path | /MDR[]/Earthshine/GEO_EARTH_ACTUAL/CENTRE_ACTUAL[INT_INDEX[band_id],]/latitude
description | The integration time index INT_INDEX[band_id] is the index of the band with the minimum integration time (limited to those bands that are ingested)
condition | CODA product version >= 12
path | /MDR[]/Earthshine/GEO_EARTH_ACTUAL_k[]/CENTRE_ACTUAL/latitude
description | The integration time index k is the index (starting with 1) of the minimum integration time such that UNIQUE_INT[k-1] == min(INTEGRATION_TIMES[j]) for all bands j (0..9) that are ingeste.
longitude | condition | CODA product version < 12
path | /MDR[]/Earthshine/GEO_EARTH_ACTUAL/CENTRE_ACTUAL[INT_INDEX[band_id],]/longitude
description | The integration time index INT_INDEX[band_id] is the index of the band with the minimum integration time (limited to those bands that are ingested).
condition | CODA product version >= 12
path | /MDR[]/Earthshine/GEO_EARTH_ACTUAL_k[]/CENTRE_ACTUAL/longitude
description | The integration time index k is the index (starting with 1) of the minimum integration time such that UNIQUE_INT[k-1] == min(INTEGRATION_TIMES[j]) for all bands j (0..9) that are ingeste.
latitude_bounds | condition | CODA product version < 12
path | /MDR[]/Earthshine/GEO_EARTH_ACTUAL/CORNER_ACTUAL[INT_INDEX[band_id],,]/latitude
description | The integration time index INT_INDEX[band_id] is the index of the band with the minimum integration time (limited to those bands that are ingested). The corners ABCD are reordered as BDCA.
condition | CODA product version >= 12
path | /MDR[]/Earthshine/GEO_EARTH_ACTUAL_k[]/CORNER_ACTUAL[]/latitude
description | The integration time index k is the index (starting with 1) of the minimum integration time such that UNIQUE_INT[k-1] == min(INTEGRATION_TIMES[j]) for all bands j (0..9) that are ingeste.
longitude_bounds | condition | CODA product version < 12
path | /MDR[]/Earthshine/GEO_EARTH_ACTUAL/CORNER_ACTUAL[INT_INDEX[band_id],,]/longitude
description | The integration time index INT_INDEX[band_id] is the index of the band with the minimum integration time (limited to those bands that are ingested). The corners ABCD are reordered as BDCA.
condition | CODA product version >= 12
path | /MDR[]/Earthshine/GEO_EARTH_ACTUAL_k[]/CORNER_ACTUAL[]/longitude
description | The integration time index k is the index (starting with 1) of the minimum integration time such that UNIQUE_INT[k-1] == min(INTEGRATION_TIMES[j]) for all bands j (0..9) that are ingeste.
wavelength_photon_radiance | path | /MDR[]/Earthshine/BAND_1A[,]/RAD, /MDR[]/Earthshine/BAND_1B[,]/RAD, /MDR[]/Earthshine/BAND_2A[,]/RAD, /MDR[]/Earthshine/BAND_2B[,]/RAD, /MDR[]/Earthshine/BAND_3[,]/RAD, /MDR[]/Earthshine/BAND_4[,]/RAD
wavelength | path | /MDR[]/Earthshine/WAVELENGTH_1A[], /MDR[]/Earthshine/WAVELENGTH_1B[], /MDR[]/Earthshine/WAVELENGTH_2A[], /MDR/Earthshine[]/WAVELENGTH_2B[], /MDR[]/Earthshine/WAVELENGTH_3[], /MDR[]/Earthshine/WAVELENGTH_4[]
integration_time | path | /MDR[]/Earthshine/INTEGRATION_TIMES[]
scan_direction_type | path | /MDR[]/Earthshine/INTEGRATION_TIMES[]
description | the scan direction is based on the subset counter of the measurement; 0-11: forward (0), 12-15: backward (1)
cloud_top_pressure | path | /MDR[]/Earthshine/CLOUD/FIT_1[]
description | If the minimum ingested integration time > 187.5ms then the corresponding cloud top pressures will be combined using logarithmic averaging. The cloud top pressure will be set to NaN if FIT_MODE in the CLOUD structure is not equal to 0 or if FIT_1 is set to a fill value (even when this holds for only one of the averaged items)
cloud_fraction | path | /MDR[]/Earthshine/CLOUD/FIT_2[]
description | If the minimum ingested integration time > 187.5ms then the corresponding cloud fractions will be combined using averaging. The cloud fraction will be set to NaN if FIT_MODE in the CLOUD structure is not equal to 0 or if FIT_2 is set to a fill value (even when this holds for only one of the averaged items)
solar_zenith_angle_toa | condition | CODA product version < 12
path | /MDR[]/Earthshine/GEO_EARTH_ACTUAL/SOLAR_ZENITH_ACTUAL[INT_INDEX[band_id],1,]
description | The integration time index INT_INDEX[band_id] is the index of the band with the minimum integration time (limited to those bands that are ingested).
condition | CODA product version >= 12
path | /MDR[]/Earthshine/GEO_EARTH_ACTUAL_k[]/SOLAR_ZENITH_ACTUAL[1]
description | The integration time index k is the index (starting with 1) of the minimum integration time such that UNIQUE_INT[k-1] == min(INTEGRATION_TIMES[j]) for all bands j (0..9) that are ingeste.
solar_azimuth_angle_toa | condition | CODA product version < 12
path | /MDR[]/Earthshine/GEO_EARTH_ACTUAL/SOLAR_AZIMUTH_ACTUAL[INT_INDEX[band_id],1,]
description | The integration time index INT_INDEX[band_id] is the index of the band with the minimum integration time (limited to those bands that are ingested).
condition | CODA product version >= 12
path | /MDR[]/Earthshine/GEO_EARTH_ACTUAL_k[]/SOLAR_AZIMUTH_ACTUAL[1]
description | The integration time index k is the index (starting with 1) of the minimum integration time such that UNIQUE_INT[k-1] == min(INTEGRATION_TIMES[j]) for all bands j (0..9) that are ingeste.
viewing_zenith_angle_toa | condition | CODA product version < 12
path | /MDR[]/Earthshine/GEO_EARTH_ACTUAL/SAT_ZENITH_ACTUAL[INT_INDEX[band_id],1,]
description | The integration time index INT_INDEX[band_id] is the index of the band with the minimum integration time (limited to those bands that are ingested).
condition | CODA product version >= 12
path | /MDR[]/Earthshine/GEO_EARTH_ACTUAL_k[]/SAT_ZENITH_ACTUAL[1]
description | The integration time index k is the index (starting with 1) of the minimum integration time such that UNIQUE_INT[k-1] == min(INTEGRATION_TIMES[j]) for all bands j (0..9) that are ingeste.
viewing_azimuth_angle_toa | condition | CODA product version < 12
path | /MDR[]/Earthshine/GEO_EARTH_ACTUAL/SAT_AZIMUTH_ACTUAL[INT_INDEX[band_id],1,]
description | The integration time index INT_INDEX[band_id] is the index of the band with the minimum integration time (limited to those bands that are ingested).
condition | CODA product version >= 12
path | /MDR[]/Earthshine/GEO_EARTH_ACTUAL_k[]/SAT_AZIMUTH_ACTUAL[1]
description | The integration time index k is the index (starting with 1) of the minimum integration time such that UNIQUE_INT[k-1] == min(INTEGRATION_TIMES[j]) for all bands j (0..9) that are ingeste.