MADIS API System Description
Basic API Calls
To initialize the MADIS software, users of the MADIS API need to first call subroutine MINIT for each dataset desired. The input arguments required include the dataset desired, e.g. "RAOB" or "SFC," the name of the database being accessed, i.e., "FSL" or "AWIPS," and a logical, i.e. ".true." or ".false.," indicating whether the user wishes error messages to be written to the standard output file.
Once the initialization is complete, users can then access the station information available for the dataset specified, via the M*STA subroutines, where * indicates the dataset, e.g. MRAOBSTA or MSFCSTA for radiosonde and meteorological surface data, respectively. The only input argument required for these calls is the year/day/hour of the data to be read. Output arguments include the number of stations available; also arrays including station identification information, such as station names and ID numbers; position information, such as latitude, longitude, and elevation information; and also the exact observation times.
The data and QC information for the time and dataset requested can then be accessed with a call to the corresponding MGET* subroutine, where again * indicates the dataset. For example, MGETRAOB will load in all radiosonde data, and MGETNPN loads all NOAA Profiler Network data for the time specified. Specific variables, or observation types, within the indicated dataset are requested via variable code names included in the input argument list to the MGET* routines. Depending on the variable requested, users can choose to either access "raw" observations, such as mandatory and significant level information from radiosonde observations, or choose to have the raw data further processed as in integrated radiosonde soundings generated by interleaving the mandatory and significant data, sorting by ascending height, interpolating missing pressure levels, and correcting for hydrostatic consistency. Additional processing beyond the raw observations stored in the database includes the ability to return various forms of certain variables, e.g., the user can request specific humidity and this will be calculated from the stored moisture, temperature and pressure observations; likewise, pressure and altimeter setting can both be requested, regardless of which one is actually reported by a given station and stored in the database. For surface data, a single MGETSFC call automatically retrieves data from all of the MADIS datasets, including METAR, SAO, maritime, and mesonet surface observations. In all cases, observations are automatically returned with QC arrays indicating the results of the QC checks.
The following code fragment demonstrates the three subroutine calls necessary to access integrated temperature profiles from all radiosonde data in the database. Note that the year/day/hour argument is specified with a 9-character string which includes a 2-digit year and 3-digit Julian day. To aid the user, however, MADIS also offers utility routines which convert these character strings back and forth from standard integer representations of the year, month, day, and hour, as well as translations to and from the AWIPS standard time-and-date string.
C Initialize the radiosonde MADIS dataset.
CALL MINIT('RAOB','FSL',.true.,istatus)
C Read in the station info for September 1, 2001, 1200 UTC.
CALL MRAOBSTA('012441200',nsta,stanam,wmoid,lat,lon,elev,timeob,
1 istatus)
C Read the integrated temperature soundings into the "temp" array.
CALL MGETRAOB('012441200','T',nsta,nobs,nlevels,temp,
1 qcd,qca,qcr,istatus)
Optional API Calls
Optional API subroutines allow the user to limit the observations that MADIS will return. Included in the optional routines are MSETWIN, which allows the user to select a specific time window within which to return the observations, MSETDOM which allows the user to obtain only those observations within a specified horizontal domain, MSETQC which allows the user to return only those observations that have passed specified QC levels, MSETCOR which allows the user to specify whether or not to apply QC corrections to the returned data, and MSET*PVDR which allows the user to limit the datasets returned with the M*STA and MGET* routines for the meteorological and hydrological surface datasets.
The input arguments for MSETWIN include the beginning and end of the time window, (in minutes relative to the nominal year/date/hour time specified in the M*STA call), and also a code number to indicate how multiple reports from a single station within the time window should be handled. Allowable codes specify that either all reports should be returned (within the time window, or within the file), or only a single report should be returned, either closest in time to the nominal time, closest in time to the beginning of the time window, or closest in time to the end of the time window.
MSETDOM provides arguments to specify the domain within which to return the observations. Domains can be specified either in terms of latitude and longitude corners, or in terms of a grid box length and projection. Projections supported in the current version of MADIS are polar stereographic and Lambert conformal conic. In the case of a projection specification, the MADIS API will automatically rotate all wind observations to be true to the specified grid, and also provides the capability to obtain the (i,j) position within the grid for each station location.
MSETQC allows the user to filter the observations based on QC results. Allowable options include the capability of returning only those observations that have passed a specific QC level, e.g. level 1 validity and position consistency checks, and an option to return only those observations that have passed the highest level of QC specified for that dataset and observation type. In all cases, the full QC structures are returned to provide information on exactly which QC checks were applied, which were passed, and which were failed. Also available in the QC structures is information indicating which radiosonde observations have been interpolated, and which have been hydrostatically corrected. Subroutine MSETCOR allows the user to activate or deactive the QC corrections.
Subroutines MSET*PVDR allow the user to choose among specific subsets of the data for datasets that include multiple "data providers". These include the meteorological surface (MSETSFCPVDR), hydrological surface (MSETHYDROPVDR), Multi-Agency Profiler (MSETMAPPVDR), radiometer (MSETRDMTRPVDR), satellite wind (MSETSATWNDPVDR), satellite sounding (MSETSATSNDPVDR) datasets, satellite radiance (MSETSATRADPVDR), and snow (MSETSNOWPVDR) datasets. One or more of the specific data providers (or group of providers) may be chosen. For example, a MADIS user may choose to access all available METAR observations, or choose to access only those observations from the Automated Surface Observing System (ASOS) stations. Likewise, mesonet data from only certain providers may be specified. In all cases, MADIS returns data with the provider type information included.
The following table shows the optional subroutines that can be called to limit which observations MADIS will return. They must be followed by a call to the appropriate M*STA routine in order to take effect, and the settings will remain in effect until superseded by subsequent calls (or a new MINIT call).
| Optional MADIS Subroutines | ||
|---|---|---|
| Subroutine | Purpose | Default (if not called) |
| MSETWIN | Select time window
|
All stations in ATIME file |
| MSETDOM | Specify horizontal domain
|
All stations |
| MSETQC | Specify QC level
|
All observations |
| MSETCOR | Specify correction handling
|
Corrections will be applied |
| MSETSFCPVDR MSETHYDROPVDR MSETMAPPVDR MSETRDMTRPVDR MSETSATWNDPVDR MSETSATSNDPVDR MSETSATRADPVDR MSETSNOWPVDR |
Specify data by provider
|
All surface/MAP/radiometer/GOES/POES satellite- operational products data returned |
Last updated 16 March 2017
