# 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.

**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**).**map**-- overlay the map in red (**co=red**)**slp**-- overlay the sea level pressure plotted in millibars, using light cyan (**co=lcyan**) line contours (**ln**) at an interval of 4 (**in=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 (e

^{x}) 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 (

**d***grid1*/**dx**) the grid*grid1*in the X direction.**dy****(***grid1***)**Finite differences (

**d***grid1*/**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:

*nx*[**x**ny**+***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***dx*[**x**dy**+***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 devo@ks.unisys.com

*Last updated by Dan Vietor on June 9, 1998*