GEMPAK Online Tutorial

3. Surface Data Mapping

The program sfmap plots any parameters which can be derived from the data in a GEMPAK surface data file.

SFMAP Input Parameters

AREA      Data area
GAREA     Graphics area
SATFIL    Satellite image filename(s)
RADFIL    Radar image filename(s)
IMCBAR    Color/ornt/anch/x;y/ln;wd/freq
SFPARM    Surface parameter list
DATTIM    Date/time
SFFILE    Surface data file
COLORS    Color list
MAP       Map color/dash/width/filter flag
MSCALE    fgc;bgc;mask/units/lat;hide/values/anch/x;y/ln;wd/freq|text_info|t
LATLON    Line color/dash/width/freq/inc/label/format
TITLE     Title color/line/title
CLEAR     Clear screen flag
PANEL     Panel loc/color/dash/width/regn
DEVICE    Device|name|x size;y size|color type
PROJ      Map projection/angles/margins|drop flag
FILTER    Filter data factor
TEXT      Size/fnt/wdth/brdr/N-rot/just/hw flg
LUTFIL    Enhancement lookup table filename
STNPLT    Txtc/txt attr|marker attr|stnfil#col
CLRBAR    Color/ornt/anch/x;y/ln;wd/freq|text_info
LSTPRM    Filtered parm|x;y|TEXT info

To list the variable definitions in the same format as they are entered, type list or l for short:

 AREA     = WV
 GAREA    = WV
 SFFILE   = $GEMPAK/data/hrcbob.sfc
 COLORS   = 1
 MAP      = 1
 MSCALE   = 0
 TITLE    = 1
 PANEL    = 0
 PROJ     = MER
 TEXT     = 1

What are looking at? hrcbob.sfc? WV?

These are the program defaults and allow us to list and plot data immediately when starting to use GEMPAK.

Run sfmap now:

Creating process: xw for queue 9797635

Data area:          WV
Graphics area name: WV
Parameter colors:     1    1    1    1    0    1    1
Time:              910820/0600
File:              $GEMPAK/data/hrcbob.sfc
Map:               1
Title:             1
Device:            XW
Projection:        MER
Clear screen:      YES
Filter:            YES
Filter factor:      1.00
Panel:             0 
Enter <cr> to accept parameters or type EXIT:

Press once more to display the map:


The X window will display surface observations from "Hurricane Bob" in 1991, centered around West Virginia.

Adjusting AREA and GAREA

GAREA is the graphics area: the part of the map that will be plotted. AREA is the data area: the area from which to select the data to plot. These areas exist separately for when you might want individual control over both the region of the map that is plotted (GAREA) and the region that is covered by data (AREA).

Both are defined by the same syntax (below), but can be defined a number of different ways:

  1. Lat/Lon

     AREA = 25;-125;50;-65        

    defines the corners Lat 1; Lon 1; Lat 2; Lon 2 of the form LL (1); UR (2).

    Be aware that South and West are negative!

  2. Center/Offset

     AREA = #37.5;-95;12.5;30       

    In the form #Center lat; Center lon; Delta lat; Delta lon

  3. Geographic Area (defined in the GEMPAK geography table $GEMTBL/stns/geog.tbl)

     AREA = US      the region around the United States.  
     AREA = MX      the region around Mexico      
     AREA = CO      the region around Colorado.
     AREA = @CO     only information inside Colorado.
     AREA = @AU:C   Australia (use :C syntac for countries
                      other than US, CN and MX)
  4. Station Area and Station Name

     AREA = LAX     the region around Los Angelos
     AREA = @DEN    only information from the Denver station
                     only Denver, LA and Portland stations
  5. Full Data Set (all stations in the file)

     AREA = DSET     
  6. Contracted and Expanded Areas

     AREA = CO+      AREA is contracted around CO
     AREA = CO++     AREA is contracted further around CO
     AREA = CO-      AREA is expanded beyond CO
     AREA = @CO--    AREA is expanded even more, but only includes
                      information inside Colorado
  7. Integer Value (stations are selected if they fall into the range indicated)

     AREA = SELV:0:2000   Selects stations with elevations
                          between 0 and 2000 meters                    
     AREA = SLAT:-45:45   Selects stations located between 45 
                          degrees south and 45 north           
     AREA = SLON:-45:45   Between 45 west and 45 east

Any station information can be used in this way:

If you want to plot a map with complete data coverage, including the edges, you should make AREA bigger than GAREA. This can be done by adding a minus - to AREA or a plus + to GAREA:

    GEMPAK-SFMAP> area = wv-
    GEMPAK-SFMAP> garea = wv

