Skip to content. | Skip to navigation

 Try out the New GES DISC site
Personal tools

README_Grid_Reader_IDL.txt

NAME OF THIS FILE:
README_Grid_Reader_IDL

AUTHOR AND CHANGE HISTORY:
Stephen Licata (SL)
Original version: on 03-17-2005.
Updated on 05-16-2007 by SL.
Full tutorial of data reading examples was added.

PURPOSE OF THIS FILE:
This README file describes a sample function in the Instrument Data Language (IDL)
programming language that allows the extraction of data from files written in the
Earth Observing System (EOS) Hierarchical Data Format (HDF) format.

The referenced code fragment (i.e., not a complete program) is offered free of charge to the public
to allow extraction of Level 3 (a.k.a. grid) data files produced by the NASA
Atmospheric Infrared Sounder (AIRS) project.

APPLICABLE INSTRUMENTS:
Atmospheric Infrared Sounder (AIRS)
Advanced Microwave Sounding Unit-A (AMSU-A)

APPLICABLE DATA FILE TYPES:
Level 3 - Data products in which parameters are binned into grids one degree square in lat/lon.

DESCRIPTION OF THE LEVEL 3 DATA FILE
The Level 3 data file is written in the Hierarchical Data Format (1). The IDL programming language
has many built-in routines that can open an HDF file and query not just its data contents but also
the embedded sets of descriptive data, such as the various parameter names and the dimensions of the
arrays in which they are stored.

(Ref. 1) http://en.wikipedia.org/wiki/Hierarchical_Data_Format)

Because the Level 3 data are intended to be laid in one-degree squares onto an Earth map projection
plot, most arrays measure 360 columns of longitude by 180 rows of latitude. In other words, there are
180 1.0 x 1.0 degree squares between the North Pole (90.0 degrees) down to the South Pole (-90.0 degrees).
There are then 360 squares around the globe at each latitude line parallel to the Equator.
The longitude convention is 0.0 to 180.0 degrees across the Eastern Hemisphere and 0.0 to -180.0 degrees
across the Western Hemisphere.

DATA FILE ASSUMPTIONS
Each data grid has three main characteristics: dimensions, attributes and data fields. The
grid dimensions are specified by name and a size(length). The attributes describe
the data collection circumstances of a data grid (e.g., time, latitude/longitude for each scan).
The data fields (and field names) describe the individual science measurements. These values
represent an average taken over a 1 x 1 degree area on the globe, with an averaged collection time.

FUNCTION BEING DESCRIBED:
read_airs_grid.pro

FUNCTION USAGE:
status = read_airs_grid(filename,content_flag,buffer,[content_list=content_list],gridname=gridname])

INPUT ARGUMENTS:
1. filename - The fully qualified path to a Level 3 granule EOS-HDF data file.

2. content_flag - An integer that specifies the type of data to be extracted, as follows:
0 - list the names of all data grids in the file.
1 - list the dimension names and sizes for ONE grid within the file.
2 - list the attribute names and values for ONE grid within the file.
3 - list the data field names and values for ONE grid within the file.
4 - list the names of all data fields within a specific grid in that file.

3. content_list [OPTIONAL] - An array of text strings which are the names of specific parameters
that will extracted per the content flag choice (Choices 1-3 only).
If content_list is left unspecified, the function will retrieve the content
on ALL items in the category specified by the content_flag.

4. gridname [OPTIONAL] - A single text expression which is the exact name of the data grid to
be extracted from the granule file. If gridname is left unspecified and there
is only one data grid in a file, that grid will automatically be used.
HINT: Run this function with the content_flag=0 option first if you suspect that
there are more than one data grid in a granule file (which is normally the case).

OUTPUTS:
The output of the data reading operation is dumped into a generic data structure called "buffer".
This is created by the data reading routine based on the above-mentioned "content_flag" options.
For example, if Option 0 is used, buffer will be a cell array of all the grid names within a file.
If Option 4 is used, buffer will be a cell array of all the parameter names within a specified grid.
If Option 1, 2, or 3 is used, "buffer" will be an anonymous IDL structure in which each member
has a "name" and a "data" component, which are actual data values.

RETURN VALUE:
The return value is "status", where a value of -1 indicates failure and 0 means success.


************** TUTORIAL FOR USING THIS FUNCTION ********************

Please work through all of the following steps to fully understand how to use this function.


WORKING EXAMPLES

Consider the following Level 3 file as one of the standard products created for the data set on March 13, 2007.
The data are based on the standard retrieval method of both AIRS and AMSU-A observations processed by the AIRS
data product software version 4.0.9.0.

AIRS.2007.03.13.L3.RetStd001.v4.0.9.0.G07074152508.hdf

STEP 1: Start an IDL session by tying "idl" at the command line prompt.

STEP 2: Compiling the file reader routine in IDL as follows:
IDL > .rn <full_path> read_airs_grid.pro

