Skip to content. | Skip to navigation

Personal tools

README_Swath_Reader_IDL.txt

README_Swath_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 1 and 2 (a.k.a. data swath) data files produced by the NASA
Atmospheric Infrared Sounder (AIRS) project.

APPLICABLE INSTRUMENTs:

Atmospheric Infrared Sounder (AIRS)
Advanced Microwave Sounding Unit-A (AMSU-A)
Humidity Sounder for Brazil (HSB)

APPLICABLE DATA FILE TYPES:

* Level 1 - Data products that include calibrated and geo-located radiances for each instrument.

* Level 2 - Data products that describe geophysical properties such as atmospheric temperature profiles.

DATA FILE ASSUMPTIONS

The fundamental unit of data is the "granule file" which covers a period of exactly 6.0 minutes.
The granule file is further specified by both an instrument type and a file type (level).
Individual data sets are then grouped together into one or more data "swaths" within each file.

Each data swath has three main characteristics: dimensions, attributes and data fields. The
dimension set describes the physical limits or boundaries of the data as a series of directions
and scale (i.e., maximum number of points on a side). The attributes of a data swath describe
the data collection circumstances of a data swath (e.g., time, latitude/longitude for each scan).
The data fields (and field names) describe the individual science measurements. These values
can be provided at the "original" time resolution (e.g. one measurement per scan) or they can be
statistical summaries (e.g. mean, maximum, minimum) expressed as one value for an entire scan.
For a full 6.0 minute granule file, the AIRS and HSB swaths each contain 135 scans per granule file.
For a full 6.0 minute granule file, the AMSU-A data swath contains 45 scans.


DATA EXTRACTION GUIDELINES

FUNCTION NAME:

read_airs_swath.pro

USAGE:

status = read_airs_swath(filename,content_flag,buffer,[content_list=content_list],[swathname=swathname])

INPUT ARGUMENTS:

filename - The fully qualified path to a Level 1/2 EOS-HDF swath format granule file.

content_flag - An integer (0-4) that specifies the type of data to be extracted, as follows:
0: A cell array of the names of all swaths in the specified file.
1: The name and values of the swath's dimension parameters.
2: The name and values of the swath's attribute parameters.
3: The name and values of the swath's data field parameters.
4: A cell array of the names of all parameters in a specific swath.

INPUT ARGUMENTS[OPTIONAL]:

content_list - An array of names for the content items to be returned. If left unspecified,
the function will return ALL the parameters in that content category.

swathname - A text expression for the data swath within the granule file that is to be
examined. This function will only process one data swath at a time. In the
(typical) case that there is only ONE data swath in the granule file, this
argument can be left unspecified.

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 String array of all the swath names within a file.
If Option 4 is used, buffer will be a cell array of all the parameter names within a specified swath.
ed_airs_swath.pro
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 VALUES:

status - where "0" means success and "-1" means failure.

SIDE EFFECTS:
None.

NOTE: For the content_list default option (all parameters), the list of parameter names includes
both the geo-location parameters as wella s the science data parameters.

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

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

USAGE EXAMPLES:

Consider the following Level 2 file as one of the standard products created for the data set on September 6, 2002.
The data are based on the standard retrieval method of both AIRS and AMSU-A observations processed by the AIRS
data product software version 2.7.11.2.

AIRS.2002.09.06.176.L2.RetStd.v2.7.11.2.Focus3.T03023212802

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_swath.pro

... should produce the following status message:

% Compiled module: READ_AIRS_SWATH.

STEP 3: Specify the filename to be used:

IDL> filename = 'AIRS.2002.09.06.176.L2.RetStd.v2.7.11.2.Focus3.T03023212802'

STEP 4: Get a list of all the swaths within this file:

IDL > content_flag = 0
IDL > status = read_airs_swath(filename,content_flag,buffer)
IDL > print, buffer

...should produce the following status message:

L2_Standard_atmospheric&surface_product

STEP 5: To save the swath list for later use, type
IDL > swath_list = buffer

STEP 6: Get a list of all the dimension names and sizes within the first swath in the file:
IDL > content_flag = 1
IDL > status = read_airs_swath(filename,content_flag,buffer,swathname=swath_list[0])

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

IDL > help,buffer,/struct

... should produce the following status message:

** Structure <240198>, 12 tags, length=48, data length=48, refs=1:
GEOXTRACK LONG 30
GEOTRACK LONG 45
STDPRESSURELEV LONG 28
STDPRESSURELAY LONG 28
AIRSXTRACK LONG 3
AIRSTRACK LONG 3
CLOUD LONG 2
CHANAMSUA LONG 15
CHANHSB LONG 5
MWHINGESURF LONG 7
HINGESURF LONG 100
ETA LONG 9

