README for subset_sage2_v620 software package 1.0 OVERVIEW This package subsets SAGE II version 6.20 binary format files. It is written in Exelis Visual Information Solutions Interactive Data Language (IDL). It can be run either with a licensed version of the IDL package or by using the IDL Virtual Machine application that can be obtained from Exelis Visual Information Solutions free of charge as described in section 3.2 below. The subset may be specified in terms of a lat/lon box and/or the parameters to be included. The selected parameter values are written to an ASCII output file along with certain file header information for profiles that match the lat/lon criteria. The procedure will operate either on one or more files selected during execution, or on a list of files contained in a file. To use a list file, specify the fname of the list file as a string value of the LISTFILE keyword in the procedure call. Note that the full path name of the list file must be specified if the list file does not reside in the current IDL default directory. Assistance with this software package may be obtained by contacting NASA Langley Atmospheric Science Data Center User and Data Services Mail Stop 157D NASA Langley Research Center Hampton, Virginia 23681-2199 U.S.A. E-mail: support-asdc@earthdata.nasa.gov Phone: (757)864-8656 FAX: (757)864-8807 URL: http://eosweb.larc.nasa.gov 2.0 UNPACKING THE PACKAGE DISTRIBUTION FILE The program files are supplied in a zip file or a tar file. The files may be extracted from either package using a freeware utility such as WinZip or pkzip on the PC. The tar file may be extracted on Unix systems with the tar command, e.g. tar xvf subset_sage2_v620.tar The package files should all reside in the same directory. This need not be the directory where the SAGE II data files are located. 3.0 PROGRAM EXECUTION 3.1 Using a licensed version of IDL 1) Start the IDL development environment (idlde): - on a PC, click on the IDL desktop icon or run IDL from the Start->Programs menu; - on Unix, at the Unix command prompt, type idlde 2) From the File item on the menu bar, choose Open Project and then select the file subset_sage2_v620.prj Note: If your preferences (File->Preferences) are set with a check mark next to Change Directory on Open, the directory containing this file will now be the IDL default directory. 2) From the Project item on the menu bar, choose Build and then choose Run. The program will be running in the mode where the SAGE II files to be processed can be selected from a dialog box. To run with a list file, build the program as indicated above, then, at the IDL command line (indicated with the IDL> prompt), type subset_sage2_v620,LISTFILE="your_listfile" where your_listfile is the name (including path if not in the default IDL directory) of the file containing the names of SAGE II species files to be processed. The program executes as follows: 1) If the LISTFILE keyword is not specified, a file selection dialog box appears which may be used to choose one or more SAGE II species files for processing. 2) A selection box is displayed for entering latitude and longitude bounds for the subset. By default, the entire globe is selected (latitudes -90 to 90, longitudes -180 to 180). 3) A parameter selection box is displayed. One or more parameters may be selected for inclusion in the subset file. An hourglass cursor is displayed while the selected files are processed. A message dialog box appears when processing is complete. This program has been tested with the following IDL versions and platforms: IDL Version Platform ----------- -------- IDL 5.3 SGI, Irix 6.5 IDL 5.5 Sun, Solaris 5.8 PC, Windows 2000 IDL 5.6 Sun, Solaris 5.8 IDL 6.0 SGI, Irix 6.5 PC, Windows 2000 If the project file cannot be opened on your system, here is an alternate method for compiling and running the program: 1) Start idlde as above. 2) From the File menu select Open and then open subset_sage2_v620.pro 3) From the Run menu, select Compile subset_sage2_v620.pro 4) From the Run menu, select Resolve Dependencies 5) From the Run menu, select Run subset_sage2_v620.pro 3.2 Using the IDL Virtual Machine The IDL Virtual Machine comes bundles with IDL and is available from Exelis Visual Information Solutions at http://www.exelisvis.com/Downloads/ProductDownloads.aspx The IDL VM software may be downloaded from this site or ordered from Exelis VIS on CD at no cost. The site provides installation instructions. To run this application using the IDL Virtual Machine, 1) In Unix At the Unix command prompt, type idl -vm. Click anywhere on the IDL VM splash screen to continue. A dialog box appears for selecting the IDL save file. Navigate to the directory where you placed the subset_sage2_v620.sav file and select that file. Click the OK button and the subset_sage2_v620 program will start. 2) In Windows, From Windows Explorer, drag the subset_sage2_v620.sav file onto the IDL Virtual Machine Desktop icon created when the IDL VM was installed. Click on the splash screen, and the subset_sage2_v620 program will start. or Click on the IDL Virtual Machine desktop icon or run the IDL Virtual Machine from the Start menu and click on the splash screen to continue. Use the dialog box that appears to navigate to the directory where you placed the subset_sage2_v620.sav file, select that file, and click OK to start the subset_sage2_v620 program. Note that the subset_sage2_v620.pro source code file may be opened with any text editor to examine the processing algorithm. 3.3 INPUTS There are no positional parameter arguments to the subset_sage2_v620 routine. The LISTFILE keyword is used to specify the name (with full path if not in the current IDL default directory) of the file containing a list of SAGE II species files to be processed. If the LISTFILE keyword is not specified, a file selection dialog box will be displayed and one or more SAGE II species files may be selected for processing. Dialog boxes are used to specify the lat/lon box bounds and the parameters to be included in the subset. 3.4 OUTPUTS An ASCII (text) format output file is created using the name of the species file with "_subset.dat" appended to it, e.g. SAGE_II_SPEC_200005.6.20_subset.dat The output file includes: 1) subset information-- The name of the file that was subset. The subset criteria used. 2) file information from the index file corresponding to the SAGE II species file and, for each profile matching the subset criteria 3) profile information from the index file 4) the specified parameters from that profile One output file is created for each SAGE II species file selected for processing. The output files are written to the directory containing the corresponding SAGE II species file. If no latitude or longitude criteria are matched, a message to that effect is written to the output file. Note that multiple subsets of the same input file will cause the output file to be overwritten since it would have the same name, so rename the output files between runs if the same SAGE II file is subset in more than one way. 3.5 SAMPLE OUTPUT Here is a partial listing of the output from a run of this program. Additional information about the SAGE II file contents may be obtained from the NASA Langley Atmospheric Science Data Center SAGE II information web page, http://eosweb.larc.nasa.gov/PRODOCS/sage2/table_sage2.html ---------------------------- Subset of File G:\Data\SAGE II\SAGE_II_SPEC_200005.6.20 Subset criteria: Latitude: 0.000000 - 20.0000 Longitude: 70.0000 - 90.0000 Included parameters: NMC_Temp NMC_Dens H2O Ext525 FILE INFORMATION ---------------- NUM_PROF 771 MET_REV_DATE 20030925 DRIVER_REV 6.20 TRANSMISSION_REV 6.20 INVERSION_REV 6.20 SPECTROSCOPY_REV 6.20 EPH_FILE_NAME SAGE_II_EPHEM_200005.6.20 MET_FILE_NAME SAGE_II_MET_200005.6.20 REF_FILE_NAME SAGE_II_REF_200005.6.20 TRANS_FILE_NAME SAGE_II_TRANS_200005.6.20 SPEC_FILE_NAME SAGE_II_SPEC_200005.6.20 FILLVAL -999.000 GRID_SIZE 0.500000 ALT_GRID 0.500000 1.00000 1.50000 2.00000 2.50000 3.00000 3.50000 4.00000 4.50000 5.00000 5.50000 6.00000 6.50000 7.00000 7.50000 8.00000 8.50000 9.00000 9.50000 10.0000 10.5000 11.0000 11.5000 12.0000 12.5000 13.0000 13.5000 14.0000 14.5000 15.0000 15.5000 16.0000 16.5000 17.0000 17.5000 18.0000 18.5000 19.0000 19.5000 20.0000 20.5000 21.0000 21.5000 22.0000 22.5000 23.0000 23.5000 24.0000 24.5000 25.0000 25.5000 26.0000 26.5000 27.0000 27.5000 28.0000 28.5000 29.0000 29.5000 30.0000 30.5000 31.0000 31.5000 32.0000 32.5000 33.0000 33.5000 34.0000 34.5000 35.0000 35.5000 36.0000 36.5000 37.0000 37.5000 38.0000 38.5000 39.0000 39.5000 40.0000 40.5000 41.0000 41.5000 42.0000 42.5000 43.0000 43.5000 44.0000 44.5000 45.0000 45.5000 46.0000 46.5000 47.0000 47.5000 48.0000 48.5000 49.0000 49.5000 50.0000 50.5000 51.0000 51.5000 52.0000 52.5000 53.0000 53.5000 54.0000 54.5000 55.0000 55.5000 56.0000 56.5000 57.0000 57.5000 58.0000 58.5000 59.0000 59.5000 60.0000 60.5000 61.0000 61.5000 62.0000 62.5000 63.0000 63.5000 64.0000 64.5000 65.0000 65.5000 66.0000 66.5000 67.0000 67.5000 68.0000 68.5000 69.0000 69.5000 70.0000 70.5000 71.0000 71.5000 72.0000 72.5000 73.0000 73.5000 74.0000 74.5000 75.0000 75.5000 76.0000 76.5000 77.0000 77.5000 78.0000 78.5000 79.0000 79.5000 80.0000 80.5000 81.0000 81.5000 82.0000 82.5000 83.0000 83.5000 84.0000 84.5000 85.0000 85.5000 86.0000 86.5000 87.0000 87.5000 88.0000 88.5000 89.0000 89.5000 90.0000 90.5000 91.0000 91.5000 92.0000 92.5000 93.0000 93.5000 94.0000 94.5000 95.0000 95.5000 96.0000 96.5000 97.0000 97.5000 98.0000 98.5000 99.0000 99.5000 100.000 ALT_MID_ATM 40.5000 41.0000 41.5000 42.0000 42.5000 43.0000 43.5000 44.0000 44.5000 45.0000 45.5000 46.0000 46.5000 47.0000 47.5000 48.0000 48.5000 49.0000 49.5000 50.0000 50.5000 51.0000 51.5000 52.0000 52.5000 53.0000 53.5000 54.0000 54.5000 55.0000 55.5000 56.0000 56.5000 57.0000 57.5000 58.0000 58.5000 59.0000 59.5000 60.0000 60.5000 61.0000 61.5000 62.0000 62.5000 63.0000 63.5000 64.0000 64.5000 65.0000 65.5000 66.0000 66.5000 67.0000 67.5000 68.0000 68.5000 69.0000 69.5000 70.0000 70.5000 71.0000 71.5000 72.0000 72.5000 73.0000 73.5000 74.0000 74.5000 75.0000 RANGE_TRANS 0.500000 100.000 RANGE_O3 0.500000 70.0000 RANGE_NO2 0.500000 50.0000 RANGE_H2O 0.500000 50.0000 RANGE_EXT 0.500000 40.0000 RANGE_DENSITY 0.500000 70.0000 RESERVED 0.500000 40.0000 ------------ Profile number: 727 YYYYMMDD 20000530 EVENT_NUM 16 HHMMSS 122223 DAY_FRAC 151.516 LAT 11.6459 LON 88.5506 BETA -29.1529 DURATION 109.422 TYPE_SAT 1 TYPE_TAN 1 NMC_TEMP 298.644 295.400 292.189 289.494 286.799 284.104 281.577 279.101 276.625 274.148 271.672 269.011 265.944 262.878 259.812 256.229 252.541 248.852 245.164 241.551 237.992 234.420 230.357 226.294 222.230 218.112 213.993 209.875 206.225 203.346 200.468 197.590 194.711 194.599 196.025 197.451 198.876 200.597 202.599 204.601 206.602 208.305 209.724 211.142 212.561 213.980 215.399 216.811 218.101 219.392 220.682 221.972 223.263 224.553 225.843 227.134 228.424 229.714 231.004 232.295 233.585 234.875 236.107 237.228 238.350 239.471 240.592 241.714 242.835 243.956 245.078 246.199 247.419 248.753 250.087 251.421 252.755 254.090 255.424 256.758 258.092 259.426 260.760 262.094 263.428 264.762 265.583 265.933 266.283 266.634 266.984 267.334 267.685 268.035 268.385 268.736 269.086 268.209 266.739 265.268 263.798 262.327 260.924 259.715 258.771 258.125 257.761 257.617 257.587 257.278 256.753 255.622 254.298 252.975 251.651 250.327 249.004 247.680 246.357 244.864 243.371 241.709 240.047 238.385 236.723 235.062 233.401 231.740 230.079 228.379 226.679 224.940 223.202 221.463 219.725 217.987 216.249 214.512 212.775 211.458 NMC_DENS 2.30338e+019 2.19976e+019 2.09946e+019 1.99886e+019 1.90221e+019 1.80939e+019 1.71887e+019 1.63172e+019 1.54828e+019 1.46841e+019 1.39199e+019 1.31997e+019 1.25321e+019 1.18910e+019 1.12758e+019 1.07033e+019 1.01558e+019 9.62878e+018 9.12189e+018 8.63274e+018 8.16184e+018 7.71055e+018 7.29345e+018 6.89209e+018 6.50622e+018 6.13821e+018 5.78460e+018 5.44507e+018 5.10579e+018 4.76180e+018 4.43657e+018 4.12933e+018 3.83932e+018 3.51870e+018 3.20227e+018 2.91629e+018 2.65763e+018 2.41913e+018 2.20015e+018 2.00286e+018 1.82493e+018 1.66813e+018 1.52914e+018 1.40256e+018 1.28720e+018 1.18200e+018 1.08601e+018 9.98369e+017 9.18268e+017 8.45011e+017 7.77977e+017 7.16606e+017 6.60391e+017 6.08873e+017 5.61635e+017 5.18300e+017 4.78526e+017 4.42003e+017 4.08450e+017 3.77609e+017 3.49249e+017 3.23158e+017 2.99208e+017 2.77252e+017 2.57000e+017 2.38311e+017 2.21060e+017 2.05129e+017 1.90412e+017 1.76811e+017 1.64238e+017 1.52610e+017 1.41822e+017 1.31812e+017 1.22557e+017 1.13996e+017 1.06074e+017 9.87394e+016 9.19466e+016 8.56529e+016 7.98193e+016 7.44101e+016 6.93925e+016 6.47362e+016 6.04137e+016 5.63995e+016 5.27439e+016 4.93957e+016 4.62641e+016 4.33347e+016 4.05943e+016 3.80305e+016 3.56316e+016 3.33869e+016 3.12863e+016 2.93203e+016 2.74802e+016 2.58887e+016 2.44431e+016 2.30709e+016 2.17688e+016 2.05334e+016 1.93593e+016 1.82334e+016 1.71513e+016 1.61121e+016 1.51175e+016 1.41715e+016 1.32787e+016 1.24552e+016 1.16915e+016 1.09985e+016 1.03514e+016 9.73940e+015 9.16076e+015 8.61381e+015 8.09696e+015 7.60868e+015 7.14755e+015 6.71666e+015 6.30941e+015 5.92864e+015 5.56852e+015 5.22805e+015 4.90628e+015 4.60229e+015 4.31524e+015 4.04426e+015 3.78857e+015 3.54800e+015 3.32111e+015 3.10773e+015 2.90661e+015 2.71710e+015 2.53863e+015 2.37062e+015 2.21255e+015 2.06388e+015 1.92415e+015 1.78943e+015 H2O -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 2.24575e-006 2.97486e-006 3.06039e-006 2.97927e-006 3.30317e-006 3.57459e-006 3.70037e-006 4.04387e-006 4.32841e-006 4.38269e-006 4.08846e-006 3.92193e-006 4.12840e-006 4.24444e-006 4.23195e-006 4.09592e-006 4.00298e-006 3.87002e-006 3.94122e-006 3.93766e-006 3.91070e-006 3.88210e-006 3.86055e-006 3.86416e-006 3.73138e-006 3.86410e-006 3.75852e-006 3.99191e-006 4.24204e-006 4.44176e-006 4.70069e-006 5.06174e-006 4.85354e-006 4.90939e-006 5.25779e-006 5.25700e-006 5.20471e-006 5.73814e-006 5.02850e-006 4.96429e-006 4.57674e-006 4.88654e-006 4.90162e-006 5.93498e-006 5.30538e-006 5.58341e-006 5.35665e-006 5.12117e-006 5.65336e-006 6.66465e-006 6.50449e-006 5.79645e-006 5.32735e-006 3.47971e-006 2.53071e-006 4.49006e-006 6.09217e-006 6.33394e-006 9.97031e-006 1.17566e-005 9.09300e-006 1.02954e-005 1.13127e-005 8.40251e-006 1.75440e-005 EXT525 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 -999.000 0.0177278 0.0179058 0.0304982 0.00449352 0.000490657 0.000454214 0.000261338 0.000342191 0.000214451 0.000339920 0.000293702 0.000281101 0.000269358 0.000272131 0.000222904 0.000233759 0.000244127 0.000212579 0.000207661 0.000198776 0.000212536 0.000197364 0.000196679 0.000188471 0.000195286 0.000171290 0.000162493 0.000152336 0.000136036 0.000149049 0.000114393 0.000108800 8.58583e-005 7.04195e-005 3.89739e-005 2.62540e-005 2.56923e-005 2.00773e-005 1.58811e-005 1.26843e-005 1.06162e-005 9.69724e-006 8.77869e-006 8.02216e-006 7.41126e-006 6.94474e-006 -999.000 -999.000 -999.000 -999.000 ------------ Profile number: 757 YYYYMMDD 20000531 EVENT_NUM 16 HHMMSS 122618 DAY_FRAC 152.518 LAT 6.59814 LON 85.5536 BETA -30.9439 DURATION 114.516 TYPE_SAT 1 TYPE_TAN 1 NMC_TEMP 298.732 295.412 292.119 289.357 286.595 283.833 281.023 278.199 275.374 272.549 269.724 267.002 ... Updated: April 23, 2004 August 02, 2010 - updated link for IDL Virtual Machine RSI to ITT VIS January 24, 2012 - updated link for ITT VIS to Exelis VIS