2.6.1 Plot options

The following options affect an entire plot. They should normally occur at most once, and should appear on the command line before the first file name. If a multiplot is being drawn, they may (with the exception of the ‘-T’ option) occur more than once. If so, the second and later occurrences should be placed on the command line immediately after each ‘--reposition x y’ option, which separates the plots in a multiplot.

‘-T type’

‘--output-format type’

(String, default "meta".) Select an output format of type type, which may be one of the strings "X", "png", "pnm", "gif", "svg", "ai", "ps", "cgm", "fig", "pcl", "hpgl", "regis", "tek", and "meta". These refer respectively to the X Window System, PNG format, portable anymap (PBM/PGM/PPM) format, pseudo-GIF format, the XML-based Scalable Vector Graphics format, the format used by Adobe Illustrator, idraw-editable Postscript, the WebCGM format for Web-based vector graphics, the format used by the xfig drawing editor, the Hewlett–Packard PCL 5 printer language, the Hewlett–Packard Graphics Language (by default, HP-GL/2), the ReGIS (remote graphics instruction set) format developed by DEC, Tektronix format, and device-independent GNU graphics metafile format. The option ‘--display-type’ is an obsolete alternative to ‘--output-format’.

‘-E x|y’

‘--toggle-axis-end x|y’

Set the position of the indicated axis to be on the other end of the plotting box from what is currently the case. E.g., ‘-E y’ will cause the y axis to appear on the right of the plot rather than the left, which is the default. Similarly, ‘-E x’ will cause the x axis to appear at the top of the plot rather than the bottom. Note that if the x axis appears at the top, no plot title will be drawn, since there will be no room.

‘-f size’

‘--font-size size’

(Float, default 0.0525.) Set the size of the font used for the axis and tick labels to be size. The size is specified as a fraction of the minimum dimension (width or height) of the plotting box.

‘-F font_name’

‘--font-name font_name’

(String, default "Helvetica" except for graph -T pcl, for which "Univers" is the default, and graph -T png, graph -T pnm, graph -T gif, graph -T hpgl, graph -T regis, graph -T tek, and raw graph, for all of which "HersheySerif" is the default.) Set the font used for the axis and tick labels, and for the plot title (if any), to be font_name. The choice of font for the plot title may be overridden with the ‘--title-font-name’ option (see below). Font names are case-insensitive. If the specified font is not available, the default font will be used. Which fonts are available depends on which ‘-T’ option is used. For a list of all fonts, see Text Fonts. The plotfont utility will produce a character map of any available font. See plotfont.

‘-g grid_style’

‘--grid-style grid_style’

(Integer in the range 0...4, default 2.) Set the grid style for the plot to be grid_style. Grid styles 0 through 3 are progressively more fancy, but style 4 is a somewhat different style.

0. no axes, tick marks or labels.
1. a pair of axes, with tick marks and labels.
2. box around plot, with tick marks and labels.
3. box around plot, with tick marks and labels; also grid lines.
4. axes intersect at the origin, with tick marks and labels.

‘-h height’

‘--height-of-plot height’

(Float, default 0.6.) Set the fractional height of the plot with respect to the height of the display (or virtual display, in the case of a multiplot) to be height. A value of 1.0 will produce a plotting box that fills the entire available area. Since labels and tick marks may be placed outside the plotting box, values considerably less than 1.0 are normally chosen.

‘-H’

‘--toggle-frame-on-top’

Toggle whether or not a copy of the plot frame should be drawn on top of the plot, as well as beneath it. This option is useful when the plotted dataset(s) project slightly beyond the frame, which can happen if a large line thickness or symbol size is specified.

‘-k length’

‘--tick-size length’

(Float, default .02.) Set the length of the tick marks on each axis to be length. A value of 1.0 produces tick marks whose length is equal to the minimum dimension (width or height) of the plotting box. A negative length yields tick marks that extend outside the box, rather than inside.

‘-K clip_mode’

‘--clip-mode clip_mode’

(Integer, default 1.) Set the clip mode for the plot to clip_mode. The clip mode is relevant only if data points are being joined by a line, and the line is not being filled to create a filled region (since filled regions are clipped in a fixed way).

