export_graph_start: Graph export with garanteed text size

Description

This function facilitates graph exportation by taking into account the final destination of the graph (typically a document) and allowing the user to use point size, an intuitive unit in written documents, as the graph scaler. Once located in the final document, the text of the graph at the default size will be at the defined point size.

Usage

export_graph_start(
  file = NULL,
  pt = 10,
  width = 1,
  height,
  w2h = 1.75,
  h2w,
  sideways = FALSE,
  res = 300,
  type = NULL,
  margin = NULL,
  margin.left = NULL,
  margin.right = NULL,
  margin.top = NULL,
  margin.bottom = NULL,
  margin.unit = "line",
  box = NULL,
  col.bg = NULL,
  col.default = NULL,
  yaxis.horiz = NULL,
  lwd = NULL,
  outermargin = NULL,
  outermargin.left = NULL,
  outermargin.right = NULL,
  outermargin.top = NULL,
  outermargin.bottom = NULL,
  outermargin.unit = "line",
  square_plot = NULL,
  nrow = NULL,
  ncol = NULL,
  byrow = TRUE,
  title.size = NULL,
  title.col = NULL,
  title.bold = NULL,
  title.italic = NULL,
  axis.size = NULL,
  axis.col = NULL,
  axis.bold = NULL,
  axis.italic = NULL,
  label.size = NULL,
  label.col = NULL,
  label.bold = NULL,
  label.italic = NULL,
  ...
)
export_graph_end()

Value

These functions do not return anything in R. export_graph_start creates a file linked to the R graphics engine, in which subsequent plots are saved. export_graph_end closes the connection and the file.

Arguments

file: Character scalar or NULL. The name of the file in which to save the graph. If the argument type is NULL, the type of file is deduced from the extension. If your file extension is different from your file type, you need to use the argument type. It file = NULL, no graph is exported but, if provided, the graphical parameters are modified accordingly.
pt: The size of the text, in pt, once the figure is inserted in your final document. The default is 10. This means that all text appearing in the plot with cex = 1 will appear with 10pt-sized fonts in your document.
width: The width of the graph, expressed in percentage of the width of the body-text of the document in which it will be inserted. Default is 1, which means that the graph will take 100% of the text width. It can also be equal to a character of the type "100%" or "80%". Alternatively, the following units are valid. Relative sizes: "pw" (page width), "tw" (text width), "ph" (page height), "th" (text height). Absolute sizes: "in", "cm", and "px".
height: Numeric between 0 and 1 or character scalar. The height of the graph, expressed in percentage of the height of the body-text of the document in which it will be inserted. Default is missing, and the height is determined by the other argument w2h. This argument should range between 0 and 1. It can also be equal to a character of the type "100%" or "80%". Alternatively, the following units are valid. Relative sizes: "pw" (page width), "tw" (text width), "ph" (page height), "th" (text height). Absolute sizes: "in", "cm", and "px".
w2h: Numeric scalar. Used to determine the height of the figure based on the width. By default it is equal to 1.75 which means that the graph will be 1.75 larger than tall. Note that when argument sideways = TRUE, the default for the height becomes 90%.
h2w: Numeric scalar, default is missing. Used to determine the aspectr ratio of the figure.
sideways: Logical, defaults to FALSE. If the figure will be placed in landscape in the final document, then sideways should be equal to TRUE. If TRUE, then the argument width now refers to the height of the text, and the argument height to its width.
res: Numeric, the resolution in ppi. Default is 300.
type: Character scalar, default is NULL. The type of file to be created. If NULL, the default, then the type of file is deduced from the extension.
margin: Numeric vector, default is NULL. Defines the size of the four plotting margins (in this order: bottom, left, top, right). If of length 1 or 2, the content is recycled to fit 4 elements. By default the unit is the "line" but you can change it with the argument margin.unit.
margin.left: Numeric scalar, default is NULL. The size of the left margin. By default the unit is the "line" but you can change it with the argument margin.unit.
margin.right: Numeric scalar, default is NULL. The size of the right margin. By default the unit is the "line" but you can change it with the argument margin.unit.
margin.top: Numeric scalar, default is NULL. The size of the top margin. By default the unit is the "line" but you can change it with the argument margin.unit.
margin.bottom: Numeric scalar, default is NULL. The size of the bottom margin. By default the unit is the "line" but you can change it with the argument margin.unit.
margin.unit: Character scalar equal to either: i) "line" (default), ii) "inch", iii) "cm".
box: Can be equal to NULL (default), a logical scalar, or a character scalar. Defines how to draw the box around the plotting region. If a logical, TRUE means that all borders are drawn, and FALSE means none. If a character scalar, it should contain the following letters: "b", "l", "t" and/or "r", which stand for the bottom, left, top and right border.
col.bg: An R color, default is NULL. The background color of the plot.
col.default: An R colors, default is NULL. They represent the default color used for plotting (the axes will be drawn with that color and it will be the default color when the argument col is not provided in plotting functions).
yaxis.horiz: Logical, default is NULL. Whether to display the y-axis labels horizontally.
lwd: Numeric scalar, default is NULL. The default width of the lines.
outermargin: Numeric vector, default is NULL. Defines the size of the four outer margins. If of length 1 or 2, the content is recycled to fit 4 elements. By default the unit is the "line" but you can change it with the argument outermargin.unit.
outermargin.left: Numeric scalar, default is NULL. The size of the left outer margin. By default the unit is the "line" but you can change it with the argument margin.unit.
outermargin.right: Numeric scalar, default is NULL. The size of the right outer margin. By default the unit is the "line" but you can change it with the argument margin.unit.
outermargin.top: Numeric scalar, default is NULL. The size of the top outer margin. By default the unit is the "line" but you can change it with the argument margin.unit.
outermargin.bottom: Numeric scalar, default is NULL. The size of the bottom outer margin. By default the unit is the "line" but you can change it with the argument margin.unit.
outermargin.unit: Character scalar equal to either: i) "line" (default), ii) "inch", iii) "cm".
square_plot: Logical, default is NULL. Whether the plotting region should fit a square. If FALSE the plotting region is maximal.
nrow: Integer scalar, default is NULL. To display multiple graphs, the number of rows of the graphical matrix.
ncol: Integer scalar, default is NULL. To display multiple graphs, the number of columns of the graphical matrix.
byrow: Logical, default is TRUE. When plotting multiple graphs on a graphical matrix, whether to plot the graphs by row.
title.size: Numeric scalar, default is NULL. Values greater than 1 increase the size of the plot titles, values lower than 1 reduce them.
title.col: An R color, default is NULL. The color for the graph titles.
title.bold: Logical, default is NULL. Whether to display the title in bold font.
title.italic: Logical, default is NULL. Whether to display the title in italic font.
axis.size: Numeric scalar, default is NULL. Values greater than 1 increase the size of the text in the plot axes, values lower than 1 reduce them.
axis.col: An R color, default is NULL. The color for the text in the graph axes.
axis.bold: Logical, default is NULL. Whether to display the axis's text in bold font.
axis.italic: Logical, default is NULL. Whether to display the axis's text in italic font.
label.size: Numeric scalar, default is NULL. Values greater than 1 increase the size of the plot labels, values lower than 1 reduce them.
label.col: An R color, default is NULL. The color for the graph labels.
label.bold: Logical, default is NULL. Whether to display the labels in bold font.
label.italic: Logical, default is NULL. Whether to display the labels in italic font.
...: Other arguments to be passed to bmp, png, jpeg, or tiff. For example: antialias, bg, etc.

