Appendix B Sec5
BEGINNERS GUIDE
To use PPLUS a minimum of preparation is required. See the chapter on Getting Started for the symbol definitions that are required. Once this has been done PPLUS can be entered by typing PPLUS (or just PPL) in response to the VAX/VMS prompt.
The minimum number of commands needed to read in data and then plot the data are: FORMAT (sets the input format), SKP (a command to position the file to a given record). VARS (tells PPLUS how the data is arranged in each data record), RD (reads the data) and PLOT (create the plot) or CONTOUR (create a contour plot). The name of the file containing the data can be specified with the RD or SKP commands. Following are discussions of these commands and some examples of how these commands are used. For more information see the Command Description chapter.
Appendix B Sec5.1
FORMAT
FORMAT informs PPLUS the type of the data file and the format the data has within this file. Valid formats are:
UNF -- the data is unformatted (data type REAL)
FREE -- the data is formatted and in free form
(xxx) -- the data is formatted with a format of xxx, where xxx is a legal FORTRAN format, i.e., (3F10.2)
Appendix B Sec5.2
VARS
The next command you need to know about is VARS. VARS is a complicated command because it allows great flexibility in the organization of the data within each file record. Position of the characters 1, 2, and 3 within the command line indicates the position of the X, Y, and Z variables within the data record. The format of the command is:
VARS,NGRP,A1, ... ,Ai
where i is the number of data values per data group
NGRP = number of groups per record. For example, if the data file has Depth,Temperature pairs packed 3 pairs per record with a format of 3(F6.1,F6.2) then NGRP=3.
Aj = 1, 2, 3 or blank to indicate that the variable in this position within the group is to be plotted as X (Aj = 1), Y (Aj = 2), Z (Aj = 3), or is not to be read at all (Aj = blank). An example will make this clearer.
EXAMPLE: VARS,1,,2,1
First arg is 1 --> there is only 1 group per record (e.g. 1 scan per line of data) in the data file
Second arg is blank --> Variable 1 in the data record is not to be read. (A1 = blank)
Third arg is 2 --> Variable 2 in the data record is to be plotted as Y (A2 = 2)
Fourth arg is 1 --> Variable 3 in the data record is to be plotted as X (A3 = 1)
No variable is to be read as Z.
The default is VARS,1,1,2 (i.e. one group per record, first variable is X, second is Y)
The following are examples of the VARS command.
VARS,1,,,1 tells PPLUS that there is one group of data per>record and to read the third number in the record as the X variable. Since no Y variable location has been specified the Y variable will contain the sequence number. VARS,5,1,2 lets PPLUS know that there are five groups of data pairs per record. Again the X variable is first and the Ysecond.
VARS,1,1,2,3 informs PPLUS that the data is X,Y,Z triplets with one group per record. The fact that X,Y, and Z appears tells PPLUS that the data is not on a regular grid and PPLUS should place it on an even grid. The method used to place the data on a regular grid and the grid itself are determined by the RD and CONSET commands.
VARS,1,,,,2,1 tells PPLUS that there is one group of data per record where the Y variable is the fourth number and the X the fifth number in the record.
VARS,1,3 tells PPLUS that there is one group of data per record and Z is the only variable in the group. This is for contour data which is already gridded. The RD command defines how the data is stored, i.e., which index varies fastest.
Appendix B Sec5.3
SKP AND RD
The name of the file containing the data to be plotted can be specified with either the SKP or the RD command. The SKP command tells PPLUS to skip records in the data file (e.g., header records or data which should not be plotted). Its format is SKP,N,FILE_NAME where N is the number or records to skip, and FILE_NAME is the name of the data file and is an optional parameter. If the name of the data file is included, the data file will be rewound before skipping. If the data file name is omitted, the file will not be rewound before skipping.
The RD command informs PPLUS how many records to read and what file to read them from. If you are not making a contour plot, the format of the command is RD,NX,FILE_NAME where NX is the number of points to read from the data file and FILE_NAME is the name of the data file and is an optional parameter. If the data file name is included, the data file will be rewound before the data is read. If the data file name is omitted, the file will not be rewound before reading.
If you are making a contour plot, the RD command format is somewhat different. If Z is being read (a 3 in the VARS command), RD defines the size of the plotting grid and prompts the user for the minimum and maximum values of X and Y to be used for the plotting grid. The format for RD is
RD,NX,NY,TYPE,FILE_NAME where NX and NY set the size of the grid for contour data read. Specifically, when X,Y,Z triplets are being read for contouring, the grid on which the data is plotted can be either coarser or finer or the same as the input data. If NX=50 and NY=21, then the data will be plotted on a grid which is 50 x 21 points (regardless of input data limits or gridding). TYPE tells PPLUS whether the data is stored by rows (X varies fastest) or columns (Y varies fastest) if the data is already-gridded contour data. Finally, FILE_NAME is the data file name. If the data file name is included, the data file will be rewound before the data is read. If the data file name is omitted, the file will not be rewound before reading.
Appendix B Sec5.4
PLOT AND CONTOUR
PLOT or CONTOUR initiates plotting. An optional label can be included and this label will be used to title the plot. The label must start with a non-numeric character. See following section on labels.
Appendix B Sec5.5
EXAMPLES
All the examples in this section can be typed in while running PPLUS interactively after typing PPLUS in response to the VAX/VMS prompt. Just be sure you have first defined the PPLUS symbols according to the Getting Started chapter before you try to do this. Once the plot appears on your terminal, enter <CR> to exit from graphics mode and continue. To exit from PPLUS, type EXIT.
Appendix B Sec5.5.1
The following example reads in data from an unformatted filewith one group of data per record. The data to be plotted has Xin the second position and Y in the first. The data file has 296data points in it but we will read only 100 at a time. The datafile also has an 8 record header that contains character data andmust be skipped.
ppl>FORMAT UNF
ppl>VARS,1,2,1
ppl>SKP,8,PPL$EXAMPLES:DEEP3000.AVG
ppl>RD,100
ppl>PLOT,The first 100 data points
ppl>RD,100
ppl>PLOT,The second 100 data points
Appendix B Sec5.5.2
Pre-gridded Data, Contour Plot
The next example illustrates reading in data to be contoured. The data file is unformatted and does not have any header. The data is already gridded with 1 value of Z per record. Since only Z is read from the data file, the input grid and the plotting grid must be identical, and are specified by the RD command. The grid is 34 points in the x-direction and 5 points in the y-direction. The PPLUS RD command prompts for the minimum and maximum for the X-Y contouring grid. In this example, the grid is 34 points in the x-direction from 10 to -6.5 units and is 51 points in the y-direction from 0 to -500 units. PPLUS will read Z values from the data file assuming x varies fastest. This means that the Z values on the data file correspond to the following x,y pairs:
x y
10.0 0
9.5 0
9.0 0
.
.
-6.5 0
10.0 -10
9.5 -10
9.0 -10
.
.
-6.5 -10
.
.
ppl>FORMAT,UNF
ppl>VARS,1,,3
ppl>RD,34,51,1,PPL$EXAMPLES:CTDDAT.DAT
ENTER XMIN,XMAX,YMIN,YMAX
rd>10,-6.5,0,-500
ppl>CONTOUR,A test plot for contouring
Appendix B Sec5.5.3
Ungridded Data, Contour Plot
This example shows the reading in of ungridded contour data. The data is unformatted with Y,X,Z the order of the triplets. We define the grid for plotting to be 22 x 11 with X and Y limits of 1,22 and -.033,.0576. Although the data file contains less than 1000 points, we can give PPLUS a much larger number to read, and it will stop at the end-of-file without error.
ppl>FORMAT,UNF
ppl>VARS,1,2,1,3
ppl>RD,22,11,PPL$EXAMPLES:GRIDWI.FMT
ENTER NUMBER PTS TO READ
rd>1000
ENTER XMIN,XMAX,YMIN,YMAX
rd>1,22,.033,.567
ppl>CONTOUR,An example of contouring with ungridded data
Appendix B Sec5.5.4
This example demonstrates the reading in of time series data and setting up the x axis to be a time axis. The data file contains a sequence number, which is the day of the year or Julian Day and temperature. Since the sequence number increments by 1 for 1 day, and delta-time is 1 day by default in PPLUS, there is no need to include the delta-time in the TAXIS command. The TAXIS command tells PPLUS that the time series has a delta-time of 1440 minutes (the default) and that the time axis is to be turned on. (The alternate form of the TAXIS command would be "taxis,1440,on".) The TIME command tells PPLUS that the time axis will start at 0000 1 Jul 85, end at 0000 1 Dec 85, and that a sequence number of 1 corresponds to a time of 1200 1 Jan 85. The YLAB command sets the y-axis label. The LIMITS command tells PPLUS to omit data where Y = 0. The VARS command is not needed since the data is formatted with one group of data per record, with the X variable first and the Y variable second, which is the VARS command default. The CROSS command suppresses the drawing of a solid line through x=0, y=0 on the plot. The BOX command suppresses the drawing of a box around the entire plotting region. The SKP command names the data file and skips past the 5 header records at the beginning of the data file. The RD command reads the data. The PLTYPE command sets the plotting medium to be both Tektronix compatible and binary suitable for routing to hardcopy devices. The PLTNME sets the name of the output plot file. The PLOT command generates the plot. See the Command Description chapter for a full description of all PPLUS commands.
ppl>format (17x,f3.0,7x,f5.0)
ppl>taxis,on
ppl>time,W8507010000,W8512010000,W8501011200
ppl>ylab,Air Temperature
ppl>limits,0,yeq,on
ppl>cross,0
ppl>box,off
ppl>skp,5,ppl$examples:atlas.dat
ppl>rd
ppl>pltype,2
ppl>pltnme,atlas.plt
ppl>plot,ATLAS Air Temperature at 2N 165E
Additional examples are in the directory PPL$EXAMPLES in the form of PPLUS command files, which are the files with extension .PPC. Use the VAX/VMS command "DIR PPL$EXAMPLES:*.PPC" to see what the file names are. You can run these command files with the VAX/VMS command "PPLUS PPL$EXAMPLES:xxx.PPC", where xxx is the name of the PPLUS command file. The file will generate a plot on your terminal. Enter a <CR> to exit from graphics mode and return to the VAX/VMS prompt. (Be sure that you have first defined the PPLUS symbols according to the Getting Started chapter before you do this.) See the chapter on Command Files for more information about using PPLUS command files.
You can copy these PPLUS command files to your own directory with the VAX/VMS command "COPY PPL$EXAMPLES:*.PPC []". Then you can run them with the VAX/VMS command "PPLUS xxx.PPC", where xxx is the name of the PPLUS command file. You can experiment with PPLUS commands by editing the PPLUS command file to change the appearance of the plot, and then run PPLUS again with your new command file.