UPCALC
Sections
NAME
upcalc - Upper air contouring program
SYNOPSIS
upcalc [parameters...] filename
PARAMETERS
| Command Line | Resource | Default | Description |
| -h | help | No | Lists basic help information. |
| -df=filename | default | .wxpdef | Sets the name of the resource file. |
| -na=name | name | upcalc | Specifies the name used in resource file parsing. |
| -ba | batch | No | Run program in batch mode |
| -me=level | message | out2 | Specifies level of messages to be displayed
|
| -fp=filepath | file_path | current directory | Specifies location of database files. |
| -dp=datapath | data_path | current directory | Specifies the location (path) of the input raw data files. This may be modified in the name convention file. |
| -cp=conpath | con_path | current directory | Specifies the location (path) of the input surface converted data files. This may be modified in the name convention file. |
| -rp=rawpath | raw_path | current directory | Specifies the location of the output raw files generated by the program. These files will not be generated unless the out_file resource is specified and the output is plotted data. |
| -gp=gridpath | grid_path | current directory | Specifies the location of the output grid files generated by the program. These files are not generated unless the out_file resource is specified and the output is a gridded field. |
| -ip=imagepath | image_path | current directory | Specifies the default location of the output GIF images generated by the program. |
| -nc=name_conv | name_conv | name_conv | The name convention file specifies how files are named in WXP. This sets which name convention file to use. |
| -if=in_file | in_file | upa_cvt | Specifies the input file name tag. The default is upa_cvt, but it can be modified to any value in the filename convention file. A full name convention can be specified as well. |
| -of=out_file[,out...] | out_file | None | Specifies what type of raw or grid file to create. By default, no output
file is generated when the program is run. To produce an output file, this resource
must be specified. There are the following output file types:
Second, the out_file resource specifies the output file name tag. The default is
upa_raw or upa_grd but it can be modified to any value in the filename
convention file. The file name tag can be specified separately or appended to the file
type: A full filename can be specified which can contain name convention tags. |
| -pf=file_param | file_param | User prompt Batch: use |
This specifies how to treat output files that exist:
|
| -cf=cityfile | city_file | upa.cty | Specifies the name of the city database file used in finding station locations. |
| -mf=mapfile[,...] | map_file | wxp.map or cont.dat, country.dat for domains outside North America |
Specifies the name of the map database file. Multiple maps can be specified along with attributes to describe how to draw the map. |
| -cu=[hour|la] | current | None | This specifies to use current data files. The current filename is based on the name convention. An optional hour can be specified for older data. If la is specified, the program will search back to find the most recent available file. |
| -ho=hour | hour | None | This resource specifies the exact hour that a data file is valid for. This locks in the start hour for a multi-file sequence. |
| -nh=num_hour | num_hour | 0 (no loop) | This specifies the number of hours that will be used in the plot. If this is not specified, a single hourly plot will appear. If this is specified, a loop of plots over this time will be generated. |
| -id=identifier | identifier | None | Used to plot a specific observation. If not specified, all stations will be plotted. |
| -pd=domain | plot_domain | User prompt Batch: first domain in wxp.reg file. |
This specifies the plotting domain. The projection, aspect ratio and the domain size are specified. |
| -gd=grid_domain | grid_domain | Same as plot domain | This specifies the domain to use when fitting data to a grid. If this is not specified, it is the plot_domain. |
| -re=region | region | Same as plot domain | This resource is synonymous with the plot_domain. |
| -pr=prior | stat_prior | Depends on domain size | This specifies the lowest priority to use in the plot. Priorities range from 1 to 7. |
| -le=level | level | User Prompt Batch: 500 |
This specifies the vertical level to use in the plot. See the level resource for more information on what can be specified. |
| -va=variable | variable | User prompt Batch: first variable listed in the upcalc.var file |
This specifies the variable to plot along with its formatting attributes. Multiple variables can be specified separated by commas for overlay plots. A list of valid variables is given below. |
| -oa=smooth[,radinf] [,passes] [,converg] [,min_sta] | object_param | 1,3,1,.2,1 | Specifies the objective analysis parameters. There are 5 parameters including smoothing, radius of influence, number of passes, convergence parameter and minimum number of stations. |
| -pl=plot_type | plot_type | User prompt Batch: fill contours or vectors |
Specifies the type of output plot. By default, the user is prompted for
the plot type. To produce a contour or vector plot, use the following plot types: Contours:
Vectors:
|
| -sc=scale_factor | plot_scale | 1.0 | Specifies a scaling factor for all plotted text, symbols, vectors, etc. |
| -fm=format | plot_format | None | Specifies the output format of the plots. This is generally used to specify how many decimal places get displayed on the plot and in the output raw files. |
| -pp=param[,param...] | plot_param | None | Specifies additional plotting parameters. See the plot_param resource for more details. |
| -dr=drawable[,...] | draw | all | Specifies which part of the plot is to be drawn. |
| -la=label[,...] | label | Program defaults | Specifies the labels to be plotted around the plot. By default, labels are generated by the program and plotted above and below the plot. This resource overrides these labels. |
| -in=interval | con_interval | None for plots, User prompt for grids. Batch: 0 | Specifies the contour interval to use in contouring grids. This can also be used to color code plotted data and vectors. |
| -cb=base | con_base | Lowest contour value, maximum wind speed | Specifies the base value for color fill contours, and wind speed per grid distance. For more details, see the con_base resource. |
| -fl=font_list | font_list | modern.fnt | Specifies a list of fonts to use in the plots. |
| -ct=color_table | color_table | wxp.clr | Specifies the color table to use in the plot. This maps color names to actual RGB color values. |
| -cot=color[:attr] | color_text | white black for inverse plots. |
Specifies the text color for labels above and below the plot. |
| -cod=color[:attr] | color_data | green | Specifies the color for plotted data. |
| -com=color[:attr] | color_map | red | Specifies the color for background maps. |
| -coln=color[:attr] | color_line | magenta:st=dsh | Specifies the color for lat/lon lines. |
| -cowd=color[:attr] | color_wind | white black for inverse plots. |
Specifies the color for wind barbs. |
| -cocm=color[:attr] | color_cmap | black | Specifies the color for color fill contour maps. |
| -coco=color[:attr] | color_cont | white black for inverse plots. |
Specifies the color for line contours. |
| -cof=[val:]color[:attr],... | color_fill | A predefined color set based on the wxp.clr color table | Specifies the color fill contour color set. See the color_fill resource for more details. |
| -cola=color[:attr] | color_label | white black for inverse plots. |
Specifies the line contour label color. |
| -cocl=color[:attr] | color_clabel | black | Specifies the color fill contour label color. |
| -de=device[,...] | device | User prompt Batch: display |
Specifies the output device. |
| -ti=title | title | Program name | Specifies the window title. |
| -ic | icon | Off | Specifies whether to open window in iconified mode. |
| -bg=color | background | black white for inverse plots |
Specifies the background color of the window. |
| -ge=geometry | geometry | 640x480 | Specifies the window and paper geometry. |
| filename[#seq] [filename[#seq]...] |
filename | None User Pompt Batch: current=la |
The name of the upper air converted data file to be plotted. An optional sequence number can be added to designate the time for non-WXP files. More than one file can be specified to generate a loop. |
DESCRIPTION
This program contours upper air data on a background map. The input to the program is a upper air converted file produced by the uacvt programs. Then, based on a plot domain and a variable selected by the user, a plot is generated. Overlay plots, plots and loops can also be generated if the appropriate options are set.
The programs starts off by prompting the user for input converted file name. The user may specify the input file either via the command line of through the current resource. The input naming convention is specified by the upa_cvt tag but this can be changed with the in_file resource. To generate a loop, the num_hour resource can be specified. This will tell the program to loop through this number of hours.
Next, the program prompts the user for the vertical level to plot. This is done through a level menu which has predefined levels and a prompt so the user can specify a level. The level resource can also be used. The levels are set up with the upairwx.lev file.
The domain defaults to the contiguous US unless changed through the plot_domain resource. The domain can be interactively changed using the mouse once the plot has been generated.
Next, the city database is read in and a cross-reference table is setup. Since converted data is not saved with location information, the program will refer to this table to location each station in the input file.
The program will now prompt the user for the particular output variable to plot. The program will show a menu of commonly used variables but many more are defined internally by the program and in the upcalc.var file. The internal variables are:
| Variable | Description and units | Plots |
| temp | Temperature (F) | value |
| dewp | Dewpoint (F) | value |
| dewd | Dewpoint depression (F) | value |
| wdir | Wind direction (deg) | value |
| wspd | Wind speed (knt) | value |
| wgst | Wind gust (knt) | value |
| wbrbc wbrb wind |
Wind speed and direction (knt) | value0=dir, value1=spd |
| uwnd | U wind component - EW relative (m/s) | value |
| vwnd | V wind component - NS relative (m/s) | value |
| uwndg | U wind component - grid relative (m/s) | value |
| vwndg | V wind component - grid relative (m/s) | value |
| hght | Geopotential height (m) | value |
| hag | Geopotential height above ground (m) | value |
| pres | Pressure (mb) | value |
| pag | Pressure above ground (mb) | value |
| vpres | Vapor pressure (mb) | value |
| mrat | Mixing ratio (g/kg) | value |
| shum | Specific humidity (g/kg) | value |
| rhum | Relative humidity (%) | value |
| wetblb | Wetbulb temperature (K) | value |
| thetaw | Wetbulb potential temperature (K) | value |
| thetae | Equivalent potential temperature (K) | value |
| thetav | Virtual potential temperature (K) | value |
| theta | Potential temperature (K) | value |
| vtemp | Virtual temperature (K) | value |
| thick | Thickness between two layers (m) | value |
| frz | Lowest freezing level (mb) -- height if units are km, m or ft | value |
| wb0 | Wet bulb zero (mb) -- height if units are km, m or ft | value |
| ccl | Convective condensation level (mb) -- height if units are km, m or ft | value |
| convt | Convective temperature (K) | value |
| pwat | Precipitable water (in) | value |
| maxt | Estimated maximum temperature (K) | value |
| tlapse | Potential temperature lapse rate (dK/m) | value |
| tlapsep | Potential temperature lapse rate over pressure (dK/mb) | value |
| lapse | Temperature lapse rate (dK/m) | value |
| ststab | Static stability (m^3/Pakg) | value |
| tlapse | Potential temperature lapse rate (dK/m) | value |
| lift | Lifted index (dC) -- parcel type dependent on level resource | value |
| cap | Cap strength (dC) -- parcel type dependent on level resource | value |
| lcl | Lifted condensation level (mb) -- parcel type dependent on level resource -- height if units are km, m or ft | value |
| lfc | Level of free convection (mb) -- parcel type dependent on level resource -- height if units are km, m or ft | value |
| el | Equilibrium level (mb) -- parcel type dependent on level resource -- height if units are km, m or ft | value |
| mpl | Maximum parcel level (mb) -- parcel type dependent on level resource -- height if units are km, m or ft | value |
| cape | Convective available potential energy (J/kg) -- parcel type dependent on level resource | value |
| cinh | Convective inhibition (J/kg) -- parcel type dependent on level resource | value |
| show | Showalter index (dC) | value |
| tt | Total totals index (dC) | value |
| vtot | Vertical totals index (dC) | value |
| ctot | Cross totals index (dC) | value |
| ki | K index () | value |
| sweat | Sweat index () | value |
| ei | Energy index (cal) | value |
| shear | Vertical wind shear (/s) -- layer can be adjusted with level resource | value |
| pshr | Positive - Vertical wind shear (/s) | value |
| nshr | Negative - Vertical wind shear (/s) | value |
| sdir | Estimated storm direction (deg) | value |
| sspd | Estimated storm speed (m/s) | value |
| dshr | Storm relative directional shear (deg) | value |
| hel | 0 - 3000 mb AG storm relative helicity (m^2/s^2) -- layer can be adjusted with level resource | value |
| ehi | Energy helicity index () | value |
| brn | Bulk Richardson number () | value |
| bshr | Bulk shear (m/s) | value |
These parameters can be accessed by name if they have not been redefined in the upcalc.var file. Otherwise, prepending a "+" to the variable name will guarantee these variables will appear.
There are several derived variables from this list which are defined in the upcalc.var file. These include composite plots, overlay plots and computed grids.
| Variable | Description | Plots |
| wind | A vector quantity of <uwndg,vwndg> | vector |
| vect | Wind vector plot | vector |
| strm | Streamline plot | vector |
| ugeos | U geostrophic wind component (m/s) | grid |
| vgeos | V geostrophic wind component (m/s) | grid |
| geos | Geostrophic winds -- vector quantity of <ugeos,vgeos> | vector |
| gspd | Geostrophic wind speed (m/s) | grid |
| ageos | Ageostrophic winds -- vector quantity | vector |
| avect | Ageostrophic wind vectors (m/s) | vector |
| uq | U component of the Q vector | grid |
| vq | V component of the Q vector | grid |
| qvect | Q vectors -- vector quantity | vector |
| qvconv | Q vector convergence | grid |
| spres | Station pressure (mb) | value |
| th50 | 1000-500 mb thickness (m) | value |
| mrat | Mixing ratio (g/kg) to 1 decimal place | value |
| shum | Specific humidity (g/kg) to 1 decimal place | value |
| conv | Wind convergence (/s) positive is convergence | grid |
| mconv | Moisture convergence (/s) | grid |
| rvort | Relative vorticity (/s) | grid |
| avort | Absolute vorticity (/s) | grid |
| tadv | Temperature advection (K/s) | grid |
| madv | Moisture advection (/s) | grid |
| vadv | Vorticity advection (/s^2) | grid |
The program will now open the graphics window and start processing the data. The user will be prompted for the output device. Then the converted file is opened and data read in. Any additional computations are performed to produce a derived variable and fit the data to a grid. The background map will plot first unless the output is a color fill contour in which the map plots last. The gridding process uses an objective analysis scheme to produce the grids. The parameters for this process are specified in the object_param resource. Once the grids have been created, the maximum and minimum of the grid are displayed for the user to pick an appropriate contour interval. Then, the contour or vector plot will display.
There are several plot types. For contour plots, there is:
- ln - line contours
- dln - dashed line contours
- ndln - negative dashed line contours. All contours less than 0 are dashed. The breakoff can be reset with the con_base resource.
- cf - color fill contours. These are contours where the areas between the contour lines are filled with a progressive color scheme. By default, this is a 15 color scale in which the colors wrap around if there are more than 15 color level. The color scheme can be set by the color_fill resource.
For vectors:
- vect -- vectors/arrows
- strm -- streamlines
- barb -- wind barbs
When the plot is complete, output can be saved to a GIF image file, spooled to the printer or the plot can be zoomed. When zooming the image, the plot will redraw to the new domain. It will also add more stations to the plot depending on the size of the domain. When the user is finished with the plot, the enter key can be hit which closes the window and returns the user to the variable prompt.
Output Files
By default, this program does not produce output files. If a raw or grid file output is desired, use the out_file resource to enable this. By default, this will create a WXP ASCII raw or grid file depending on the plot type. The out_file can be a filename, a file tag (lookup in file name convention file) or a name convention (with wildcards). The output can be GIF file by specifying gif as the file type. It may be desirable to turn plotting of when producing output files. To do this, specify none for the plot_type resource.
EXAMPLES
upcalc -cu=la -le=500 -va=temp -pl=cf -in=2 -de=d
This produces a color fill contour plot of 500 mb temperature for the contiguous US region at an interval of 2.
upcalc -cu=la -le=850 -va=hght -of=wxp -pl=none
This will generate grid file based on the upa_grd name convention. A specific filename can be used instead of wxp.
FILES
- upa.cty - the upper air station location database file
- upcalc.lev - level menu definition
- upcalc.var - variable menu and definitions
SEE ALSO
- uacvt - the upper air data decoding program
- upairwx - the upper air data plotting program
- uacalplt - the upper air sounding display program
Last updated July 30, 1998