------------------------------ MADIS Satraddump Program Usage ------------------------------ 1.0 Introduction ----------------- The MADIS satraddump program can be used to read satellite radiance metadata, observations, and quality control (QC) information for a single time, and dump this to an output text file. The operation of the program is controlled by a text parameter file that allows the user to exercise all of the options included in the MADIS system for satellite soundings data. The program can be run as needed to access any MADIS data stored on your system, or can be run as a time-scheduled task to get data keyed to the current time. This document describes how to setup the parameter file, how to run the program, and what to expect in the way of outputs. Fortran programmers who wish to write their own programs to read MADIS data can find much of the same information in the satraddump.f source code in the src directory. In addition to being used for the dump utility, the code is annotated to provide a tutorial for programmers. 2.0 How to Run --------------- 1. Make sure you have the necessary environment variables defined: - MADIS_STATIC points to the MADIS static files directory - MADIS_DATA points to the top-level MADIS data directory See the INSTALL.* files for information on how to set environment variables on your system. 2. Setup the desired parameters in a satraddump parameter file. 3. Move to the directory in which you'll be running the program. 4. Copy the parameter file to the run directory, and make sure that its name is "satraddump.par". 5. Run the program. (bin/satraddump.exe on Unix/Linux, bin/satraddump on Windows) 6. Outputs: a. An activity log showing the selections made from the parameter file, as well as any errors that resulted will be written to standard output. b. The data that's been obtained will be written to satraddump.txt in the run directory. 3.0 How to Setup the Parameter File ------------------------------------ These sample parameter files can be found in the doc directory: - satraddump.par Dumps all variables, using defaults for all options. - satraddump1.par Example of how to specify that data be dumped for only certain data providers, and for only a few variables. The parameter file is split into several sections, with each section delimited by a line of "----------"'s. With a couple of exceptions noted below, you must include all lines that are within each section (in other words, the sections are "fixed length"). Each of the sections is described below, in the order in which they appear in the parameter file. 3.1 Time Window Section ------------------------ --------------------------------------------------------------------------------- Time Window (use 0,0,0 for default) FIXED LENGTH SECTION ----------- -150 Number of minutes relative to nominal time at which to start window 30 Number of minutes relative to nominal time at which to end window 4 0 - return all records within the file containing nominal time 4 - return all records within *window* --------------------------------------------------------------------------------- The user selects the nominal time of the data to be returned in the Time Selection section below. Time "windowing" is used so that the program will know how close in time each station's (i.e., satellite) observation time needs to be to the nominal time in order to be included. The time window is specified by selecting the number of minutes before and after the nominal time to be used for the window. If the default values (0,0,0) are selected, then all records will be returned from the file containing the nominal time. Each file contains one hour, with observation times from 29 minutes before the top of the hour through 30 minutes after the top of the hour. The sounding products are available for the different satellites, and for the different types of sounding products. The observation times vary, and the latency ranges from about one and a half to three hours (latency is defined as the time the data are available minus the observation time). The settings shown in the sample section above (-150,30,4) will return all records within 2.5 hours before and 0.5 hours after the nominal time. If you are running the program as a scheduled task with the nominal time keyed to the current time, one recommended window setting would be -150,0,4. This would return the observations for every satellite soundings product that had been made available within the last 2.5 hours. The maximum window is 180 minutes. Also note that the window is inclusive, that is, using start & end minutes -30,30 with a nominal time of 12:00 will return observations with times ranging from 11:30 through 12:30. 3.2 Provider Section --------------------- --------------------------------------------------------------------------------- Providers (see doc/satrad_providers.txt) VARIABLE LENGTH SECTION --------- 0 0 - all providers N - list of N provider names follow this line --------------------------------------------------------------------------------- Satellite sounding datasets are available for different satellites. In MADIS parlance, these are specified by "provider". If desired, the user can select only a subset of the total by specifying which providers are to be included or excluded. The default (shown above) is to enable all satellites. See satraddump1.par for an example of how to edit this variable-length section to specify a list of providers to be enabled. Here's the list of provider names recognized by MADIS: 'ALL-POES' All POES satellites 'NOAA-15' NOAA-15 'NOAA-16' NOAA-16 'NOAA-18' NOAA-18 3.3 Domain Filter Section -------------------------- --------------------------------------------------------------------------------- Domain Filter FIXED LENGTH SECTION ------------- 0 0 - don't filter 1 - return stations within latitude/longitude corners 2 - return stations within specified Polar Stereographic grid 3 - return stations within specified Lambert Conformal Conic grid Latitude/Longitude Corners (lines skipped if not Domain Filter 1) -------------------------- 37.0 SW corner latitude (north) -109.0 SW corner longitude (east) 41.0 NE corner latitude (north) -102.0 NE corner longitude (east) Polar Stereo Specification (lines skipped if not Domain Filter 2) -------------------------- 190500.0 Grid box size (meters) 7.838 Latitude (north) of 1st grid point (lower left = SW) -141.028 Longitude (east) of 1st grid point (lower left = SW) -95.0 Orientation longitude (east) 33.0 I-coordinate of pole 45.0 J-coordinate of pole 60.0 Lat (north) at which X-Y scale is true 65 Number of grid points in X-direction (I dimension) 43 Number of grid points in Y-direction (J dimension) Lambert Conformal Conic Specification (lines skipped if not Domain Filter 3) ------------------------------------- 40635.25 Grid box size (meters) 12.19 Latitude (north) of 1st grid point (lower left = SW) -133.459 Longitude (east) of 1st grid point (lower left = SW) -95.0 Orientation longitude (east) 25.0 Latitude (north) of first Lambert Conformal tangent 25.0 Latitude (north) of second Lambert Conformal tangent 185 Number of grid points in X-direction (I dimension) 129 Number of grid points in Y-direction (J dimension) --------------------------------------------------------------------------------- The horizontal domain can be limited to match one of two map projections (polar stereographic, Lambert conformal conic) or it can be limited to a latitude/longitude rectangle. Only stations within the domain will be returned. If one of the map projections is selected, any soundings (of any form) returned will be rotated to match the projection. If the default is selected (as above), no domain filtering will be performed, and all available stations will be returned, regardless of their location. (The example Latitude/Longitude specification shown above is for the state of Colorado, the example Polar Stereographic specification defines AWIPS grid 202 (NATIONAL-CONUS), and the example Lambert Conformal specification defines AWIPS grid 212 (REGIONAL-CONUS-DOUBLE RESOLUTION).) If one of the map projections has been selected for the horizontal domain, the station latitude and longitude will be converted to a grid index into the 2-dimensional grid (RI,RJ). Note that this works for grids laid out this way: NE (I=NX,J=NY) SW (I=1,J=1) The calculated index will appear in satraddump.txt in the "Grid I" and "Grid J" columns. If a map projection isn't being used, Grid I and Grid J will be output as zeros. 3.4 QC Filter Section ---------------------- --------------------------------------------------------------------------------- QC Filter FIXED LENGTH SECTION --------- 0 0 - none 1 - coarse 99 - highest possible --------------------------------------------------------------------------------- The primary variables in all MADIS datasets have been screened by automated quality control (QC) checks. Different variables have different levels of QC, or "stages", applied to them. In addition to the QC processing done by the satellite provider (who generally toss observations that are below their own quality thresholds), currently the satellite sounds have a MADIS level 1 validity check applied to the temperature and level 1 and 2 applied to the dewpoint temperature (calculated from the mixing ratio). See satrad_qc_variable_list.txt for more information. (Level 1 checks = "coarse".) Each variable that gets dumped will also have its associated QC information written to satraddump.txt. This includes a QC data descriptor (a single character summarizing the info), and bitmasks showing which QC checks were applied and the results of the checks. These appear in the "QCD", "QCA", and "QCR" columns of the output. For details on how to interpret these items see qc_info.txt. If the user doesn't want to interpret the QC info, he or she can limit the returned obs to selectable levels of quality. In that case, obs that don't meet the selected QC level will be omitted. There are three ways that the user can request and process the QC information: 1) Use the default setting (shown above) which will disable QC filtering. Then you can examine the QC info before deciding whether or not to use each observation. This allows for the maximum amount of control over what's available. 2) If you know ahead of time that the same level of QC is available for all variables you'll be using, select that level. 3) To require that all variables pass the highest level of QC that are specified for them, select QC level 99. User's of MADIS data who want the data filtered by QC results, but don't want to interpret the QC information themselves, should select QC level 99. 3.5 Time Selection Section --------------------------- --------------------------------------------------------------------------------- Time Selection FIXED LENGTH SECTION -------------- 1 0 - Julian format (YYJJJHHMM) 1 - Month/Day format (YYYYMMDD_HHMM) 0 0 - Use the nominal time line below 1 - Use the current time as the nominal time 20040324_1200 Nominal time (in selected format) --------------------------------------------------------------------------------- All MADIS data are time-stamped in Universal Coordinated Time (also called GMT). Two formats are supported, both for inputting the nominal time in the parameter file, and for outputting the time in the satraddump.txt output file. "Julian format" is in the form of "YYJJJHHMM", where: YY = 2-digit year (good from 1980 - 2179) JJJ = Julian date of the year (001-366) HH = Hour (00-23) MM = Minute (00-59) "Month/Day" format uses "YYYYMMDD_HHMM", where: YYYY = 4-digit year (still only good from 1980 - 2179) MMDD = Month/Day HHMM = Hour/Minute The nominal time shown above in the Month/Day format translates to 040841200 in the Julian format. Nominal times can be specified at any minute, not just at the top of the hour (minute 00). To run the program as a scheduled task, specify that the current time be used as the nominal time and set an appropriate time window. 3.6 Variables Section ---------------------- --------------------------------------------------------------------------------- Variables (1 per line, until end of file) VARIABLE LENGTH SECTION --------- (see doc/satrad_variable_list.txt) TB01 TB02 --------------------------------------------------------------------------------- This is the last section in the parameter file. The code names for the variables to be dumped are listed, one per line, until the end of file is reached. (The section delimiter line shown here is simply for readability. If you have this line or any other non-variable line in the real parameter file you'll get an error.) The list of code names is found in the first column of satrad_variable_list.txt, along with the units for each variable, the maximum QC level, and many other details. In the above example, note that we're dumping the temperature and mixing ratio. For many variables, you can select multiple forms and MADIS will do the calculations for you. For full information on what variables are available and how to interpret them, see satrad_variable_list.txt.