.. _showapi.level1b: Level 1B: Spectra ----------------- The SHOW Level 1B data product store SHOW spectra derived from Fourier analysis Level 1A interferogram data structures as well as an attitude solution if available. The following corrections are applied 1. Attitude solution if available 2. Height profile of average signal. Sometimes callled the *non-modulated* signal 3. Hamming apodization filter 4. Complex Fourier transform on real data. Stores magnitude and phase of complex number 4. Nominal wavelength registration. 5. SHOW filter correction Accessing Data ^^^^^^^^^^^^^^ The data are stored in directory hierarchy that organizes data by time and science/group name. To load Level 1B data using the `showapi` you will need to know the group-name and UTC time range of the data you need, note the current version only has 1 minute resolution. The `showapi` uses the concept of a collection object to store all of the images and then unitilize indexing and iteration to access individual elements. In essence the collection object looks like an array of Level 1A data records,. An example is given below:: from showapi.level1.showlevel1b import SHOWLevel1BCollection groupname = '2017_05_01_WHT_ARMA_BLK_3A_300ms_vect' # specify a SHOW science/group name startutc = '2017-05-01 16:09' # Specify start time to 1 minute accuracy (higher accuracy is not yet supported endutc = '2017-05-01 16:12' # Specify end time to 1 minute accuracy ( higher accuracy is not yet supported) with SHOWLevel1ACollection('er2_2017',groupname ) as l1bcoll: # use the "with" statement to ensure the SHOWLevel1BCollection resources are closed at the end of the 'with' section l1bcoll.load( startutc, endutc ) # load the records between the start and end time (note it includes all the records from the end minuite) n = len(l1acoll) # Get the number of records for i in range(n): # and for each record l1b = l1bcoll[i] # get the individual record print("Indexed entry:", l1b.time) # and do something with it Note the following: - The startutc and endutc parameters can be strings or datetime.dattime object. The parameters are optional to method SHOWLevel1BCollection.load(). If omitted the method will load all records for the *group* stored in the directory hierarchy. This latter option may take a long time. - The **with** statement is highly recommended as it guarantees that all the internal netcdf caching is properly released at the end of the **with** block. If you choose not to use the **with** statement please ensure you call method SHOWLevel1ACollection.close() on each L1B collection instance. An alternative version is given below that has the same functional code as the above example but uses a more modern iterating style using the iterator support built into the objects:: from showapi.level1.showlevel1b import SHOWLevel1BCollection groupname = '2017_05_01_WHT_ARMA_BLK_3A_300ms_vect' # specify a SHOW science/group name startutc = '2017-05-01 16:09' endutc = '2017-05-01 16:12' with SHOWLevel1BCollection('er2_2017',groupname ) as l1bcoll: # use the "with" statement to ensure the SHOWLevel1ACollection resources are closed at the end of the 'with' section l1bcoll.load( startutc, endutc ) # load the records between the start and end time (note it includes all the records from the end minuite) for l1b in l1bcoll: print("Iterated entry:", l1b.time) Level 1B structure ^^^^^^^^^^^^^^^^^^ The level 1B data structure captures the full complex fourier transform of the Level 1A interferograms. We only save the the first half of the full transform as the input interferogram is a pure real function. Assume the input interferogram is of shape **H,M** where **H** is the number of height rows and **M** is the number of interferogram columns. Then the fourier transform will be of shape **H,S** where S is the number of spectral elements given by `int(M/2) + 1` .. py:class:: SHOWL1BEntry The Level 1B files are stored in netcdf files as spectra derived from the Fourier transform of apodized interferograms. The structure also contains an attitude solution that can be used by radiative transfer models. .. py:attribute:: time The UTC time of the interferogram expressed as `numpy.datetime64` in micro-seconds resolution. This value can be converted to regular python datetime using:: utc = l1b.time.astype(datetime.datetime) .. py:attribute:: heightrow A 1D array(H) that maps each height (1st) row of the spectral `image` back to the original detector row. All indices are 0 based. .. py:attribute:: wavelength A 1D array(S) that gives the nominal central wavelength of each spectral element in the spectral image. .. py:attribute:: exposure_time The exposure time of the spectra in milliseconds. Scalar float. .. py:attribute:: sensor_names A 1D array that provides a human-readable name for each element in the `temperatures` field. .. py:attribute:: temperatures A 1D array of temperatures derived from the SHOW housekeeping telemetry. The names of each element can be found in the `sensor_names` field. .. py:attribute:: spectrum A 2D array(H,S) of spectra at each height. This is the magnitude of the complex Fourier transform components. If there are M elements in the original sub-windowed interferogram then there are S elements in the spectral wavelength direction where S = int(M/2) + 1 .. py:attribute:: phase A 2D image(H,S) of phase. This is the phase in degrees of the complex Fourier transform components. It is the same shape as the :attr:`spectrum` element. .. py:attribute:: error A 2-D array(H,S) giving the error in the :attr:`spectrum` element. It is the same shape as the :attr:`spectrum` element. .. py:attribute:: average_profile A 1-D array(H) containing the height profile of the 2-D interferogram derived from the average value of the 2-D interferogram at each height row. .. py:attribute:: locationxyz A 3 element array storing the geocentric vector location of the SHOW instrument as x,y,z coordinates in meters. The coordinates are expressed using the WGS80 geoid. The elements will be math.nan if no attitude solution is available. .. py:attribute:: pixelrow_lookxyz A 2D array(H,3) that provides the geocentric look direction unit vector away from the instrument for each height row in the spectral image. all elements will be math.nan if no attitude solution is available. .. py:attribute:: pixelrow_pitch_offset A 1D array (H) that provides the pitch offset of the SHOW instrument in degrees from the *nose* unit vector in the aircraft reference frame. This value is math.nan if no attaitude solution is available. .. py:attribute:: aircraft_iwg1_names A 6 element array that provides human readable names for the IWG1 attitude data derived from the aircraft attitude solution. The IWG1 values include latitude longitude, altitude, pitch, roll and heading. .. py:attribute:: aircraft_iwg1 A 6 element array that contains the IWG1 attitude data for the aircraft reference frame. The names of the fields can be found in :attr:`aircraft_iwg1_names`. The values will be math.nan if no attitude solution is available. .. py:attribute:: aircraft_nose A 3 element array specifying the geocentric unit vector of the *aircraft nose* direction. This will be math.nan if no attitude solution is available. .. py:attribute:: aircraft_starboard A 3 element array specifying the geocentric unit vector of the *aircraft starboard* direction. This will be math.nan if no attitude solution is available. .. py:attribute:: aircraft_wheels A 3 element array specifying the geocentric unit vector of the *aircraft wheels* direction. This will be math.nan if no attitude solution is available. .. py:attribute:: version A 3-element integer tuple of the form `major version`, `minor version`, `build number`. Level 1B Directory Structure ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Level 1B directory structure is identical to the Level 1A file structure except the file prefix is changed from *l1a* to *l1b*:: Level 1B basedirectory +---- 20170501 +---- 20170502 +---- 20170503 +---- ARMA_BLK_2p6A_vect +---- ARMB_BLK_2p6A_vect +---- l1b_20170501-1805_v000.nc +---- l1b_20170501-1806_v000.nc +---- l1b_20170501-1807_v000.nc +---- l1b_20170501-1808_v000.nc +---- l1b_20170501-1809_v000.nc +---- l1b_20170501-1810_v000.nc +---- l1b_20170501-1811_v000.nc +---- l1b_20170501-1812_v000.nc +---- l1b_20170501-1813_v000.nc +---- l1b_20170501-1814_v000.nc +---- l1b_20170501-1815_v000.nc +---- l1b_20170501-1816_v000.nc +---- l1b_20170501-1817_v000.nc +---- 20170504 +---- yyyymmdd +---- +---- l1a_yyyymmdd-HHMM_.nc