Previous: lsf
Up: Manual Pages
Next: mpl2col
Previous Page: lsf
Next Page: mpl2col
Previous: lsf
Up: Manual Pages
Next: mpl2col
Previous Page: lsf
Next Page: mpl2col
mpl [ XView_arguments] plotfilelist [ mpl_options]
[-device=" device-name"[," device-arguments"]] [-output[= filename]]
The device option allows specification of the device name, along with optional arguments to be passed to the device driver. The default device is named in the MPL_DEVICE environment variable. The names of supported devices can be obtained by running mpl without arguments. A list of some presently supported devices is given below.
Device-driver arguments are currently supported only for X11 and Motif graphics; these are typically drawn from the possible XView arguments (see the system manual page on xview).
Most device drivers deliver plotting commands to the standard output; while this can be redirected into a file or printer, mpl has no way of detecting such redirection, and will behave as if it is running interactively. To avoid this, the user can redirect output to a file using the output option. (Also, see the rapid_fire option below.)
[-scales={ xl,xh,yl,yh | scale_file}] [-equal_aspect[=1 | -1]] [-unsuppress_zero[=x,y]]
] [-pspace= pmin,pmax,qmin,qmax]
By default, mpl sets the scales of a plot to encompass all of the data, with 5% margins (see, however, the options for multi-page output below). The scales option allows one to change the scales, either by specifying the plotting region by the lower and upper limits in x and y, or by naming a file from which the scales will be derived as if this file contained all of the data that would be plotted. In the former case, if the lower and upper values are equal for either x, y, or both, then mpl autoscales as before.
The scales may be altered in other ways as well. The equal_aspect option directs mpl to
adjust either the pspace (defined presently) or the plotting region in order to achieve a
unit aspect ratio, depending on whether the value given is or
;
is the default.
The unsuppress_zero option directs mpl to alter the plotting region to include zero, in both
x and y by default, or for x and/or y as requested. The zoom option directs mpl to magnify
the plotting region about (0, 0), or about the specified center, by the specified factors; a factor less
than zero zooms out.
By default, mpl uses as much of the physical device plotting space as consistent with placement of labels and legends. This may be changed using the pspace option, which specifies the corners of the physical device plotting space in terms of coordinates [0, 1] x [0, 1] covering the maximum extent of the plot. (0, 0) is the lower-left corner.
[-plot_code= filenum,plotcode,... [-default_plot_code= plotcode] [-multi_pen]
]
By default, mpl plots all data sets using the same line type, typically a solid line (depending on the device). This behavior can be changed using the plot_code, default_plot_code, and multi_pen options. For each filenum, mpl will accept a plotcode specifying the linetype or symbol type to use for plotting that file. The syntax for a plotcode is {l | s | c | e | d | i | a}n[+m], where the letter codes indicate, respectively, line, symbol, connected symbol, error bar, dots, impulses, and arrow plotting. The integer n is the line, symbol, etc. number (typically 0 through 9), while the integer m is the size exponent (0 through 15, for symbol plotting only). While plot_code allows one to change the plot code for files individually, default_plot_code allows one to change the plot code for all files simultaneously by changing the default from l0. If multi_pen is invoked, successive files are assigned the same letter code with n incremented by 1 for each file.
[-separate_pages [-same_scale]] [-with= extrafile[, sample_interval[, plotcode]]
By default, mpl plots all files on the same page or screen. If separate_pages is invoked, each file is plotted by itself. By default, the scales are adjusted individually for each plot; if same_scale is invoked, the scales will be those that would have been used had all the data be plotted together.
The with option may be employed only in concert with separate_pages. If, invoked, it directs mpl to plot each file from plotfilelist separately with extrafile, a file named in the with option. The with option also accepts a sample_interval (see below) and plotcode for extrafile.
[-no_border | -no_scales] [-subticks= nx,ny] [-grid[={x,y}]] [-axes[=x,y]]
These options provide control of numeric scales, axes, and grids. By default, mpl draws a border around the plotting region, and places tick marks and numeric labels around this border. If no_border is invoked, none of this happens. If no_scales is invoked, a border is drawn, but no ticks or numeric labels are produced.
The grid option directs mpl to draw lines across the plot rather than making ticks; by default this will be done for both x and y. The axes option directs mpl to draw the axes, if they are visible; by default, both the x and y axes are drawn. For both of these options one may limit the application to either x or y by providing the appropriate keywords with the option.
By default, mpl determines the number of ticks (or grid lines) automatically, and provides each tick mark (or grid line) with a numeric label. Invoking the subticks option directs mpl to place half-length, unlabeled tick marks (or grid lines of a different linetype) between the labeled ticks. nx and ny are the number of intervals into which the space between labeled tick marks is divided for x and y.
[-legend=[{filenames | ylabels
| rootnames }][,specified, filenum," string",...] ]
These options provide methods of labeling the data from files to allow the user to identify each graph. The legend option directs mpl to make a legend containing an identifying string and a sample of the plotting style corresponding to this string. Normally, there is one identifying string for each file plotted. By default, the identifying string is the name of the quantity plotted, as extracted from the ``ylabel'' (y-axis label) string for the file. The default may be changed to use the filenames or rootnames (a short section of the filename). In addition, strings may be specified individually for each file by using the specified keyword and providing a list of filenum, " string" pairs. If no legend is desired for a given file, specify an empty string as the legend string.
The lspace option specifies the placement of the legends. pmin and pmax ( qmin and qmax) are the horizontal (vertical) limits in unit coordinates mapped to the plotting region.
The number_graphs option is rather primitive and is not recommended; it places the filenum on each graph.
[-sample= filenum,sampling_interval,...] [-mode= xmode,ymode] These options provide means of changing what data is plotted and of invoking certain types of processing before plotting.
The sample option allows the user to specify an integer sampling_interval for any file, identified by its filenum. In order to set the default sampling interval for all files, use -1 for the filenum.
By default, mpl does not plot data points that are outside the plotting region. These points are removed from the data set prior to plotting, a process referred to as ``windowing'' the data. This will produce undesirable results for many graphs that go outside the plotting region and then back inside. In this case, one prefers that lines be clipped at the plotting region boundaries. This behavior is obtained by invoking the no_window option.
By default, when plotting with the l and c plot-codes, mpl connects all the points in a data set without regard to the ordering of the points. This is sometimes undesirable, as when a data set contains several distinct curves. As a partial solution to the problem, the sever option may be invoked, directing mpl to break any line when the current abscissa value is less than the last abscissa value.
The stagger option provides a means of offsetting data sets for clarity. When this option
is invoked, it directs mpl to offset the abscissae and ordinates of the
data set by
x_amount and
y_amount, respectively.
The mode option provides a means of doing logarithmic plots. xmode and ymode must be one of linear or logarithmic. When invoked, the logarithmic option directs mpl to take the base-ten logarithm of the specified column prior to processing.
[-no_labels] [-labels_from_file= filenum] [-no_filenames]
[-ylabel=" string"] [-title=" string"] [-topline=" string"]
[-query_for_labels] [-vertical_print={up | down}]
These options provide means of altering the plot labels and how (or whether) they are plotted.
If no_labels is invoked, no labels are plotted.
By default, mpl uses the labels from the first input file, and appends the filenames of all input files to the title line. labels_from_file accepts a filenum directing mpl to take the labels from a different file. no_filenames directs mpl to not put the input filenames on the title line.
xlabel, ylabel, title, and string allow the user to specify the respective label strings explicitly. Any of the strings may contain a single occurence of the sequence %s; if present, it will be replaced with the default label (i.e., the label that would otherwise be used for the item in question). query_for_labels provides another mechanism for changing the labels; if invoked, it directs mpl to prompt the user to type in changes to the labels.
By default, the y axis label is written in rotated characters with the direction of writing being upward. Some prefer that the label be written in the downward direction, a behavior that is invoked by supplying the down keyword with the vertical_print option.
[-overlay= filename[, plotcode[, hmag,vmag[, hpos,vpos[,user | unit]]]]]
When mpl plots multiple data sets on a single page, all data sets are plotted to the same scale. In contrast, a data set plotted as an overlay need not be plotted to the same scale as the other data sets. filename is the name of the data set to be overlayed, while plotcode is the plot code to use.
The hmag ( vmag) parameter has two possible uses. Normally, it provides a factor by which to multiply the abscissa (ordinate) values in the overlayed data set. (The ``h'' (``v'') stands for ``horizontal'' (``vertical'').) If the magnification is 1, the data is scaled to fill the plot region, without the normal 5% margin that mpl usually leaves. The second use of these parameters is to provide a flag to direct mpl to plot the coordinates in question to the same scale as the non-overlayed data; this behavior is invoked by setting the relevant magnification parameter to -1. An example of the utility of this would be plotting two data sets with the same range of abscissae but greatly differing ranges of ordinates.
If hmag ( vmag) is not -1, then the hpos ( vpos) parameter is interpreted as the horizontal (vertical) offset of the data set relative to the left (bottom) side of the plotting region. This offset may be in either user or unit coordinates. unit coordinates run from 0 to 1 from the left (or bottom) edge to the top (or right) edge of the plotting region. user coordinates run from the limits previously chosen for plotting the non-overlayed data sets. If either hmag or vmag is -1, then the corresponding offset parameter is ignored, though it may need to be given as a place holder.
[-sleep] [-rapid_fire[= interval_in_secs]]
mpl is intended to be a device-independent program. By default, it assumes that the device is a terminal, and that the graph is being displayed on the terminal from which the program was run. In such a case, the one needs a signal that the graph is finished and one needs to be able to signal that one is done looking at the graph and ready to continue. Hence, mpl will usually emit a beep after finishing a plot, then wait for the user to enter a carriage return before continuing to the next plot or exiting.
There are cases where this behavior is inappropriate. For example, when sending data to a printer or to an independent graphical display window. The sleep and rapid_fire options provide a means of changing the terminal-oriented behavior.
If sleep is invoked, mpl does not beep the terminal when the graph is finished. Instead, the program goes into an indefinite sleep state until killed. This is useful in some cases when one wants to create a graph in a separate window that will stay up until removed.
If rapid_fire is invoked, mpl proceeds from one graph to the next without prompting the user, waiting interval_in_secs seconds between ending one graph and beginning the next. The default interval is 0 seconds. This is useful for sending graphs to files, non-interactive devices (e.g., printers), and independent graphical windows with multiple-page storage capability. (To date, only the motif device type falls into the last category; however, it does not require the rapid_fire option since the code has been written to take this into account automatically.)
borland@aps.anl.gov