Basic IDL Tools for extraction information from TES L2 HDF Product files. Release January, 2011 for version F01, F02, F03, and F04, F05, F06 files. IMPORTANT NOTE: These routines only work with IDL version 6.3 and higher for reading format version F04+ speices and ancillary files and format version F01+ summary & supplemental files. 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_l2_hdf.pro read_l2_hdf_ancillary.pro read_l2_hdf_summary.pro read_l2_hdf_summary_swath.pro read_l2_hdf_field.pro read_l2_hdf_geofield.pro read_l2_hdf_supplemental.pro get_data_attributes.pro (support routine--not called directly by the user) The routines and this readme file are distributed in a Unix .tar file package which may also be unbundled using extraction software such as WinZip. Each routine takes the name of a TES L2 HDF product file and returns all or some portion of the files. The routine read_l2_hdf.pro complete contents of a L2 HDF species data file. The routine read_l2_hdf_ancillary.pro returns the data fields from a TES L2 ancillary file. The routine read_l2_hdf_summary.pro reads and returns the contents of a summary file. The routines read_l2_hdf_field.pro and read_l2_hdf_geofield.pro each return one particular data field from a species data file for cases where only one or a few of the fields are needed. The subroutine get_data_attributes.pro is a support routine used by the read_l2 routines and should not be called directly. For all of the above routines, a standard IDL documentation header has been placed at the top of each file. This document summarized the naming and calling information for each routine. For details of the various dimensions and fields of the returned data, please see the header in each file. For details of the TES L2 HDF product file specifications, please see the Data Products Specifications (DPS) document. SIDE NOTE: 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 and a sample TES L2 HDF file will help one quickly become acquainted with the contents of TES L2 HDf files. 2) SUMMARIES OF EACH ROUTINE AND ITS USAGE ---- read_l2_hdf.pro ---- This routine returns the complete contents of a TES L2 HDF species product file. Calling syntax: read_l2_hdf,file,species_data,geo_data,status=status, $ species_attributes = species_attributes,geo_attributes = $ geo_attributes, additional_data = additional_data, $ hdfeos_data = hdfeos_data,read_ph=read_ph where file is the input file name(string), species_data is a structure containing all of the retrieval data, and geo_data is a structure containing all of the geolocation information. Optionally the attributes data associated with each species data field and geolocation field can be obtained with the output keywords species_attributes and geo_attributes. The additional_data containes file attributes data in a structure, and the HDFEOS metadata information is contained in the hdfeos_data output keyword. The read_ph keyword forces the reading of the 'ProductionHistory' field, which is skipped by default(this entry is not present in files produced at the JPL SCF with CASPER). ---- read_l2_hdf_ancillary.pro ---- This routine returns the contents the ancillary swath groups present and other ancillary data from a TES L2 ANCILLARY HDF product file. Calling syntax: read_l2_hdf_nancillary,file,$ nadir_ancillary_data = nadir_ancillary_data, $ limb_ancillary_data = limb_ancillary_data, $ nadir_geo_data = nadir_geo_data, $ limb_geo_data = limb_geo_data, $ nadir_ancillary_attributes = nadir_ancillary_attributes, $ limb_ancillary_attributes = limb_ancillary_attributes, $ nadir_geo_attributes = nadir_geo_attributes, $ limb_geo_attributes = limb_geo_attributes, $ file_attributes = file_attributes, hdfeos_data = hdfeos_data, $ status = status,read_ph=read_ph where file is the input file name(string). The nadir and limb swath data are returned separately, and the return keywords are only defined if there is data in the file for that swath. [nadir or limb]_ancillary_data is a structure containing all of the ancillary data, and [nadir or limb]_geo_data is a structure containing all of the geolocation information. Optionally the attributes data associated with each data field and geolocation field can be obtained with the output keywords [nadir or limb]_ancillary_attributes and [nadir or limb]_ancillary geo_attributes. The HDFEOS metadata information is contained in the hdfeos_data output keyword. The read_ph keyword forces the reading of the 'ProductionHistory' field, which is skipped by default (this entry is not present in files produced at the JPL SCF with CASPER). ---- read_l2_hdf_summary.pro ---- The routine returns the contents of a TES L2 SUMMARY file. Summary files are very large and users are cautioned to read the program header documentation carefully to most expiditiously make use of summary-type files. Calling syntax: read_l2_hdf_summary,file, $ read_swaths = read_swaths,$ anc_nadir = anc_nadir, $ anc_limb = anc_limb, $ tatm_nadir = tatm_nadir, $ tatm_limb = tatm_limb, $ o3_nadir = o3_nadir, $ o3_limb = o3_limb, $ co_nadir = co_nadir, $ co_limb = co_limb, $ h2o_nadir = h2o_nadir, $ h2o_limb = h2o_limb, $ hdo_nadir = hdo_nadir, $ hdo_limb = hdo_limb, $ ch4_nadir = ch4_nadir, $ ch4_limb = ch4_limb, $ hno3_limb=hno3_limb, $ no2_limb=no2_limb, $ file_attributes = file_attributes, $ hdfeos_data = hdfeos_data, $ status = status,read_ph=read_ph, $ show_options = show_options, $ list_swaths = list_swaths, $ actual_swaths = actual_swaths file is the name (string) of the file to be read, read_swaths is an optional input keyword for reading subsets of the data. show_options will list all possible read_swaths options. list_swaths is a input keyword flag that will print to the terminal all of the swaths actually present in the file. All other keywords are output keywords that contain the various data from the file. lease see the program header documentation for information about the format of this data. Not all swaths are expected to be present in all files. Swaths not present in the file will have their output keywords undefined regardless of the input read request. The actual_swaths keywords is an output keyword that will contain an array of all of the swaths present in the file (same as shown by list swaths, but returned in as an IDL variable). ---- read_l2_hdf_summary_swath.pro ---- The routine returns the a single swath from a TES L2 SUMMARY file. This version has been added to make reading swath files less memory intensive and quicker for those whom do not need the whole file Calling syntax: read_l2_hdf_summary,file, $ read_swath,$ ancillary_swath=ancillary_swath, species_swath=species_swath, file_attributes = file_attributes, $ hdfeos_data = hdfeos_data, $ status = status,read_ph=read_ph, $ show_options = show_options, $ list_swaths = list_swaths, $ actual_swaths = actual_swaths file is the name (string) of the file to be read, read_swath is swath to be read. show_options will list all possible read_swath options. list_swaths is a input keyword flag that will print to the terminal all of the swaths actually present in the file. Output is via the ancillary_swath or species_swath keyword that contain the various data from the requested swath. Ancillary and species swaths have different formats and thus different keywords. Please see the program header documentation for information about the format of this data. Not all swaths are expected to be present in all files. The actual_swaths keywords is an output keyword that will contain an array of all of the swaths present in the file (same as shown by list swaths, but returned in as an IDL variable). ---- read_l2_hdf_field.pro ---- This function extracts one particular data field from a TES L2 HDF product file. This might be used in cases where only one or a few of the data fields are wanted and greater speed is desired. Since this routine only returns one of the fields, it is easier to use read_l2_hdf if most of the fields are needed. Calling syntax: result = read_l2_hdf_field(file,fieldname,$ status=status,attributes=attributes, file_attributes=file_attributes, swath_data=swath_data) File is the name of the file to be read (string). Fieldname is a string containing the name of the field wanted (example: Altitude or AveragingKernel) and is case insensitive and may be specified with the least number of non-ambiguous characters for each field. The short-hand 'gas' may be used to specify the particular retrieval species from the file. Optionally the associated field attributes may be obtained in the output keyword attributes. The output keyword file_attributes gives the file attributes group information (including the date of observation). The swath_data keyword contains the swath level attribute data. ---- read_l2_hdf_geofield.pro ---- This function extracts one particular geolocation data from a TES L2 HDF product file. This might be used in cases where only one or a few of the data fields are wanted and greater speed is desired. Since this routine only returns one of the fields, it is easier to use read_l2_hdf if most of the fields are needed. Calling syntax: result = read_l2_hdf_geofield(file,fieldname,$ index=index, status=status,attributes=attributes) File is the name of the file to be read (string). Fieldname is a string containing the name of the geolocation field wanted (example: Latitude or Longitude) and is case insensitive and may be specified with the least number of non-ambiguous characters for each field. Optionally the associated field attributes may be obtained in the output keyword attributes. ---- read_l2_hdf_supplemental.pro ---- This proceedure reads and returns the contents of TES L2 HDF supplemental product filles. Calling syntax: read_l2_hdf_supplemental,file,status=status, $ cfc11limb = cfc11limb, $ cfc12limb = cfc12limb, $ ch4limb = ch4limb, $ co2limb = co2limb, $ co2nadir = co2nadir, $ n2olimb = n2olimb, $ n2onadir = n2onadir, $ o3limb = o3limb, $ list_swath=list_swath, $ file_attributes=file_attributes, $ hdfeos_data = hdfeos_data, $ read_ph=read_ph where file is the file to be read. Output will be in the various keywords. Not all fields will be present in every file, so the user must check for undefined variables (keyword output for swaths not in the current file). 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