Skip to content. | Skip to navigation

Personal tools



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

This README file describes a sample function in the Matrix Laboratory (MATLAB)
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.


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


* 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.


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.





buffer = read_airs_swath(filename,content_flag,content_list,swathname);


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.

The following arguments should be provided as an empty set [] if not containing an actual value.

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.


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 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.
If Option 1, 2, or 3 is used, "buffer" will be a generic MATLAB data structure in which each member
has a "name" and a "data" component, which are actual data values.

buffer - MATLAB data structure with fields of parameter name/parameter value.
Type "buffer" at the MATLAB command line for details.
The buffer structure will be empty ([]) if the function fails.
When the content_flag "0" and "4" options are used, buffer is a cell array.

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.


Consider the following Level 3 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


STEP 1: Start an MATLAB session by tying "matlab" at the command line prompt.

STEP 2: Verify that the routine is in your PATH by typing:
MATLAB > help read_airs_swath

... should display the first several lines of the comments section of the function.

STEP 3: Specify the filename to be used:
MATLAB> 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:
MATLAB > content_flag = 0;
MATLAB > buffer = read_airs_swath(filename,content_flag,[],[]);
MATLAB > buffer

...should produce the following status message:

buffer =

STEP 5: To save the list of swaths for later use, type
MATLAB > swath_list = buffer;

STEP 6: Get a list of all the dimension names and sizes within the first swath in the file:
MATLAB > content_flag = 1;
MATLAB > buffer = read_airs_swath(filename,content_flag,[],swath_list{1});

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

... should produce the following status message:

buffer =

GeoXTrack: 30
GeoTrack: 45
StdPressureLev: 28
StdPressureLay: 28
AIRSXTrack: 3
AIRSTrack: 3
Cloud: 2
ChanAMSUA: 15
ChanHSB: 5
MWHingeSurf: 7
HingeSurf: 100
Eta: 9

Which means that there are 45 footprintd in the GeoTrack directions, 30 footprints in the GeoXTrack
directions, 15 AMSU channels, ... 28 standard pressure layers, 28 standard preseeure levels, etc.

STEP 8: Get a list of all the attribute names within each swath in the file. Note that only that last swath actually has attributes:
MATLAB > content_flag = 2;
MATLAB > buffer = read_airs_swath(filename,content_flag,[],swath_list{1});
MATLAB > buffer

... should produce the following status message:

buffer =

processing_level: [7x1 char]
instrument: [5x1 char]
DayNightFlag: [4x1 char]
AutomaticQAFlag: [8x1 char]
NumTotalData: [4x1 int32]
NumProcessData: [4x1 int32]
NumSpecialData: [4x1 int32]
NumBadData: [4x1 int32]
NumMissingData: [4x1 int32]
NumLandSurface: [4x1 int32]
NumOceanSurface: [4x1 int32]
node_type: [10x1 char]
start_year: [4x1 int32]
start_month: [4x1 int32]
start_day: [4x1 int32]
start_hour: [4x1 int32]
start_minute: [4x1 int32]
start_sec: [4x1 single]
start_orbit: [4x1 int32]
end_orbit: [4x1 int32]
orbit_path: [4x1 int32]
start_orbit_row: [4x1 int32]
end_orbit_row: [4x1 int32]
granule_number: [4x1 int32]
num_scansets: [4x1 int32]
num_scanlines: [4x1 int32]
start_Latitude: [8x1 double]
start_Longitude: [8x1 double]
start_Time: [8x1 double]
end_Latitude: [8x1 double]
end_Longitude: [8x1 double]
end_Time: [8x1 double]
eq_x_longitude: [4x1 single]
eq_x_tai: [8x1 double]
orbitgeoqa: [4x1 uint32]
num_satgeoqa: [2x1 int16]
num_glintgeoqa: [2x1 int16]
num_moongeoqa: [2x1 int16]
num_ftptgeoqa: [2x1 int16]
num_zengeoqa: [2x1 int16]
num_demgeoqa: [2x1 int16]
num_fpe: [2x1 int16]
LonGranuleCen: [2x1 int16]
LatGranuleCen: [2x1 int16]
LocTimeGranuleCen: [2x1 int16]
num_invalid: [2x1 int16]
num_clear_flag: [2x1 int16]
num_MW_ret_used: [2x1 int16]
num_retrieval_type: [2x1 int16]
granules_present: ' '

