Enter a ZIP code to get a forecast:
Setup Location

WRN Logo

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
  • Abbreviation - This define an abbreviation which is used to define the variable for use in the variable resource.
  • Name - this is the text to be used in the menu listing. No spaces are allowed but underscores "_" can be used in their place.
  • Toggle - this is a menu toggle which defines when the menu item will appear.  This can be one of the following:
    • 1 -- the item always appears
    • 0 -- the item never appears. This is not useful in a menu file but is in a variable file.
    • mo=model -- a model type. This is the string specified by the model resource.
    • ft=time -- a forecast time. This is a string either specified by the time resource or at the time menu prompt
    • le=level -- a vertical level.  This is a string either specified by the level resource or at the level menu prompt

    Wildcard characters are permitted.   Each of the above strings can be logically and'd or or'd.

    . or ? match a single character
    * match any character
    [letters] match a single character from the set.
    [^letters] match any character except those from the set.
    str match string
    ~str true if doesn't match string
    str1|str2... match a set or strings (logical or). Pipe "|" separates strings
    str1&str2... match all strings (logical and). Ampersand "&" separates strings
    _ underscore matches a space.
  • Definition -- This defines which variable will be plotted and how it is to be plotted. The syntax of the definition is:

    time:level:variable:units:attributes...

    The syntax of this is explained below.

A simple entry will look like:

temp   Temperature           1 anal:sfc:temp  [F]