... should produce the following status message:

% Compiled module: READ_AIRS_GRID.

STEP 3: Specify the filename to be used:
IDL> filename = 'AIRS.2007.03.13.L3.RetStd001.v4.0.9.0.G07074152508.hdf'


STEP 4: Get a list of all the grids within this file:
IDL > content_flag = 0
IDL > status = read_airs_grid(filename,content_flag,buffer)
IDL > print, buffer

...should produce the following status message:

ascending,descending,ascending_MW_only,descending_MW_only,location

STEP 5: To save this grid list for later use, type
IDL > grid_list = buffer

STEP 6: Get a list of all the dimension names and sizes within the first grid in the file:
IDL > content_flag = 1
IDL > status = read_airs_grid(filename,content_flag,buffer,gridname=grid_list[0])

STEP 7: To see the structure of the buffer output, type
IDL > help,buffer,/struct

... should produce the following status message:

"** Structure <311d18>, 3 tags, length=12, data length=12, refs=1:
TEMPPRSLVLS LONG 24
H2OPRSLVLS LONG 12
EMISLVLS LONG 4

Which means that there are 24 temperature pressure levels, 12 H2O pressure levels, and 4 Emissivity levels.


STEP 8: Get a list of all the attribute names within each grid in the file. Note that only that last grid actually has attributes:
IDL > content_flag = 2
IDL > status = read_airs_grid(filename,content_flag,buffer,gridname=grid_list[0])
Message -> ERROR - The ascending grid has no attrbutes.

IDL > status = read_airs_grid(filename,content_flag,buffer,gridname=grid_list[1])
Message -> ERROR - The descending grid has no attrbutes.

IDL > status = read_airs_grid(filename,content_flag,buffer,gridname=grid_list[2])
Message -> ERROR - The ascending_MW_only grid has no attrbutes.

IDL > status = read_airs_grid(filename,content_flag,buffer,gridname=grid_list[3])
Message -> ERROR - The descending_MW_only grid has no attrbutes.

IDL > status = read_airs_grid(filename,content_flag,buffer,gridname=grid_list[4])

STEP 9: To see the structure of the buffer output, type
IDL > help,buffer,/struct

... should produce the following status message:

** Structure <23af98>, 14 tags, length=848, data length=848, refs=1:
YEAR LONG Array[4]
MONTH LONG Array[4]
DAY LONG Array[4]
NUMOFDAYS LONG Array[4]
ASCENDINGGRIDSTARTTIMEUTC STRING '2007-03-13T01:30:00.000000Z'
ASCENDINGGRIDENDTIMEUTC STRING '2007-03-14T01:29:59.999999Z'
DESCENDINGGRIDSTARTTIMEUTC STRING '2007-03-12T13:30:00.000000Z'
DESCENDINGGRIDENDTIMEUTC STRING '2007-03-13T13:29:59.999999Z'
TEMPPRESLVLNUM LONG Array[4]
TEMPPRESLVLS FLOAT Array[96]
H2OPRESLVLNUM LONG Array[4]
H2OPRESLVLS FLOAT Array[48]
IREMISFREQS FLOAT Array[16]
MWEMISFREQS FLOAT Array[12]

STEP 10: Get a list of all the parameter names within one grid in the file.
IDL > content_flag = 4
IDL > status = read_airs_grid(filename,content_flag,buffer,gridname=grid_list[0])
IDL > print, buffer

... should produce the following status message:

TotalCounts_A TotCldLiqH2O_A TotCldLiqH2O_A_ct TotCldLiqH2O_A_sdev TotH2OVap_A TotH2OVap_A_ct...
TotH2OVap_A_sdev TotO3_A TotO3_A_ct TotO3_A_sdev SurfAirTemp_A SurfAirTemp_A_ct SurfAirTemp_A_sdev ...
SurfSkinTemp_A SurfSkinTemp_A_ct SurfSkinTemp_A_sdev SurfPres_A SurfPres_A_ct SurfPres_A_sdev ...
OLR_A OLR_A_ct OLR_A_sdev ClrOLR_A ClrOLR_A_ct ClrOLR_A_sdev EmisIR_A EmisIR_A_ct EmisIR_A_sdev ...
GPHeight_A GPHeight_A_ct GPHeight_A_sdev CloudFrc_A CloudFrc_A_ct CloudFrc_A_sdev CloudTopPres_A ...
CloudTopPres_A_ct CloudTopPres_A_sdev RelHumid_A RelHumid_A_ct RelHumid_A_sdev H2OVapMMR_A ...
H2OVapMMR_A_ct H2OVapMMR_A_sdev Temperature_A Temperature_A_ct Temperature_A_sdev CloudFrcVis_A ...
CloudFrcVis_A_ct CloudFrcVis_A_sdev


STEP 11: To save this parameter list for later use, type
IDL > param_list = buffer