There are three clip modes: 0, 1, and 2. They have the same meaning as in the gnuplot plotting program. Clip mode 0 means that a line segment joining two data points will be plotted only if neither point is outside the plotting box. Clip mode 1 means that it will be plotted if no more than one of the two points is outside, and clip mode 2 means that it will be plotted even if both are outside. In all three clip modes the line segment will be clipped to the plotting box.

‘-l x|y’

‘--toggle-log-axis x|y’

Set the specified axis to be a log axis rather than a linear axis, or vice versa. By default, both axes are linear axes.

‘-L top_label’

‘--top-label top_label’

(String, default empty.) Place the text string top_label above the plot, as its `top label', i.e., title. The string may include escape sequences (see Text String Format). The ‘--title-font-size’ option may be used to specify the size of the font. The font is normally the same as the font used for labeling axes and ticks, as selected by the ‘-F’ option. But this can be overridden with the ‘--title-font-name’ option.

‘-N x|y’

‘--toggle-no-ticks x|y’

Toggle the presence of ticks and tick labels on the specified axis. This applies to the grid styles that normally include ticks and tick labels, i.e., grid styles 1, 2, 3, and 4.

‘-Q’

‘--toggle-rotate-y-label’

Position the label on the y axis (which is set with the ‘-Y’ option) horizontally instead of vertically, or vice versa. By default, the label is rotated, so that it is parallel to the y axis. But some output devices (e.g., old X Window System displays, and buggy new ones) cannot handle rotated fonts. So if you specify ‘-T X’, you may also need ‘-Q’.

‘-r right’

‘--right-shift right’

(Float, default 0.2.) Move the plot to the right by a fractional amount right with respect to the width of the display (or virtual display, in the case of a multiplot). This produces a margin on the left side of the plotting box. A value of 0.5 will produce a margin half the width of the available area. Note that the tick marks and labels are drawn in the margin.

‘-R x|y’

‘--toggle-round-to-next-tick x|y’

Toggle whether or not the upper and lower limits of the specified axis should be expanded, so that they both become integer multiples of the spacing between labeled tick marks.

This option is meaningful whenever the user specifies either or both of the limits, by using the ‘-x’ or ‘-y’ option. If the user leaves both limits unspecified, they will always be chosen to satisfy the `integer multiple' constraint.

‘-s’

‘--save-screen’

Save the screen. This option requests that graph not erase the output device before it begins to plot.

This option is relevant only to graph -T tek and raw graph. Tektronix displays and emulators are persistent, in the sense that previously drawn graphics remain visible. So by repeatedly using graph -T tek -s, you can build up a multiplot.

‘-t’

‘--toggle-transpose-axes’

Transpose the abscissa and ordinate. This causes the axes to be interchanged, and the options that apply to each axis to be applied to the opposite axis. That is, data points are read in as (y, x) pairs, and such options as ‘-x’ and ‘-X’ apply to the y axis rather than the x axis. If the ‘-I e’ option is in force, so that the data points are read with error bars, the orientation of the error bars will be switched between vertical and horizontal.

‘-u up’

‘--upward-shift up’

(Float, default 0.2.) Move the plot up by a fractional amount up with respect to the height of the display (or virtual display, in the case of a multiplot). This produces a margin below the plotting box. A value of 0.5 will produce a margin half the height of the available area. Note that the tick marks and labels are drawn in the margin.

‘-w width’

‘--width-of-plot width’

(Float, default 0.6.) Set the fractional width of the plot with respect to the width of the display (or virtual display, in the case of a multiplot) to be width. A value of 1.0 will produce a plotting box that fills the entire available area. Since labels and tick marks may be placed outside the plotting box, values considerably less than 1.0 are normally chosen.

‘-x [lower_limit [upper_limit [spacing]]]’

‘--x-limits [lower_limit [upper_limit [spacing]]]’

(Floats.) The arguments lower_limit and upper_limit specify the limits of the x axis, and the optional argument spacing specifies the spacing of labeled ticks along the axis. If any of the three arguments is missing or is supplied as ‘-’ (i.e., as a single hyphen), it is computed from the data. Both arguments lower_limit and upper_limit must be present if graph is to act as a real-time filter.

By default, the supplied limit(s) are strictly respected. However, the ‘-R x’ option may be used to request that they be rounded to the nearest integer multiple of the spacing between labeled ticks. The lower limit will be rounded downward, and the upper limit upward.

‘-X x_label’

‘--x-label x_label’