where:

  • temp -- is the name used for the variable resource "-va=temp".
  • Temperature -- is the menu label which will show up in the variable menu
  • 1 -- specifies that temperature will always appear in the menu
  • anal:sfc:temp[F] -- is the variable definition.  This states that an analysis of surface temperature in Fahrenheit will be plotted.

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:

  • time -- This is the forecast time that the variable is valid. This uses a standard time reference (see time resource)
  • level -- This is the level that the variable is valid. This uses a standard level reference (see level resource)
  • variable -- This is the variable to plot.  This can either be a variable defined in the program (internal variables), in the file (GRIB variables) or a reference to another variable in the variable file (variable aliasing).
  • units -- This is the units to plot the variable in.  The program will recompute the variable with the new units prior to plotting.
  • attributes -- This defines how the variable will appear on the plot. This defines the plot type, colors, etc.

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

  • max(grid1,grid2)
    Computes the maximum value at each gridpoint based on the values in the grids grid1, grid2, etc.  More than two grids can be listed
  • min(grid1,grid2)
    Computes the minimum value at each gridpoint based on the values in the grids grid1, grid2, etc.  More than two grids can be listed
  • sum(grid1,grid2)
    Computes the sum of each gridpoint based on the values in the grids grid1, grid2, etc.  More than two grids can be listed.
  • add(grid1,grid2)
    Same as sum
  • avg(grid1,grid2)
    Computes the average at each gridpoint based on the values in the grids grid1, grid2, etc.  More than two grids can be listed
  • interp(grid1,grid2|value,grid3)
    This interpolates between the grid specified in grid1 and the grid in grid3 based on the value specified either in grid2 or the value.  This does a simple linear interpolation.  A value of .5 would essentially give an average.  A value of .8 will return a value that is .8 of the way to the second grid.
  • sub(grid1,grid2)
    This subtracts grid2 from grid1.
  • thick(grid1,grid2)
    Same as sub
  • mul(grid1,grid2)
    Multiplies the grids in grid1 and grid2.
  • div(grid1,grid2)
    Divides the values in grid1 by the values in grid2.
  • mod(grid1,grid2)
    Does the modulus of grid1 divided by grid2.  This produces the remainder of the division computation.
  • sqrt(grid1)
    Does the square root of all values in grid1.
  • abs(grid1)
    Returns the absolute value of the values in grid1.
  • log(grid1)
    Takes the logarithm of each value in grid1
  • log10(grid1)
    Takes the logarithm base 10 of each value in grid1
  • exp(grid1)
    Exponentiates (ex) the values in grid1 .  This is the inverse of the log function
  • pow(grid1,grid2)
    This performs for power function of the values in grid1 raised to the power of the values in grid2.
  • sin(grid1)
    Performs the trigonometric function sine of the values in grid1.  Input values are in degrees
  • cos(grid1)
    Performs the trigonometric function cosine of the values in grid1. Input values are in degrees
  • tan(grid1)
    Performs the trigonometric function tangent of the values in grid1.  Input values are in degrees
  • asin(grid1)
    Performs the trigonometric function arcsine of the values in grid1.  Output values are in degrees
  • acos(grid1)
    Performs the trigonometric function arccosine of the values in grid1. Output values are in degrees
  • atan(grid1)
    Performs the trigonometric function arctangent of the values in grid1.  Output values are in degrees
  • atan2(grid1,grid2)
    Performs the trigonometric function arctangent of the values in grid1 divided by grid2.  The sign of 2 values determines the quadrant.  This is the equivalent of the C atan2 function. Output values are in degrees
  • dewp(grid1,grid2)
    Computes the dewpoint based on temperature in grid1 and the relative humidity in grid2
  • rhum(grid1,grid2)
    Computes the relative humidity based on temperature in grid1 and the dewpoint in grid2
  • wetblb(grid1,grid2)
    Computes the wetbulb temperature based on temperature in grid1 and the relative humidity or dewpoint in grid2.
  • wchill(grid1,grid2,[grid3])
    Computes the wind chill temperature based on the temperature in grid1 and wind speed in grid2, or the U wind component in grid2 and the V wind component in grid3.
  • heat(grid1,grid2)
    Computes the heat index temperature based on temperature in grid1 and the relative humidity or dewpoint in grid2.
  • theta(grid1,[grid2])
    Computes the potential temperature based on temperature in grid1 and the pressure in grid2.  The pressure is optional if grid1 is on a pressure surface (ie 500mb).
  • thetae(grid1,grid2,[grid3])
    Computes the equivalent potential temperature based on temperature in grid1, the relative humidity or dewpoint in grid2 and the pressure in grid3.  The pressure is optional if grid1 is on a pressure surface (ie 500mb).
  • thetav(grid1,grid2,[grid3])
    Computes the virtual potential temperature based on temperature in grid1, the relative humidity or dewpoint in grid2 and the pressure in grid3.  The pressure is optional if grid1 is on a pressure surface (ie 500mb).
  • vtemp(grid1,grid2,[grid3])
    Computes the virtual temperature based on temperature in grid1, the relative humidity or dewpoint in grid2 and the pressure in grid3.  The pressure is optional if grid1 is on a pressure surface (ie 500mb).
  • vapor(grid1,[grid2])
    Computes the vapor pressure based on dewpoint in grid1, or the temperature in grid1 and the relative humidity in grid2.
  • shum(grid1,[grid2],[grid3])
    Computes the specific humidity based on dewpoint in grid1 and pressure in grid2, or temperature in grid1, relative humidity in grid2 and pressure in grid3. The pressure is optional if grid1 is on a pressure surface (ie 500mb).
  • mixrat(grid1,[grid2],[grid3])
    Computes the mixing ratio based on dewpoint in grid1 and pressure in grid2, or temperature in grid1, relative humidity in grid2 and pressure in grid3. The pressure is optional if grid1 is on a pressure surface (ie 500mb).
  • spd(grid1,grid2)
    Computes the wind speed based on U wind component in grid1 and the V wind component in grid2.
  • mag(grid1,grid2)
    Computes the vector magnitude based on X component in grid1 and the Y component in grid2.
  • dir(grid1,grid2)
    Computes the vector/wind direction based on X/U wind component in grid1 and the Y V wind component in grid2.
  • ugeos(grid1)
    Computes the U geostrophic wind component based on geopotential height in grid1.
  • vgeos(grid1)
    Computes the V geostrophic wind component based on geopotential height in grid1.
  • uq(grid1,grid2)
    Computes the U Q-vector component based on geopotential height in grid1 and temperature in grid2.
  • vq(grid1,grid2)
    Computes the V Q-vector component based on geopotential height in grid1 and temperature in grid2.
  • dx(grid1)
    Finite differences (dgrid1/dx) the grid grid1 in the X direction.
  • dy(grid1)
    Finite differences (dgrid1/dy) the grid grid1 in the Y direction.
  • grad(grid) => xgrid ygrid
    Gradient of the grid.  Outputs 2 grid vector, one for the X component and the second for the Y component.
  • vdiff(xgrid1,ygrid1,xgrid2,ygrid2) => xgrid ygrid
    Computes a vector difference. Outputs 2 grids: X and Y.
  • dot(xgrid1,ygrid1,xgrid2,ygrid2)
    Computes a dot product.
  • cross(xgrid1,ygrid1,xgrid2,ygrid2) => xgrid ygrid
    Computes a vector cross product. Outputs 2 grids: X and Y.
  • lapl(grid1)
    Computes the Laplacian of grid1.
  • conv(grid1,grid2,[grid3])
    Computes the convergence of the vector/wind field based on the U wind component in grid1 and the V wind component in grid2.  If grid3 is specified, the convergence is done on the grid field in grid3.
  • diverg(grid1,grid2,[grid3])
    Computes the divergence of the vector/wind field based on the U wind component in grid1 and the V wind component in grid2.  If grid3 is specified, the divergence is done on the grid field in grid3.
  • def1(grid1,grid2)
    Computes the first deformation term of the vector/wind field based on the U wind component in grid1 and the V wind component in grid2.
  • def2(grid1,grid2)
    Computes the second deformation term of the vector/wind field based on the U wind component in grid1 and the V wind component in grid2.
  • rvort(grid1,grid2)
    Computes the vorticity or curl of the vector/wind field based on the U wind component in grid1 and the V wind component in grid2.
  • avort(grid1,grid2)
    Computes the absolute vorticity of the wind field based on the U wind component in grid1 and the V wind component in grid2.
  • adv(grid1,grid2,grid3)
    Computes the advection of a specified field in grid3 by the wind with the U wind component in grid1 and the V wind component in grid2.

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:

  • nxxny[+x+y]
    These coordinates represent the relative panel coordinates. The nx and ny represent the number of plots in each direction. The x and y are the offsets measured from the upper left. For example, to produce a 4 panel plot (2x2) and the current plot is the lower left, the geometry would be:
       2x2+0+1
  • dxxdy[+x+y]
    These coordinates represent the fractional panel coordinates. The dx and dy represent the fraction of the overall window ( 0 < dx < 1)   the panel will use. The x and y are the offsets measured from the lower left. For example, to produce a 4 panel plot (2x2) and the current plot is the upper left, the geometry would be:
       .5x.5+0+.5

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.


For further information about WXP, email technical-support@weather.unisys.com
Last updated by Dan Vietor on June 9, 1998