SASENOAA Interface Engine

You can query the SWDI data sets to retrieve the observations or data values for a list of time series or events by specifying the data format (FORMAT= option), the data set to access (NOAASET= option), and the date range (RANGE= option).

The SASENOAA engine’s FORMAT= option supports three formats: XML (default), SHP, and KMZ. The XML format stores the weather data results in a SAS data set (.sas7bdat) named in the OUTXML= option, and when applicable, in two additional data sets: one for message text output (_M.sas7bdat), and another for statistics output (_S.sas7bdat).

The SHP format produces a ZIP file that contains four Esri shapefiles (with the extensions .shp, .shx, .dbf, and .prj). The SASENOAA interface unzips the SHP ZIP file to surface the four Esri files. The KMZ format produces a ZIP file (with the extension .kmz) that can be opened in virtual globe software such as Google Earth. The SASENOAA engine unzips the KMZ file to produce the resulting KML file, which can then be imported into Google Maps to create a detailed map of the SWDI time series data.

The NOAASET= option is required. You can specify one of the following Next-Generation Radar (NEXRAD) Level III types: nx3tvs (tornado vortex signatures), nx3meso (mesocyclone signatures), nx3mda (digital mesocyclone detection algorithm), nx3hail (hail signatures), or nx3structure (storm cell structure information). You can also specify two other types: plsr (preliminary local storm reports) and warn (severe thunderstorm, tornado, flash flood, and special marine warnings).

After you specify both the NOAASET= option and the format, you must also use the RANGE= option to specify the date range of the data that you are selecting for output, as shown in the following example.

The statements that follow enable you to access the severe weather tornado vortex signature (TVS) events that are recorded in the nx3tvs database for the date range beginning May 5, 2006, and ending May 6, 2006. The observations are sorted in chronological order (the datetime variable is ztime). The output is shown in Figure 1.

options validvarname=any;

title 'Retrieve Tornado Vortex Signature Data for the Range 20060505:20060506';
libname mylib "/sasusr/noaa/doc/";
libname noaa sasenoaa "physical path to the folder where you want the NOAA data"
   NOAASET=nx3tvs
   RANGE='20060505:20060506'
   OUTXML=cinco
   AUTOMAP=replace
   MAPREF=MyMap
   XMLMAP="%sysget(NOAA_DATA)cinco.map"
   FORMAT=xml;

data mylib.mycinco;
   set noaa.cinco;
run;

proc contents data=mylib.mycinco; run;
proc print data=mylib.mycinco(obs=10); run;

The XML data that the NOAA SWDI web service returns are placed in a file that is named by the OUTXML= option—in this case, CINCO1.xml. Note that the SASENOAA engine appends a numeral to the XML file name, and the file extension (.xml) is excluded from the file name that appears in the OUTXML= option. The NOAA data reside in the location that is given inside the string enclosed in double quotation marks in the SASENOAA LIBNAME statement. So, if the NOAA_DATA environment variable is set to /sasusr/noaa/test/ , then the NOAA data is located in the folder /sasusr/noaa/test . An equivalent LIBNAME statement that does not use any environment variables could be as follows:

libname noaa sasenoaa "physical path to the folder where you want the NOAA data"
   NOAASET=nx3tvs
   RANGE='20060505:20060506'
   OUTXML=cinco
   XMLMAP="/sasusr/noaa/test/cinco.map"
   AUTOMAP=replace
   MAPREF=MyMap
   FORMAT=xml;

The XML map that is created is assigned the full path name that the XMLMAP= option specifies. The SASENOAA engine appends a numeral to the XML file name to prevent file names from being overwritten during multiple read requests.

The RANGE= option specifies the start date and end date for the range of days for which you want to retrieve data. This option accepts a string, enclosed in single quotation marks, that gives start and end dates (in YYYYMMDD format) so that only the recorded severe weather events from the selected dates are included. The result, MYCINCO, is named in the DATA step and is shown in Figure 1.

It is more efficient to use the DATA step to store your NOAA SWDI data in a SAS data set and then refer to the SAS data set directly in your PROC statements. You can also refer to the SASENOAA libref directly, as in the statement

proc print data=noaa.cinco(obs=10);

The PROC PRINT statement uses the member name, CINCO; this usage corresponds to the OUTXML=CINCO option. Although using this statement might seem easier, it is not as efficient, because every time you use the SASENOAA libref, the SASENOAA interface engine reads the entire XML file into SAS again. So it is better to refer to the SAS data set repeatedly than to invoke the interface engine repeatedly.

The SASENOAA interface engine supports the XML format by placing the XML data that the NOAA SWDI web service returns in a file named by the OUTXML= option. The XML map that is automatically created is assigned the full path name specified by the XMLMAP= option, and the fileref that is used for the map assignment is specified by the MAPREF= option. In the preceding sample code, the SASENOAA engine uses the MAPREF= and XMLMAP= options in the FILENAME statement to assign a file name:

FILENAME MyMap "/sasusr/noaa/test/cinco.map";

You can use the MAPREF= and XMLMAP= options to control where the map resides, what you name the map, and how you refer to it with a fileref. You can use the OUTXML= option to name your XML data file; it is described in the section SAS OUTXML File. The XML data file is placed in the folder that is designated by physical-name, which is described in the section The LIBNAME libref SASENOAA Statement. You can refer to your data by using the NOAA libref defined in your SASENOAA LIBNAME statement. The NOAA libref is shown inside the DATA step in the SET statement. The SET statement reads observations from the input data set Noaa.cinco and stores them in a SAS data set named Mycinco, as shown in Figure 1. You can also use the SAS DATA step to perform further processing and to store the resulting time series in a SAS data set; this process is described in the section SAS Output Data Set.

In summary, to specify the NOAA SWDI data set that you want to retrieve, use the NOAASET= option. This required option accepts a string that names the desired NOAA data set, in this case, NOAASET=NX3TVS. The RANGE= option is also required and selects the date range based on the ztime variable, which is the time ID variable for the resulting SAS data set. The Mycinco data set contains the NX3TVS data variables whose observation range is controlled by the RANGE= option. The Mycinco data set contains observations that start May 5, 2006, and end the same day, as specified by the end date May 6, 2006, which is excluded from the selected data. Note: The begin date on the RANGE= option is inclusive, but the end date is exclusive of the data.