STEP 8: Get a list of all the attribute names within each swath in the file. In this case there is only one swath:

IDL > content_flag = 2
IDL > status = read_airs_swath(filename,content_flag,buffer,swathname=swath_list[0])

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

IDL > help,buffer,/struct

... should produce the following status message:

** Structure <2b39f8>, 50 tags, length=296, data length=284, refs=1:
PROCESSING_LEVEL STRING 'level2'
INSTRUMENT STRING 'AIRS'
DAYNIGHTFLAG STRING 'Day'
AUTOMATICQAFLAG STRING 'Suspect'
NUMTOTALDATA LONG Array[1]
NUMPROCESSDATA LONG Array[1]
NUMSPECIALDATA LONG Array[1]
NUMBADDATA LONG Array[1]
NUMMISSINGDATA LONG Array[1]
NUMLANDSURFACE LONG Array[1]
NUMOCEANSURFACE LONG Array[1]
NODE_TYPE STRING 'Ascending'
START_YEAR LONG Array[1]
START_MONTH LONG Array[1]
START_DAY LONG Array[1]
START_HOUR LONG Array[1]
START_MINUTE LONG Array[1]
START_SEC FLOAT Array[1]
START_ORBIT LONG Array[1]
END_ORBIT LONG Array[1]
ORBIT_PATH LONG Array[1]
START_ORBIT_ROW LONG Array[1]
END_ORBIT_ROW LONG Array[1]
GRANULE_NUMBER LONG Array[1]
NUM_SCANSETS LONG Array[1]
NUM_SCANLINES LONG Array[1]
START_LATITUDE DOUBLE Array[1]
START_LONGITUDE DOUBLE Array[1]
START_TIME DOUBLE Array[1]
END_LATITUDE DOUBLE Array[1]
END_LONGITUDE DOUBLE Array[1]
END_TIME DOUBLE Array[1]
EQ_X_LONGITUDE FLOAT Array[1]
EQ_X_TAI DOUBLE Array[1]
ORBITGEOQA ULONG Array[4]
NUM_SATGEOQA INT Array[1]
NUM_GLINTGEOQA INT Array[1]
NUM_MOONGEOQA INT Array[1]
NUM_FTPTGEOQA INT Array[1]
NUM_ZENGEOQA INT Array[1]
NUM_DEMGEOQA INT Array[1]
NUM_FPE INT Array[1]
LONGRANULECEN INT Array[1]
LATGRANULECEN INT Array[1]
LOCTIMEGRANULECEN INT Array[1]
NUM_INVALID INT Array[1]
NUM_CLEAR_FLAG INT Array[1]
NUM_MW_RET_USED INT Array[1]
NUM_RETRIEVAL_TYPE INT Array[1]
GRANULES_PRESENT STRING ''

STEP 10: Get a list of all the parameter names within one swath in the file.
IDL > content_flag = 4
IDL > status = read_airs_swath(filename,content_flag,buffer,swathname=swath_list[0])
IDL > print, buffer

... should produce the following status message:

Latitude Longitude Time satheight satroll satpitch satyaw satgeoqa glintgeoqa moongeoqa ftptgeoqa ...
zengeoqa demgeoqa nadirTAI sat_lat sat_lon scan_node_type satzen satazi solzen solazi glintlat glintlon ...
sun_glint_distance topog topog_err landFrac landFrac_err pressStd latAIRS lonAIRS numHingeSurf numCloud ...
freqEmis PSurfStd nSurfStd TSurfStd TSurfAir TAirStd H2OMMRStd H2OMMRSat totH2OStd O3VMRStd totO3Std ...
emisIRStd rhoIRStd sfcTbMWStd EmisMWStd totCldH2OStd TCldTopStd PCldTopStd CldFrcStd CldClearParamStd ...
PSurfStdErr TSurfStdErr TAirStdErr H2OMMRStdErr totH2OStdErr O3VMRStdErr totO3StdErr emisIRStdErr ...
rhoIRStdErr EmisMWStdErr totCldH2OStdErr TCldTopStdErr PCldTopStdErr CldFrcStdErr CldClearParamStdErr ...
GP_Height GP_Surface clear_flag_4window invalid clear_flag MW_ret_used retrieval_type

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 swath in the file.
IDL > content_flag = 3
IDL > status = read_airs_swath(filename,content_flag,buffer,swathname=swath_list[0])

NOTE: The resulting parameter list combines geo-location and science data fields.

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

... should produce the following status message:

