WXP version 5
User's Guide

Variable Files

Most plotting is done by specifying a variable to plot. The variable is then used by the program to select data from the input data file. In general, the type of output is specified by resources such as plot_type, color_data, or plot_format. In its simplest form, the variable file acts just the same as the time and level menu files.  The biggest difference is the last column which represents the variable information. This column allows for variable aliasing, composite plots and overlay products.

Each program that uses the variable resource and/or has a variable menu has its own .var file. For example, sfcwx has a variable file named sfcwx.var.  The program then parsing this file to determine how to process each variable request.  

Variable File Syntax

This file is a list of variables and each variable has a list of commands which specify which variable to plot and how to plot it. The syntax of each line in the file is:

   Abbrev    Name      Toggle   Definition

A simple entry will look like:

temp   Temperature           1 anal:sfc:temp  [F]

where:

Here is a sample variable file.

temp   Temperature           le=~snd&le=~sfc  temp         [C]
stemp  Temperature           le=sfc           :2m_ag:temp  [C]
t_rh   Temp_Rel_Hum          0                temp,rhum
dewp   Dewpoint              le=~snd&le=~sfc  dewp(t_rh)   [C]
sdewp  Dewpoint              le=sfc           :2m_ag:dewp(t_rh)   [C]
wind   Winds                 le=~snd&le=~sfc  wind<uwnd,vwnd> [m/s:wind]
swind  Winds                 le=sfc           wind<:10m_ag:uwnd,:10m_ag:vwnd> [m/s:wind]
wind8  Winds                 0                wind<:850:uwnd,:850:vwnd> [m/s:wind]
wind3  Winds                 0                wind<:300:uwnd,:300:vwnd> [m/s:wind]
wdir   Wind_Direction        le=~snd          dir(wind)    [deg]
wspd   Wind_speed            le=~snd          spd(wind)    [knt]

Variable Definitions

The variable definition is a quite powerful tool for defining variables, aliasing variables, generating composite, overlay and multipanel plots. The syntax of the definition is:

   time:level:variable[units:attributes...]
   variable[units:attributes...]

The sections of the definition are:

