CERES CRS R3-564 Readme File

1.0  Introduction
     This readme file document provides information on the
     following Clouds and Earth's Radiant Energy System (CERES)
     CRS data sets:

     Aqua:
       CER_CRS_Aqua-FM3_Edition2A
       CER_CRS_Aqua-FM4_Edition2A
       CER_CRS_Aqua-FM3_Beta1
       CER_CRS_Aqua_FM4_Beta1
     Terra
       CER_CRS_Terra_FM1_Edition2B
       CER_CRS_Terra_FM2_Edition2B

     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
         2 South Wright Street
         NASA Langley Research Center
         Hampton, Virginia 23681-2199
         U.S.A.

         E-mail:   larc@eos.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

        For a complete description of the CERES experiment and instruments,
        please refer to the documentation provided at the URL
        http://asd-www.larc.nasa.gov/ceres/ASDceres.html.

    2.2 Data Quality

        For a discussion regarding the quality of the CRS data sets,
        please refer to the corresponding Quality Summary Document
        available from the URL
        http://eosweb.larc.nasa.gov/PRODOCS/ceres/table_ceres.html.

    2.3 Other pertinent information

        The CERES CRS product is produced from software maintained
        by the CERES Inversion 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. Bruce A. Wielicki, CERES Interdisciplinary Principal 
            Investigator
    	    NASA Langley Research Center
            Mail Stop 420
            Hampton, VA 23681-2199
            E-mail:   Bruce.A.Wielicki@nasa.gov
            FAX:      (757)864-7996
            Phone:    (757)864-5683

         2. Dr. Patrick Minnis, Clouds Working Group chair
    	    NASA Langley Research Center
            Mail Stop 420
            Hampton, VA 23681-2199
            E-mail:   P.Minnis@nasa.gov
            FAX:      (757)864-7996
            Phone:    (757)864-5671

         3. Dr. Norman Loeb, ADM Working Group chair
            NASA Langley Research Center
            Mail Stop 420
            Hampton, VA 23681-2199
            E-mail:   N.G.Loeb@larc.nasa.gov
            FAX:      (757)864-7996
            Phone:    (757)864-5688

         4. Dr. David Kratz, Surface-only Working Group chair
	    NASA Langley Research Center
            Mail Stop 420
            Hampton, VA 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 CRS HDF file.  The examples provided in the main (CRS_readhdf.c) 
     program are written specifically for SDS(s) and Vdata(s) in CRS files.
     This read program is provided as a template to the user who will need 
     to modify it, if they need to read different CRS parameters.

     Information on the structure of the CRS 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_CRS_Terra-FM2-MODIS_Sample_000000.2001100101.dump.  
     Complete parameter descriptions are available in the 
     Collection/User's Guide, which is on-line at URL: 
     http://asd-www.larc.nasa.gov/ceres/collect_guide.

    3.1 Sample Read Package Contents

        This package consists of the following files:

        1) CER_CRS_Terra-FM2-MODIS_Sample_000000.2001100101
        2) CER_CRS_Terra-FM2-MODIS_Sample_000000.2001100101.dump
        3) CER_CRS_Terra-FM2-MODIS_Sample_000000.2001100101.met
        4) CRS_HDFread.h
        5) CRS_readHDFfuncs.c
        6) CRS_readhdf.c
        7) compile_CRS_readhdf
 
        Descriptions for each file is as follows:
        1)'CER_CRS_Terra-FM2-MODIS_Sample_000000.2001100101' is a sample 
	  5-footprint CRS file which is used by the examples in 'CRS_readhdf.c'

        2)'CER_CRS_Terra-FM2-MODIS_Sample_000000.2001100101.dump' is an ASCII 
	  file containing a description of the data in the sample CRS, 
	  'CER_CRS_Terra-FM2-MODIS_Sample_000000.2001100101'. If a value 
	  in the CRS granule is out-of-range or not valid, a default value is 
	  inserted in its place.  Default values depend on data type.  
	  CERES default values are greater than or equal to:
          INT2    - 32767
          INT4    - 2147483647
          REAL4   - 3.402823E+38
          REAL8   - 1.797693134862315E+308

          The 'CER_CRS_Terra-FM2-MODIS_Sample_000000.2001100101.dump' file 
	  includes a list of ALL the data on the 5 footprint sample CRS 
	  (250 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_CRS_Terra-FM2-MODIS_Sample_000000.2001100101.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 
          CRS HDF data file.  An example of a metadata parameter found 
          in the metadata file and on the CRS HDF file is LOCALGRANULEID, 
          which has a value set to the original granule file name.

        4)'CRS_HDFread.h' is a header file for 'CRS_readhdf.c' 
          and the CRS HDF read functions.

        5)'CRS_readHDFfuncs.c' is a file consisting of C functions that
          are linked with 'CRS_readhdf.c' and call the HDF functions.

        6)'CRS_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 CRS 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_CRS_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] <HDF file name> - lists information about
                      the SDSs found on the specified file
          hdp dumpvd  [-options] <HDF file name> - lists information about
                      the Vdatas found on the specified file

    3.4 Data Format

        The CRS data files are written in HDF as collections of SDS(s) and 
        Vdata(s).

    3.5 Breakdown of the File Naming Convention

        The CRS data granules adhere to the following CERES file
        naming convention:

                  CER_PID_SS_PS_CC.DataDate

        where: CER = the CERES experiment

               PID = the CERES product, e.g., CRS

                SS = the CERES sampling strategy, e.g.,
                     Terra-FM2-MODIS, as defined by the CERES experiment.
                     For the CRS, this indicates the satellite and
                     instruments that were the source of the input
                     data into the software system that produced
                     the CRS data.

                PS = the CERES production strategy, e.g.,
                     'Beta2', as defined by the CERES experiment.
                     'BetaN' production strategies indicate versions
                     of the product produced with algorithms that
                     are still being validated.  CRS data products
                     with BetaN production strategies may only be
                     available for a limited time and cannot be
                     be used to publish. CRS data products with
                     'EditionN' 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 CERES experiment.
                     This code is internal to the CERES 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 CRS
                     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 CRS, 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 CRS 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 CRS product and the number of data records contained
     on an actual CRS file are large, the sample software only 
     demonstrates reading a limited number of SDSs for the five
     footprints included in the sample CRS file.  The contents of
     the CRS footprint, along with a list of all the SDS(s) contained
     on the CRS 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 CRS read program to 
     read different CRS parameters, the user should first compile and 
     run the CRS read program using the sample CRS 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 CRS sample dump file,
     'CER_CRS_Terra-FM2-MODIS_Sample_000000.2001100101.dump'.
     If this test is successful, then the user should modify the 
     the CRS read program or their own software to read the parameters 
     in which they are interested and run that software using the Sample 
     CRS 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 CRS 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_CRS_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_CRS_readhdf

          A line similar to the following will be displayed:

          -rwxr--r--  1 OWNER  GROUP 1450 Mar 6 14:49 compile_CRS_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_CRS_readhdf

       3. Execute the script 'compile_CRS_readhdf' to create the
          executable crs_rd by typing at the command line:


           > source compile_CRS_readhdf

          or, on some systems, type:

           > compile_CRS_readhdf


    6.2 How to Run the Sample Read Software

        Execute crs_rd by typing at the command line:

             > crs_rd CER_CRS_Terra-FM2-MODIS_Sample_000000.2001100101


 7.0 Sample Output