MAKE NOTE GAREA can be specified in some of the same ways as AREA, with one caveat: You can not use the @ symbol to specify GAREA.

Because GAREA defines the boundaries of the graph, adding @ would force an irregular boundary. Think of the @ sign as a way to restrict the selection of data.

SFPARM Surface Parameters

Multiple surface parameters may be defined in SFPARM by entering a list separated by semicolons:

sfparm = tmpc;pmsl;skyc

GEMPAK can also calculate a number of parameters if the requested parameter is not present in the data set, for example, such as with relative humidity, which GEMPAK determines from a function defined internally as RELH=FUNC (TMPC;DWPT).

sfparm = RELH 

Arithmetic functions and upper and lower limits may be used in the paramater definition:

sfparm = tmpc/2    
sfparm = pmsl>1000      

where pmsl>1000 restricts sea-level pressure records to those below 1000 mb,

You can manipulate the values of parameters using the following arithmetic functions:

Raw hourly and special reports (if stored in a file) can be accessed as well:

sfparm = text
sfparm = spcl
sfparm = text;spcl
sfparm = pmsl;tmpc;wthr;text

For now, to continue with our SFMAP example, set sfparm back to:


Date and Time

DATTIM is date and time, formatted in a number of ways:

  1. Explicit, for all observations at time YYMMDD/HHMM:

     DATTIM = 101025/1200        
  2. Abbreviation, for the last available date and/or time specified:

     DATTIM = 25/1200      DD/HHMM        
     DATTIM = 25/12        DD/HH    
     DATTIM = /1200        /HHMM
     DATTIM = 12           HH
  3. Range, for all observations between the two date/time ranges:

     DATTIM = 17/00-17/1200
  4. List, for all available observations that match the exact date/times listed:

     DATTIM = 17/00;17/06;17/12   
  5. List, for all times in the file, useful for when you don`t know the times when the data was collected:

      DATTIM = list     
  6. Last, for observations from the last date/time in the file:

     DATTIM = last                 
  7. All, for observations from every date/time in the file, useful for comprehensive analyses:

     DATTIM = all

What happens when we change DATTIM = all for sfmap:


If DEVICE = xw you should see an animation through all times in the file. If DEVICE = gif you'll see stations plotted multiple times to the map if CLEAR = no is defined.

Clearing the Map Window

CLEAR is a logical variable which determines whether the graphics screen is cleared before plotting.

  1. CLEAR = YES (or CLEAR = y for short) will clear the window of all previously-drawn graphics before plotting what has been specified.
  2. CLEAR = NO (or CLEAR = n) will draw what is currently specified over any previously-drawn graphics.

With CLEAR = n, you have the ability to overlay observations, images, maps and various vector and scalar quantities, depending on the GEMPAK program being used. Additionally, because GEMPAK mapping programs operate within one gplt process (until gpend is called from the command line), you can overlay fields on the same map projection using multiple programs!

Map Projections

PROJ determines the map projection, and directly affects the way the map looks on the screen. PROJ and GAREA together give you the flexibility to generate very specific map projections. Both simple map projections and full map projections are avaiable to select:

  1. Simple Map Projections

    Simple map projections only require the three-character identifier to be defined:

     proj = mer

    Available simple map projections:

     MER     Mercator
     NPS     North Polar Stereographic
     SPS     South Polar Stereographic
     LCC     Northern Hemisphere Lambert Conic Conformal
     SCC     Southern Hemisphere Lambert Conic Conformal
     CED     Cylindrical Equidistant
     MCD     Modified Cylindrical Equidistant
     UTM     Universal Transverse Mercator
     NOR     North Orthographic 
     SOR     South Orthographic 
  2. Full Map Projections

    For full map projections, each definition MUST be followed by three specified angles based on the projection class (CYL,AZM, CON), which are defined like so:

     proj = STR/a1;a2;a3
     proj = STR/90;-100;0

    You can read about these angles and projections in more detail on the PROJ parameter page.

    Available full map projections:

     MER (CYL)   Mercator
     CED (CYL)   Cylindrical Equidistant
     MCD (CYL)   Modified Cylindrical Equidistant
     STR (AZM)   Polar Stereographic
     AED (AZM)   Azimuthal Equidistant
     ORT (AZM)   Orthographic
     LEA (AZM)   Lambert equal area
     GNO (AZM)   Gnomonic
     LCC (CON)   Northern Hemisphere Lambert Conic Conformal
     SCC (CON)   Southern Hemisphere Lambert Conic Conformal

Exercise #2 (Overlay Satellite Image)

Display the visible satellite image from 18Z and overlay the surface data for the area covered by the image. Plot a standard station model for each location in the data set. The surface data to plot include:

  1. sky cover symbol
  2. temperature in Fahrenheit
  3. weather symbol
  4. coded mean sea level pressure
  5. pressure tendency with symbol
  6. dewpoint in Fahrenheit
  7. station ID
  8. wind barbs in knots

Therefore, the surface parameters used would be

SFPARM = skyc; tmpf; wsym; smsl; ptnd; dwpf; stid;; brbk

and colors

COLORS = 26; 2; 7; 25; 20; 22; 18; 6

    AREA     =  us
    GAREA    =  dset
    SATFIL   =  $GEMPAK/data/VIS_910819_1801
    RADFIL   =  
    IMCBAR   =  
    SFPARM   =  skyc;tmpf;wsym;smsl;ptnd;dwpf;stid;;;brbk
    DATTIM   =  910819/1800
    SFFILE   =  $GEMPAK/data/hrcbob.sfc
    COLORS   =  26;2;7;25;20;22;18;6
    MAP      =  1
    LATLON   =  
    TITLE    =  1
    CLEAR    =  yes
    PANEL    =  0
    DEVICE   =  xw
    PROJ     =  sat
    FILTER   =  1
    TEXT     =  0.75/22//hw
    LUTFIL   =
    STNPLT   =
    CLRBAR   =
    LSTPRM   = 

COLORS, MAP, TITLE, FILTER and TEXT control the graphic colors, line thickness, style, text fonts and titles. These map aesthetics allow you to generate very specific graphics. Check the parameter definition pages in the manual for more detail, or with the phelp command at the GEMPAK prompt.

After running sfmap, you can see how the colors match the surface parameters:

 Parameter colors:    26    2    7   25   20   22   18    0    0    6 


Save your session! In the sfmap command prompt, you can save the current definitions with the command

  GEMPAK-SFMAP>save bob.nts

then exit the program and check that the file exists

  ls -la
  -rw-r--r--    1 gempak  staff      3151 Oct 29 14:38 bob.nts

You can reload this file in any other GEMPAK program, at any time, to retrieve the saved definitions, though only the variables which were saved in sfmap will be reloaded:

  GEMPAK-SFMAP> restore bob.nts

Exercise #3 (Live Data)

Now let's look at data from today. Using an alias for real-time metar observations SFFILE = metar, and DATTIM = 1200, we can redisplay the map for this morning.

Make note of what the two new definitions are doing to retreive observations:

  1. The SFFILE = metar definition uses an alias to the latest GEMPAK metar surface file (typically $GEMDATA/surface/YYYYMMDD_sao.gem, where YYYYMMDD is the current year, month and day, such as 20121028).
  2. DATTIM = 1200 uses only the 1200 UTC records in SFFILE

But how to know the latest available? Exit SFMAP and return to the terminal, and execute the command line program sfctime metar and you will see surface reports in today's GEMPAK surface file for every twenty minutes:

> sfctime metar

Inside our sfmap session, let's define a new AREA, GAREA, and PROJ:

 AREA     = us-
 GAREA    = us
 SFFILE   = metar
 DATTIM   = last
 SATFIL   = 
 CLEAR    = y
 PROJ     = STR/90;-100;0


Also note: the position of parameters in a list,

  SFPARM   = skyc;tmpf;wsym;smsl;ptnd;dwpf;stid;;;brbk
              1    2    3    4    5    6   7       10

correspond to chart position:

    18      14      8       16      22
    19      2       10      4       23
    12      3       1       5       13
    20      6       11      7       24
    21      15      9       17      25

which also corresponed to the standard ordering of data on a surface chart:


To overlay the current GOES satellite visible image on your map, you must explicitly define SATFIL. To find the latest EAST-CONUS visible satellite image, list the contents of $SAT/EAST-CONUS/1km/VIS/ with the command:

ls $SAT/EAST-CONUS/1km/VIS/ | tail -1

then use the entire path name for SATFIL (evironmental variables allowed):

GAREA    = dset
PROJ     = sat
SATFIL   = $SAT/EAST-CONUS/1km/VIS/VIS_20121029_2132
DATTIM   = last

Make Note:

  1. When using SATFIL or RADFIL, you must set PROJ either to sat or rad.
  2. with DATTIM = last, there may not be any surface observations available in the last timeslot in the file referenced by metar. If this is the case, explicitly define DATTIM using the a previous 20 minutes interval (i.e. 1140, 1200, 1220).
  3. This method of finding a recent satellite image to overlay is cumbersome! We will soon explore how shell scripting can manage the latest files and images for your GEMPAK programs with ease.
  4. Always run gpend after finishing a GEMPAK graphics program session.

GEMPAK Online Tutorial | Next: Sounding Data Mapping