zipfR (version 0.6-70)

zipfR.plotutils: Plotting Utilities (zipfR)

Description

These functions are deprecated and should not be used in new code.

Conveniently create plots with different layout and in different output formats (both on-screen and various graphics file formats).

Each plot is wrapped in a pair of zipfR.begin.plot and zipfR.end.plot commands, which make sure that a suitable plotting window / image file is opened and closed as required. Format and dimensions of the plots are controlled by global settings made with zipfR.par, but can be overridden in the zipfR.begin.plot call.

zipfR.pick.device automatically selects a default device by scanning the specified vector for strings of the form --pdf, --eps, etc.

NB: These are advanced functions intended to make it easier to produce plots in different formats. Most users will only need the basic plotting functionalities provided by plot.tfl, plot.spc and plot.vgc.

Usage

zipfR.pick.device(args=commandArgs())
zipfR.begin.plot(device=zipfR.par("device"), filename="",
                 width=zipfR.par("width"), height=zipfR.par("height"),
                 bg=zipfR.par("bg"), pointsize=zipfR.par("pointsize"))
## plotting commands go here
zipfR.end.plot(shutdown=FALSE)

Arguments

args

a character vector, which will be scanned for strings of the form --pdf, --eps, etc. If args is not specified, the command-line arguments supplied to R will be examined.

device

name of plotting device to be used (see "Devices" below)

filename

for graphics file devices, basename of the output file. A suitable extension for the selected file format will be added automatically to filename. This parameter is ignored for screen devices.

width, height

width and height of the plotting window or image, in inches

bg

background colour of the plotting window or image (use "transparent" for images with transparent background)

pointsize

default point size for text in the plot

shutdown

if set to FALSE (the default), on-screen plot devices will be kept open for re-use in the next plot. Specify shutdown=TRUE to ensure that the screen device is closed after a series of related plots.

Value

zipfR.begin.plot invisibly returns the ID of the active plot device.

Devices

Currently, the following devices are supported (and can be used in the device argument).

Screen devices:

x11

opens the default graphic device set by getOption("device"). In an interactive R sessions, this will usually be a suitable on-screen device.

quartz

accepted as an alias for x11 on macOS platforms

Graphics file devices:

eps

Encapsulated PostScript (EPS) output (using postscript device with appropriate settings)

pdf

PDF output

png

PNG bitmap file (may not be available on all platforms)

Details

zipfR.begin.plot opens a new plotting window or image file of the specified dimensions (width, height), using the selected graphics device (device). Background colour (bg) and default point size (pointsize) are set as requested. Then, any global graphics parameter settings (defined with the init.par option of zipfR.par) are applied. See the zipfR.par manpage for the "factory default" settings of these options.

zipfR.end.plot finalizes the current plot. For image file devices, the device will be closed, writing the generated file to disk. For screen devices, the plotting window remains visible until a new plot is started (which will close and re-open the plotting window).

The main purpose of the zipfR plotting utilities is to make it easier to draw plots that are both shown on screen (for interactive work) and saved to image files in various formats. If an R script specifies filenames in all zipfR.begin.plot commands, a single global parameter setting at the start of the script is sufficient to switch from screen graphics to EPS files, or any other supported file format.

On-screen plotting devices are platform-dependent, and there may be different devices available depending on which version of R is used. For this reason, zipfR.begin.plot no longer allows users to pick an on-screen device explicitly, but rather opens a default device with dev.new. Note that this default device may write output to a graphics file, but is usually set to a suitable on-screen device in an interactive R session. In any case, users can change the default by setting options(device=...). For backwards-compatibility, the device name x11 (and quartz on macOS is accepted for the default graphics device.

The png bitmap device may not be available on all platforms, and may also require access to an X server. Since the width and height of a PNG device have to be specified in pixels rather than inches, zipfR.begin.plot translates the width and height settings, assuming a resolution of 150 dpi. Use of the png device is strongly discouraged. A better way of producing high-quality bitmaps is to generate EPS image (with the eps device) and convert them to PNG or JPEG format with the external pstoimg program (part of the latex2html distribution).

zipfR.pick.device will issue a warning if multiple flags matching supported graphics devices are found. However, it is not an error to find no matching flag, and all unrecognized strings are silently ignored.

See Also

zipfR.par, par

Devices, dev.new, postscript, pdf and png for more information about the supported graphics devices

zipfR-specific plotting commands are plot.spc, plot.spc and plot.vgc

Examples

# NOT RUN {
## these graphics parameters will be set for every new plot
zipfR.par(init.par=list(bg="lightblue", cex=1.3))
zipfR.par(width=12, height=9)

## will be shown on screen or saved to specified file, depending on
## selected device (eps -> "myplot.eps", pdf -> "myplot.pdf", etc.)

zipfR.begin.plot(filename="myplot")
plot.spc(Brown100k.spc)
zipfR.end.plot()

## By starting an R script "myplots.R" with this command, you can
## display plots on screen when stepping through the script in an
## interactive session, or save them to disk files in various
## graphics formats with "R --no-save --args --pdf < myplots.R" etc.
zipfR.pick.device()
# }