(String, default empty.) Set the label for the x axis to be the text string x_label. The string may include escape sequences (see Text String Format). The ‘-F’ and ‘-f’ options may be used to specify the name of the font and the size of the font.

‘-y [lower_limit [upper_limit [spacing]]]’

‘--y-limits [lower_limit [upper_limit [spacing]]]’

(Floats.) The arguments specify the limits of the y axis, and the spacing of labeled ticks along it, as for the x axis (see above). Both arguments lower_limit and upper_limit must be present if graph is to act as a real-time filter.

By default, the supplied limit(s) are strictly respected. However, the ‘-R y’ option may be used to request that they be rounded to the nearest multiple of the tick spacing. The lower limit will be rounded downward, and the upper limit upward.

‘-Y y_label’

‘--y-label y_label’

(String, default empty.) Set the label for the y axis to be the text string y_label. The string may include escape sequences (see Text String Format). The label will be rotated by 90 degrees so that it is parallel to the axis, unless the ‘-Q’ option is used. (Some X Window System displays, both old and new, do not properly support rotated labels, so that if you specify ‘-T X’, you may also need ‘-Q’.) The ‘-F’ and ‘-f’ options can be used to specify the name of the font and the size of the font.

‘--bg-color name’

(String, default "white".) Set the color used for the plot background to be name. This is relevant only to graph -T X, graph -T png, graph -T pnm, graph -T gif, graph -T cgm, graph -T regis, and graph -T meta. An unrecognized name sets the color to the default. For information on what names are recognized, see Color Names. The environment variable BG_COLOR can equally well be used to specify the background color.

If the ‘-T png’ or ‘-T gif’ option is used, a transparent PNG file or a transparent pseudo-GIF, respectively, may be produced by setting the TRANSPARENT_COLOR environment variable to the name of the background color. See graph Environment. If the ‘-T svg’ or ‘-T cgm’ option is used, an output file without a background may be produced by setting the background color to "none".

‘--bitmap-size bitmap_size’

(String, default "570x570".) Set the size of the graphics display in which the plot will be drawn, in terms of pixels, to be bitmap_size. This is relevant only to graph -T X, graph -T png, graph -T pnm, and graph -T gif, for all of which the size can be expressed in terms of pixels. The environment variable BITMAPSIZE may equally well be used to specify the size.

The graphics display used by graph -T X is a popped-up X window. Command-line positioning of this window on an X Window System display is supported. For example, if bitmap_size is "570x570+0+0" then the window will be popped up in the upper left corner.

If you choose a rectangular (non-square) window size, the fonts in the plot will be scaled anisotropically, i.e., by different factors in the horizontal and vertical direction. Any font that cannot easily be anisotropically scaled will be replaced by a default scalable font, such as the Hershey vector font "HersheySerif".

For backward compatibility, graph -T X allows the user to set the window size and position by setting the X resource Xplot.geometry, instead of ‘--bitmap-size’ or BITMAPSIZE.

‘--emulate-color option’