The variable definition can be up to 1000 characters long, can include spaces for readability and can span lines (as long as "\" is the last character of the line).  Also, the time and level can be omitted, assuming program defaults (normally the values of the time and level resources).

The definition can also specify functions, vectors and composite plotting. 

The resulting plot will be labeled based not on the menu listing but on the variable to plot. This is looked up in the variable.lup file which should cross-reference the variable name "temp" with a full name such as in "Temperature".  The program will then tack on the units to produce a final label of "Temperature (F)".

Simple Variables

The default output of a variable is integral.  In some cases like altimeter setting, plotting to 2 decimal places is required. This can be established using a plot attribute:

alt    Altimeter_Setting     1 alt  [:%.2f]

The output format uses a standard C printf floating point format. 

In some cases, the data might be not numeric. This is the case with cloud cover which can be a string such as "B" for broken. To plot the data rather than the value, specify a plot type of data:

cldcv  Cloud_Cover           1 cldcv [:data]

It is also possible to plot the cloud cover as a symbol.  WXP provides a couple of default symbols such as cloud cover and wind barbs.  To plot symbols, just specify a different plot type:

cldcv  Cloud_Cover           1 cldcv [:cloud]

In some cases, WXP does not provide symbols directly. To handle this, there is a symbol file which cross-references the data with a list of drawing commands. In one case, present weather, there is a plot type (wx) that will read in and use the symbol file wx.smb. In other cases, it must be explicitly specified.   Notice, the plot type is still "wx" but that a different symbol file (or weather file) is specified.

ptype  Pressure_Tendency     0 ptend [mb/3hr:wx:wf=ptend.smb]

Composite overlays

In some cases, it is nice to be able to define new plot types as composites of several variables. The variable definition then becomes a list of variables, separated by commas.

lmhcd  Clouds                0 city      [:mk=pnt],\
                               lcld      [:wx:wf=cl.smb:xy=0-.5],\
                               mcld      [:wx:wf=cm.smb:xy=0+.5],\
                               hcld      [:wx:wf=ch.smb:xy=0+1]

This specifies a set of variables to plot. First, the city location will plot as a point (mk=pnt attribute). Then, the low, medium and high clouds will plot as symbols, each using a specific symbol file which cross-references the value to a set of plotting commands. In order to keep each plot from overlapping, an x,y offset is applied to the plot. The offset is normalized so that 1 is roughly the vertical size of text plotted on the screen. 

The problem with the above plot is that the label that appears on the plot lists all of the variables.  It would be nice to have a composite plot with only one label like "All Data". This is accomplished by enclosing the variables in braces "var{var1,var2,...}".   Only the first variable var is looked up in the variable.lup file.  In this case, it will plot "All data".

all    All_Data              1 all{\
                                  +temp      [F :ul],\
                                  +dewp      [F :ll],\
                                  :sl:+pres  [mb:data:ur],\
                                  +wbrbc     [  :cbarb],\
                                  +cldcv     [  :cloud],\
                                  +wx        [  :wx:cl]}

This will plot temperature upper left (attribute ul), dewpoint lower left, sea level pressure upper right, wind barbs (plot type cbarb plots a barb but allows for a cloud cover symbol), cloud cover symbols (plot type cloud) and present weather (plot type wx).  The plusses in front of the variable name will be explained later.

When using this with the statlog program, composite plotting can also be used to put more than one variable on a graph.

all    All_Data              1 temp {temp,dewp} [F  :plot:sz=.18],\
                               extt             [F  :value],\
                               wx               [   :wx],\
                               snwdp            [in :value],\
                               prec             [in :value:%.2f],\
                               vis              [mi :value],\
                               wgst             [knt:value],\
                               wind { \
                                 wind           [knt:cbarb],\
                                 cldcv          [%  :cloud] },\
                               cld              [ft :plot:sz=.14],\
                               cldcl            [100_ft:data],\
                               pralt            [mb :plot:sz=.14]

In this case, the temperature and dewpoint are plotted on the same graph and the attribute information "[F  :plot:sz=.18]" refers to the plot and not each individual variable.  A new plot type is introduced.  "plot" specifies that this will be a plotted graph.  There is one other example of compositing. The wind section includes both wind and cldcv which will produce a standard cloud cover and wind barb. If this is not specified, the cloud cover and barbs will plot on separate lines.

Overlay plots

Overlay is the ability to put two or more plots on the plot and the same time.   This is often used with contour plots but can be plotted data over a contour plot:

comp1  Composite_1           0 temp     [:cf:in=5],\
                               strm     [:co=black],\
                               cldcv    [:co=black]

Again, multiple variables are specified separated by commas.  In this case, temperature is contoured (plot type color fill cf) with an interval of 5, overlaid with streamlines, colored in black and cloud cover symbols in black.

Complete plots can be specified but the more complex the plot, the more control is needed. In some cases, the map needs to be specifically plotted:

cpres  Composite_Surface     le=snd  prec  [in:cf:cof=prec.cfl:bar:labs],\
                                     map   [  :co=red],\
                                     slp   [mb:ln:co=lcyan:in=4],\
                                     thk   [m :ln:cof=thick.cfl:co=off:cb=5400:in=60]

In this case, 4 variables are being plotted. 

  1. prec -- quantitative precipitation in inches, plotted as a color fill contour (cf), using a specific color fill file which lists the values and colors (cof=prec.cfl), labeling the plot with a color bar (bar) and specifying to use short text labels in upper left (labs).
  2. map -- overlay the map in red (co=red)
  3. slp -- overlay the sea level pressure plotted in millibars, using light cyan (co=lcyan) line contours (ln) at an interval of 4 (in=4).
  4. thk -- overlay 1000-500 mb thickness in meters, plotted as line contours, line styles defined in the thick.cfl file (cof=thick.cfl), colors turned off to force use of thick file (co=off), contour base set to 5400 to make sure solid line appears at value 5400 (cb=5400) and a contour interval of 60 (in=60).

This example is also using variable aliasing.  The variables prec, slp, and thk are defined elsewhere in the variable file. This will be discussed later.

Plotting Attributes

For a full list of possible attributes, see the following pages:

Variable Aliasing

In order to simplify the variable file, variable aliasing is possible. What aliasing does is allow the user to specify a variable that is defined elsewhere in the variable file.  Taking the above example, the variable prec, slp and thk are actually:

prec   Quant_precipitation   le=snd   prec          [in]
slp    Sea_level_pressure    le=snd   :sl:pres      [mb]
thk    1000-500_mb_thickness le=snd   :p1000-500:thick (:500:hght:m,:1000:hght:m)[m]

The variable in this case is also prec but if the variable abbreviation matches the variable type, no further searching is done. In the case of sea level pressure, it is actually pressure at sea level. For thickness, this is actually 1000 mb height and 500 mb height run through the function thick. That function will just difference the two grids. The function thick has a specific level designation in order to format the label properly The function name is looked up in the variable.lup file to get a full label.  The resulting label would be:

1000-500 mb Thickness (m)

In some cases, aliasing can have side effects. To prevent aliasing, add a plus "+" in front of the variable name. This forces the program to immediately search internal variables rather than a recursive search of the variable file. This also clarifies the difference between aliases and real variables.

wdir   Wind_Direction        1 +wdir     [deg]

In this case, "wdir" can be used as an alias elsewhere in the file but "+wdir" tells the program to use the internal variable "wdir" and not the alias.

Vectors

In some cases, grids need to be grouped in order to represent vector quantities.   This is done by enclosing the components in "var<var1,var2>". The variable var is only used to name the plot.  The variables var1 and var2 define the X and Y components of the vector. This is handy for defining wind as a vector quantity.

wind   Wind_vectors          le=~snd&le=~sfc wind<uwndg,vwndg> [m/s:wind]

This defines a wind vector based on grid relative U and V wind components. The alias wind can then be used elsewhere to represent these components.  For example, convergence:

conv   Convergence           le=~snd     conv(wind)            [10^-5_/s]

This will apply the function conv (convergence) to the grid relative U and V wind components. This simplifies the use of vector quantities and makes the variable file more readable.

Functions

Often simple variables do not cover all the possible variable types.  In the case of grids, functions can be applied to create new variables.

tadv   Temperature_Advection le=~snd     adv(wind,temp:K)      [10^-4_K/s]

The advection function adv takes 3 parameters: U, V and a parameter to advect. The U and V are represented by the variable wind which is a vector field defined elsewhere in the variable file. With many of the functions, the program will make an attempt to produce a label. In the case of advection, it produces a label like "Surface Temperature Advection (10^-4_K/s)".   In other cases, the name must be forced.  For example, the advection function could have been listed as "adv-tadv". This will run the adv function but it will use the variable tadv to lookup a label from the variable.lup file.

Some functions can get quite elaborate:

p10ht  1000_mb_height        0 :p1000:mul-hght (sub  (slp:mb, #1000), #8.4) [m]

This computes an estimated 1000 mb height based on sea level pressure. This can now be used in a pseudo-thickness computation:

pthk   1000-500_mb_thickness 0 :p1000-500:thick (:500:hght:m, p10ht) [m]

Here is an example of wind shear:

wind8  Winds_850             0 wind<:850:uwnd,:850:vwnd> [m/s:wind]
wind3  Winds_300             0 wind<:300:uwnd,:300:vwnd> [m/s:wind]
shr83  Shear                 0 vdiff(wind3,wind8)
mshr83 Mag_Shear             0 mag(shr83)

In this case, a shear value is computed. The variable shr83 is a vector quantity that can be plotted as vectors or streamlines. The variable mshr83 is the magnitude which can be contoured.

Function List

NOTE: The grid specifications can be replaced by numeric constants with the syntax: 

  #number

in most of the above functions.  For example, the number 5.32 would be entered "#5.32".

Panel Plots

Overlay plots put one plot on top of another.  The panel option allows plots to be separated into 4 or 6 panels.  The attributes for the panel option are the panel size and location information:

A sample panel setup:

c4p    Composite_4_panel     0 panel       [.5x.5+0+0],\
                                  c850,\
                               panel       [.5x.5+.5+0],\
                                  c700,\
                               panel       [.5x.5+0+.5],\
                                  c500,\
                               panel       [.5x.5+.5+.5],\
                                  c300

This will generate a 4 panel plot of composite plots.  The upper left panel will be a composite 850 plot. The upper right panel will be a composite 700 mb plot. The lower left panel will be a composite 500 mb plot.  The lower right panel will be a 300 mb composite plot.

Last updated June 9, 1998

Vietor Weather
Email (support) to obtain more information about this web site.
Server: devoweb