Skip to content. | Skip to navigation

Personal tools

README_Grid_Reader_MATLAB.txt

NAME OF THIS FILE:
README_Grid_Reader_MATLAB

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

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 MATLAB 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.m

FUNCTION USAGE:
buffer = read_airs_grid(filename,content_flag,content_list,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.

The following arguments should be specified as empty [] if no actual values are being provided.

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

RETURN VALUE:
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 a generic MATLAB data structure in which each member
has a "name" and a "data" component, which are actual data values.

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

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

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

...should produce the following status message:

buffer =
ascending,descending,ascending_MW_only,descending_MW_only,location

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

STEP 6: Get a list of all the dimension names and sizes within the first grid in the file:
MATLAB > content_flag = 1;
MATLAB > buffer = read_airs_grid(filename,content_flag,content_list,grid_list{1});

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

... should produce the following status message:

buffer =

TempPrsLvls: 24
H2OPrsLvls: 12
EmisLvls: 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:
MATLAB > content_flag = 2;
MATLAB > buffer = read_airs_grid(filename,content_flag,content_list,grid_list{1});
Message -> ERROR - The ascending grid has no attrbutes.

MATLAB > buffer = read_airs_grid(filename,content_flag,content_list,grid_list{2});
Message -> ERROR - The descending grid has no attrbutes.

MATLAB > buffer = read_airs_grid(filename,content_flag,content_list,grid_list{3});
Message -> ERROR - The ascending_MW_only grid has no attrbutes.

MATLAB > buffer = read_airs_grid(filename,content_flag,content_list,grid_list{4});
Message -> ERROR - The descending_MW_only grid has no attrbutes.

MATLAB > buffer = read_airs_grid(filename,content_flag,content_list,grid_list{5})

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

... should produce the following status message:

buffer =

Year: [2007 0 0 0]
Month: [3 0 0 0]
Day: [13 0 0 0]
NumOfDays: [1 0 0 0]
AscendingGridStartTimeUTC: '2007-03-13T01:30:00.000000Z '
AscendingGridEndTimeUTC: '2007-03-14T01:29:59.999999Z '
DescendingGridStartTimeUTC: '2007-03-12T13:30:00.000000Z '
DescendingGridEndTimeUTC: '2007-03-13T13:29:59.999999Z '
TempPresLvlNum: [24 0 0 0]
TempPresLvls: [1x96 single]
H2OPresLvlNum: [12 0 0 0]
H2OPresLvls: [1x48 single]
IREmisFreqs: [832 961 1203 2616 0 0 0 0 0 0 0 0 0 0 0 0]
MWEmisFreqs: [23.8000 50.3000 89 0 0 0 0 0 0 0 0 0]

STEP 10: Get a list of all the parameter names within one grid in the file.
MATLAB > content_flag = 4;
MATLAB > buffer = read_airs_grid(filename,content_flag,content_list,grid_list{1});
MATLAB > buffer

... should produce the following status message:

buffer =

'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
MATLAB > param_list = buffer;

STEP 12: Get the value of all the parameter names within one grid in the file.
MATLAB > content_flag = 3;
MATLAB > buffer = read_airs_grid(filename,content_flag,content_list,grid_list{1});

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

... should produce the following status message:


buffer =

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

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.

MATLAB > content_flag = 3;
MATLAB > content_list = {param_list{11},param_list{12}};
MATLAB > buffer = read_airs_grid(filename,content_flag,content_list,grid_list{1});

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

... should produce the following status message:

buffer =

SurfAirTemp_A: [360x180 single]
SurfAirTemp_A_ct: [360x180 int16]


STEP 16: To access specific data values within "buffer", use the following convention:
MATLAB > buffer.SurfAirTemp_A(2,3:5)

... should produce the following status message:


ans =

-9999 261.375 257.75

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