PAVE User's Guide - Version 2.3
PAVE version 2.3 was released on October 18, 2004. See New Features in PAVE 2.3.0 for more information on the improvements made in this version. The last public release of PAVE was version 2.2 in June, 2004. For information on the improvements in version 2.2, please see New Features in PAVE 2.2.0 . Binary executables for the latest version of PAVE are available for IRIX 6.5 (SGI), Solaris 2.7 (Sun), Linux 2, and Windows 2000/XP (on PCs with Microsoft SFU (Services for Unix) and an X11 server such as Exceed or Cygwin/X with Lesstif installed). Operating system versions later than the ones specified should also work in most cases. Older versions of PAVE are available for HP-UX, AIX, and OSF1. PAVE can be recompiled for later versions of these operating systems by installing the libraries from older versions and then compiling the latest source code from the PAVE source code distribution. For information on obtaining and using PAVE, see the on-line PAVE Resources listed below.
PAVE is a product of the Center for Environmental Modeling for Policy Development at the University of North Carolina.
We hope you enjoy your PAVE visualizing experience!
On-line PAVE Resources
| Download PAVE |
| PAVE FAQs |
| PAVE User's manual as seperate chapters |
| Page for submitting bug reports, suggestions, and questions |
| Getting started with PAVE |
From left to right, these are examples of a smoothed tile plot, a 3D mesh plot, a time series line plot, and a time series bar plot.
From left to right, these are examples of a tile plot of a vertical cross section, a wind vector plot, and a scatter plot.
The Models-3/ EDSS Input/Output Applications Programming Interface (see http://www.baronams.com/products/ioapi for further info) provides an easy-to-learn, easy-to-use programming interface to files for the air quality model developer and model-related-tool developer, in both FORTRAN and C/C++. I/O API files are portable across computing platforms. This means that the same file can be read on a Sun workstation, a DEC Alpha workstation, and on a Cray supercomputer. If your data is not already in IO/API, UAM-IV, or UAM-V format, we recommend that you write a translation program to convert your data into IO/API format.
There is source code for three example conversion programs is included with the PAVE distribution. One of them converts an ASCII ROM dataset with a Lat/Lon map projection, and the other converts a binary SAQM dataset with a Lambert Conformal map projection, the third converts the standard AIRS AMP350 observational data format to the Models-3 I/O API format that PAVE requires. Note that you will need additional libraries, and possibly header files, in order to successfully compile this code. These libraries and header files can be found in:
<top level PAVE dir>/<platform type>/lib/*The example conversion code is in:
<top level PAVE dir>/doc/pave/convert_to_m3ioapi/rom_to_m3ioapi/* <top level PAVE dir>/doc/pave/convert_to_m3ioapi/saqm_to_m3ioapi/*The AIRS AMP350 convertor was first provided with the PAVE 2.1 release. It can be downloaded from the web site.
NOTE: these example codes will probably need to be adapted for use with your data files. They were written for specific data files being used for testing purposes, and were NOT originally intended to be cleanly written examples of how to easily convert generic gridded data data into PAVE format. However, they are being included here with the hope that you may find them useful.
One sometimes confusing concept is the precise meaning of the XORIG, YORIG, XCELL, and YCELL parameters in an IO/API data file. Below is an image of an example of using these parameters with two different data files that need to be co-registered within a PAVE plot. Note that units are in meters.
Most geographically oriented UAM-IV input and output files are directly readable by PAVE. These include DIFFBREAK, REGIONTOP, TEMPERATURE, WIND, AIRQUALITY, BOUNDARY, TOPCONC, EMISSIONS, PTSOURCE, AVERAGE, and INSTANT.
Some of the UAM-V input and output files are compatible with the UAM-IV file formats. These files are readily visualized by PAVE because it can obtain all the information it needs from inside the files (i.e. they are "self-describing"). The files in this category are: EMISSIONS, PTSOURCE, BOUNDARY, AIRQUALITY, and the coarse grid AVERAGE and INSTANT files.
However, many UAM-V files have new formats that are not self-describing. PAVE needs additional information in order to read these files, such as the kind of data in the file, the number of rows, columns, and layers in the data, the geographic region covered, etc. The file types that fall into this category are wind, temperature, cloud, water vapor, rain, vertical diffusion, height, fine grid average, and fine grid instant.
In order to display a file of one of these latter types with PAVE, a UAM-V "metafile" must be used. A metafile is an ASCII file that contains the additional information PAVE needs to read and correctly interpret the data. To visualize data in a file that needs a metafile, select the metafile from the PAVE file browser, instead of the file that contains the data. A description of the contents of UAM-V metafiles follows.
The very first line of the metafile MUST be the following:
#! UAMV DESCRIPTION FILE
If PAVE does not find the above string, the file is considered to be of unknown type and an error is returned.
Several keywords must be present in the metafile. Each keyword should be on a separate line and followed by a value. Blank lines are permitted. The following keywords are required (and are listed in the recommended order):
UAMV_FILE UAMV_TYPE NCOLS NROWS LEVELS XORG YORG DX or DLON DY or DLAT UTM_ZONE (for UTM-based domains only) FINE_GRID (for UAM-V output files only - not for input meteorology files) TITLE
Keyword Descriptions
UAMV_FILE - the name of the file that contains the actual data to be displayed by PAVE. It can be either a full or a relative pathname to the current working directory.
UAMV_TYPE - the type of data in the UAMV_FILE. Valid choices are: Wind, Temp, Cloud, H2O, Rain, Vdif, Height, FineGridAverage, FineGridInstant
NCOLS - number of horizontal columns in the grid
NROWS - number of horizontal rows in the grid
LEVELS - number of vertical layers in the grid
XORG - the x-coordinate of the lower left corner of the grid, in km for UTM-based grids and degrees for latitude-longitude grids
YORG - the y-coordinate of the lower left corner of the grid, in km for UTM-based grids and degrees for latitude-longitude grids
DX - size of the horizontal cell in the x-direction for UTM-based grids (km)
DLON - size of the horizontal cell in x-direction for lat-lon grids (degrees)
DY - size of the horizontal cell in y-direction for UTM-based grids (km)
DLAT - size of the horizontal cell in y-direction for lat-lon grids (degrees)
FINE_GRID - logical variable. Possible values: 0 and 1. If the value is 1, the file represents data on a fine grid, otherwise it is on a coarse grid. For meteorological input files, this value should be set to one only if there is a layer of cells outside the domain specified by { XORG, YORG, NROWS, NCOLS, DX, and DY]}.
TITLE - A title for tile plots. Spaces are allowed.
Example of a UAM-V temperature metafile on the OTAG coarse grid:
#! UAMV DESCRIPTION FILE UAMV_FILE /home/user/tmpr.cc.20jul93.ld.rams1 UAMV_TYPE Temp NCOLS 64 NROWS 63 LEVELS 5 XORG -99.0 YORG 26.0 DLON 0.5 DLAT 0.3333333 FINE_GRID 0 TITLE Coarse Grid Temperature: July 20, 1993Example of a UAM-V fine grid average metafile on the OTAG fine grid:
#! UAMV DESCRIPTION FILE UAMV_FILE /home/trayanov/testpave/avrg.ff.20jul93-93.mc.93basA1 UAMV_TYPE FineGridAverage NCOLS 137 NROWS 110 LEVELS 7 XORG -92.0 YORG 32.0 DLON 0.16666667 DLAT 0.11111111 FINE_GRID 1 TITLE Base Case Fine Grid AverageExample of a UAM-V temperature file on a UTM-based grid:
#! UAMV DESCRIPTION FILE UAMV_FILE /metdata/uamv.t.jun26-28.16km.8.v4 UAMV_TYPE Temp NCOLS 35 NROWS 50 LEVELS 8 XORG 200.0 YORG 4400.0 DX 16.0 DY 16.0 UTM_ZONE 16 FINE_GRID 0 TITLE Coarse Grid Temperature FileCreating metafiles with scripts
It is relatively straightforward to use a script to create metafiles. Examples of scripts that do this follow. However, the specifics (such as parsing file names to determine file type) depend on the particular application. The two examples given below are for the OTAG project. Note that these are hypertext links which are only available if you are reading this document using a Web browser.
Script to create OTAG input metafiles
Script to create OTAG output metafiles
The above scripts are provided with your PAVE installation. They are called make_in_metas and make_out_metas and are located in the scripts/ subdirectory of the top level directory where PAVE is installed. Before using them, be sure to edit the upper portion of the scripts to match your episode and directory structure.
Viewing multiple sequential files as one dataset
using chain files
Data from multiple files can be concatenated and displayed as if they
were from a single file. This is useful if you wish to animate over
sequential data that is stored in multiple files. In order to do this
you need to supply a "chain file" - an ASCII file that
contains a list of the data files to be concatenated.
The first line of a chain file must be
If this is not found, PAVE will not recognize that the file is a chain file.
A list of full path names to the individual files to be concatenated
should follow this line with one filename per line. Note that no
blank lines or comment lines are permitted and the files MUST be in the order
in which you wish the data to be displayed. The individual files can be one
of the following types: netCDF, UAM-IV or UAM-V (regular or meta files).
A script is provided with PAVE to simplify the creation of chain files.
The script will currently work only in cases where the files to be
chained reside in a single directory. To create a chain file, cd to the
directory that contains the files you wish to chain, and type
Limitations:
The current version of PAVE does not check the files for
consistency (i.e. whether they are of the same type, whether the grid is the
same in all the files, or whether the files are listed in the proper
sequential order).
Here is an example of a chain file:
#! LIST_OF_CHAINED_FILES
chain_files name_of_chain_file list_of_files_to_chain
For example: chain_files avrg.cc.20-30jul93-93.mc.basB avrg.cc.*
#! LIST_OF_CHAINED_FILES
/home/trayanov/testpave/rain.cc.20jul93.ai.meta
/home/trayanov/testpave/rain.cc.21jul93.ai.meta
/home/trayanov/testpave/rain.cc.22jul93.ai.meta
Return To Table of Contents
All PAVE visualizations are generated using one or more formulas. A formula may be very simple. For example, the formula "O3a" refers to the variable "O3" in data set "a" - which is the first dataset that was loaded into PAVE. (Note that data sets are given sequential letters as they are loaded into PAVE, and are referred to by those letters in PAVE formulas.) An example of a formula to calculate the percent difference in O3 between datasets a and b is: "(O3a-O3b)*100/(O3b+0.001)".
Formulas must be in infix notation, and can contain the following operators, listed in their order of precedence:
Highest 1) abs, sqr, sqrt, exp, log, ln, sin, cos, tan,
Precedence sind, cosd, tand, minx, miny, minz, maxx, maxy, maxz,
mint, maxt, mean, sum, min, max,
2) **
3) /, *
4) +, -
5) <, <=, > >=
6) ==, !=
7) &&
Lowest 8) ||
Precedence
Explanations of these operations are given below. If you wish to
override the default operator precedence, or are uncertain as
to which operator will take precedence, you can feel free to use
parentheses in your formulas. This will force expressions within the
parentheses to be evaluated first.
PAVE also has an occasionally used feature that allows you to specify a time step index after a variable name. For example, O3a:1 is the first hour of ozone. So, if you wanted to plot each cell averaged in time over the first six hours of your data, you could enter and plot the following formula:
(O3a:1+O3a:2+O3a:3+O3a:4+O3a:5+O3a:6)/6This is cumbersome and it also uses a lot of memory, but it may be useful for you.
There is another useful feature of the parser that not many people know about, that enables you to compute and visualize the the rate of change of a variable. For example, the formula d[O3a]/dt calculates the change in ozone concentration over time. A limitation of this feature is that the variable between the brackets must be an atomic variable, that is to say, it can not be a formula other than a basic variable from one of your datasets.
Formulas may also contain integer or floating point constants, or the following operands which are replaced by PAVE's formula parser to be the constant values noted:
E 2.7182818284590452354 PI 3.14159265358979323846 NROWS number of rows in the formula's currently selected domain NCOLS number of rows in the formula's currently selected domain NLEVELS number of levels in the formula's currently selected domainThe following operators are binary (they have an operand on both sides of the operator), and usually return an array of data by performing that operation on each cell of the operands' arrays. The only time these operators return a single number is when both operands (ops) are themselves a single number.
+ Returns the sum of the ops - Returns the difference of the ops * Returns the product of the ops / Returns ratio of the ops ** Returns the left op raised to the power of the right op, calculated using the C math library's pow() functionThe following operators are boolean binary operators. Boolean operators return either 0 or 1 for each cell of the resulting array of data, or in the case of two operands (ops) that are single numbers, just the single number 0 or 1. You may find these operators useful to "screen out" ranges of your data that are of particular interest. For example, if you are only concerned about the variable O3a when its value exceeds 0.080, you might look at the formula (O3a>0.080)*O3a. If O3a is less than or equal to 0.080, the result of the formula will be set to 0 in that cell. Otherwise, the value of O3a will be used in that cell.
< Returns 1 if the left op is less than the right op,
else 0
<= Returns 1 if the left op is less than or equal to
the right op, else 0
> Returns 1 if the left op is greater than the right
op, else 0
>= Returns 1 if the left op is greater than or equal
to the right op, else 0
!= Returns 1 if the left op is not equal to the
right op, else 0
== Returns 1 if the left op is equal to the right op, else 0
&& Returns 1 if both ops are non-zero, else 0
|| Returns 1 if either op is non-zero, else 0
The following operators are unary (they have a single operand on the
right side of the operator), and usually return a time-stepped matrix of
data by performing that operation on each cell of the operand's array.
The only time these operators return a single number is when the operand
is itself a single number. The C math library routines called are listed
with most of these operators. For further information on these routines,
please check your man pages.
abs fabs(op) sqrt sqrt(op) sqr Returns the square of the op log log10(op) exp exp(op) ln log(op) sin sin(op) cos cos(op) tan tan(op) sind sin(op*(PI/180.0)) cosd cos(op*(PI/180.0)) tand tan(op*(PI/180.0))The following unary operators return a single number in all cases. Their single operand must follow on the right hand side of the operator. The functionality is listed beside each operator name.
mean average cell value for all cells in currently selected domain sum sum of all cell values in currently selected domain mint time step index with minimum value in currently selected domain maxt time step index with maximum value in currently selected domain minx x index with minimum value in currently selected domain maxx x index with maximum value in currently selected domain miny y index with minimum value in currently selected domain maxy y index with maximum value in currently selected domain minz z index with minimum value in currently selected domain maxz z index with maximum value in currently selected domainwhere "currently selected domain" includes the currently selected rows, columns, layers, and time steps for the currently selected formula. Thus, the minimum and maximum values in the currently selected domain occur at the locations (minx,miny,minz,mint) and (maxx,maxy,maxz,maxt), respectively. An interesting use of the sum operator is to calculate the sum of the result of a boolean expression (e.g. sum(O3a>120)) to find the number of cell-hours that meet the boolean condition.
The unary min and max operators behave a little differently:
min For each cell (i,j,k) in the currently selected domain,
this calculates the minimum value for that cell
over the currently selected time steps. In other words,
the minimum value in cells (i,j,k,tmin..tmax).
max For each cell (i,j,k) in the currently selected domain,
this calculates the maximum value for that cell
over the currently selected time steps. In other words,
the maximum value in cells (i,j,k,tmin..tmax).
NOTE: currently the unary + and - operators [as in -1 or -(x+y)] are not supported, but hopefully these will be added later.
Each dataset has some number of layers greater than or equal to one, some number of time steps greater than or equal to one, and some geographic region onto which its grid maps. A geographic region, often referred to as a domain, is defined by the map projection type (Lat/Lon, UTM, Lambert Conformal, etc.), the number of rows and columns in the dataset, and the geographic boundaries of the area on which the grid falls.
For each unique geographic region (or domain) that PAVE learns about by examining the dataset(s) chosen by the user, PAVE keeps a single domain object. Domain objects are where the currently selected geographic region for formulas and datasets are stored in memory. When a domain object is created by PAVE, it defaults to having all of its cells selected, until the user chooses a subregion within that domain. Because PAVE only stores a single domain object for each unique domain that it learns of, there may be numerous datasets and formulas that make use of the same domain object. Therefore, when a user chooses to modify a formula's or a dataset's selected region of interest, the region of interest for all formulas and datasets that refer to the same region and have the same grid dimensions will be affected. Any subsequent plots of any formulas who rely on that domain object will reflect its newly selected geographic region of interest.
Similarly, PAVE uses layers objects to store information about currently selected layer ranges. Each dataset i has some Ni number of layers associated with it, and each formula j has some Nj number of layers associated with it. For each unique number of layers that PAVE learns about, PAVE keeps a single layers object in memory. Therefore, when a user chooses to modify a formula's or a dataset's selected layer range, there may be more than one dataset and more than one formula on which the modified layer range has an effect. When PAVE learns about a new unique number of layers, the layers object that it creates by default has only the first layer selected, until the user modifies the layer range for this layers object.
Time ranges are handled differently than layer ranges and geographic regions of interest. Each dataset has exactly one unique time range object associated with it. That time range object is associated only with that one dataset. Each formula also has exactly one unique time range object associated with it. That time range object is associated only with that one formula. Because a formula may rely on more than one dataset to derive its data, a formula's time step range is always bounded by the time ranges of the datasets it depends on. For example, a formula could have three datasets from which it derives data. Those datasets could have 72, 48, and 24 time steps of data in their currently selected time range objects. In this case, the maximum number of time steps in that formula's time range object could ever have would be 24. Should the user reduce the number of steps in the currently selected time range of any of the three datasets to less than 24, then the maximum number of time steps in that formula's time range object would immediately be reduced accordingly.
Choose Configuration File For New Tile Plots brings up a file browser that allows you to select a file that contains configuation settings for tile plots. Settings can include information such as colors to use, number of colors to use, min and max values for the legend, etc. These settings will be used for all subsequent tile plots, until another configuration file is chosen. The ASCII configuration files can be edited manually, or saved directly from a tile plot. For further information, please see the section on Configuring plots.
Load Dataset List From File brings up a file browser that allows you to select an ASCII file that contains a list of datasets that you would like to visualize with PAVE. Loading in a dataset list from a file will first cause PAVE to remove any currently loaded datasets from PAVE's memory. In this way, dataset names loaded in will then be referenced by letters a, b, c, etc.
Load Formula List From File brings up a file browser that allows you to select an ASCII file that contains a list of formulas that you would like to visualize with PAVE. Note that any formulas loaded in will be verified against the currently loaded datasets. As long as the variables in the formulas match variables in the respective datasets, they will be loaded into PAVE. Otherwise they will be ignored.
Save Dataset List To File allows you to save a list of the currently loaded datasets to an ASCII file. If you want to look at the same set of datasets in many different PAVE sessions, you may find this feature useful. Dataset lists can subsequently be retrieved using the Load Dataset List From File menu item described above.
Save Formula List To File allows you to save a list of the currently loaded formulas to an ASCII file. If you want to look at the same set of formulas in many different PAVE sessions, you may find it useful to use this feature. Formula lists can subsequently be retrieved using the Load Formula List From File menu item described above.
Exit PAVE causes your PAVE session to end.
Edit/Select From Dataset List brings up an "Add/Delete/Select Dataset" window that allows to you load and delete datasets from PAVE's memory. Click on the "Add" button, and an EDSS File Browser should appear (this may take a couple of seconds). You can then browse for datasets on your local machine and on remote machines if your system is properly configured. For more information on using the EDSS File Browser, see Quick Pave Jumpstart.
If you want to browse for files on remote machines, first verify that you've met the requirements discussed in the Requirements for use section of this document. Then click on the large button in the center of the EDSS File Browser that contains information about "Host:", "User:", and "Owner Module:". This brings up a "host selector" window in which you can enter the remote host name (e.g. sequoia.nesc.epa.gov). Clicking on "Select" will cause the file browser to go to your home directory on the remote machine if your system is configured properly. You should then be able to browse for files on that machine.
Datasets selected with the EDSS File Browser are loaded into PAVE sequentially, and are referenced using the letters a, b, c, etc. When a new dataset it loaded into PAVE, it becomes the currently selected dataset. You can always determine which is the currently selected dataset by looking at the "Dataset:" line on the main PAVE window. You can change the currently selected dataset by simply single-clicking on the desired dataset name in the "Add/Delete/Select Dataset" window. PAVE's "Species List" window will then contain the names of the variables contained in the dataset, each followed by the letter corresponding to the dataset.
Clicking on a dataset name and then clicking on the "Delete" button will remove that dataset from PAVE's memory. Clicking on the "Close" button will close the window.
Select Time Range of Current Dataset brings up a window with two sliders that can be used to crop the currently selected dataset's time range to a smaller time range, which by default is set to the maximum range in the dataset. Cropping, or subselecting, a dataset's time range will affect any plots made using that dataset's variables. The maximum time range that can be used for any of the variables in a plot is specified by these sliders. Please see the section on Spatial and temporal data subsetting for further information on how PAVE stores time ranges.
Select Layer Ranges Matching Current Dataset brings up a window with two sliders that can be used to change the currently selected dataset's layer range to a different layer range. By default, a dataset's layer range is set to be layer 1 (ground level) only. Changing a dataset's layer range will affect any plots made using that dataset's variables, and may also affect plots made using other datasets. The maximum layer range that can be used for any of the variables in a plot is specified by these sliders. Note that there may be multiple datasets and formulas that share the same layer range information. Please see the section on Spatial and temporal data subsetting for further information on how PAVE stores layer ranges.
Select Regions Of Interest Matching Current Dataset brings up a window that can be used to change the currently selected dataset's geographic region of interest. By default, a dataset's geographic region of interest is the entire region referenced by the dataset. This window can be used to select part of this region. Changing a dataset's geographic region of interest will affect any plots made using that dataset's variables, and possibly those of other data sets because there may be multiple datasets and formulas that refer to the same region of interest.
The geographic region of interest window has its own menu. The File menu can be used to save a geographic region of interest to a file, retrieve a region of interest from a file, or to close the window. The Edit menu can be used to easily select all of the grid cells in the window, or to select none of them. Cells can explicitly be toggled on or off by dragging the mouse over the region to be toggled. You may find that selecting a particular region is easier if you resize the window to make it larger. Please see the section on Spatial and temporal data subsetting for further information on how PAVE stores geographic regions of interest.
View Variables In Current Dataset will cause a window to appear that lists the variables in the currently selected dataset, followed by the letter that corresponds to the dataset. You can click on any of the variables to cause that variable to be added to the formula list and become the currently selected formula. The formula can then be plotted using selections from the Graphics menu without any further clicks of the mouse.
Edit/Select From Formula List brings up an "Add/Delete/Select Formula" window that allows to you add and delete formulas from PAVE's memory. You can enter a formula using the "Enter New Formula:" typein widget according to the rules described in the Using formulas section, then click on the "Add" button to load it into PAVE's memory. When a new formula is loaded into PAVE, it becomes the currently selected formula. You can always determine which is the currently selected formula by looking at the "Formula:" line on the main PAVE control window. You can change the currently selected formula by simply clicking on the desired formula name in the "Add/Delete/Select Formula" window.
Clicking on a formula and then clicking on the "Delete" button will remove that formula from PAVE's memory. Clicking on the "Close" button will close the window.
Select Time Range of Current Formula brings up a window with two sliders that can be used to crop the currently selected formula's time range to a smaller time range. Cropping, or subselecting, a formula's time range will affect any plots made using that formula. The maximum time range that can be used for the formula in a plot is specified by these sliders. Please see the section on Spatial and temporal data subsetting for further information on how PAVE stores time ranges.
Select Layer Ranges Matching Current Formula brings up a window with two sliders that can be used to change the currently selected formula's layer range to a different layer range. By default, a formula's layer range is set to be layer 1 (ground level) only. Changing a formula's layer range will affect any plots made using that formula, and possibly that of other plots too since there may be multiple datasets and formulas that share this same layer range information. Please see the section on Spatial and temporal data subsetting for further information on how PAVE stores layer ranges.
Select Regions Of Interest Matching Current Formula brings up a window that can be used to change the currently selected formula's geographic region of interest. By default, a formula's geographic region of interest is set to be the entire region referenced by the formula . This window can be used to select part of this region. Changing a formula's geographic region of interest will affect any plots made using that formula's variables, and possibly other plots since there may be multiple datasets and formulas that share this same geographic region of interest information.
The geographic region of interest window has its own menu. The File menu can be used to save a geographic region of interest to a file, retrieve a region of interest from a file, or to close the window. The Edit menu can be used to easily select all of the grid cells on the window, or to select none of them. Cells can explicitly be toggled on or off by dragging the mouse over the region to be toggled. You may find that selecting a particular region is easier if you resize the window to make it larger. Please see the section on Spatial and temporal data subsetting for further information on how PAVE stores geographic regions of interest.
Create Tile Plot makes a tile plot of data for the currently selected formula using that formula's selected geographic region of interest, layer range, and time step range. A tile plot has its own menus that can be used to operate on that tile plot and/or its data.
Create Vector Plot makes a vector plot from the formula selected as component 1 and the formula selected as component 2. The formulas selected as the components of the vector must match in geographic region of interest, layer range, and time step range.
Create Vector Tile Plot overlays a vector plot from the formula selected as component 1 and the formula selected as component 2 with a tile plot of a scalar variable. The formulas selected as the components of the vector, and the scalar must match in geographic region of interest, layer range, and time step range.
Create 3D Mesh Plot uses data for the currently selected formula at that formula's selected geographic region of interest, layer range, and time step range, to make a 3D mesh plot.
Create Time Series Line Plot makes a time series line plot using data for the currently selected formula at that formula's selected geographic region of interest, layer range, and time step range. Each time step's data is averaged linearly to produce that time step's data point. WARNING: If multiple layers are selected, PAVE 1.4.2 will show data for only the topmost layer instead of averaging the data over the selected layers.
Create Time Series Bar Plot makes a time series bar plot using data for the currently selected formula at that formula's selected geographic region of interest, layer range, and time step range. Each time step's data is averaged linearly to produce that time step's data point.
Create Scatter Plot makes a scatter plot from the formula selected as component 1 and the formula selected as component 2. The formulas selected as the components of the vector must match in geographic region of interest, layer range, and time step range.
Create N-Hour Average Tile Plot creates a tile plot that contains in the first timestep, the nhour average starting at the first timestep, in the second timestep, the nhour average starting at the second timestep, etc.. First, specify the formula using the menu item Formula, and the menu item Edit/Select from Formula List prior to the selection of the Create N-Hour Average Tile Plot. The title for tile plot generated by the Create N-Hour Average Tile Plot menu is labeled n-hour average, i.e. n-hour average:formula name
Create N-Layer Average Tile Plot creates a tile plot of the nlayer average for the layers selected using the menu item Formulas, then the menu Select Layer Ranges Matching Current Formula. The title for tile plot generated by the Create N-Layer Average Tile Plot menu is labeled n-layer average, i.e. n-layer average:formula name
Animate Tile Plots Synchronously.. animates all currently displayed tile plots in a round-robin fashion. As of Version 1.7, PAVE will synchronize the animation based on the time stamps of the plots, as opposed to the frame number. As a result, files that start at different times can be animated synchronously in a meaningful way.
Set Minimum Frame Time.. brings up a window that allows you to adjust the minimum time between animation frames. This is useful if you have an extremely fast machine on which you want to slow down the animation. The minimum time can be set in 0.1 second increments to any value between 0 and 5 seconds.
Set Tile Plot Cross Section Type brings up a sub-menu that can be used to choose the axis on which PAVE slices the data to make a plot. By default, PAVE does a "Z Cross Section" plot, where every data point on the plot is on the same Z layer. "X Cross Section" and "Y Cross Section" plot types can also be chosen. Subsequent plots will reflect the chosen plot type. Choose X Cross Section when you want to plot a cross section in which the x coordinate is constant, and Y Cross Section when you want the y coordinate to be constant. Note that you will have to adjust your geographic region of interest and the layer range appropriately for the plot type, as PAVE needs to have the geographic region of interest sufficiently cropped for it to be able to resolve which individual plane it is plotting. The other sub menu items are currently grayed out, as PAVE doesn't make use of them. Future versions of PAVE may have these enabled.
Default slices.. is grayed out as PAVE doesn't use this feature.
AVS5 saves the currently selected formula's data to an AVS5 field file, that can then be visualized with the Application Visualization System from Advanced Visual Systems, Inc.
netCDF saves the currently selected formula's data to a Models-3 IO/API data file. Data in this format can be visualized later using PAVE, or any other program that reads netCDF/Models-3 IO/API data files. You may find it helpful to save your data this way to perform an extraction from your data, or save the result of a complex formula to prevent having to recalculate the result.
Tabbed ASCII saves the currently selected formula's data to a tab delimited data file suitable for reading into a spreadsheet application such as Excel or Lotus.
Data Explorer and Iris Explorer are grayed out, as this functionality has not yet been added to PAVE.
User Guide first looks on the local disk for the PAVE user guide, for <top level PAVE directory>/doc/pave/index.shtml. If this file does not exist, it attempts to connect to the on-line user guide installed at CEP, which is at http://www.ie.unc.edu/cempd/EDSS/pave_doc/index.shtml.
Frequently Asked Questions first looks on the local disk for the PAVE FAQ, for <top level PAVE directory>/doc/pave/Pave.FAQ.html. If this file does not exist, it attempts to connect to the FAQ installed on-line at CEP, which is at http://www.ie.unc.edu/cempd/EDSS/pave_doc/Pave.FAQ.html.
Models-3 IO/API attempts to use Mosaic to browse the Models-3 IO/API web pages located at http://www.baronams.com/products/ioapi/H.AA.html.
Please try to answer your questions using these resources before entering a help ticket at http://bugz.unc.edu
"Control..Configure...Tile..." menu item on a tile plot is used to adjust the configuration of a tile plot. You will see a window similar to the following:
[MPEG FILE NAME].param
[MPEG FILE NAME].mpg.0000.xwd
[MPEG FILE NAME].mpg.0001.xwd
:
[MPEG FILE NAME].mpg.N.xwd [where there are N+1 frames in the MPEG]
Note that the MPEG animation will be generated, regardless of the setting of the "Keep MPEG Input" button.
Parameter files are used by mpeg_encode to generate the MPEG files from a stream of XWD images saved by PAVE. If you want to edit a parameter file and then generate an MPEG "manually" using mpeg_encode, the command line format is:
mpeg_encode <parameter file name>
Using the parameter file below, /home/thorpe/UWINDa2.mpg would be generated from /home/thorpe/UWINDa2.mpg.[0000-0005].xwd.
IQSCALE 6 PQSCALE 6 BQSCALE 6 PSEARCH_ALG LOGARITHMIC BSEARCH_ALG CROSS2 GOP_SIZE 10 SLICES_PER_FRAME 1 PIXEL HALF RANGE 10 PATTERN IBBPBBPBBPBBPBB FORCE_ENCODE_LAST_FRAME BASE_FILE_FORMAT PPM OUTPUT /home/thorpe/UWINDa2.mpg INPUT_CONVERT /pub/storage/edss/framework/EDSSv0.x/IRIX5_mips/bin/OPTIMIZE/publi c_domain/xwdtopnm * | /pub/storage/edss/framework/EDSSv0.x/IRIX5_mips/bin/OPTIMIZE/public_ domain/pnmdepth 255 INPUT_DIR /home/thorpe INPUT UWINDa2.mpg.*.xwd [0000-0005] END_INPUT REFERENCE_FRAME ORIGINAL FORCE_ENCODE_LAST_FRAME
"Control..Configure...Contour..." menu item on the tile plot is used to adjust the configuration of the Contour plots. This option is only active when the tile plot has contours on it. Otherwise, this option is greyed out. Need an image showing what this window looks like
"Control..Configure...VectObs..." menu item on the tile plot is used to adjust the configuration of the Vectors overlayed with Observational data. This option is only active when the tile plot has vectors and observational data on it. Otherwise, this option is greyed out. Need an image showing what this window looks like
"Control..Configure...Title/Subtitle Font..." menu item on the tile plot is used to adjust the font size of Titles and Subtitles of the tile plot. Need an image showing what this window looks like
Saving configuration settings for later use
Tile plot configuration settings can be saved to an ASCII file, edited if desired, and reused in future PAVE sessions. Using a tile plot's a "File...Save Configuration Settings" menu item brings up a file browser that allows you to save the current configuration of the tile plot to an ASCII file suitable for editing. The information saved includes the legend range, the format of the legend labels, the number of labels on the legend, the number of tiles/colors used, the colors themselves, and all of the individual toggle and radio buttons on the Configure.. window. In subsequent PAVE sessions, these configuration settings can be retrieved to affect future tile plots.
An example of the file format used is as follows:
ColorMapType NEWTON_COLORMAP Legend_Max 0.128 Legend_Min 0.000 Legend_Format %4.3f Number_Labels 5 Invert_Colormap 0 Number_Tiles 8 255 0 0 ColorNumber8 255 147 0 ColorNumber7 218 255 0 ColorNumber6 70 255 0 ColorNumber5 0 255 221 ColorNumber4 0 143 255 ColorNumber3 0 95 255 ColorNumber2 223 223 223 ColorNumber1 Save_MPEG_Files 0 Disable_Map 0 Smooth_Plot 1 Draw_Grid_Lines 1 Scale_Vectors 0
Note the following about the format of the configuration file:
NEWTON_COLORMAP [for Newton RGB (AVS)]
JET_COLORMAP [for Newton RGB (InkJet)]
GREY_COLORMAP [for Grey Scale (AVS)]
Configuration files can be loaded into PAVE sessions in two ways -
using the user interface or from the command line. PAVE's main
window now has a "File... Choose Configuration File For New Tile Plots"
menu item, which can be used to select the file. Alternatively, PAVE's
command line arguments or standard input stream can accept input of
the form "-configFile
To print tile plots, if you are printing to a black and white printer,
you should probably choose "Control/Configure" from the plot's menu bar and then
experiment with various settings for the colors. You may want to
reduce the number of colors in the plot by choosing a smaller number
of tiles, or alternatively you may want to choose to use the grayscale
colormap. Once you are ready to print the image, just choose the File..Print
menu item on the tile plot, and it will be printed on the printer specified
by the PRINTER environment variable. If for some reason this
doesn't work, then see the sections below on using snapshot
and/or xv. These tools will enable you to save a screen
captured image to a PostScript file that can then be printed.
To print 3D mesh plots, first decide whether you want to print using
black and white or color PostScript. You can then select either the
"Black & White PostScript" or the "Color PostScript" button on the 3D mesh plot's
"ANIMATING SURFACE" window. Then type in the filename, complete with path
name, in the resulting window. Your PostScript will be saved to the chosen
file, and then you can issue an lpr command from the Unix command line to
print that file.
To print time series line plots or scatter plots,
select the "print" button on the plot's window. Then type in the filename,
complete with path name, in the resulting window. Your PostScript will be
saved to the chosen file, and then you can issue an lpr command from the Unix
command line to print that file.
To print time series bar plots,
see the sections below on using snapshot
and/or xv. These tools will enable you to save an screen
captured image to a PostScript file that can then be printed.
Tile plots can be saved to an MPEG animation using the
File..Save MPEG Animation menu item on the tile plot.
Several points to note regarding MPEG animations:
mpeg_play test.mpeg -loop -framerate 5 -quiet
"-loop" keeps it looping.
"-quiet" keeps it from printing to stdout (which makes the transition from the
last frame to the first much faster).
"-framerate 5" slows it down to print 5 frames per second.
Once you have selected the portion of the screen to be captured, use
the Save as ... option on the snapshot menu to create an RGB file.
To convert the RGB file to black and white PostScript, type
tops your_file.rgb > your_file.ps
If you want a color PostScript file, type
tops your_file.rgb -rgb > your_file.ps
You can then use xpsview your_file.ps to view the new PostScript
file. You can then capture another image by placing the mouse
pointer over snapshot, pressing and holding the shift button, and
then creating a new box with your left mouse button.
For more information on snapshot and tops, see their man pages.
Sun also has a version of snapshot that can capture images. The images
can be loaded and viewed with imagetool and then saved to a variety of
formats, including postscript. Both snapshot and imagetool have nice
user interfaces to help you through the process. See the man pages
for more information.
Now left-click the "xv controls"'s Save button.
Choose PostScript from the "Format" menu, and "Full Color" or
your preferred color choice from the "Colors" Menu. Next use
the browser to save the PostScript to a file. It is recommended
that you give the file a .ps extension, to indicate its format.
You can then use xpsview your_file.ps to view the new PostScript
file.
xv is available for a variety of UNIX Platforms via anonymous
ftp to ftp://www.trilon.com/pub/xv
For more information on xv, see the WWW page at
http://www.trilon.com/xv
NOTE: xv is a shareware program that you will need to pay $25 to
license if you decide to use it. This can be remitted to
PAVE has a large number of command line arguments. These can be typed
into the PAVE standard input stream (the window where PAVE was launched),
or supplied via command line arguments when PAVE is invoked. The command
line argument method is often used within scripts written to automate
plots for the user. Notes regarding the scripting commands are available
below. Several example scripts
are provided below. The format for PAVE command line arguments can
be determined by typing "pave -usage" at the command line, which
produces the following:
usage: pave
An example script to create a tile plot of a user specified alias:
-autoContourRange tells PAVE to no longer use the contour range
supplied by a previous -contourRange command, but rather use the default
range that is set by the range of the data for each plot.
-barplotYformat"<format string>" can be used to adjust
the format used by sprintf() to draw the y axis labels on bar plots. The default
format is %g. Please see a C reference book or the man pages on sprintf()
for specifics on usable formats for float variables.
NOTE: This option does not work on the IBM platform.
-closeWindow"<windowid>" closes the window with the specified
X window ID
-configFile <configFileName> specifies a configuration
file for PAVE to use for configuring subsequent tile plots. Please
see the Configuring plots section for
more information on configuration files.
-contourRange <minCut> <maxCut> sets the contour
minimum and maximum cutoffs to use for tile plots. By default,
the contour range is set by the range of the data for each plot.
-copyright prints out copyright information on PAVE itself
and all of the third party public domain applications that it uses.
PAVE will not start until the user scrolls throught the copyright information by
hitting rertun or the space key in PAVE's standard input window
-crossSectionType X|Y|Z sets the graphics cross section type
for subsequent plots to the slice type specified.
-drawGridLabels ON|OFF
-f [<host>:]<pathname/filename> tells PAVE
to load in this dataset and make it the currently selected dataset.
Each time you enter a new sequence of
script commands with -f options in it, PAVE will remove any
previously loaded datasets from its memory, and begin denoting
the new dataset(s) with the letters a, b, etc. So if you want
to load in a number of datasets using the -f option with PAVE's standard
input, be sure to have all the -f
-fulldomain sets the PAVE domain matching the currently selected dataset
to be completely selected. The currently selected dataset is usually the
most recently added dataset, unless you have modified it by selecting another
dataset using the user interface.
-gtype <tile|line|mesh|bar> instructs PAVE to create
a plot using the specified type and the currently selected formula's data.
-help | -fullhelp | -usage display the information on all the
command line arguments available. Each of these three versions
perform the identical function.
-imageMagickArgs 'args' was added
in version 2.3.
When used, this command line argument will pass the contents of
args to the convert program that is called when images are converted
from X-window dumps to other image formats. For more information
on the command line arguments for convert, see the ImageMagick
documentation (available from
http://www.imagemagick.org).8. Printing and exporting images, animations, and data
PAVE provides facilities to print plots, export images and animations, and export subsets of data. In cases where PAVE's
built in capabilities do not allow you to capture the images you want
(e.g. saving multiple windows together), the tools xv
and snapshot may allow you to accomplish your goals.
Printing plots
You probably need to set your PRINTER environment variable prior to
launching PAVE for printing to work correctly.
(See the Quick PAVE Jump start section for
further information.)
Tile plots can be saved as GIF, Postscript, SGI's RGB, XWD, TIFF,
and several other image file formats using file menu items on the tile
plot.
Exporting images and animations
Tile plots can be saved to an animated GIF using the
File..Save Animated GIF menu item on the tile plot.
Several points to note regarding animated GIFs:
To print other types of PAVE plots,
see the sections below on using snapshot
and/or xv. These tools will enable you to save an screen
captured image to an image file that can then be printed.
PAVE's Export menu enables you to save the currently selected formula's
data in AVS5 field format, netCDF Models-3 IO/API format,
and as tabbed ASCII data suitable for use in spreadsheet
applications. (Note that the currently selected formula's data
is saved when using the export menu items.)
Of particular interest may be the option to export netCDF
data. You might find a very large dataset cumbersome to keep around when
you are only interested in a small number of variables, perhaps in a
small time range or spatial region. PAVE can be used to subselect the
variable, time, levels and region of interest and then save this
data to a smaller, more manageable dataset. Also, you can save the result
of a complex formula to a netCDF file and therefore prevent having to wait
for it to compute again.
Exporting PAVE data
On an SGI, type snapshot. To view the snapshot menu, place the
mouse pointer over snapshot and press the right mouse button. Choose the
New file name option to name the file that will be output from
snapshot. You should give it a name with a ".rgb" extension. While the
mouse pointer is over snapshot, press and hold down the shift key. Then
move the mouse pointer to the top left corner of the part of the screen
you wish to capture. Then press the left mouse button and drag the mouse
pointer until you reach the bottom right corner of the section you want
to capture. You should see a red box surrounding the part of the screen
that will be captured. If you need to modify the size or location of the
box, place the mouse pointer over snapshot and press and hold down the
shift button. To move the box, place the mouse pointer inside the box and
then drag the box using the middle mouse button. To resize the box, place
the mouse pointer near one of the edges of the box and drag the edge (or
corner) using the left mouse button.
Using snapshot to create PostScript files from screen images Using xv to create PostScript files from screen
images
xv is a very usfule tool for capturing and manipulating
images - especially GIF files. Type xv to start the program. To view
the xv menu, place the mouse pointer over the inital window and press the
right mouse button. Click on the grab button with the left mouse button,
then use the middle button to drag over the screen region you wish to
save to a PostScript file. A copy of these pixels will appear in a
separate window.
US Mail: John Bradley
1053 Floyd Terrace
Bryn Mawr, PA 19010
FAX: (610) 520-2042
Electronic Mail regarding XV should be sent to one of these three addresses:
xv@trilon.com - general XV questions
xvbiz@trilon.com - XV licensing & pricing questions
xvtech@trilon.com - bug reports, technical questions
9. Driving PAVE using scripts
[-alias <aliasname=definition> (NEW in v2.1)!!!]
[-animateWindows<single|continuous> ]
[-animatedGIF<filename> ]
[-autoContourRange]
[-barplotYformat<format string> ]
[-closeWindow<windowid> ]
[-configFile<configFileName> ]
[-contourRange<minCut> <maxCut> ]
[-copyright ]
[-crossSectionType X|Y|Z ]
[-display <display> ]
[ -drawGridLabels ON|OFF (NEW in v2.3!!!) ]
[ -drawLegend ON|OFF (NEW in v2.3!!!) ]
[ -drawMinMax ON|OFF (NEW in v2.3!!!) ]
[ -drawTimeStamp ON|OFF (NEW in v2.3!!!) ]
[ -drawTiles ON|OFF (NEW in v2.3!!!) ]
[-f [<host>:]<filename> ]
[-fulldomain ]
[-g <tile|line|mesh|bar> ]
[-gtype <tile|line|mesh|bar> ]
[-height <tile plot height in pixels> ]
[-help|fullhelp|usage ]
[ -imageMagickArgs 'args' (NEW in v2.3!!!) ]
[-kedamode]
[-legendBins "<bin0,bin1,...,bin_n>" ]
[-level <level> ]
[-levelRange <levelMax> <levelMin> ]
[-mapCounties]
[-mapName "<pathname>/<mapFileName>" ]
[-minMaxModelObs <col> <row> <radius> <formula1> <formula2> ]
[ -minMaxObs <col> <row> <radius> <formula1> <formula2> ]
[ -multivarNcf <formulaList> <varList> <fileName>" ]
[ -multitime <Nformulas> "<formula1>" ... "<formulaN>" ]
[ -nHourAverage <nhours> ]
[ -nHourSum <nhours> ]
[ -nLayerAverage ]
[ -nLayerSum ]
[ -obs <formula> ]
[ -obsidtable <filename> ]
[ -obsSize <size> ]
[ -obsThick<size> ]
[ -obsTimeSeries]
[ -onlyDrawLegend (NEW in v2.3!!!) ]
[ -preClip <llLat> <llLon> <urLat> <urLon> ]
[ -printAlias ]
[ -quit|exit ]
[ -raiseWindow <windowid> ]
[ -s "<formula>" ]
[ -save2ascii <filename> ]
[ -save2d <imagetype> <filename> ]
[ -save2ncf <filename> ]
[ -saveImage "<image type>" <file name> ]
[ -scatter "<formula1>" "<formula2>" ]
[ -showWindow <windowId> <timestep> ]
[ -subDomain <xmin> <ymin> <xmax> <ymax> ]
[ -subTitle1"<sub title 1 string>" ]
[ -subTitle2"<sub title 2 string>" ]
[ -subTitleFont <fontSize> ]
[ -system "<unix command>" ]
[ -tfinal <final time step> ]
[ -tileYlabelsOnRight ]
[ -tinit <initial time step> ]
[ -titleFont <fontSize> ]
[ -titleString "<title string>" ]
[ -ts <time step> ]
[ -tzoffset <Timezone offset> ]
[ -tzset <in Timezone> <out Timezone ]
[ -unalias <aliasname> ]
[ -unitString "<unit string>" ]
[ -vectobs <formula> <formula> ]
[ -vector "<U>" "<V>"]
[ -vectorPlotEvery "<number>"]
[ -vectorScale "<scale factor>"]
[ -vectorTile "<formula>" "<U>" "<V>"]
[ -version ]
[ -width <tile plot width in pixels> ]
[ -windowid ]
-alias <aliasname=definition>The user can define an alias by
creating a definition using variable names and derived variables that are calculated using the
mathematical operators described in the PAVE Using Formulas documentation. The alias definition
does not include the dataset name. The alias is treated like any other formula once the alias
definition and the dataset to which it should be applied to is specified. If you need to redefine
an alias definition, you must first use the -unalias command. The alias definitions are saved
to a .pave.alias file in your home directory. Pave uses this type of optional file in your home
directory to maintain a snapshot of the current aliases being used within pave. The following
warning will be reported if an alias is defined more than once: WARNING: Alias <aliasname>
already defined, new definition ignored. The user is also responsible for not making circular
references. If the aliasname is contained within its definition, then PAVE will crash. Use the
-printAlias command to view what aliases are already defined.
#!/bin/csh -f
setenv DATA_DIR /env/data/trayanov
setenv FILE1 CHEM_CONC_3D_G1.200021512
pave \
-f ${DATA_DIR}/${FILE1} \
-alias NTOT=NO+NO2+NO3+N2O5+HONO+HNO3+HNO4 \
-s NTOTa \
-gtype tile \
-unalias NTOT
-animatedGIF<filename>creates an animated GIF by doing an x window dump
of each of the timesteps in the tile plot then converting them to gif images.
While the animaged GIF is being created by PAVE, the user must not bring up other windows.
If other windows cover the tile plot while the x window dumps are being performed,
then the animated gif will incorrectly include these contents of these windows rather than
the tile plot window. After the x window dumps are completed, a program called convert
creates the animated gif. If there are many timesteps in the dataset, there will be a
slight delay before the user is again given control of the pave gui, after the convert
program has finished running.
-drawLegend ON|OFF
-drawMinMax ON|OFF
-drawTimeStamp ON|OFF
-drawTiles ON|OFF were added in version 2.3,
along with other command line arguments that control
whether various parts of tile plots are drawn. You may find this useful
when placing PAVE outputs in other documents. Note that the syntax
to prevent the drawing of titles was already in earlier versions of
PAVE - just give a string of spaces as the argument for the title
command line arguments (e.g. -titleString " " -subTitle 1 " "
-subTitle2 " "). Also see -onlyDrawLegend.
-level <level> sets the level range of all formulas to the single level specified.
-levelRange <levelMax> <levelMin> sets the level range of all formulas to the range specified.
-mapCounties causes PAVE to use the county map for subsequently created plots. If the PAVE_DISTINCT_STATE_COUNTIES environment variable is set, the state and county lines will be drawn with different colors.
-mapName "<pathname>/<mapFileName>" causes PAVE to use the supplied map name instead of the default map for tile plots. The default map is <top level PAVE directory>/$EDSS_ENV/bin/OPTIMIZE/maps/OUTLUSAM, which is a medium resolution state outline map.
-minmaxobs <col> <row> <radius> <formula1> <formula2>
<formula1> = "MODEL_VAR", <formula2> = "OBS_VAR"
creates a plot of the Min and Max of the Model Variable computed over an
area defined with a radius (number of cells) and center cell (Column, Row).
The Observational variable defined at cell (Column, Row) is also displayed
-minmaxmodelobs <col> <row> <radius> <formula1> <formula2>
<formula1> = "MODEL_VAR", <formula2> = "OBS_VAR"
creates a plot of the Min and Max of the Model Variable computed over an
area defined with a radius (number of cells) and center cell (Column, Row).
The Observational variable defined at cell (Column, Row) and the Model Variable
defined at cell (Column, Row) are also displayed
-multivarNcf <formulaList> <varList> <fileName>"export multiple netCDF variables to a file name. The fileName must currently be listed using the full path name.
An example script to create export multiple formulas to a netCDF file:
#!/bin/csh -f
setenv DATA_DIR /env/data/trayanov
setenv FILE1 CHEM_CONC_3D_G1.200021512
pave \
-f ${DATA_DIR}/${FILE1} \
-alias NTOT=NO+NO2+NO3+N2O5+HONO+HNO3+HNO4 \
-s NTOTa \
-gtype tile \
-s NOa \
-s NO2a \
-multivarNCF "NTOTa,NOa,NO2a" "NTOT,NO,NO2" $EDSS_ROOT/data/frmwk/pave/multiNTOT.ncf \
-unalias NTOT
-multitime <Nformulas> "<formula1> .. "<formulaN>"
creates a time series line plot showing each of the Nformulas formulas
with its own line.
Note that Nformulas must be between 1 and 8, and that all the formulas for
the plot should have already been loaded into PAVE,
and they are case sensitive.-NhourAverage <nhours>creates a tile plot that contains in the first timestep, the nhour average starting at the first timestep, in the second timestep, the nhour average starting at the second timestep, etc.. The formula specified using -s <formula> prior to the -NhourAverage option is displayed in the tile plot. The title for tile plot generated by the -NhourAverage option is labeled n-hour average, i.e. n-hour average:formula name
-NhourSum <nhours>creates a tile plot that contains in the first timestep, the nhour sum starting at the first timestep, in the second timestep, the nhour sum starting at the second timestep, etc.. The formula specified using -s <formula> prior to the -NhourSum option is displayed in the tile plot. The title for tile plot generated by the -NhourSum option is labeled n-hour sum, i.e. n-hour sum:formula name
-NlayerAverage <nlayers>creates a tile plot of the nlayer average for the layers selected using the -levelRange option
-NlayerSum <nlayers>creates a tile plot of the nlayer sum for the layers selected using the -levelRange option
-obs <formula> plot standard AIRS AMP350 observational data overlayed on a gridded tile plot with model variable data. The program AIRS2M3 is provided to convert the standard AIRS AMP350 observational data format to the Models-3 I/O API format that PAVE requires.
-obsidtable <filename> An example lookup table for converting AIRS AMP350 numeric observation station ids to text names is available with the airs.lookup file provided with the PAVE 2.1b release. The required format for the file is a two column, space delimited ascii file, the entries in the first column contain the AIRS AMP350 numeric observation station ids that can be unquoted or quoted, the entries for the second column contain the cooresponding name e.g. "CITY, COUNTY, STATE" that can either be a tightly packed string, or a quoted string. If PAVE finds a match between the AIRS AMP350 numeric observation station id provided in the gridded observational data file, and a numeric entry in first column of the airs.lookup file, then it will replace the AIRS AMP350 numeric observation station id with the cooresponding name provided in the second column of the airs.lookup file. If no match is found, the AIRS AMP350 numeric observation station id will be preserved
-obsSize <size> specify the size (an integer number) of the diamond shaped observational data point markers. Specify this option after the -obs option
-obsThick <size> specify the thickness (an integer number) of the diamond shaped observational data point markers. Specify this option after the -obs option
-obsTimeSeries creates a time series plot displaying the observations and average observations versus time. The labels currently list the numeric observation id. To focus in on specific counties or regions use the -subdomain option.
An example script application:
#!/bin/csh -f
setenv DATA_DIR $EDSS_ROOT/data/frmwk/pave/
setenv FILE1 O38.ids.obs_on
setenv FILE2 SM_b1on_cc3_g0.l1.O3.8hr.2hours
pave \
-f ${DATA_DIR}/${FILE1} -s O38_OBSa \
-f ${DATA_DIR}/${FILE2} -s O3b \
-subdomain 26 3 72 50 \
-gtype tile -obs O38_OBSa \
-obsSize 6
-obsThick 3
-obstimeseries
-onlyDrawLegend ON|OFF was added in version 2.3. If this is set to ON, you'll get a plot for which only the legend is drawn. This is useful if you want to place the legend in another document. You can crop this plot when exporting images using scripts by using the -imageMagickArgs command line option.
-preClip <llLat> <llLon> <urLat> <urLon> will cause PAVE to use a "pre-clip" map region bounded by the supplied lat/lon coordinates. These arguments can be used to access PAVE's world map over a region outside of North America. For further information on how to use the world map, please see the PAVE FAQ located at Pave.FAQ.html#WorldMap.-printAlias prints existing alias definitions
-quit | -exit ends the PAVE session.
-raiseWindow "<windowid>" raises the window with the specified X window ID (i.e. brings it to the front)
-s "<formula>" loads the specified formula into PAVE's memory, and makes it the currently selected formula.
-save2d <imagetype> <filename> used to save a timeseries plot to an image file. Supported imagetypes include GIF, RGB, XWD, MPEG, or PS. The environment variable GRAPH2DCFG is used to specify the graph2d.blt BLT configuration file. An example graph2d.blt BLT configuration file is provided with the PAVE 2.1b release.
-save2ascii <filename>export data to a tab delimited data file suitable for reading into a spreadsheet application such as Excel or Lotus
-save2ncf <filename>export data to a Models-3 I/O API netCDF formatted file. Data in this format can be visualized later using PAVE, or any other program that reads Models-3 I/O API netcdf data files.
-saveImage <image type> <file name> saves the most recently created tile plot, The image type can be RGB, XWD, GIF, MPEG, or PS. Note: this may cause PAVE to crash if the most recently created tile plot has been closed.
This option can also be used to generate a stream of images from a tile plot, one for each time step of data associated with that tile plot. This can be done either through a command line option (-saveImage) or through the standard Motif user interface that comes with a tile plot's window. By supplying a file name with % format characters suitable by the C Language's printf() routine, PAVE is notified that a stream of images should be saved rather than a single image. The printf % format characters are used to generate the individual file name for each time step of data.
For example, if a user needs to:
The following script would do the job:
#!/bin/csh setenv SMOOTH_PLOTS 1 pave \ -f /home/thorpe/example_data/399test.wind.bin.d1 \ -s UWINDa \ -contourRange -4000 4000 \ -tinit 0 -tfinal 12 -gtype tile -saveImage GIF /tmp/test%02d.gif \ -quit-scatter "<formula1>" "<formula2>" creates a scatter plot using the two formulas specified. Note that the formulas for the two components should have already been loaded into PAVE, and they are case sensitive.
-showWindow <windowId> <timestep> Sets the time step of the window with the specified X-window ID to the specified timestep. The timestep must be within the allowable range for the dataset.
-subdomain <xmin> <ymin> <xmax> <ymax> sets the PAVE domain matching the currently selected dataset to the bounding box specified by its arguments. The currently selected dataset is usually the most recently added dataset, unless you have modified it by selecting another dataset using the user interface. It is often handy to type -subdomain commands into PAVE's standard input if you are trying to select a very precise subdomain (such as that needed for a vertical cross-section plot).
-subTitle1 and -subTitle2 allow the user to control a tile or vector plot's subtitles if desired. Subsequent plots will use the default subtitles, unless these arguments are used again.
-subTitleFont"<fontSize>"allow the user to control the font size of the subtitle of a pave plot.
-system "<unix command>" sends the specified command to the UNIX command line using C language's system() routine.
-tfinal <final time step> sets the last time step for each formula's time step range to the specified step number, where the first step number is denoted by 0.
-tileYlabelsOnRight causes the tile plot's Y axis labels to appear on the right hand side of the plot, rather than the default of the left hand side.
-tinit <initial time step> sets the first time step for each formula's time step range to the specified step number, where the first step number is denoted by 0.
-titleFont"<fontSize>"allow the user to control the font size of the title of a pave plot.
-titleString "<title string>" sets the title for the next plot made to the specified title. Subsequent plots will use the default PAVE title, unless this argument is used again.
-ts <time step> sets the selected time step for each formula in PAVE's memory to the specified step number, where the first step number is denoted by 0.
-tzoffset <Timezone offset>changes the time by the specified offset value, use a +/- integer value. This option is specified after the -gtype tile option
-tzset <in Timezone> <out Timezone> The <out Timezone> will be
displayed in parenthesis next to the time on the tile plot. The correct specification
of the <in Timezone> can not be verified by PAVE. It is the responsibility
of the user that the timezone specified as <in Timezone> matches the native timezone
of the input data.
Currently Supported Timezones, (use the acronym in all caps)
GMT, Greenwich Mean Time; CET, Central European Time; EET, Eastern European Time
AST, Atlantic Standard Time; EST, Eastern Standard Time; CST, Central Standard Time
MST, Mountain Standard Time; PST, Pacific Standard Time; YST, Yukon Standard Time
HST, Hawaii Standard Time
-width and -height allow the user to control a tile plot's width and height in pixels. All subsequent plots will use the supplied value for height/width, until a non-positive value is supplied as a subsequent argument. At that point PAVE's default height/width will be used.
-unalias <aliasname>used to undefine an alias
-unitString can be used to override the default unit label used for tile plots. The default value comes from the dataset(s) themselves.
-vector "<U>" "<V>" creates a vector plot with U as the left to right vector component and V as the down to up vector component. There are no background colors used for this type of plot. Note that the formulas for the two components should have already been loaded into PAVE, and they are case sensitive.
-vectobs <formula> <formula> plot wind vector observational data overlayed on a vector tile plot of model wind vector data.
An example script application:
#!/bin/csh -f
setenv DATA_DIR1 $EDSS_ROOT/data/frmwk/pave/
setenv FILE1 mm5_winds.smraq.lyr_1.avg.full
setenv FILE2 TDL_OBS.avg.smraq
setenv PAVE_VECTOBS_COLOR blue
pave \
-f ${DATA_DIR1}/${FILE1} \
-s U_AVGa -gtype tile\
-s V_AVGa \
-f ${DATA_DIR1}/${FILE2} \
-s U_OBSb \
-s V_OBSb \
-vectorScale 15 \
-vectortile U_AVGa U_AVGa V_AVGa \
-vectobs U_OBSb V_OBSb
-vectorPlotEvery <number> causes PAVE to plot every n vectors where n is equal to the number specifed (n must be an integer).
-vectorScale <scale factor> uses scale (an integer number) to adjust the length of non-uniform vectors. This needs to be specified before the -vectortile option
-vectorTile "<formula>" "<U>" "<V>" creates a vector plot with the result of "formula" as the background tiles, U as the left to right vector component, and V as the down to up vector component. Note that the formulas for the three components should have already been loaded into PAVE, and they are case sensitive.
-version prints out information about the PAVE version being used on the standard output stream, that is usually sent to the window PAVE was launched in.
-windowidPrint the X-window ID of the most recently created window.
Here are a few notes to keep in mind regarding the above scripting commands:
compare.pave: #!/bin/csh -f setenv DATA_DIR /ep/otag/jul93/output setenv SCEN1 07bas1B setenv SCEN2 93snsDuc2 pave \ -f $DATA_DIR/$SCEN1/bin/avrg.cc.22jul93-07.mc.$SCEN1 \ -f $DATA_DIR/$SCEN2/bin/avrg.cc.22jul93-93.mc.$SCEN2 \ -configFile /ep/otag/jul93/output/base_o3.cfg \ -unitString "PPM" \ -titleString "$SCEN1 Ozone" \ -s O3a -tinit 12 -tfinal 17 -gtype tile \ -titleString "$SCEN2 Max Ozone" \ -s max\(O3b\) -tinit 12 -tfinal 18 -gtype tile \ -configFile /ep/otag/jul93/output/compare_o3.cfg \ -titleString "$SCEN1 Ozone - $SCEN2 Ozone" \ -s O3a-O3b -gtype tileThis script compares ozone concentrations in coarse grid average files for two scenarios and draws three plots. In the first few lines some environment variables are set to help find data in a generic fashion.
pave \ -f $DATA_DIR/$SCEN1/bin/avrg.cc.22jul93-07.mc.$SCEN1 \ -f $DATA_DIR/$SCEN2/bin/avrg.cc.22jul93-93.mc.$SCEN2 \Here pave is started and two files are loaded (coarse grid average files for a day of interest).
-configFile /ep/otag/jul93/output/base_o3.cfg \In the next line a configuration file is defined. This contains preferences for "base ozone plots" (i.e. plots of ozone concentrations, not differences). The contents of the file are:
base_o3.cfg: ColorMapType NEW in v2.1TON_COLORMAP Legend_Max 0.160 Legend_Min 0.000 Legend_Format %4.3f Number_Labels 7 Invert_Colormap 0 Number_Tiles 8 Save_MPEG_Files 0 Disable_Map 0 Smooth_Plot 0 Draw_Grid_Lines 0 Scale_Vectors 0Here the standard colormap is being used, max and min values are set, and the number of labels is changed to 7. The rest of the values are defaults - they do not need to be in the configuration file. You can create a configuration file by configuring a plot as you want it and choosing Save Configuration Settings from the file menu of the plot.
-unitString "PPM" \ -titleString "$SCEN1 Ozone" \ -s O3a -tinit 12 -tfinal 17 -gtype tile \In these lines, setup is being done up to plot ozone for the first data set. The units and title are defined, the formula to plot is chosen, and in this case only hours 12-17 will be plotted. Finally, a tile plot is created due to the keywords "-gtype tile". NOTE: the \'s at the ends of the lines are continuation characters - don't forget these when you're using PAVE from a C-shell script!
-titleString "$SCEN2 Max Ozone" \ -s max\(O3b\) -tinit 12 -tfinal 18 -gtype tile \In these lines a plot of the maximum ozone in dataset b is created by using the max operator. The \'s around the ()s are required because C-shell will try to interpret the ()s otherwise. Note that by using tinit and tfinal, the maximum is for those hours only, but the resulting file will contain multiple time steps with the same value for each one.
-configFile /ep/otag/jul93/output/compare_o3.cfg \ -titleString "$SCEN1 Ozone - $SCEN2 Ozone" \ -s O3a-O3b -gtype tileIn the last three lines a difference plot is drawn with different preferences as defined by a new configuration file. The rest is similar to the other plots. Here is the configuration file for the difference plot:
compare_o3.cfg: ColorMapType JET_COLORMAP Legend_Max 0.032 Legend_Min -0.032 Legend_Format %4.3f Number_Labels 9 Invert_Colormap 0 Number_Tiles 9Huge example of command line usage:
Here is a huge example of invoking PAVE with command line arguments. Almost all available command line arguments are used by this example. These types of invocations typically are used from within a script that can be run over and over. Of particular note are the vectorTile, vector, scatter, and multitime options, that are only available through command line or via stdin (but NOT via the PAVE user interface).
pave \ -f /pub/storage/edss/framework/EDSSv0.2/example_data/399a.uam.emis.d1 \ -f /200p_scratch/olerud/399a/uamdata/399a.wind.bin.d1 \ -s "sqrt(UWINDb*UWINDb+VWINDb*VWINDb)" \ -s UWINDb \ -contourRange -3.0 3.0 \ -titleString "Ground Level U Wind Speed" \ -gtype tile \ -s VWINDb \ -contourRange -3.0 3.0 \ -titleString "Ground Level V Wind Speed" \ -gtype tile \ -autoContourRange \ -titleString "Ground Level Winds (Bckgnd=Speed)" \ -vectorTile "sqrt(UWINDb*UWINDb+VWINDb*VWINDb)" "UWINDb" "VWINDb" \ -vector "UWINDb" "VWINDb" \ -s "NO2a+NOa" \ -titleString "Ground Level NOx Emissions" \ -gtype tile \ -titleString "Ground Level NOx Emissions" \ -gtype mesh \ -titleString "Ground Level NOx Emissions" \ -gtype line \ -titleString "Ground Level NOx Emissions" \ -gtype bar \ -scatter "UWINDb" "VWINDb" \ -f /200p_scratch/rmm/eastUS_em1_g0 \ -s "NOc+NO2c" \ -contourRange 0 200 \ -subdomain 26 24 37 34 \ -level 1 \ -titleString "Ground Level NOx" \ -gtype tile \ -level 5 \ -titleString "Level 5 NOx" \ -gtype tile \ -levelRange 1 5 \ -contourRange 0 200 \ -subdomain 31 24 31 34 \ -crossSectionType X \ -titleString "First 15 Levels NOx at Col 31" \ -gtype tile \ -contourRange 0 200 \ -subdomain 26 30 37 30 \ -crossSectionType Y \ -titleString "First 15 Levels NOx at Row 30" \ -gtype tile \ -s "NOc" \ -s "NO2c" \ -multitime 2 NOc NO2c
setenv PAVE_EXE <some pathname/executable name> will cause the pave script to use that version of the binary executable when launching PAVE.
setenv PAVE_DEBUG <ON|OFF> in interpreted by the pave script in versions 2.3 or later. If PAVE_DEBUG is set to ON (default is OFF), then the script prints some debugging information about the various paths used when PAVE is executed. This is useful if you are having problems getting PAVE or one of its components to work. You can turn this on by doing setenv PAVE_DEBUG ON before running PAVE.
setenv KILL_PROCESS_GROUP <ON|OFF> is interpreted by the pave script in version 2.3 or later. If KILL_PROCESS_GROUP is set to ON (which is the default behavior in the pave script), then all processes started by PAVE during the session (e.g. time series plots) will be killed when PAVE exits. However, we have found that on Linux, if PAVE is being run from a script the parent script is also killed. Therefore, you may wish to do setenv KILL_PROCESS_GROUP OFF before running PAVE on Linux - especially if you are using scripts.
setenv LOCAL_FILES_ONLY <ON|OFF> is interpreted by the pave script in versions 2.3 or later. If LOCAL_FILES_ONLY is set to ON (the default value is OFF), PAVE will execute without running the software bus. This is useful when running from scripts because you can run multiple instances of PAVE from the same user account. A limitation is that when LOCAL_FILES_ONLY is ON and you are running PAVE in interactive mode, we have been unable to get the local file browser to communicate back to PAVE properly when new files are added. However, files that were added in prior sessions or via the command line may be analyzed.
setenv DENOMINATOR_CUTOFF <some floating point number> will cause PAVE to workaround divide by zero conditions. If this environment variable is set, then for each division, if the denominator is less than or equal to DENOMINATOR_CUTOFF's value, then the result of the divide is set to 0
setenv DISABLE_MAPS 1 will cause PAVE to disable map drawing by default on tile plots
setenv DRAW_GRID_LINES 1 will cause grid lines to be drawn by default on tile plots
setenv ELLISPOID ellipsoidName will cause PAVE to use a
non-default ellipsoid when drawing maps. The valid values for
ellipsoidName are:
MERIT_1983, SGS_85, GRS_1980, IAU_1976, CLARKE_1866, CLARKE_1880
ENGELIS_1985, EVEREST_1969, WGS_60, WGS_66, WGS_72, and WGS_84.
See also the entries on this page for SPHERICAL_EARTH and GRS80.
setenv EDSS_MAPDIR <directory_name> will override PAVE's <top level PAVE directory>/$EDSS_ENV/bin/OPTIMIZE/maps dir, which is where PAVE looks for its maps by default.
setenv GRS80 will cause PAVE to assume the earth's ellipsoid is the one defined by the GRS80 specifications. The defalt ellipsoid is MERIT_1983. See also SPHERICAL_EARTH and ELLIPSOID on this page.
setenv LEGEND_BINS &qu;1,10,100,1000&qu; for example will cause plots to be created with three colors that correspond to values of 1-10, 10-100, and 100-1000. The general format for the value of this environment variable is a comma separated list of numbers.
setenv NO_AUTHOR_STRING will cause PAVE not to put PAVE by MCNC on plots.
setenv PAVE_EXPORT_VARNAME <some alphanumeric string> can be used to override the default variable name of "VAR" when exporting data to netCDF files from PAVE.
setenv PAVE_DISTINCT_STATE_COUNTIES will cause PAVE to display state and county lines in different colors (gray / black).
setenv PAVE_VECTOBS_COLOR <colorName> will cause PAVE to draw the observational vectors with the specified color. Potential colors and RGB values are usually found in /usr/lib/X11/rgb.txt for non-Suns or /usr/openwin/lib/X11/rgb.txt on Suns.
setenv PRECLIP_LLLAT <0>
setenv PRECLIP_LLLON <-180>
setenv PRECLIP_URLAT <85>
setenv PRECLIP_URLON <70> will cause PAVE
to use a "pre-clip" map region bounded by the lat/lon coordinate
pairs (-180,0) and (70,85). These environment variables can be
used to access PAVE's world map over a region outside of North
America.
For further information on how to use the world map, please see the
PAVE FAQ located at
Pave.FAQ.html#WorldMap.
setenv PRINTER 200p_lw will cause tile plots to be sent to 200p_lw when printed
setenv SBUS_EXEC_RC <rc file name> can be used to override the default file ~/.edss_exec_rc, which is used to locate various EDSS subsystems
setenv SBUS_RLOGIN_RC <rc file name> can be used to override the default file ~/.edss_rlogin_rc, which is used for the userids to use for remote data access. You will only need to worry about this if your remote account's login name is not the same as your local login name.
setenv SCALE_VECTORS 1 will cause vector length to be scaled by their magnitude by default on vector plots
setenv SMOOTH_PLOTS 1 will cause PAVE to smoothly interpolate pixels on tile plots by default
setenv TENTHS_SECS_BETWEEN_FRAMES 10 will cause a minimum of 1 wall clock second between animation frames. Units are tenths of a second, allowable range is 0..50
setenv PAVE_COORD "GDTYP P_ALP P_BET P_GAM XCENT YCENT"
<some real number> can be used to define the projection
parameters. CAMx or UAM files in the Lambert conformal projection are
not self-contained, as the lambert parameters are not specified in the file header.
To inform PAVE that the CAMx or UAM file has the conformal projection,
specify the values using the PAVE_COORD environment variable.
GDTYP,P_ALP,P_BET,P_GAM,XCENT,YCENT are defined in the the IOAPI documentation
http://www.baronams.com/products/ioapi/GRIDS.html
An example for a lambert conformal grid with a reference lat/lon of (40N,100W)
and latitudes of two parallels, 60N and 30N. Note XCENT is typically equal to
P_GAM.
setenv PAVE_COORD "2 30 60 -100 -100 40"
setenv [ P_ALP|P_BET|P_GAM|XCENT|YCENT|XORIG|YORIG|XCELL|YCELL ]
<some real number> can be used to supersede any of the respective
netCDF header values. Before
creating a PAVE plot, the environment variables will be checked and
appropriate fields replaced.
setenv SPHERICAL_EARTH radius will cause PAVE to treat the earth as a sphere with the specified radius when drawing maps. If you set the value of radius to 1, it will use the default radius of 6370997 meters. Note that the default ellipsoid is MERIT_1983. See also the entries on this page for GRS80 and ELLIPSOID.
setenv UAM_MISSING_VALUE <some floating point number> can be used to define a value that corresponds to missing data for UAM format files. If this environment variable is not set, the value defaults to -999.0.
setenv USE_LOCAL_VISD will cause PAVE to read all files on the local computer with the visd instead of as local files. This is useful if a file to be visualized on a 64 bit capable SGI is larger than 2 GB. This should only be used at times when very large files are being visualized because it is slower than reading files locally.
setenv VECTOR_COLOR <colorName> will cause PAVE to draw the vectors with the specified color. Potential colors and RGB values are usually found in /usr/lib/X11/rgb.txt for non-Suns or /usr/openwin/lib/X11/rgb.txt on Suns.
setenv ADD2DHLINE <some floating point number> used to define a horizontal line to a 2-D plot such as a timeseries plot.
setenv GRAPH2DCFG <blt filename> This specifies a BLT configuration file that can be modified to configure 2D plots. All 2D plotting in PAVE is generated using the BLT library, which is an extension to the (Tcl)/Tk library.
setenv HOST <machine name or ip address> used to specify a remote hostname from which to obtain a file, used in the -f option.
You must have your input datasets in Models-3 IO/API (netCDF) UAM-IV, or UAM-V formatted data files.
PAVE can be displayed on most X displays with at least 8 bits of color. Using X windows software on a PC or Macintosh, you should be able to to display PAVE output from any of the above Unix platforms.
(OPTIONAL - READ THE REST OF THIS SECTION THIS ONLY IF YOU WANT TO ACCESS REMOTE DATA)
PAVE uses several optional files in your home directory when starting up, and writes over them with each PAVE session termination. These are used to maintain a snapshot of the current formulas, datasets, and aliases being used within PAVE:
~/.edss_rlogin_rc # you may need to create if using remote data
~/.edss_exec_rc # PAVE will create if not already there
~/.pave_history_rc # PAVE will set this up automatically
~/.pave.alias # PAVE will set this up automatically
~/.pave.AA.cases # PAVE will set this up automatically
~/.pave.AA.formula # PAVE will set this up automatically
The only one that really matters is ~/.edss_rlogin_rc, which
is used for setting up remote data accessibility. Here are the contents
of an example ~/.edss_rlogin_rc file, which you can borrow
from to create your own. Also note the instructions for setting up
remote .rhosts files and paths to the visd and busd daemons.
# ~/.edss_rlogin_rc # # ------------------------------------------- # If you want to use PAVE to read remote data: # ------------------------------------------- # This file will need to be used by PAVE to launch a # daemon on any remote machine(s). The daemon(s) actually # read the data and ship it back to your local machine. # # Copy this file to *your* ~/.edss_rlogin_rc and modify # it appropriately # # On each machine you will need to set up a ~/.rhosts # file that allows THIS machine to rsh to it. On most machines # a .rhosts file is a list of machine and login name pairs # found in your home directory (e.g. sirrocco smith). Make sure # that this file is readable only by you for security reasons. # # Suppose you are running PAVE on sirocco, and you want to use it # to read data that is sitting on sequoia. Test to see that your # .rhosts file on sequoia works by making sure the following # commands on sirocco: # # rsh sequoia.nesc.epa.gov -l <YOUR sequoia USERID> which visd # rsh sequoia.nesc.epa.gov -l <YOUR sequoia USERID> which busd # # successfully execute and tell you the paths to the visd and busd # daemons on the remote sirocco machine. The visd and busd daemons # are in <pave installation dir>/<platform type>/bin/OPTIMIZE/ # for each platform type; on remote machines you may just wish to # copy them to your home directory if it makes it easier for you. # These daemons are used to read remote data; until they are in your # remote path, you won't be able to read any data on that remote # machine. # # Any line in this file with a # in it is ignored. # #################################################################### # $HOME/.edss_rlogin_rc file contains the userids for remote machine # names. If remote userid is same as local, you don't need to list it. # Lines preceded by a '#' are ignored. # The format of the contents in the file are: # <machine-name><space><userid> # The machine name can be the entire name or without the domain name # (eg. nox, rain) #################################################################### #mary.jane.doe doe sequoia.nesc.epa.gov tsr t90.ncsc.org demo_t90The other files will be set up for you automatically whenever PAVE executes.
Typing "pave" launches a "wrapper script", which in turn fires up the software bus and the PAVE executable itself. The PAVE executable itself should never be launched directly from the command line, as this wrapper script is required to set up PAVE's environment.
Click on its "Add" button, and an EDSS file browser should appear:
(this may take a couple seconds). The file browser has a "Filter" widget at the top. You can see the files in a particular directory by typing or pasting in the directory name and adding a "/*" at the end and hitting return. Alternatively, you can navigate through the directory structure by double clicking on directories in the Directories list (or single clicking and hitting return). Once you get to the directory that contains the file you want, you can select the file by clicking on it in the Files list.
Use the file browser to add the file
"<top level PAVE directory>/example_data/RADM_CONC_1"(If RADM_CONC_1 is not available, choose any dataset in the directory.) This will become PAVE's dataset "a", and this will be the currently selected dataset. Do the same with
"<top level PAVE directory>/example_data/399a.uam.emis.d1"which will become dataset b.
There may be several other example datasets in <top level PAVE directory>/example_data that you may want to play around with, although some may be missing due to disk space considerations:
-rw-r--r-- 1 thorpe edss 8549788 Aug 17 09:26 399a.avrg.bin.d2 -rw-r--r-- 1 thorpe edss 1070068 Aug 17 09:27 399a.uam.emis.d1 -rw-r--r-- 1 thorpe edss 11870588 Aug 17 09:29 MET_CROSS_2 -rw-r--r-- 1 thorpe edss 11870584 Aug 17 09:30 RADM_CONC_1 -rw-rw-r-- 1 thorpe edss 7871036 Aug 17 09:32 bot_west_chem_ec1_g0 -rw-r--r-- 1 thorpe edss 201048 Aug 17 09:32 exact1
This should now be displaying the species available in dataset b, the currently selected dataset.
Add item "HOa+HO2a" in the "Enter New Formula:" typein box and click on "Add". Add "NOb" and "O3a" as well. You now have a total of four formulas added to your formula list, and O3a is the currently selected formula.
"Graphics/Create Tile Plot"
"Graphics/Create 3d Mesh Plot"
"Graphics/Create Time Series Line Plot"
"Graphics/Create Time Series Bar Plot"
NOTE: All the plots above are associated with the selected
formula, which is probably O3a. The selected formula
can be modified with the "Formulas menu/ Edit/Select from Formula List"
window.
The tile plot and mesh plot show data for the selected region at a particular time step, and can be animated to show other time steps. The time series line and bar plots show data averaged over the selected region at each time step. Here are some things to try with the plots:
By default, the entire domain is selected for any dataset/formula loaded into PAVE. This is indicated by a light blue background on all of the cells in the domain window. You may want to do a time series of a single cell, or perhaps a tile plot of a smaller region of cells. To subselect a region, just left-click-and-drag over any blue areas to deselect cells, and conversely over any white areas to select cells. Also, you can use the Edit menu's "Select All" and "Select None" items to turn all the cells in the domain on or off. Subsequent plots will show data only from the subselected region.
This window can be closed using the File menu's "Close" item. Also note the File menu's "Save Domain To File" and "Load Domain From File" menu items that allow you to save and later retrieve frequently used domain subselections.
After selecting the layers you want to see, type a statement of the following form into PAVE's standard input:
-subdomain 80 20 80 90
Here the arguments to -subdomain are: x1 y1 x2 y2 to define the region to be selected. This will cause the data where x = 80, and y is between 20 and 90 to be selected. To see this region on the screen (and/or to set this region using the User Interface rather than a command line option), you can choose "Select Regions of Interest Matching Current Dataset". A window showing the domain will come up. Alternatively, you can select the cells with the mouse, but this gets difficult when grid cells are small and you want to select a very precise area.
Now that the layers and region to be plotted are selected, you need to set the cross section type. Under the Graphics menu, choose "Set Tile Plot Cross Section Type" and you will see a submenu of X, Y, or Z cross sections. To make a plot for the above example choose "X Cross Section" (remember this by noting that x is constant). Next, draw the plot for a formula using that dataset by choosing "Create Tile Plot" from the Graphics menu, and you will see the plot of that cross section.
We have a new tool for submitting bug reports, suggestions, and questions. A complete list of the bugs and their status may be obtained by doing a query on PAVE. Please submit bugs or requests for enhancement to Bugzilla for any bugs or requests for enhancements that are needed. If you would like to be notified of any change of status for bugs that were submitted by another user, please add your e-mail address to the CC list by clicking on the bug id, and entering your information to the Add CC text box. http://bugz.unc.edu
Malloc failure: If PAVE prints or pops up a message of the form "malloc failure" or "VIS_DATA_Dup() failed" this means that PAVE has run out of usable memory while trying to perform the requested operation. To make more memory available, try closing some plots or quit and restart PAVE.
Can't allocate ramp color xxx: If PAVE prints a message about not being able to allocate a color that means that all available colors for the current session on your system have been used up. Applications like netscape will use as many colors as possible. To keep more colors available to applications like PAVE, try running netscape with the option -ncols 64 to prevent it from getting all the colors. This problem may also occur if you've selected a lot of different color schemes during your current PAVE session. To get all colors in the desired color scheme try quitting and restarting PAVE after you've chosen the scheme that you like. Also, logging out of your current session and logging back in should make the maximum number of colors available.
The pave script now responds to the environment variable KILL_PROCESS_GROUP. If KILL_PROCESS_GROUP is set to ON (which is the default behavior in the pave script), then all processes started by PAVE during the session (e.g. time series plots) will be killed when PAVE exits. However, we have found that on Linux, if PAVE is being run from a script the parent script is also killed. Therefore, you may wish to do setenv KILL_PROCESS_GROUP OFF before running PAVE on Linux - especially if you are using scripts.
The pave script now reponds to the environment variable LOCAL_FILES_ONLY. If LOCAL_FILES_ONLY is set to ON (the default value is OFF), PAVE will execute without running the software bus. This is useful when running from scripts because you can run multiple instances of PAVE from the same user account. A limitation is that when LOCAL_FILES_ONLY is ON and you are running PAVE in interactive mode, we have been unable to get the local file browser to communicate back to PAVE properly when new files are added. However, files that were added in prior sessions or via the command line may be analyzed.
The pave script now reponds to the environment variable PAVE_DEBUG. If PAVE_DEBUG is set to ON (default is OFF), then the script prints some debugging information about the various paths used when PAVE is executed. This is useful if you are having problems getting PAVE or one of its components to work. You can turn this on by doing setenv PAVE_DEBUG ON before running PAVE.
-drawLegend ON|OFF -drawMinMax ON|OFF -drawTimeStamp ON|OFF -drawTiles ON|OFF -drawGridLabels ON|OFF
A new command line argument -onlyDrawLegend ON|OFF was added. In this case, you'll get a plot for which only the legend is drawn. This is useful if you want to place the legend in another document. You can crop this plot when exporting images using scripts by using the -imageMagickArgs command line option.
The command line argument -imageMagickArgs 'args' was added. When used, this command line argument will pass the contents of args to the convert program that is called when images are converted from X-window dumps to other image formats. For more information on the command line arguments for convert, see the ImageMagick documentation (available from http://www.imagemagick.org).
PAVE now responds to the environment variable ELLISPOID to specify the earth's ellipsoid. See Environment Variables page for more information.
You can now specify the radius of the earth and treat the earth as a spher using the environment variable SPHERICAL_EARTH. See Environment Variables page for more information.
Updated COPYRIGHT info to GNU Public License.
Removed references to MCNC.
PAVE by MCNC is no longer put on plots by default.
The map region is no longer preclipped by default.
Added PNG as a format to which images can be exported.
PAVE now kills BLT and other child processes upon exit. This works for Interix, but should be tested more thoroughly on other platforms.
The limitation on the maximum number of timesteps was removed. Now annual hourly files can be analyzed.
Updated Makefiles to have more utility.
Corrected problem with very large and small numbers changing to scientific notation then causing problems in formulas.
[ -alias <aliasname=definition> (NEW)!!!]
[ -animatedGIF <filename>(NEW!!!)]
[ -minMaxModelObs <col> <row> <radius> <formula1> <formula2> (NEW!!!) ]
[ -minMaxObs <col> <row> <radius> <formula1> <formula2> (NEW!!!) ]
[ -multivarNcf <formulaList> <varList> <fileName> (NEW!!!) ]
[ -nHourAverage <nhours> (NEW!!!)]
[ -nHourSum <nhours> (NEW!!!)]
[ -nLayerAverage (NEW!!!)]
[ -nLayerSum (NEW!!!)]
[ -obs <formula> (NEW!!!) ]
[ -obsIdTable <filename> (NEW!!!) ]
[ -obsSize <size> (NEW!!!) ]
[ -obsThick <size> (NEW!!!) ]
[ -obsTimeSeries (NEW!!!) ]
[ -printAlias (NEW!!!) ]
[ -save2ascii <filename> (NEW!!!)]
[ -save2ncf <filename> (NEW!!!)]
[ -subTitleFont <fontSize> (NEW!!!)]
[ -titleFont <fontSize> (NEW!!!)]
[ -ts <time step> (NEW!!!)]
[ -tzoffset <Timezone offset> (NEW!!!)]
[ -tzset <in Timezone> <out Timezone> (NEW!!!)]
[ -unalias <aliasname> (NEW!!!) ]
[ -vectobs <formula> <formula> (NEW!!!) ]
setenv LEGEND_BINS "1,10,100,1000"
-tinit 0 -tfinal 12 -gtype tile -saveImage GIF /tmp/test%02d.gif
There are several bug fixes with this release:
Op Name Function -- ---- -------- a < b Less than Returns 1 if a < b, else 0 a <= b Less than or equal Returns 1 if a <= b, else 0 a > b Greater than Returns 1 if a > b, else 0 a >= b Greater than or equal Returns 1 if a >= b, else 0 a == b Equal Returns 1 if a equals b, else 0 a != b Not equal Returns 1 if a does not equal b, else 0 a && b And Returns 1 if a != 0 and b != 0, else 0 a || b Or Returns 1 if a != 0 or b != 0, else 0Please note that PAVE's operator precedence (highest to lowest) is as follows. If you wish to override the precedence given below, or are uncertain as to which operator will take precedence, you can feel free to use parentheses in your formulas. This will force expressions within the parentheses to be evaluated first.
Highest 1) abs, log, sqr, sqrt, exp, ln, sin, cos, tan, sind, cosd,
Precedence tand, minx, miny, minz, max, maxy, maxz, mean, min, max,
sum, mint, maxt
2) **
3) /, *
4) +, -
5) <, <=, > >=
6) ==, !=
7) &&
Lowest 8) ||
Precedence
-barplotYformat <format string>
-tileYlabelsOnRight
-subTitle1 "<sub title 1 string>"
-subTitle2 "<sub title 2 string>"
-height <tile plot height in pixels>
-width <tile plot width in pixels>
-copyright
-system "<System Command>"
<format string> is a format character string that will be used by
sprintf() to draw the y axis labels on bar plots. The default
format is %g. NOTE: This option does not work on the IBM platform.The -tileYlabelsOnRight causes the tile plot's Y axis labels to appear on the right hand side of the plot, rather than the default of the left hand side.
The -width and -height command line arguments have been added to PAVE, to allow the user to control a tile plot's width and height in pixels. All subsequent plots will use the supplied value for height/width, until a non-positive value is supplied as a subsequent argument. At that point PAVE's default height/width will be used.
The -subTitle1 and -subTitle2 arguments allow the user to control a tile or vector plot's subtitles if desired.
The -copyright option prints out copyright information on PAVE itself and all of the third party public domain applications that it uses.
The -system option allows the user to supply a command to be fed to the Unix command line using a call to the system() library routine.
The "close" and "quit" menu items have been removed from the Motif menu accessed from the upper left hand corner of a tile plot window or a time series bar plot window.
A Tile Plots "Configure..." window has been reorganized to be smaller, in order to fit on smaller displays.
Several other minor user interface improvements have been made.
A bug with colors and tile plot configuration files has been resolved. Users can now select a configuration file with color information in it, make plots, and then select a configuration file without color information, and the original colormaps will correctly be used.
Closing a tile plot while it is animating no longer causes PAVE to crash .
Chained files with greater than one layer no longer cause PAVE to crash.
Double clicking on the upper left hand corner of the main PAVE window, a tile plot window, or time series bar plot window will now have no effect . Previously, this caused PAVE to immediately crash.
nan (bogus not-a-number) data in a tile plot no longer causes PAVE to crash. Instead, a warning message is printed to the stderr stream, and no color is plotted in that part of the image.
PAVE no longer kills all processes in its process group when exiting. This means that parent processes (such as VisDriver or the EDSS Console) will remain alive when PAVE exits. However it also means that any mesh plots will prevent PAVE's completion, until they are quit out of individually.
Several other minor bugs have been fixed.
/usr/lib/X11/rgb.txtfor non-Suns or
/usr/openwin/lib/X11/rgb.txton Suns.
[MPEG FILE NAME].param
[MPEG FILE NAME].mpg.0000.xwd
[MPEG FILE NAME].mpg.0001.xwd
:
[MPEG FILE NAME].mpg.N.xwd [where there are N+1 frames in the MPEG]
Note that the MPEG animation will be generated regardless of the setting of the "Keep MPEG Input" button.
Parameter files are used by mpeg_encode to generate the MPEG files from a stream of XWD images saved by PAVE. If you want to generate an MPEG file "manually" using mpeg_encode, the command line format is:
mpeg_encode
For the parameter file below, /home/thorpe/UWINDa2.mpg would be generated from /home/thorpe/UWINDa2.mpg.[0000-0005].xwd.
IQSCALE 6 PQSCALE 6 BQSCALE 6 PSEARCH_ALG LOGARITHMIC BSEARCH_ALG CROSS2 GOP_SIZE 10 SLICES_PER_FRAME 1 PIXEL HALF RANGE 10 PATTERN IBBPBBPBBPBBPBB FORCE_ENCODE_LAST_FRAME BASE_FILE_FORMAT PPM OUTPUT /home/thorpe/UWINDa2.mpg INPUT_CONVERT /pub/storage/edss/framework/EDSSv0.x/IRIX5_mips/bin/OPTIMIZE/public_domain/xwdtopnm * | /pub/storage/edss/framework/EDSSv0.x/IRIX5_mips/bin/OPTIMIZE/public_domain/pnmdepth 255 INPUT_DIR /home/thorpe INPUT UWINDa2.mpg.*.xwd [0000-0005] END_INPUT REFERENCE_FRAME ORIGINAL FORCE_ENCODE_LAST_FRAME
An example of the file format used is as follows:
ColorMapType NEWTON_COLORMAP Legend_Max 0.128 Legend_Min 0.000 Legend_Format %4.3f Number_Labels 5 Invert_Colormap 0 Number_Tiles 8 255 0 0 ColorNumber8 255 147 0 ColorNumber7 218 255 0 ColorNumber6 70 255 0 ColorNumber5 0 255 221 ColorNumber4 0 143 255 ColorNumber3 0 95 255 ColorNumber2 223 223 223 ColorNumber1 Save_MPEG_Files 0 Disable_Map 0 Smooth_Plot 1 Draw_Grid_Lines 1 Scale_Vectors 0
Note the following about the format of the configuration file:
NEWTON_COLORMAP [for Newton RGB (AVS)]
JET_COLORMAP [for Newton RGB (InkJet)]
GREY_COLORMAP [for Grey Scale (AVS)]
Configuration files can be loaded into PAVE sessions in two ways -
using the user interface or from the command line. PAVE's main
window now has a "File... Choose Configuration File For New Tile Plots"
menu item that can be used to select the file. Alternatively, PAVE's
command line arguments or standard input stream can accept input of
the form "-configFile
For example, if a user needs to do the following:
1) save Gif images
2) for the first 13 hours
3) saved to files /tmp/test00.gif .. /tmp/test12.gif
3) of variable UWIND
4) from dataset /home/thorpe/example_data/399test.wind.bin.d1
5) with smoothly colored background (as opposed to tiled)
6) with a contour range of -4000 to +4000
7) from a script, quitting PAVE upon completion
The following script would do the job:
#!/bin/csh
setenv SMOOTH_PLOTS 1
pave \
-f /home/thorpe/example_data/399test.wind.bin.d1 \
-s UWINDa \
-contourRange -4000 4000 \
-tinit 0 -tfinal 12 -gtype tile -saveImage GIF /tmp/test%02d.gif \
-quit
Some of the features we would like to add are listed below.
If you know of additional features that the community would benefit from, please use our new Bugzilla web page to submit enhancement requests. http://bugz.unc.edu
It would be a good idea to update PAVE to use the most recent versions of BLT for time series plots, Tcl/Tk, and PLPLOT.
Currently the MPEG generation uses an old technique. It would be good to update this to use ImageMagick to generate MPEGs as well as the other formats.
Currently, when Lesstif is used, some of the default windows don't come up in the correct positions and the Close buttons don't work properly.
People often want to use simple statistics to assist with there data analysis (e.g. mean, std. dev.). It would be good if PAVE could produce these. In addition, people may want to slice the data in different ways to obtain these statistics (e.g. mean for each time step or for each vertical layer). There are also a number of commonly used statistics that deal with comparing model data with observations. We may want to examine the "tables" generated for OTAG for ideas for other typically used statistics.
Only limited testing has been done using PAVE with the polar stereographic map projection. More testing is required, and any bug fixes should be implemented.
Additional kinds of plots have been requested by users. Some examples include: vertical cross section plots where the size of the layers is proportional to actual layer size, vertical profiles, contour plots, flux plots, observational data plots described above, PIG plots, nested grid plots, adaptive grid plots, box & whisker plots. Also, making scatter plots internal to PAVE would help reduce the problems associated with transferring data to BLT and would provide additional flexibility.
It would be useful to be able to plot multiple maps (e.g. state + counties, or counties + roads) using different colors and thicknesses as needed. Another possibility would be to allow backgrounds generated by packages such as GISs to be displayed - these might show roads, water, cities, etc.
It would be useful in some cases to allow users to define the cutoffs between the colors plotted (currently PAVE makes each bin of equal size from the min to the max). Another alternative might include assigning bins according to percentiles. Additional configuration options could be added to vector plots wrt the density of the vectors plotted.
The density and location of grid cell numbering on tile plots and in the domain selector could be improved. Also, the legend could be outlined in black to set off any white or light values and be positioned relative to the size of the legend labels. The size of tile plots could be made user configurable, and the aspect ratio preserved when the plot is manually resized. Data plotted on time series plots could be labeled more clearly.
PAVE performance, both CPU and memory related, can be improved in a number of ways. For example, loops can be reordered to reduce paging to disk, memory leaks can be plugged, and memory can be reused in some formulas.