STEP 10: Get a list of all the parameter names within one swath in the file.
MATLAB > content_flag = 4;
MATLAB > buffer = read_airs_swath(filename,content_flag,[],swath_list{1});
MATLAB > buffer' (print list in one column)

... should produce the following status message:

ans =


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

STEP 12: Get the value of all the parameter names within one swath in the file.
MATLAB > content_flag = 3;
MATLAB > buffer = read_airs_swath(filename,content_flag,[],swath_list{1});

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

... should produce the following status message:

buffer =

Latitude: [30x45 double]
Longitude: [30x45 double]
Time: [30x45 double]
satheight: [45x1 single]
satroll: [45x1 single]
satpitch: [45x1 single]
satyaw: [45x1 single]
satgeoqa: [45x1 uint32]
glintgeoqa: [45x1 uint16]
moongeoqa: [45x1 uint16]
ftptgeoqa: [30x45 uint32]
zengeoqa: [30x45 uint16]
demgeoqa: [30x45 uint16]
nadirTAI: [45x1 double]
sat_lat: [45x1 double]
sat_lon: [45x1 double]
scan_node_type: [45x1 int8]
satzen: [30x45 single]
satazi: [30x45 single]
solzen: [30x45 single]
solazi: [30x45 single]
glintlat: [45x1 single]
glintlon: [45x1 single]
sun_glint_distance: [30x45 int16]
topog: [30x45 single]
topog_err: [30x45 single]
landFrac: [30x45 single]
landFrac_err: [30x45 single]
pressStd: [28x1 single]
latAIRS: [4-D single]
lonAIRS: [4-D single]
numHingeSurf: [30x45 int16]
numCloud: [30x45 int32]
freqEmis: [100x30x45 single]
PSurfStd: [30x45 single]
nSurfStd: [30x45 int32]
TSurfStd: [30x45 single]
TSurfAir: [30x45 single]
TAirStd: [28x30x45 single]
H2OMMRStd: [28x30x45 single]
H2OMMRSat: [28x30x45 single]
totH2OStd: [30x45 single]
O3VMRStd: [28x30x45 single]
totO3Std: [30x45 single]
emisIRStd: [100x30x45 single]
rhoIRStd: [100x30x45 single]
sfcTbMWStd: [7x30x45 single]
EmisMWStd: [7x30x45 single]
totCldH2OStd: [30x45 single]
TCldTopStd: [2x30x45 single]
PCldTopStd: [2x30x45 single]
CldFrcStd: [5-D single]
CldClearParamStd: [9x30x45 single]
PSurfStdErr: [30x45 single]
TSurfStdErr: [30x45 single]
TAirStdErr: [28x30x45 single]
H2OMMRStdErr: [28x30x45 single]
totH2OStdErr: [30x45 single]
O3VMRStdErr: [28x30x45 single]
totO3StdErr: [30x45 single]
emisIRStdErr: [100x30x45 single]
rhoIRStdErr: [100x30x45 single]
EmisMWStdErr: [7x30x45 single]
totCldH2OStdErr: [30x45 single]
TCldTopStdErr: [2x30x45 single]
PCldTopStdErr: [2x30x45 single]
CldFrcStdErr: [5-D single]
CldClearParamStdErr: [9x30x45 single]
GP_Height: [28x30x45 single]
GP_Surface: [30x45 single]
clear_flag_4window: [4-D int8]
invalid: [30x45 int8]
clear_flag: [30x45 int8]
MW_ret_used: [30x45 int8]
retrieval_type: [30x45 int8]

STEP 14: Get the value of a few selected parameters within one swath in the file.
NOTE: Be sure to use the actual case-sensitive names of each parameter.
MATLAB > content_flag = 3;
MATLAB > content_list = {param_list{35},param_list{36}};
MATLAB > buffer = read_airs_swath(filename,content_flag,content_list,swath_list{1});

STEP 15: To see the structure of the buffer output, type
MATLAB > buffer

... should produce the following status message:

buffer =

PSurfStd: [30x45 single]
nSurfStd: [30x45 int32]

STEP 16: To access specific data values within "buffer", use the following convention:
MATLAB > buffer.PSurfStd(3,6:9)

... should produce the following status message:

ans =

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 Privacy Policy and Important Notices
Last updated: Sep 09, 2009 02:26 PM ET