READ_CALIPSO and READ_CALIPSO_SUBSET documentation. 1.0 Introduction The file readers provided by the Calipso team allow you to read all fields in a specific file type. Given the size of some of these files, this may not be desirable. The IDL routines provided in this small set of routines allow selective reading of these files, selecting both on the fields, and on indices within a data-field. 2.0 Installation Copy the files into a location where IDL will find them. IDL can compile these routines on the fly (no prior compilation is needed). The routines have been tested with IDL version 6.4, but should work with at least 6.0 onwards. 3.0 Usage First we give a typical usage sample of the code, and then some more detailed instructions are given. 3.1 Example In this usage example we will read part of a day-side orbit of the vertical feature mask (VFM), selecting data between 10 and 15 degrees latitude north. ; Provide the location of the data files and the name of the file path='C:\Calipso\Data' fname='CAL_LID_L2_VFM-Prov-V1-10.2006-06-14T17-56-47ZD.hdf' ; read the latitude and longitude from the file. Multiple field ; names can be specified at once. fieldnames=['Latitude', 'Longitude'] read_calipso, path, fname, fieldnames, geolocation ; The geolocation variable is a structure, with names equal to the ; field names in the hdf file. Use IDL's where() function to find the ; wanted geolocation. idx = where(geolocation.latitude ge 10.0 and geolocation.latitude lt 15.0, $ count_items) ; Process the output of the where() function to obtain the indices: start = [0,min(idx)] count = [-1,count_items] read_calipso_subset, path, fname, ['Feature_Classification_Flags'], $ vertical_feature_mask, start=start, count=count Because we only specified a single field, we get an array back, not a structure. 3.2 Parameters of READ_CALIPSO The READ_CALIPSO procedure has the following calling sequence: READ_CALIPSO, PATH, FNAME, FIELDNAMES, DATA, ATTRIBUTENAMES, ATTRIBUTES with: PATH: The directory where the files are located (string scalar). FNAME: The file name from which to read (string scalar). FIELDNAMES: The fields to be read from the file. This can be a string array or a string scalar). DATA: named variable in which the results will be placed. The data is returned in a nameless structure (if FIELDNAMES has more than one element) or an array (if FIELDNAMES has a single element). The order of the fields within the structure is the same as in the array FIELDNAMES, and the names are the same as well. ATTRIBUTENAMES: The names of the attributes to be read from the 'metadata' table. Just like FIELDNAMES, this can be a string array or string scalar. This parameter is optional. ATTRIBUTES: A named variable that will receive the attributes. The attributes are returned in a structure (like the DATA itself). The FIELDNAMES can be found with either hdfview, or by inspecting the Calipso file readers. 3.3 Parameters of READ_CALIPSO_SUBSET The READ_CALIPSO_SUBSET procedure has the following calling sequence: READ_CALIPSO_SUBSET, PATH, FNAME, FIELDNAMES, DATA [, START=start] [, COUNT=count] [, STRIDE=stride] with: PATH, FNAME, FIELDNAMES, and DATA as with READ_CALIPSO. The START, COUNT and STRIDE named parameters are passed on to the HDF_SD_GETDATA procedure after sanitation. If you don't care about a specific dimension, just set the value to -1, and a suitable default will be generated. START: begin reading from this index. This array has one element for each of the dimensions of the target field. A positive value starts reading from this particular index. Zero or -1 starts from the first element. COUNT: the number of elements that is to be read. This array has one element for each of the dimensions of the target field. A positive value limits the length, -1 reads until the end of the field. STRIDE: the number of elements that can be skipped when reading. This array has one element for each of the dimensions of the target field. zero or -1 will get all elements, positive values give the number of elements that are to be skipped, i.e. 1 will give you every other element. 3.4 Sample output The example given above will give the following output: IDL> help % At $MAIN$ COUNT LONG = Array[2] COUNT_ITEMS LONG = 111 FIELDNAMES STRING = Array[2] FNAME STRING = 'CAL_LID_L2_VFM-Prov-V1-10.2006-06-14T17-56-47ZD.hdf' GEOLOCATION STRUCT = -> Array[1] IDX LONG = Array[111] PATH STRING = './' START LONG = Array[2] VERTICAL_FEATURE_MASK UINT = Array[5515, 111] Compiled Procedures: $MAIN$ READ_CALIPSO READ_CALIPSO_SUBSET Compiled Functions: PATH_SEP IDL> help, /structure, geolocation ** Structure <825286c>, 2 tags, length=33664, data length=33664, refs=1: LATITUDE FLOAT Array[1, 4208] LONGITUDE FLOAT Array[1, 4208] IDL> print, count -1 111 IDL> print, START 0 1706 IDL> print, geolocation.latitude[idx] 10.0258 10.0706 10.1154 10.1603 10.2051 10.2499 10.2948 10.3397 10.3845 10.4295 10.4745 10.5194 10.5645 10.6094 10.6543 10.6991 10.7441 10.7891 10.8340 10.8788 10.9240 10.9690 11.0140 11.0590 11.1037 11.1486 11.1936 11.2386 11.2838 11.3288 11.3739 11.4191 11.4643 11.5093 11.5543 11.5993 11.6442 11.6892 11.7340 11.7786 11.8234 11.8683 11.9132 11.9580 12.0028 12.0477 12.0925 12.1373 12.1821 12.2268 12.2717 12.3166 12.3618 12.4069 12.4518 12.4968 12.5418 12.5866 12.6313 12.6761 12.7210 12.7660 12.8110 12.8560 12.9009 12.9460 12.9911 13.0359 13.0809 13.1259 13.1707 13.2154 13.2603 13.3053 13.3505 13.3955 13.4404 13.4854 13.5304 13.5752 13.6200 13.6650 13.7101 13.7551 13.8002 13.8453 13.8905 13.9356 13.9806 14.0254 14.0703 14.1153 14.1600 14.2046 14.2496 14.2944 14.3392 14.3842 14.4288 14.4736 14.5184 14.5631 14.6080 14.6527 14.6976 14.7426 14.7873 14.8324 14.8774 14.9223 14.9673 IDL> print, geolocation.longitude[idx] -70.2698 -70.2795 -70.2893 -70.2991 -70.3089 -70.3187 -70.3285 -70.3383 -70.3481 -70.3579 -70.3678 -70.3775 -70.3871 -70.3969 -70.4067 -70.4165 -70.4264 -70.4362 -70.4460 -70.4559 -70.4657 -70.4756 -70.4854 -70.4953 -70.5050 -70.5149 -70.5247 -70.5346 -70.5445 -70.5543 -70.5642 -70.5741 -70.5840 -70.5938 -70.6036 -70.6134 -70.6232 -70.6330 -70.6429 -70.6528 -70.6627 -70.6724 -70.6822 -70.6921 -70.7019 -70.7118 -70.7217 -70.7316 -70.7414 -70.7512 -70.7610 -70.7709 -70.7809 -70.7908 -70.8007 -70.8106 -70.8203 -70.8303 -70.8404 -70.8503 -70.8601 -70.8700 -70.8799 -70.8898 -70.8997 -70.9096 -70.9194 -70.9293 -70.9393 -70.9493 -70.9593 -70.9692 -70.9791 -70.9890 -70.9989 -71.0088 -71.0187 -71.0287 -71.0386 -71.0486 -71.0587 -71.0686 -71.0785 -71.0884 -71.0984 -71.1085 -71.1186 -71.1285 -71.1384 -71.1483 -71.1583 -71.1683 -71.1783 -71.1884 -71.1983 -71.2082 -71.2182 -71.2282 -71.2382 -71.2482 -71.2582 -71.2681 -71.2783 -71.2882 -71.2981 -71.3081 -71.3181 -71.3283 -71.3384 -71.3484 -71.3584 IDL> cloud=where((VERTICAL_FEATURE_MASK[*,1] and 7) eq 2, cnt) IDL> print, cnt 846 IDL> print, min(cloud), max(cloud) 364 5361 4.0 Contact Information Questions regarding the use of these routines may be addressed to User and Data Services at the Atmospheric Science Data Center: e-mail: larc@eos.nasa.gov phone: 757-864-8658 fax: 757-864-8807 mailing address: User and Data Services Atmospheric Science Data Center NASA Langley Research Center MS 157D, 2 S. Wright St. Hampton, VA 23681-2199 USA