STEP 12: Get the value of all the parameter names within one grid in the file.
IDL > content_flag = 3
IDL > status = read_airs_grid(filename,content_flag,buffer,gridname=grid_list[0])

STEP 13: To see the structure of the buffer output, type

IDL > help,buffer,/struct

... should produce the following status message:

** Structure <8dc588>, 49 tags, length=56505600, data length=56505600, refs=1:
TOTALCOUNTS_A INT Array[360, 180]
TOTCLDLIQH2O_A FLOAT Array[360, 180]
TOTCLDLIQH2O_A_CT INT Array[360, 180]
TOTCLDLIQH2O_A_SDEV FLOAT Array[360, 180]
TOTH2OVAP_A FLOAT Array[360, 180]
TOTH2OVAP_A_CT INT Array[360, 180]
TOTH2OVAP_A_SDEV FLOAT Array[360, 180]
TOTO3_A FLOAT Array[360, 180]
TOTO3_A_CT INT Array[360, 180]
TOTO3_A_SDEV FLOAT Array[360, 180]
SURFAIRTEMP_A FLOAT Array[360, 180]
SURFAIRTEMP_A_CT INT Array[360, 180]
SURFAIRTEMP_A_SDEV FLOAT Array[360, 180]
SURFSKINTEMP_A FLOAT Array[360, 180]
SURFSKINTEMP_A_CT INT Array[360, 180]
SURFSKINTEMP_A_SDEV FLOAT Array[360, 180]
SURFPRES_A FLOAT Array[360, 180]
SURFPRES_A_CT INT Array[360, 180]
SURFPRES_A_SDEV FLOAT Array[360, 180]
OLR_A FLOAT Array[360, 180]
OLR_A_CT INT Array[360, 180]
OLR_A_SDEV FLOAT Array[360, 180]
CLROLR_A FLOAT Array[360, 180]
CLROLR_A_CT INT Array[360, 180]
CLROLR_A_SDEV FLOAT Array[360, 180]
EMISIR_A FLOAT Array[360, 180, 4]
EMISIR_A_CT INT Array[360, 180, 4]
EMISIR_A_SDEV FLOAT Array[360, 180, 4]
GPHEIGHT_A FLOAT Array[360, 180, 24]
GPHEIGHT_A_CT INT Array[360, 180, 24]
GPHEIGHT_A_SDEV FLOAT Array[360, 180, 24]
CLOUDFRC_A FLOAT Array[360, 180]
CLOUDFRC_A_CT INT Array[360, 180]
CLOUDFRC_A_SDEV FLOAT Array[360, 180]
CLOUDTOPPRES_A FLOAT Array[360, 180]
CLOUDTOPPRES_A_CT INT Array[360, 180]
CLOUDTOPPRES_A_SDEV FLOAT Array[360, 180]
RELHUMID_A FLOAT Array[360, 180, 12]
RELHUMID_A_CT INT Array[360, 180, 12]
RELHUMID_A_SDEV FLOAT Array[360, 180, 12]
H2OVAPMMR_A FLOAT Array[360, 180, 12]
H2OVAPMMR_A_CT INT Array[360, 180, 12]
H2OVAPMMR_A_SDEV INT Array[360, 180, 12]
TEMPERATURE_A FLOAT Array[360, 180, 24]
TEMPERATURE_A_CT FLOAT Array[360, 180, 24]
TEMPERATURE_A_SDEV FLOAT Array[360, 180, 24]
CLOUDFRCVIS_A FLOAT Array[360, 180]
CLOUDFRCVIS_A_CT INT Array[360, 180]
CLOUDFRCVIS_A_SDEV FLOAT Array[360, 180]

STEP 14: Get the value of a few selected parameters within one grid in the file.
NOTE: Be sure to use the actual case-sensitive names if you specify the parameters by name,
not the uppercase notation shown above in the "buffer" structure display message.
You may also just refer to the "param_list" array just created.

IDL > content_flag = 3
IDL > content_list = [param_list[10],param_list[11]]
IDL > status = read_airs_grid(filename,content_flag,buffer,content_list=content_list,gridname=grid_list[0])

STEP 15: To see the structure of the buffer output, type
IDL > help,buffer,/struct

... should produce the following status message:

** Structure <2749c8>, 2 tags, length=388800, data length=388800, refs=1:
SURFAIRTEMP_A FLOAT Array[360, 180]
SURFAIRTEMP_A_CT INT Array[360, 180]

STEP 16: To access specific data values within "buffer", use the following convention:
IDL > print,buffer.SurfAirTemp_A[1,2:4]

... should produce the following status message:

-9999.00
261.375
257.750

NOTE: The -9999.0 is a generic value for "bad data marker".

Document Actions
NASA Logo - nasa.gov
NASA Privacy Policy and Important Notices
Last updated: Sep 09, 2009 02:26 PM ET
Top