********************************************************************************
*                                                                              *
*              Readme file for V4 MOPITT MOP02 Data Set                        *
*                                                                              *
********************************************************************************

1.0 Introduction

     This file contains information about the sample read software and data 
files for the Measurements Of Pollution In The Troposphere (MOPITT) project. 
This software will read the data set:

     MOPITT Level 2 (MOP02)
 
1.1 Purpose

    The purpose of this read software is to extract data from a MOPITT 
Level 2 (MOP02) HDF-EOS file and write the data out to an ASCII file. Very 
basic subsetting is implemented by specifying the minimum and maximum values 
for latitude and longitude.

1.2 Contents of Document

    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


2.0 Data Set Description 

    The MOPITT Level 2 data are written in the HDF-EOS data format. The
read software is written in the IDL language. The IDL language supports 
the HDF-EOS format. 

   Information about MOPITT Level 2 files can be found at:

   http://eosweb.larc.nasa.gov/PRODOCS/mopitt/table_mopitt.html

   More information about HDF-EOS can be found in the online IDL documentation 
on Scientific Data Formats. Also there is a web site at: 

   http://hdfeos.org/

    NCSA's (National Center for Supercomputing Applications) HDF 
(Hierarchical Data Format) libraries are required to build any C or Fortran 
read software. These libraries can be obtained via anonymous ftp from 
ftp.ncsa.uiuc.edu or via the World Wide Web at http://hdf.ncsa.uiuc.edu. 

2.1 Instrumentation Description

    Information about the MOPITT instrument can be found at:

    http://eosweb.larc.nasa.gov/PRODOCS/mopitt/table_mopitt.html

2.2 Data Quality

    Data quality information about these data products can be found at: 

    http://eosweb.larc.nasa.gov/PRODOCS/mopitt/table_mopitt.html

2.3 Science Contact

    Comments or questions should be directed to:

           NASA Langley Atmospheric Science Data Center
           Science, Users and Data Services Office
           NASA Langley Research Center
           Mail Stop 157D
           2 South Wright Street
           Hampton, Virginia 23681-2199
           U.S.A.

           E-mail:   larc@eos.nasa.gov
           Phone:    (757)864-8656
           FAX:      (757)864-8807

    Additional info may be obtained by contacting the MOPITT Data Manager: 

           Dallas Masters
           National Center for Atmospheric Research (NCAR)
           PO Box 3000
           Boulder, Colorado 80307-3000
           U.S.A.

           E-mail:   mastersd@ucar.edu
           Phone:    (303) 497-2924
           FAX:      (303) 497-2920

3.0 Format and Packaging

    The following files are required:
         mop02_v4_1.pro         Main IDL source code 
         mop02_fields.dat       Required table describing each field  
         path_sep.pro		Subroutine for getting path seperator

    The mop02_fields.dat file must be in the same directory as 
the IDL program. So must path_sep.pro for IDL 5.3 & 5.4. IDL 5.5
already has path_sep.pro available.

Tested with IDL 5.3 on SGI IRIX, IDL 5.4 on Sun Solaris, and IDL 5.5
on a PC running Windows. 

    The file naming convention is as follows:

        MOP02-YYYYMMDD-L2VN.N.N.hdf

        where YYYY is the year,
              MM is the month,
              DD is the day, 
              and N.N.N is the version. 

        For example, MOP02-20040501-L2V8.0.2.hdf is a MOPITT Level 2
file for May 1, 2004 Version 8.0.2

4.0 Science Parameters Information

    Information about the MOPITT science parameters can be found at:

    http://eosweb.larc.nasa.gov/PRODOCS/mopitt/table_mopitt.html


5.0 Description of Sample Read Software

    The software written in mop02_v4_1.pro is an IDL application
that opens an HDF-EOS file and extracts the field data. The IDL program 
was developed and tested using IDL 5.3 on an SGI system. Information 
about IDL can be obtained at the ITT Visual Information Solutions web site at:
 
          http://www.ittvis.com/

    To read a swath from an HDF-EOS file the following steps occur: 

          Open the file
          Attach to the swath
          Get the field info
          Read the field  
          Detach the swath
          Close the file

    The code can process only a single file at a time. 

    The sample read program utilizes a graphical user interface (GUI)
to prompt the user for various data selections. This program prompts 
the user for the input file name using a file dialog box. It then puts 
up a dialog box that asks for the latitude/longitude range and the 
output directory. Finally the program prompts the user for which 
parameter(s) he wants to export. With all these inputs the program 
then creates an ASCII file with these parameters selected.

    The sample software allows the user to select almost any parameter
from the MOPITT data file. Additional data can be extracted from the 
MOPITT file. More information about the MOPITT file specification can be
found at: 

    http://www.acd.ucar.edu/mopitt/file_spec.html.