** Structure <2d9598>, 75 tags, length=4642632, data length=4642627, refs=1:
LATITUDE DOUBLE Array[30, 45]
LONGITUDE DOUBLE Array[30, 45]
TIME DOUBLE Array[30, 45]
SATHEIGHT FLOAT Array[45]
SATROLL FLOAT Array[45]
SATPITCH FLOAT Array[45]
SATYAW FLOAT Array[45]
SATGEOQA ULONG Array[45]
GLINTGEOQA UINT Array[45]
MOONGEOQA UINT Array[45]
FTPTGEOQA ULONG Array[30, 45]
ZENGEOQA UINT Array[30, 45]
DEMGEOQA UINT Array[30, 45]
NADIRTAI DOUBLE Array[45]
SAT_LAT DOUBLE Array[45]
SAT_LON DOUBLE Array[45]
SCAN_NODE_TYPE BYTE Array[45]
SATZEN FLOAT Array[30, 45]
SATAZI FLOAT Array[30, 45]
SOLZEN FLOAT Array[30, 45]
SOLAZI FLOAT Array[30, 45]
GLINTLAT FLOAT Array[45]
GLINTLON FLOAT Array[45]
SUN_GLINT_DISTANCE INT Array[30, 45]
TOPOG FLOAT Array[30, 45]
TOPOG_ERR FLOAT Array[30, 45]
LANDFRAC FLOAT Array[30, 45]
LANDFRAC_ERR FLOAT Array[30, 45]
PRESSSTD FLOAT Array[28]
LATAIRS FLOAT Array[3, 3, 30, 45]
LONAIRS FLOAT Array[3, 3, 30, 45]
NUMHINGESURF INT Array[30, 45]
NUMCLOUD LONG Array[30, 45]
FREQEMIS FLOAT Array[100, 30, 45]
PSURFSTD FLOAT Array[30, 45]
NSURFSTD LONG Array[30, 45]
TSURFSTD FLOAT Array[30, 45]
TSURFAIR FLOAT Array[30, 45]
TAIRSTD FLOAT Array[28, 30, 45]
H2OMMRSTD FLOAT Array[28, 30, 45]
H2OMMRSAT FLOAT Array[28, 30, 45]
TOTH2OSTD FLOAT Array[30, 45]
O3VMRSTD FLOAT Array[28, 30, 45]
TOTO3STD FLOAT Array[30, 45]
EMISIRSTD FLOAT Array[100, 30, 45]
RHOIRSTD FLOAT Array[100, 30, 45]
SFCTBMWSTD FLOAT Array[7, 30, 45]
EMISMWSTD FLOAT Array[7, 30, 45]
TOTCLDH2OSTD FLOAT Array[30, 45]
TCLDTOPSTD FLOAT Array[2, 30, 45]
PCLDTOPSTD FLOAT Array[2, 30, 45]
CLDFRCSTD FLOAT Array[2, 3, 3, 30, 45]
CLDCLEARPARAMSTD FLOAT Array[9, 30, 45]
PSURFSTDERR FLOAT Array[30, 45]
TSURFSTDERR FLOAT Array[30, 45]
TAIRSTDERR FLOAT Array[28, 30, 45]
H2OMMRSTDERR FLOAT Array[28, 30, 45]
TOTH2OSTDERR FLOAT Array[30, 45]
O3VMRSTDERR FLOAT Array[28, 30, 45]
TOTO3STDERR FLOAT Array[30, 45]
EMISIRSTDERR FLOAT Array[100, 30, 45]
RHOIRSTDERR FLOAT Array[100, 30, 45]
EMISMWSTDERR FLOAT Array[7, 30, 45]
TOTCLDH2OSTDERR FLOAT Array[30, 45]
TCLDTOPSTDERR FLOAT Array[2, 30, 45]
PCLDTOPSTDERR FLOAT Array[2, 30, 45]
CLDFRCSTDERR FLOAT Array[2, 3, 3, 30, 45]
CLDCLEARPARAMSTDERR FLOAT Array[9, 30, 45]
GP_HEIGHT FLOAT Array[28, 30, 45]
GP_SURFACE FLOAT Array[30, 45]
CLEAR_FLAG_4WINDOW FLOAT Array[3, 3, 30, 45]
INVALID BYTE Array[30, 45]
CLEAR_FLAG BYTE Array[30, 45]
MW_RET_USED BYTE Array[30, 45]
RETRIEVAL_TYPE BYTE Array[30, 45]

STEP 14: Get the value of a few selected parameters within one 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[34],param_list[35]]
IDL > status = read_airs_swath(filename,content_flag,buffer,content_list=content_list,swathname=swath_list[0])

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

... should produce the following status message:

** Structure <23c508>, 2 tags, length=10800, data length=10800, refs=1:
PSURFSTD FLOAT Array[30, 45]
NSURFSTD LONG Array[30, 45]

STEP 16: To access specific data values within "buffer", use the following convention:
IDL > print,buffer.PSurfStd[2,5:8]

... should produce the following status message:

1012.75
1012.68
1012.66
1012.67


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