FLASHFlux SSF R4-555 Readme File 1.0 Introduction This readme file document provides information on the Fast Longwave And SHortwave Radiative Fluxes (FLASHFlux) SSF data sets: Aqua: FLASH_SSF_Aqua-FM3-MODIS_Version2G FLASH_SSF_Aqua-FM3-MODIS_Version2F FLASH_SSF_Aqua-FM3-MODIS_Version2E FLASH_SSF_Aqua-FM3-MODIS_Version2D FLASH_SSF_Aqua-FM3-MODIS_Version2C FLASH_SSF_Aqua-FM3-MODIS_Version2B FLASH_SSF_Aqua-FM3-MODIS_Version2A FLASH_SSF_Aqua-FM3-MODIS_Version1B Terra: FLASH_SSF_Terra-FM1-MODIS_Version2G FLASH_SSF_Terra-FM1-MODIS_Version2F FLASH_SSF_Terra-FM1-MODIS_Version2E FLASH_SSF_Terra-FM1-MODIS_Version2D FLASH_SSF_Terra-FM1-MODIS_Version2C FLASH_SSF_Terra-FM1-MODIS_Version2B FLASH_SSF_Terra-FM1-MODIS_Version2A FLASH_SSF_Terra-FM1-MODIS_Version1C FLASH_SSF_Terra-FM1-MODIS_Version1B FLASH_SSF_Terra-FM1-MODIS_Version1A This document includes the following sections: Section 2.0 - Data Set Description Section 3.0 - Format and Packaging Section 4.0 - Science Parameters Information Section 5.0 - Description of Sample Read Software Section 6.0 - Implementing Sample Read Software Section 7.0 - Sample Output Section 8.0 - Additional Data Information (This section is optional) If users have questions, please contact the Langley ASDC User and Data Services Office at: Atmospheric Science Data Center User and Data Services Office Mail Stop 157D NASA Langley Research Center Hampton, Virginia 23681-2199 U.S.A. E-mail: support-asdc@earthdata.nasa.gov Phone: (757)864-8656 FAX: (757)864-8807 URL: http://eosweb.larc.nasa.gov 2.0 Data Set Description 2.1 Instrumentation Description The FLASHFlux products are based upon the Clouds and the Earth's Radiant Energy Systems (CERES) products. For a complete description of the CERES experiment and instruments, please refer to the documentation provided at the URL http://science.larc.nasa.gov/ceres/. 2.2 Data Quality For a discussion regarding the quality of the SSF data sets, please refer to the corresponding Quality Summary Document available from the URL http://eosweb.larc.nasa.gov/PRODOCS/ceres/level2_ceres-flash_table.html. 2.3 Other pertinent information The FLASHFlux SSF product is produced from software maintained by the FLASHFlux Data Management Team. 2.4 Science Representatives *NOTE TO USER: If you have any questions concerning the sample code or the data, please contact the Atmospheric Science Data Center User Services Office. The contact information is provided above in Section 1.0. 1. Dr. Paul W. Stackhouse, FLASHFlux Principal Investigator NASA Langley Research Center Mail Stop 420 Hampton, Virginia 23681-2199 E-mail: Paul.W.Stackhouse@nasa.gov FAX: (757)864-7996 Phone: (757)864-5368 2. Dr. David P. Kratz, FLASHFlux Working Group Coordinator NASA Langley Research Center Mail Stop 420 Hampton, Virginia 23681-2199 E-mail: David.P.Kratz@nasa.gov FAX: (757)864-7996 Phone: (757)864-5669 3.0 Format and Packaging This package includes a program, written in C, which will read an SSF HDF file. The examples provided in the main (SSF_readhdf.c) program are written specifically for SDS(s) and Vdata(s) in SSF files. This read program is provided as a template to the user who will need to modify it, if they need to read different SSF parameters. Information on the structure of the SSF file can be found in the Data Products Catalog (DPC) pages included in this package. This information is also available in the enclosed dump file, CER_SSF_Sample_R4V1.dump. Complete parameter descriptions are available in the Collection/User's Guide, which is on-line at URL: http://ceres.larc.nasa.gov/collect_guide.php . 3.1 Sample Read Package Contents This package consists of the following files: 1) CER_SSF_Sample_R4V1 2) CER_SSF_Sample_R4V1.dump 3) CER_SSF_Sample_R4V1.met 4) SSF_HDFread.h 5) SSF_readHDFfuncs.c 6) SSF_readhdf.c 7) compile_SSF_readhdf Descriptions for each file is as follows: 1)'CER_SSF_Sample_R4V1' is a sample 5-footprint SSF file which is used by the examples in 'SSF_readhdf.c' 2)'CER_SSF_Sample_R4V1.dump' is an ASCII file containing a description of the data in the sample SSF, 'CER_SSF_Sample_R4V1'. If a value in the SSF granule is out-of-range or not valid, a default value is inserted in its place. Default values depend on data type. FLASHFlux default values are greater than or equal to: INT2 - 32767 INT4 - 2147483647 REAL4 - 3.402823E+38 REAL8 - 1.797693134862315E+308 The 'CER_SSF_Sample_R4V1.dump' file includes a list of ALL the data on the 5 footprint sample SSF (160 parameters/SDS's plus header Vdata). The output data are the same as what the user would produce using hdp, but for this example, the CERES Team modified the format of the output from the hdp command to make it easier to read. 3)CER_SSF_Sample_R4V1.met is an ASCII metadata file that is delivered with every data granule. The file is written in Object Descriptive Language (ODL) and contains information that is associated with the origin, content, quality, and condition of the data granule. The metadata information contained in the granule metadata file is also included as metadata on the SSF HDF data file. An example of a metadata parameter found in the metadata file and on the SSF HDF file is LOCALGRANULEID, which has a value set to the original granule file name. 4)'SSF_HDFread.h' is a header file for 'SSF_readhdf.c' and the SSF HDF read functions. 5)'SSF_readHDFfuncs.c' is a file consisting of C functions that are linked with 'SSF_readhdf.c' and call the HDF functions. 6)'SSF_readhdf.c' is the main program which accesses the HDF reading functions. It consists of six examples of accessing SDS and Vdata structures from the included sample SSF file. Comments are provided throughout the program. This file must be modified if the user wishes to read SDSs or Vdatas other than those in the examples. 7)'compile_SSF_readhdf' is a sample script to compile the C programs in a UNIX environment. The script must be modified for different platforms to properly compile the programs and correctly link the HDF libraries. 3.2 Zip Information To read the files, first unzip them with Info-Zip software. Information about downloading and using this freeware is available at the URL: http://www.info-zip.org/pub/infozip/Info-ZIP.html 3.3 HDF library HDF information, documentation, tutorials, libraries, etc. can be found on-line at the URL http://hdf.ncsa.uiuc.edu. The utility hdp, provided in the HDF libraries, extracts information regarding the HDF file contents, such as the size, type, order, names, and the data itself. Some examples are: hdp -H - provides "help" on how to use the "hdp" utility hdp dumpsds [-options] - lists information about the SDSs found on the specified file hdp dumpvd [-options] - lists information about the Vdatas found on the specified file 3.4 Data Format The SSF data files are written in HDF as collections of SDS(s) and Vdata(s). 3.5 Breakdown of the File Naming Convention The SSF data granules adhere to the following FLASHFlux file naming convention: FLASH_PID_SS_PS_CC.DataDate where: FLASH = the FLASHFlux experiment PID = the FLASHFlux product, e.g., SSF SS = the FLASHFlux sampling strategy, e.g., Terra-FM2-MODIS, as defined by the CERES experiment. For the SSF, this indicates the satellite and instruments that were the source of the input data into the software system that produced the SSF data. PS = the FLASHFlux production strategy, e.g., 'Beta2', as defined by the FLASHFlux experiment. 'BetaN' production strategies indicate versions of the product produced with algorithms that are still being validated. SSF data products with BetaN production strategies may only be available for a limited time and cannot be be used to publish. SSF data products with 'VersionN' production strategies usually indicate products that contain validated data with which the user can publish. CC = the product configuration code, e.g., '017018', assigned by the FLASHFlux experiment. This code is internal to the FLASHFlux project, and is updated whenever the software system producing the product is modified for any reason. Multiple files that are identical in all aspects of the filename except for the 6 digit configuration code differ little, if any, scientifically. Users may, therefore, analyze data from the same sampling strategy and production strategy without regard to configuration code. For a complete history of the changes to the software, see the SSF product Description/Abstract document available from the URL http://eosweb.larc.nasa.gov/PRODOCS/ceres/table_ceres.html DataDate = the date of the data included in the file. For the SSF, this date is in the format YYYYMMDDHH where: YYYY = the four-digit data year, MM = the two-digit month DD = the two-digit day HH = the two-digit hour (00-23) 4.0 Science Parameters Information Refer to the SSF CERES Data Products Catalog pages included with this package (listed under Section 3.1) for the following information for each science parameter: Name Units Type (integer, real, character, etc...) Ranges (minimum and maximum values) Fill values / bad data flags 5.0 Description of Sample Read Software The sample read software in this package is intended only as an example. As both the number of SDSs and Vdatas that make up the SSF product and the number of data records contained on an actual SSF file are large, the sample software only demonstrates reading a limited number of SDSs for the five footprints included in the sample SSF file. The contents of the SSF footprint, along with a list of all the SDS(s) contained on the SSF product, are described in the Data Products Catalog pages discussed in Section 3.1. A note to the user: It is recommended that before modifiying the SSF read program to read different SSF parameters, the user should first compile and run the SSF read program using the sample SSF file as input and compare the results that are created by the read program for each SDS/parameter with the list of values for corresponding parameters in the SSF sample dump file,'CER_SSF_Sample_R4V1.dump'. If this test is successful, then the user should modify the the SSF read program or their own software to read the parameters in which they are interested and run that software using the Sample SSF as input. The values read should be compared to the values of the corresponding parameters in the sample dump file. If both of these test are successful, then the user will be ready to use their altered program with a full size SSF data file. 6.0 Implementing Sample Read Software 6.1 Compiling the Sample Read Software 1. Download and install the HDF libraries from the NCSA web site http://hdf.ncsa.uiuc.edu This code uses version HDF4.1r5. Other versions of the HDF libraries may not work with this code. NCSA uses the GNU gzip compression utility for some packages. If necessary, the software needed to uncompress the file can be obtained from one of the GNU mirror sites listed at the URL: http://www.gnu.org/order/ftp.html 2. Edit the sample script 'compile_SSF_readhdf' to link the HDF libraries and compile the C programs. Check the permissions on this file to make sure execute permission is set for the owner by typing at the command line (denoted by ">"): > ls -l compile_SSF_readhdf A line similar to the following will be displayed: -rwxr--r-- 1 OWNER GROUP 1450 Mar 6 14:49 compile_SSF_readhdf where OWNER and GROUP are the file owner and group information. The owner executable permission is the x in -rwxr--r--. To set the proper permissions, at the command line type: > chmod 744 compile_SSF_readhdf 3. Execute the script 'compile_SSF_readhdf' to create the executable ssf_rd by typing at the command line: > source compile_SSF_readhdf or, on some systems, type: > compile_SSF_readhdf 6.2 How to Run the Sample Read Software Execute ssf_rd by typing at the command line: > ssf_rd CER_SSF_Sample_R4V1 7.0 Sample Output The following is the screen output generated from executing the ssf_rd program with the provided sample file. > ./ssf_rd CER_SSF_Sample_R4V1 Name of HDF file to be read: < CER_SSF_Sample_R4V1 ********************************************************* * Example 1: * ********************************************************* Footprint 1 X component of satellite inertial velocity = 1.002511 Footprint 2 X component of satellite inertial velocity = 1.024786 Footprint 3 X component of satellite inertial velocity = 1.067702 Footprint 4 X component of satellite inertial velocity = 1.404886 Footprint 5 X component of satellite inertial velocity = 1.677296 ********************************************************* * Example 2: * ********************************************************* Footprint 1 Surface type percent coverage(1) = 100 Surface type percent coverage(2) = 0 Surface type percent coverage(3) = 32767 Surface type percent coverage(4) = 32767 Surface type percent coverage(5) = 32767 Surface type percent coverage(6) = 32767 Surface type percent coverage(7) = 32767 Surface type percent coverage(8) = 32767 Footprint 2 Surface type percent coverage(1) = 95 Surface type percent coverage(2) = 5 Surface type percent coverage(3) = 32767 Surface type percent coverage(4) = 32767 Surface type percent coverage(5) = 32767 Surface type percent coverage(6) = 32767 Surface type percent coverage(7) = 32767 Surface type percent coverage(8) = 32767 Footprint 3 Surface type percent coverage(1) = 100 Surface type percent coverage(2) = 32767 Surface type percent coverage(3) = 32767 Surface type percent coverage(4) = 32767 Surface type percent coverage(5) = 32767 Surface type percent coverage(6) = 32767 Surface type percent coverage(7) = 32767 Surface type percent coverage(8) = 32767 Footprint 4 Surface type percent coverage(1) = 99 Surface type percent coverage(2) = 1 Surface type percent coverage(3) = 0 Surface type percent coverage(4) = 32767 Surface type percent coverage(5) = 32767 Surface type percent coverage(6) = 32767 Surface type percent coverage(7) = 32767 Surface type percent coverage(8) = 32767 Footprint 5 Surface type percent coverage(1) = 100 Surface type percent coverage(2) = 32767 Surface type percent coverage(3) = 32767 Surface type percent coverage(4) = 32767 Surface type percent coverage(5) = 32767 Surface type percent coverage(6) = 32767 Surface type percent coverage(7) = 32767 Surface type percent coverage(8) = 32767 ********************************************************* * Example 3: * ********************************************************* Footprint 1 Percentiles of visible optical depth for cloud layer Percentile 1 for Lower Layer = 0.198329 Percentile 1 for Upper Layer = 0.620540 Percentile 2 for Lower Layer = 0.926831 Percentile 2 for Upper Layer = 0.688517 Percentile 3 for Lower Layer = 1.079679 Percentile 3 for Upper Layer = 0.811510 Percentile 4 for Lower Layer = 1.292997 Percentile 4 for Upper Layer = 0.970381 Percentile 5 for Lower Layer = 1.483705 Percentile 5 for Upper Layer = 0.983912 Percentile 6 for Lower Layer = 1.790222 Percentile 6 for Upper Layer = 1.288952 Percentile 7 for Lower Layer = 2.090532 Percentile 7 for Upper Layer = 1.425513 Percentile 8 for Lower Layer = 2.615130 Percentile 8 for Upper Layer = 1.738967 Percentile 9 for Lower Layer = 3.374945 Percentile 9 for Upper Layer = 1.829643 Percentile 10 for Lower Layer = 4.377486 Percentile 10 for Upper Layer = 2.088193 Percentile 11 for Lower Layer = 5.389586 Percentile 11 for Upper Layer = 2.577281 Percentile 12 for Lower Layer = 7.175561 Percentile 12 for Upper Layer = 2.648829 Percentile 13 for Lower Layer = 8.913366 Percentile 13 for Upper Layer = 2.825786 Footprint 2 Percentiles of visible optical depth for cloud layer Percentile 1 for Lower Layer = 2.660139 Percentile 1 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 2 for Lower Layer = 2.660139 Percentile 2 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 3 for Lower Layer = 2.660139 Percentile 3 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 4 for Lower Layer = 2.660139 Percentile 4 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 5 for Lower Layer = 2.660139 Percentile 5 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 6 for Lower Layer = 2.660139 Percentile 6 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 7 for Lower Layer = 2.660139 Percentile 7 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 8 for Lower Layer = 2.660139 Percentile 8 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 9 for Lower Layer = 2.660139 Percentile 9 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 10 for Lower Layer = 2.660139 Percentile 10 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 11 for Lower Layer = 2.660139 Percentile 11 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 12 for Lower Layer = 2.660139 Percentile 12 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 13 for Lower Layer = 2.660139 Percentile 13 for Upper Layer = 340282346638528860000000000000000000000.000000 Footprint 3 Percentiles of visible optical depth for cloud layer Percentile 1 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 1 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 2 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 2 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 3 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 3 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 4 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 4 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 5 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 5 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 6 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 6 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 7 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 7 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 8 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 8 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 9 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 9 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 10 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 10 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 11 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 11 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 12 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 12 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 13 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 13 for Upper Layer = 340282346638528860000000000000000000000.000000 Footprint 4 Percentiles of visible optical depth for cloud layer Percentile 1 for Lower Layer = 0.678105 Percentile 1 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 2 for Lower Layer = 0.678105 Percentile 2 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 3 for Lower Layer = 0.678105 Percentile 3 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 4 for Lower Layer = 0.678105 Percentile 4 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 5 for Lower Layer = 0.678105 Percentile 5 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 6 for Lower Layer = 0.678105 Percentile 6 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 7 for Lower Layer = 0.678105 Percentile 7 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 8 for Lower Layer = 2.518090 Percentile 8 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 9 for Lower Layer = 2.518090 Percentile 9 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 10 for Lower Layer = 2.518090 Percentile 10 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 11 for Lower Layer = 2.518090 Percentile 11 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 12 for Lower Layer = 2.518090 Percentile 12 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 13 for Lower Layer = 2.518090 Percentile 13 for Upper Layer = 340282346638528860000000000000000000000.000000 Footprint 5 Percentiles of visible optical depth for cloud layer Percentile 1 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 1 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 2 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 2 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 3 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 3 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 4 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 4 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 5 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 5 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 6 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 6 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 7 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 7 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 8 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 8 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 9 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 9 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 10 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 10 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 11 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 11 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 12 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 12 for Upper Layer = 340282346638528860000000000000000000000.000000 Percentile 13 for Lower Layer = 340282346638528860000000000000000000000.000000 Percentile 13 for Upper Layer = 340282346638528860000000000000000000000.000000 ********************************************************* * Example 4: * ********************************************************* Central wavelengths of imager channels 1. 0.469000 2. 0.555000 3. 0.645000 4. 0.858000 5. 0.905000 6. 1.240000 7. 1.375000 8. 1.640000 9. 2.130000 10. 3.792000 11. 4.050000 12. 6.720000 13. 8.550000 14. 11.030000 15. 12.020000 16. 13.340000 17. 13.640000 18. 13.940000 19. 14.240000 20. 0.000000 ********************************************************* * Example 5: * ********************************************************* ASSOCIATEDPLATFORMSHORTNAME = Terra ********************************************************* * Example 6: * ********************************************************* NUMBEROFRECORDS = 5 8.0 Additional Information Regarding FLASHFlux SSF Data Updated: Jul 29, 2009; May 14, 2008; Oct 20, 2010 May 17, 2012 - changed User Services email Oct 12, 2012 - changed links for data table -----------------------------------------------------------------------------