There is a file called, mop02_fields.dat that contains all of the table
information for all parameters in the data file.  The contents
are as follow:

+=available,*=permanent,-=not available|Field Name|Num Col|Column(s) Annotation
-------------------------------------------------------------------------------
+|Surface Pressure|1|surf Pres hPa
+|Retrieved Surface Emissivity|1|surf Emis
+|Retrieved Surface Temperature|1|surf Temp K
+|Retrieved CO Total Column|1|CO TC mol/cm2
+|Retrieved CO Mixing Ratio Profile|9|900 hPa|800 hPa|700 hPa|600 hPa|500 hPa|400 hPa|300 hPa|200 hPa|100 hPa
+|Retrieved CO Surface Mixing Ratio|1|surf CO Mix ppbv
-|Pressure Grid|0
*|Time|1|TAI Time
*|Latitude|1|Latitude
*|Longitude|1|Longitude
*|Seconds in Day|1|Time of Day
+|A Priori Surface Emissivity|1|AP surf Emis
+|A Priori Surface Temperature|1|AP surf Temp K
+|A Priori CO Mixing Ratio Profile|9|900 hPa|800 hPa|700 hPa|600 hPa|500 hPa|400 hPa|300 hPa|200 hPa|100 hPa
+|A Priori CO Surface Mixing Ratio|1|AP surf CO Mix ppbv
+|Solar Zenith Angle|1|Sol ZA deg
+|Satellite Zenith Angle|1|Sat ZA deg
+|Cloud Description|1|Cloud
+|Degrees of Freedom for Signal|1|DFS
+|Surface Index|1|surf Ind
-|coremetadata.0|0

Each column is separated by the pipe symbol, "|".  The first column
represents which science parameters are displayed in the selection
portion of the sample read software.  The second column represents
the name of the science parameter that is shown in the selection
portion of the sample read software.  The third column represents
how man follow on columns there will be in the output text file
representing the parameter as well as the column heading.

For example:
+|Surface Pressure|1|surf Pres hPa

This is the first item in the mop02_fields.dat file.  The plus sign
informs the code, Yes, data are available for this parameter.
The name of the science parameter that is displayed in column two
is called Surface Pressure.  The third column has
a three "1" in its position.  This means that there will be one
columns of data representing this science parameter in the 
output file.  The column that will appear in the output
file is "surf Pres hPa".


6.0 Implementing Sample Read Software

    The read software was written in IDL.

6.1 How to build the Sample Read Software  

    External Routines:  none
    Internal Routines:  Uses the IDL HDF-EOS library functions
    Language/Compiler Version:  IDL Version 7.1
    Code Files:  mop02_v4_1.pro, mop02_fields.dat, path_sep.pro

    From the command line, type the following commands to
    launch IDL and then to compile the code:

          commandline>   idl
          IDL> .compile mop02_v4_1.pro
          % Compiled module: READ_FIELDS.
          % Compiled module: ELAPSED_TIME.
          % Compiled module: FIND_INDEX.
          % Compiled module: SELECT_REGION.
          % Compiled module: SELECT_REGION_EVENT.
          % Compiled module: SELECT_PARAMETERS.
          % Compiled module: SELECT_PARAMETERS_EVENT.
          % Compiled module: MOP02_V4_1.

 
6.2 How to Run the Sample Read Software

    Note: For Unix machines the user must have X-Windows
          up and running in order for the user interface
          to appear.

    Invoke IDL then enter:

          idl> mop02_v4_1

    At execution time, an IDL window will appear on the screen
with the current directoy.  This is the time the user should
select the data file he wishes to extract the data from.
Only one file at a time can be selected.

    Once the file has been selected, a new window will appear
for the user to identify the geolocation (latitude and longitude
ranges) of the data as well as where to create the output
text file.

    Finally, the last window will appear.  At this time, the 
user is able to select 1 or 2 parameters to output to this
text file.  Once the user has pressed the Ok button, the code
will begin to generate the output file.  This process will 
take a few seconds.

7.0 Sample Output

    The output from the program is an ASCII file placed in the output
directory specified by the user during data entry.

    The output file name will match the input file name but with the
extension ".txt" at the end instead of ".hdf". This way the source 
file is always known.

    The format of the output file depends on which parameters are selected.
For example, an input file with "CO Total Column" as the single parameter
would give the following results:

       *** MOPITT Example Program ***
          TAI Time          Time of Day Latitude Longitude    CO TC mol/cm2
          226209297.0970000 03:54:52.09 20.7296  -77.03265    1.698E+18
          226209297.0970000 03:54:52.09 20.4999  -77.00012    1.994E+18

       The units are:
          TAI Time - Seconds since Jan 1, 1993 00Z
          Time of Day - hh:mm:ss.ss
          Latitude - degrees
          Longitude - degrees
          CO Total Column - molecules cm-2



Last Updated: August 31, 2009