Functions

export_graph_end(): Ends the connection to the current export and creates the file.

Setting the page size

You can set the page size with the function setFplot_page, which defines the size of the page and its margins to deduce the size of the body of the text in which the figures will be inserted. By default the page is considered to be US-letter with normal margins (not too big nor thin).

It is important to set the page size appropriately to have a final plotting-text size guaranteed once the figure is inserted in the document.

Author

Laurent Berge

Details

When the function export_graph_end() is called, the resulting exported graph is displayed in the Viewer. The viewer function is found with getOption("viewer") and should work on RStudio and VSCode (with the R extension).

When the graphical parameters are modified in export_graph_start, they are reset once a call to export_graph_end, or new call to export_graph_start, is run.

When the argument file = NULL (default), the function export_graph_start can be used in lieu of par, possibly facilitating the reset of the graphical parameters.

To export a ggplot2 graph, remember that you need to print it!

library(ggplot2)
data = data.frame(x = c(1, 2, 3, 4, 5), y = c(2, 4, 6, 8, 10))
# NOT GOOD
export_graph_start("test.pdf")
ggplot(data, aes(x, y)) +
  geom_point(color = "#54BF98") +
  geom_line(color = "#d34661")
export_graph_end()
# GOOD
my_graph = ggplot(data, aes(x, y)) +
             geom_point(color = "#54BF98") +
             geom_line(color = "#d34661")
export_graph_start("test.pdf")
print(my_graph)
export_graph_end()

Examples

Run this code


tmpFile = file.path(tempdir(), "png_examples.pdf")

# we start the exportation
export_graph_start(tmpFile, pt = 8)

plot(1, 1, type = "n", ann = FALSE)
text(1, 1, "This text will be displayed in 8pt.")

# the line below closes the connection and displays the 
# graph in the viewer pane if appropritate
export_graph_end()

# We create a 'normal' graph where we change a few graphical parameters
export_graph_start(col.default = "deepskyblue1", title.col = "indianred1", 
                   title.italic = TRUE, title.size = 2)
with(iris, plot(Sepal.Length, Petal.Length, pch = 18, cex = 2))
title("Iris data set")
# we reset the graphical parameters:
export_graph_end()

Run the code above in your browser using DataLab