The following is the screen output generated from executing the crs_rd
program with the provided sample file.


> ./crs_rd CER_CRS_Terra-FM2-MODIS_Sample_000000.2001100101

Name of HDF file to be read:
< CER_CRS_Terra-FM2-MODIS_Sample_000000.2001100101



*********************************************************
*    Example 1:                                         *
*********************************************************

Footprint 1

Photosynthetically active radiation over surface = 73.684990

Footprint 2

Photosynthetically active radiation over surface = 115.411194

Footprint 3

Photosynthetically active radiation over surface = 119.516678

Footprint 4

Photosynthetically active radiation over surface = 123.762253

Footprint 5

Photosynthetically active radiation over surface = 129.438751


*********************************************************
*    Example 2:                                         *
*********************************************************

Footprint 1

Aerosol constituency flags(1) = 24016030
Aerosol constituency flags(2) = 25006010
Aerosol constituency flags(3) = 18847036
Aerosol constituency flags(4) = 1000005
Aerosol constituency flags(5) = 11022035
Aerosol constituency flags(6) = 10100038
Aerosol constituency flags(7) = 9000038

Footprint 2

Aerosol constituency flags(1) = 24016030
Aerosol constituency flags(2) = 25006010
Aerosol constituency flags(3) = 18847036
Aerosol constituency flags(4) = 1000005
Aerosol constituency flags(5) = 11022035
Aerosol constituency flags(6) = 10100038
Aerosol constituency flags(7) = 9000038