(String, default "no".) If option is "yes", replace each color in the output by an appropriate shade of gray. This is seldom useful, except when using ‘graph -T pcl’ to prepare output for a PCL 5 device. (Many monochrome PCL 5 devices, such as monochrome LaserJets, do a poor job of emulating color on their own. They usually map HP-GL/2's seven standard pen colors, including even yellow, to black.) You may equally well request color emulation by setting the environment variable EMULATE_COLOR to "yes".

‘--frame-color name’

(String, default "black".) Set the color used for drawing the plot frame, and for drawing monochrome datasets (if any) to be name. An unrecognized name sets the color to the default. For information on what names are recognized, see Color Names.

‘--frame-line-width frame_line_width’

(Float, default −1.0.) Set the thickness of lines in the plot frame, as a fraction of the size (i.e., minimum dimension) of the graphics display, to frame_line_width. A negative value means that the default value for the line thickness provided by the GNU libplot graphics library should be used. This is usually 1/850 times the size of the display, although if ‘-T X’, ‘-T png’, ‘-T pnm’, or ‘-T gif’ is specified, it is zero. By convention, a zero-thickness line is the thinnest line that can be drawn. This is the case in all output formats. Note, however, that the drawing editors idraw and xfig treat zero-thickness lines as invisible.

graph -T tek and graph -T regis do not support drawing lines with other than a default thickness, and graph -T hpgl does not support doing so if the environment variable HPGL_VERSION is set to a value less than "2" (the default).

‘--max-line-length max_line_length’

(Integer, default 500.) Set the maximum number of points that a polygonal line drawn through any dataset may contain, before it is flushed to the output device, to equal max_line_length. If this flushing occurs, the polygonal line will be split into two or more sub-lines, though the splitting should not be noticeable. Splitting will not take place if the ‘-q’ option, which requests filling, is used.

The reason for splitting long polygonal lines is that some display devices (e.g., old Postscript printers and HP-GL pen plotters) have limited buffer sizes. The environment variable MAX_LINE_LENGTH can also be used to specify the maximum line length. This option has no effect on graph -T tek or raw graph, since they draw polylines in real time and have no buffer limitations.

‘--page-size pagesize’

(String, default "letter".) Set the size of the page on which the plot will be positioned. This is relevant only to graph -T svg, graph -T ai, graph -T ps, graph -T cgm, graph -T fig, graph -T pcl, and graph -T hpgl. "letter" means an 8.5in by 11in page. Any ISO page size in the range "a0"..."a4" or ANSI page size in the range "a"..."e" may be specified ("letter" is an alias for "a" and "tabloid" is an alias for "b"). "legal", "ledger", and "b5" are recognized page sizes also. The environment variable PAGESIZE can equally well be used to specify the page size.

For graph -T ai, graph -T ps, graph -T pcl, and graph -T fig, the graphics display (or `viewport') within which the plot is drawn will be, by default, a square region centered on the specified page. For graph -T hpgl, it will be a square region of the same size, but may be positioned differently. Either or both of the dimensions of the graphics display can be specified explicitly. For example, pagesize could be specified as "letter,xsize=4in", or "a4,xsize=10cm,ysize=15cm". The dimensions are allowed to be negative (a negative dimension results in a reflection).

The position of the graphics display, relative to its default position, may optionally be adjusted by specifying an offset vector. For example, pagesize could be specified as "letter,yoffset=1.2in", or "a4,xoffset=−5mm,yoffset=2.0cm". It is also possible to position the graphics display precisely, by specifying the location of its lower left corner relative to the lower left corner of the page. For example, pagesize could be specified as "letter,xorigin=2in,yorigin=3in", or "a4,xorigin=0.5cm,yorigin=0.5cm". The preceding options may be intermingled.

graph -T svg and graph -T cgm ignore the "xoffset", "yoffset", "xorigin", and "yorigin" options, since SVG format and WebCGM format have no notion of the Web page on which the graphics display will ultimately be positioned. However, they do respect the "xsize" and "ysize" options. For more on page sizes, see Page and Viewport Sizes.

‘--pen-colors colors’

(String, default "1=red:2=green:3=blue:4=magenta:5=cyan".) Set the colors of the pens used for drawing plots, as numbered, to be colors. The format should be self-explanatory. An unrecognized name sets the corresponding color to the default. For information on what names are recognized, see Color Names.

‘--rotation angle’

(Integer, default 0.) Set the rotation angle of the graphics display to be angle degrees. The rotation is counterclockwise. The environment variable ROTATION can equally well be used to specify the rotation angle.

This option is used for switching between portrait and landscape orientations, which have rotation angles 0 and 90 degrees respectively. Postmodernists may also find it useful.

‘--title-font-name font_name’

(String, default "Helvetica" except for graph -T pcl, for which "Univers" is the default, and graph -T png, graph -T pnm, graph -T gif, graph -T hpgl, graph -T regis, and graph -T tek, for all of which "HersheySerif" is the default.) Set the font used for the plot title to be font_name. Normally the font used for the plot title is the same as that used for labeling the axes and the ticks along the axes, as specified by the ‘-F’ option. But the ‘--title-font-name’ option can be used to override this. Font names are case-insensitive. If the specified font is not available, the default font will be used. Which fonts are available depends on which ‘-T’ option is used. For a list of all fonts, see Text Fonts. The plotfont utility will produce a character map of any available font. See plotfont.

‘--title-font-size size’

(Float, default 0.07.) Set the size of the font used for the top label (`title'), as specified by the ‘-L’ option, to be size. The size is specified as a fraction of the minimum dimension (width or height) of the plotting box.