Basic IDL Tools for extraction information from TES L1B HDF product files. Released January, 2007 for version F02, F03 files. These routines are written in Research System, Inc. Interactive Data Language (IDL). IMPORTANT NOTE: These routines only work with IDL version 6.1 and higher. The routines and this readme file are distributed in a Unix .tar file package which may also be unbundled using extraction software such was WinZip. The tar file was written such that a directory named TES_L1BReadSoftwareV3 will be created under the current directory where the tar file is placed, and the IDL program files will be written into that directory. CONTENTS: 1) Introduction and Overview 2) Summaries of each routine and its usage 3) Contact Information 1) INTRODUCTION AND OVERVIEW The routines covered by this README are: read_l1b_hdf.pro (RECOMMENDED) (The following routines may not be supported past Level 1B file format version F03.) read_l1b_hdf_eng.pro read_l1b_hdf_geo.pro read_l1b_hdf_hdfeos.pro read_l1b_hdf_l1bmeta.pro read_l1b_hdf_nesr.pro read_l1b_hdf_qa.pro read_l1b_hdf_spectra.pro read_l1b_hdf_tesmeta.pro Each routine takes as input a the name of a TES L1B HDF product file and returns some portion of the file. The routines are divided as the data are, each group and metadata set having a separate routine. The routine read_l1b_hdf_spectra is special in that it also returns the frequency scale attributes (combined) or optionally as separate start_frequency and delta_frequency keywords (see detailed routine explanation below). For all of the above routines, a standard IDL documentation header has been placed at the top of each file and a very brief usage message will be printed if the routine is called without any arguments. This document summarizes the information found in the header. For details of the various dimensions and fields of the returned data, please see the header in each file. For details of the TES L1B HDF product file specifications, please see the Data Products Specifications (DPS) document (http://eosweb.larc.nasa.gov/PRODOCS/tes/DPS/). SIDE NOTES: a) IDL has a nice GUI tool for browsing HDF files called h5_browser. It will show you the structure of the HDF file and all of the data, and allow you to export it to the IDL command line. Using this tool with a TES L1B HDF file will assist with quickly becoming acquainted with the contents of TES L1B HDf files. b) Several of the routines take filter as an input parameter. A function, find_l1b_filters which returns the filters found in a TES Level 1B file is also included in this package. It is found in the file find_l1b_filters.pro and takes as input the name of the file to be checked. The return value of the function is a string array where each array element is a filter name. Status can be returned using the status keyword. The calling sequence is filter_list = find_l1b_filters(file,status=status) Additional documentation can be found in the routine's header comments. Possible filter values are: Filter Plane Filters 1A 1A1, 1A2, 1A3, 1A4, 1A5 1B 1B1, 1B2 2A 2A1, 2A2, 2A3, 2A4 2B 2B1 See Table IV: Filter Bands & Species Coverage in the Level 1B Algorithm Theoretical Basis Document (available via link from http://eosweb.larc.nasa.gov/PRODOCS/tes/table_tes.html) for more filter detail. 2) SUMMARIES OF EACH ROUTINE AND ITS USAGE For all of the L1B HDF reader routines, the status keyword is an optional output parameter that is set to the following values (non-zero for an error condition): status = 0 for success (no errors) 1 if file does not exist 2 the file name does not have correct version string 3 the file is not HDF 5 ********************* read_l1b_hdf.pro: ********************* This routine reads the entire L1B file and returns the spectra, NESR and the frequency scale as arguments. All other fields are returned using output keywords. Calling syntax: read_l1b_hdf,file,filter,spectra,nesr,freq_scale, $ start_frequency=start_frequency, $ delta_frequency=delta_frequency, $ qa_data=qa_data,geo_data=geo_data, $ eng_data=eng_data,l1b_meta=l1b_meta, $ tes_meta=tes_meta,hdfeos=hdfeos, $ status=status,read_ph=read_ph where file is the input file name (string), filter (string) is the filter desired, spectra is the three-dimensional spectral data array, NESR is the three-dimensional NESR data array and freq_scale is the one-dimensional array containing the frequency values associated with the spectral axis of the data. The actual attributes from the HDF file, the start_frequency and delta_frequency, are available as optional output keywords. Note that freq_scale = dindgen(L)*delta_frequency+start_frequency read_ph is an input keyword to force reading of the ProductionHistory field. All other fields are output keywords. See the routine for details of the contents of the various fields. ********************* read_l1b_hdf_eng.pro: ********************* This routine returns the engineering data from the L1A diagnostic file, and contains information such as run, sequence, and scan numbers, instrument temperatures and signal chain state. Calling syntax: read_l1b_hdf_eng,file,filter,data,status=status where file is the input file name (string), filter is the filter desired, and data is an array of structures (one for each observation) containing the engineering data. ********************* read_l1b_hdf_geo.pro: ********************* This routine returns an array of structures of the geolocation data, including the latitude, longitude, and DEM surface elevation. Calling syntax: read_l1b_hdf_geo,file,filter,data,status=status where file is the input file name (string), filter is the filter desired, and data is the an array of structures (one for each observation) containing the geolocation data. ************************ read_l1b_hdf_hdfeos.pro: ************************ This routine returns the "HDFEOS Information" coremetadata as a concatenated string. Information includes PGE version, production date, and temporal coverage information. Calling syntax: read_l1b_hdf_hdfeos,file,info,status=status where file is the input file name and info is the returned metadata string. ************************* read_l1b_hdf_l1bmeta.pro: ************************* This routine returns the TES L1B metadata as a structure. The L1B metadata includes the run counter, orbit path ID, orbit number, and time range of the observations. Calling syntax: read_l1b_hdf_l1bmeta,file,data,status=status where file is the input file name and data is the return data as a structure. ********************** read_l1b_hdf_nesr.pro: ********************** This routine returns the Noise Equivalent Spectral Radiance (NESR) data as an LxMxN floating point array, where L is the number of spectra points, M is the number of observations, and N is the number of detectors (16). Calling syntax: read_l1b_hdf_nesr,file,filter,nesr,status=status where file is the input file name (string), filter (string) is the filter desired, and nesr is the NESR data array. ******************** read_l1b_hdf_qa.pro: ******************** This routine returns all of the QA data contained in a TES L1B HDF file as a structures of structures. The four types of QA data are l1a_pixel, l1aqa, l1b_bt, and l1b_target. Each substructure contains many different fields dimensioned by the number of observations and pixel (if a pixel level quality field). Please see the routine and or the DPS for all of the explicit details about the various QA data available. Calling syntax: read_l1b_hdf_spectra,file,filter,qa_data,status=status where file is the input file name (string), filter (string) is the filter desired, and qa_data is the returned QA data in a structure. ************************* read_l1b_hdf_spectra.pro: ************************* This routine returns the primary L1B information: the spectral radiances. The returned data is a floating point array of dimensions LxMxN, where L is the number of spectra points, M is the number of observations, and N is the number of detectors (16). Additionally this routine returns the attribute data associated with the spectra that give the frequency scale of the spectra. Calling syntax: read_l1b_hdf_spectra,file,filter,spectra,freq_scale,status=status start_frequency=start_frequency, delta_frequency=delta_frequency where file is the input file name (string), filter (string) is the filter desired, spectra is the three-dimensional data array, and freq_scale is the one-dimensional array containing the frequency values associated with the spectral axis of the data. The actual attributes from the HDF file, the start_frequency and delta_frequency, are available as optional output keywords. Note that freq_scale = dindgen(L)*delta_frequency+start_frequency ************************* read_l1b_hdf_tesmeta.pro: ************************* This routine returns the TES-common metadata information as a structure. Information includes the PGE version and the run number among others. Calling syntax: read_l1b_hdf_tesmeta,file,data,status=status where file is the input file name (string) and data is the returned structure of TES-common metadata. 3) CONTACT INFORMATION Questions about using these routines may be directed to: NASA Langley Atmospheric Science Data Center User and Data Services Office NASA Langley Research Center Mail Stop 157D Hampton, Virginia 23681-2199 U.S.A. E-mail: support-asdc@earthdata.nasa.gov Phone: (757)864-8656 FAX: (757)864-8807