Footprint 3

Aerosol constituency flags(1) = 24023030
Aerosol constituency flags(2) = 25008010
Aerosol constituency flags(3) = 18805036
Aerosol constituency flags(4) = 1000005
Aerosol constituency flags(5) = 11028035
Aerosol constituency flags(6) = 10126038
Aerosol constituency flags(7) = 9000038

Footprint 4

Aerosol constituency flags(1) = 24023030
Aerosol constituency flags(2) = 25008010
Aerosol constituency flags(3) = 18805036
Aerosol constituency flags(4) = 1000005
Aerosol constituency flags(5) = 11028035
Aerosol constituency flags(6) = 10126038
Aerosol constituency flags(7) = 9000038

Footprint 5

Aerosol constituency flags(1) = 24023030
Aerosol constituency flags(2) = 25008010
Aerosol constituency flags(3) = 18805036
Aerosol constituency flags(4) = 1000005
Aerosol constituency flags(5) = 11028035
Aerosol constituency flags(6) = 10126038
Aerosol constituency flags(7) = 9000038


*********************************************************
*    Example 3:                                         *
*********************************************************

Footprint 1

Percentiles of visible optical depth for cloud layer 
Percentile 1 for Lower Layer = 3.090291
Percentile 1 for Upper Layer = 0.607926
Percentile 2 for Lower Layer = 3.090291
Percentile 2 for Upper Layer = 0.623101
Percentile 3 for Lower Layer = 3.090291
Percentile 3 for Upper Layer = 0.665449
Percentile 4 for Lower Layer = 3.160731
Percentile 4 for Upper Layer = 0.738107
Percentile 5 for Lower Layer = 3.160731
Percentile 5 for Upper Layer = 0.798151
Percentile 6 for Lower Layer = 3.323212
Percentile 6 for Upper Layer = 0.840746
Percentile 7 for Lower Layer = 3.323212
Percentile 7 for Upper Layer = 0.865967
Percentile 8 for Lower Layer = 3.669725
Percentile 8 for Upper Layer = 0.886713
Percentile 9 for Lower Layer = 3.702814
Percentile 9 for Upper Layer = 0.913339
Percentile 10 for Lower Layer = 3.702814
Percentile 10 for Upper Layer = 0.967665
Percentile 11 for Lower Layer = 3.827324
Percentile 11 for Upper Layer = 1.172163
Percentile 12 for Lower Layer = 3.827324
Percentile 12 for Upper Layer = 1.194814
Percentile 13 for Lower Layer = 3.827324
Percentile 13 for Upper Layer = 1.257099

Footprint 2

Percentiles of visible optical depth for cloud layer 
Percentile 1 for Lower Layer = 3.160731
Percentile 1 for Upper Layer = 0.424145
Percentile 2 for Lower Layer = 3.160731
Percentile 2 for Upper Layer = 0.584905
Percentile 3 for Lower Layer = 3.160731
Percentile 3 for Upper Layer = 0.632624
Percentile 4 for Lower Layer = 3.160731
Percentile 4 for Upper Layer = 0.675495
Percentile 5 for Lower Layer = 3.168009
Percentile 5 for Upper Layer = 0.738107
Percentile 6 for Lower Layer = 3.168009
Percentile 6 for Upper Layer = 0.795196
Percentile 7 for Lower Layer = 3.315473
Percentile 7 for Upper Layer = 0.822367
Percentile 8 for Lower Layer = 3.315473
Percentile 8 for Upper Layer = 0.857506
Percentile 9 for Lower Layer = 3.669725
Percentile 9 for Upper Layer = 0.899631
Percentile 10 for Lower Layer = 3.669725
Percentile 10 for Upper Layer = 0.967370
Percentile 11 for Lower Layer = 3.827324
Percentile 11 for Upper Layer = 1.118129
Percentile 12 for Lower Layer = 3.827324
Percentile 12 for Upper Layer = 1.192195
Percentile 13 for Lower Layer = 3.827324
Percentile 13 for Upper Layer = 1.257099

Footprint 3

Percentiles of visible optical depth for cloud layer 
Percentile 1 for Lower Layer = 0.489349
Percentile 1 for Upper Layer = 0.424145
Percentile 2 for Lower Layer = 0.489349
Percentile 2 for Upper Layer = 0.505649
Percentile 3 for Lower Layer = 0.508105
Percentile 3 for Upper Layer = 0.541235
Percentile 4 for Lower Layer = 0.515958
Percentile 4 for Upper Layer = 0.588517
Percentile 5 for Lower Layer = 0.519933
Percentile 5 for Upper Layer = 0.636103
Percentile 6 for Lower Layer = 0.578260
Percentile 6 for Upper Layer = 0.677702
Percentile 7 for Lower Layer = 0.579179
Percentile 7 for Upper Layer = 0.733393
Percentile 8 for Lower Layer = 0.597049
Percentile 8 for Upper Layer = 0.790235
Percentile 9 for Lower Layer = 0.612633
Percentile 9 for Upper Layer = 0.832468
Percentile 10 for Lower Layer = 0.619928
Percentile 10 for Upper Layer = 0.892121
Percentile 11 for Lower Layer = 0.668977
Percentile 11 for Upper Layer = 1.124277
Percentile 12 for Lower Layer = 0.679953
Percentile 12 for Upper Layer = 1.225360
Percentile 13 for Lower Layer = 0.679953
Percentile 13 for Upper Layer = 3.669725

Footprint 4

Percentiles of visible optical depth for cloud layer 
Percentile 1 for Lower Layer = 0.468898
Percentile 1 for Upper Layer = 0.424145
Percentile 2 for Lower Layer = 0.489349
Percentile 2 for Upper Layer = 0.426124
Percentile 3 for Lower Layer = 0.494110
Percentile 3 for Upper Layer = 0.505649
Percentile 4 for Lower Layer = 0.510434
Percentile 4 for Upper Layer = 0.548802
Percentile 5 for Lower Layer = 0.519933
Percentile 5 for Upper Layer = 0.579436
Percentile 6 for Lower Layer = 0.536402
Percentile 6 for Upper Layer = 0.623109
Percentile 7 for Lower Layer = 0.565042
Percentile 7 for Upper Layer = 0.646220
Percentile 8 for Lower Layer = 0.579179
Percentile 8 for Upper Layer = 0.681160
Percentile 9 for Lower Layer = 0.597049
Percentile 9 for Upper Layer = 0.718963
Percentile 10 for Lower Layer = 0.601603
Percentile 10 for Upper Layer = 0.790235
Percentile 11 for Lower Layer = 0.619928
Percentile 11 for Upper Layer = 0.857290
Percentile 12 for Lower Layer = 0.668977
Percentile 12 for Upper Layer = 0.928477
Percentile 13 for Lower Layer = 0.679953
Percentile 13 for Upper Layer = 0.980604

Footprint 5

Percentiles of visible optical depth for cloud layer 
Percentile 1 for Lower Layer = 0.408507
Percentile 1 for Upper Layer = 340282346638528860000000000000000000000.000000
Percentile 2 for Lower Layer = 0.468898
Percentile 2 for Upper Layer = 340282346638528860000000000000000000000.000000
Percentile 3 for Lower Layer = 0.494110
Percentile 3 for Upper Layer = 340282346638528860000000000000000000000.000000
Percentile 4 for Lower Layer = 0.515958
Percentile 4 for Upper Layer = 340282346638528860000000000000000000000.000000
Percentile 5 for Lower Layer = 0.536402
Percentile 5 for Upper Layer = 340282346638528860000000000000000000000.000000
Percentile 6 for Lower Layer = 0.571457
Percentile 6 for Upper Layer = 340282346638528860000000000000000000000.000000
Percentile 7 for Lower Layer = 0.586729
Percentile 7 for Upper Layer = 340282346638528860000000000000000000000.000000
Percentile 8 for Lower Layer = 0.608916
Percentile 8 for Upper Layer = 340282346638528860000000000000000000000.000000
Percentile 9 for Lower Layer = 0.629334
Percentile 9 for Upper Layer = 340282346638528860000000000000000000000.000000
Percentile 10 for Lower Layer = 0.658407
Percentile 10 for Upper Layer = 340282346638528860000000000000000000000.000000
Percentile 11 for Lower Layer = 0.720721
Percentile 11 for Upper Layer = 340282346638528860000000000000000000000.000000
Percentile 12 for Lower Layer = 0.761722
Percentile 12 for Upper Layer = 340282346638528860000000000000000000000.000000
Percentile 13 for Lower Layer = 0.801018
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:                                         *
*********************************************************

NUMFOV = 5


8.0 Additional Information Regarding CERES CRS Data



     Last Updated: May 31, 2007
-----------------------------------------------------------------------------