Package 'fplot'

Description

fplot provides automatic plotting of common graphs (distributions, lines, bar plots and boxplots). The syntax uses formulas, allowing aggregate/conditional/weighted graphs with minimum efforts. The many arguments are automatically adjusted to the data in order to provide the nicest and most meaningful graphs.

Details

The core functions is plot_distr to draw distributions. Two other graphical functions are provided for convenience: plot_lines to represent the (usually temporal) evolution of some variables, and plot_box to easily represent conditional boxplots.

It also integrates tools to easily export graphs: pdf_fit and png_fit. In these functions, instead of providing the size of the graphics, you instead give the point size that the text should have in the final document–because an exported graph usually ends up in a document. You can set the size of your document with the function setFplot_page. If you use the function fit.off to close the connection, you will also see how the export looks like in the Viewer pane.

Author(s)

Maintainer: Laurent Berge [email protected]

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,
  pt = 10,
  width = 1,
  height,
  w2h = 1.75,
  h2w,
  sideways = FALSE,
  res = 300,
  type = NULL,
  ...
)

export_graph_end()

Arguments

Details

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()

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).

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.

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(s)

Laurent Berge

See Also

The tool to set the page size and the exporting defaults: setFplot_page. Exporting functions pdf_fit, png_fit, jpeg_fit.

The functions export_graph_start() and export_graph_end() provide similar features.

Examples

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()

Description

This function is deprecated: Please use the functions export_graph_start() and export_graph_end() instead.

Usage

fit.off()

Details

To be used in combination with pdf_fit or png_fit when exporting images. It performs exactly the same thing as dev.off() but additionaly shows the resulting graph in the viewer pane provided you're using RStudio.

To view the results of PDF exports, the function pdf_convert from package pdftools is used to convert the PDF files into images – so you need to have installed pdftools to make it work.

In PDFs, only the first page will be viewed.

Value

This function does not return anything in R. It closes the connection between the R graphics engine and a file that has been defined via one of the functions: pdf_fitpng_fit

Author(s)

Laurent Berge

See Also

The tool to set the page size and the exporting defaults: setFplot_page. Exporting functions pdf_fit, png_fit, jpeg_fit.

The functions export_graph_start() and export_graph_end() provide similar features.

Examples

# Exportation example
# The functions pdf_fit, png_fit, etc, guarantee the right
#  point size of the texts present in the graph.
# But you must give the exact size the graph will take in your final document.
# => first use the function setFplot_page, default is:
# setFplot_page(page = "us", margins = "normal")
# By default the graph takes 100% of the text width

data(us_pub_econ)

tmpFile = file.path(tempdir(), "DISTR -- institutions.png")

png_fit(tmpFile)
plot_distr(~institution, us_pub_econ)
fit.off()

# What's the consequence of increasing the point size of the text?
png_fit(tmpFile, pt = 15)
plot_distr(~institution, us_pub_econ)
fit.off()

Description

(This function is deprecated: Please use the functions export_graph_start() and export_graph_end() instead.) This function is an alternative to pdf, it makes it easy to export figures of appropriate size that should end up in a document. Instead of providing the height and width of the figure, you provide the fraction of the text-width the figure should take, and the target font-size at which the plotting text should be rendered. The size of the plotting text, once the figure is in the final document, is guaranteed.

Usage

pdf_fit(
  file,
  pt = 10,
  width = 1,
  height,
  w2h = 1.75,
  h2w,
  sideways = FALSE,
  ...
)

Arguments

Details

If you use fit.off instead of dev.off to close the graph, the resulting graph will be displayed in the viewer pane. So you don't have to open the document to see how it looks.

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
pdf_fit("test.pdf")
ggplot(data, aes(x, y)) +
  geom_point(color = "#54BF98") +
  geom_line(color = "#d34661")
fit.off()

# GOOD
my_graph = ggplot(data, aes(x, y)) +
             geom_point(color = "#54BF98") +
             geom_line(color = "#d34661")

pdf_fit("test.pdf")
print(my_graph)
fit.off()

Value

This function does not return anything. It connects the output of the R graphics engine to a 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(s)

Laurent Berge

See Also

To set the geometry and the defaults: setFplot_page. To close the graph and display it on the viewer pane: fit.off.

Examples

# This function creates figures made to be inserted
# in a Latex document (US-letter with "normal" margins)
# By default, the figures should take 100% of the
# text width. If so, the size of the text in the figures
# will be exact.

# You need pdftools and knitr to display PDFs in the viewer pane with fit.off
if(require(pdftools) && require(knitr)){

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

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

  pdf_fit(tmpFile, pt = 12)
  plot(1, 1, type = "n", ann = FALSE)
  text(1, 1, "This text will be displayed in 12pt.")
  fit.off()

  pdf_fit(tmpFile, pt = 12, sideways = TRUE)
  plot(1, 1, type = "n", ann = FALSE)
  text(1, 1, "This text will be displayed in 12pt if in sideways.")
  fit.off()

  # If we reduce the end plot width but keep font size constant
  # this will lead to a very big font as compared to the plot
  pdf_fit(tmpFile, pt = 8, width = "50%")
  plot(1, 1, type = "n", ann = FALSE)
  text(1, 1, "This text will be displayed in 8pt\nif in 50% of the text width.")
  fit.off()
}

Description

This function allows to draw a boxplot, with possibly separating different moderators.

Usage

plot_box(
  fml,
  data,
  case,
  moderator,
  inCol,
  outCol = "black",
  density = -1,
  lty = 1,
  pch = 18,
  addLegend = TRUE,
  legend_options = list(),
  lwd = 2,
  outlier,
  dict = NULL,
  dict_case,
  dict_moderator,
  order_case,
  order_moderator,
  addMean,
  mean.col = "darkred",
  mean.pch = 18,
  mean.cex = 2,
  mod.title = TRUE,
  labels.tilted,
  trunc = 20,
  trunc.method = "auto",
  line.max,
  ...
)

Arguments

Value

Invisibly returns the coordinates of the x-axis.

Author(s)

Laurent Berge

Examples

# Simple iris boxplot
plot(1:10)

# All numeric variables
plot_box(. ~ 1, iris)

# All numeric variable / splitting by species
plot_box(. ~ Species, iris)

# idem but with renaming
plot_box(. ~ Species, iris, dict = c(Species="Iris species",
         setosa="SETOSA", Petal.Width="Width (Petal)"))

# Now using two moderators
base = iris
base$period = sample(1:4, 150, TRUE)

plot_box(Petal.Length ~ period | Species, base)

Description

This function plots distributions of items (a bit like an histogram) which can be easily conditioned over.

Usage

plot_distr(
  fml,
  data,
  moderator,
  weight,
  sorted,
  log,
  nbins,
  bin.size,
  legend_options = list(),
  top,
  yaxis.show = TRUE,
  yaxis.num,
  col,
  border = "black",
  mod.method,
  within,
  total,
  mod.select,
  mod.NA = FALSE,
  at_5,
  labels.tilted,
  other,
  cumul = FALSE,
  plot = TRUE,
  sep,
  centered = TRUE,
  weight.fun,
  int.categorical,
  dict = NULL,
  mod.title = TRUE,
  labels.angle,
  cex.axis,
  trunc = 20,
  trunc.method = "auto",
  ...
)

Arguments

Details

Most default values can be modified with the function setFplot_distr.

Value

This function returns invisibly the output data.table containing the processed data used for plotting. With the argument plot = FALSE, only the data is returned.

Author(s)

Laurent Berge

See Also

To plot temporal evolutions: plot_lines. For boxplot: plot_box. To export graphs: pdf_fit, png_fit, fit.off.

Examples

# Data on publications from U.S. institutions
data(us_pub_econ)

# 0) Let's set a dictionary for a better display of variables
setFplot_dict(c(institution = "U.S. Institution", jnl_top_25p = "Top 25% Pub.",
                jnl_top_5p = "Top 5% Pub.", Frequency = "Publications"))

# 1) Let's plot the distribution of publications by institutions:
plot_distr(~institution, us_pub_econ)

# When there is only the variable, you can use a vector instead:
plot_distr(us_pub_econ$institution)

# 2) Now the production of institution weighted by journal quality
plot_distr(jnl_top_5p ~ institution, us_pub_econ)

# You can plot several variables:
plot_distr(1 + jnl_top_25p + jnl_top_5p ~ institution, us_pub_econ)

# 3) Let's plot the journal distribution for the top 3 institutions

# We can get the data from the previous graph
graph_data = plot_distr(jnl_top_5p ~ institution, us_pub_econ, plot = FALSE)
# And then select the top universities
top3_instit = graph_data$x[1:3]
top5_instit = graph_data$x[1:5] # we'll use it later

# Now the distribution of journals
plot_distr(~ journal | institution, us_pub_econ[institution %in% top3_instit])
# Alternatively, you can use the argument mod.select:
plot_distr(~ journal | institution, us_pub_econ, mod.select = top3_instit)

# 3') Same graph as before with "other" column, 5 institutions
plot_distr(~ journal | institution, us_pub_econ,
           mod.select = top5_instit, other = TRUE)

#
# Example with continuous data
#

# regular histogram
plot_distr(iris$Sepal.Length)

# now splitting by species:
plot_distr(~ Sepal.Length | Species, iris)

# idem but the three distr. are separated:
plot_distr(~ Sepal.Length | Species, iris, mod.method = "split")

# Now the three are stacked
plot_distr(~ Sepal.Length | Species, iris, mod.method = "stack")

Description

The typical use of this function is to represents trends of average along some categorical variable.

Usage

plot_lines(
  fml,
  data,
  time,
  moderator,
  mod.select,
  mod.NA = TRUE,
  smoothing_window = 0,
  fun,
  col = "set1",
  lty = 1,
  pch = c(19, 17, 15, 8, 5, 4, 3, 1),
  legend_options = list(),
  pt.cex = 2,
  lwd = 2,
  dict = NULL,
  mod.title = TRUE,
  ...
)

Arguments

Value

This function returns invisibly the output data.table containing the processed data used for plotting.

Author(s)

Laurent Berge

Examples

data(airquality)

plot_lines(Ozone ~ Day, airquality)

plot_lines(Ozone ~ Day | Month, airquality)

plot_lines(Ozone ~ Month | cut(Day, 8), airquality)

Description

(This function is deprecated: Please use the functions export_graph_start() and export_graph_end() instead.) This is an alternative to png and others. It makes it easy to export figures that should end up in documents. Instead of providing the height and width of the figure, you provide the fraction of the text-width the figure should take, and the target font-size at which the plotting text should be rendered. The size of the plotting text, once the figure is in the final document, is guaranteed.

Usage

png_fit(
  file,
  pt = 10,
  width = 1,
  height,
  w2h = 1.75,
  h2w,
  sideways = FALSE,
  res = 300,
  ...
)

tiff_fit(
  file,
  pt = 10,
  width = 1,
  height,
  w2h = 1.75,
  h2w,
  sideways = FALSE,
  res = 300,
  ...
)

jpeg_fit(
  file,
  pt = 10,
  width = 1,
  height,
  w2h = 1.75,
  h2w,
  sideways = FALSE,
  res = 300,
  ...
)

bmp_fit(
  file,
  pt = 10,
  width = 1,
  height,
  w2h = 1.75,
  h2w,
  sideways = FALSE,
  res = 300,
  ...
)

Arguments

Value

This function does not return anything. It connects the output of the R graphics engine to a 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.

Examples

# This function creates figures made to be inserted
# in a Latex document (US-letter with "normal" margins)
# By default, the figures should take 100% of the
# text width. If so, the size of the text in the figures
# will be exact.

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

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

png_fit(tmpFile, pt = 12)
plot(1, 1, type = "n", ann = FALSE)
text(1, 1, "This text will be displayed in 12pt.")
fit.off()

png_fit(tmpFile, pt = 12, sideways = TRUE)
plot(1, 1, type = "n", ann = FALSE)
text(1, 1, "This text will be displayed in 12pt if in sideways.")
fit.off()

# If we reduce the end plot width but keep font size constant
# this will lead to a very big font as compared to the plot
png_fit(tmpFile, pt = 8, width = "50%")
plot(1, 1, type = "n", ann = FALSE)
text(1, 1, "This text will be displayed in 8pt\nif the graph is 50% of the text width.")
fit.off()

Description

Sets/gets the default dictionary used to rename the axes/moderator variables in the functions of the package fplot. The dictionaries are used to relabel variables (usually towards a fancier, more explicit formatting) that can be useful not to explicitly use the arguments xlab/ylab when exporting graphs. By setting the dictionary with setFplot_dict, you can avoid providing the argument dict in fplot functions.

Usage

setFplot_dict(dict)

getFplot_dict

Arguments

Format

An object of class function of length 1.

Details

This function stores a named vector in the option "fplot_dict". The dictionary is automatically accessed by all fplot functions.

Value

The function setFplot_dict() does not return anything, it only sets an option after checking the format of the arguments.

The function getFplot_dict() returns a named vector representing the dictionary set in setFplot_dict().

Author(s)

Laurent Berge

Examples

data(airquality)
setFplot_dict(c(Ozone = "Ozone (ppb)"))
plot_distr(Ozone ~ Month, airquality, weight.fun = mean)

Description

The default values of most arguments of plot_distr can be set with setFplot_distr.

Usage

setFplot_distr(
  sorted,
  log,
  top,
  yaxis.num,
  col,
  border = "black",
  mod.method,
  within,
  total,
  at_5,
  labels.tilted,
  other,
  cumul = FALSE,
  centered = TRUE,
  weight.fun,
  int.categorical,
  dict = NULL,
  mod.title = TRUE,
  labels.angle,
  cex.axis,
  trunc = 20,
  trunc.method = "auto",
  reset = FALSE
)

getFplot_distr()

Arguments

Value

The function setFplot_distr() does not return anything, it only sets the default parameters for the function plot_distr().

The function getFplot_distr() returns a named list containing the arguments that have been set with the function setFplot_distr().

See Also

plot_distr, pdf_fit, fit.off.

Examples

# Changing the default color set for plot_distr only
my_col = c("#36688D", "#F3CD05", "#F49F05", "#F18904", "#BDA589")

setFplot_distr(col = my_col, mod.method = "split", border = NA)

plot_distr(~ Petal.Length | Species, iris)

# Back to normal
setFplot_distr(reset = TRUE)

plot_distr(~ Petal.Length | Species, iris)

Description

Tha package fplot offers some functions (e.g. pdf_fit or png_fit) to export figures, with a guarantee to obtain the desired point size for the plotting text. The function setFplot_page sets the target page size (once and for all). This is important for the accuracy of the export, although the default values should be working well most of the time.

Usage

setFplot_page(
  page = "us",
  margins = "normal",
  units = "tw",
  pt = 10,
  w2h = 1.75,
  reset = FALSE
)

getFplot_page()

Arguments

Details

This function sets the option "fplot_export_opts" after parsing the arguments. This option is then automatically accessed by the functions used to export graphs export_graph_start().

Value

The function setFplot_page() does not return anything. It sets an R option containing the page parameters.

The function getFplot_page() returns the named list of page parameters which has been set in setFplot_page().

See Also

Exporting functions: pdf_fit, png_fit. The function closing the connection and showing the obtained graph in the viewer: fit.off.

Examples

#
# How to set the page size
#

# All examples below provide the same page size
setFplot_page(page = "us")
setFplot_page(page = "8.5in, 11in")
setFplot_page(page = "8.5/11in")
setFplot_page(page = c(8.5, 11))

# All examples below provide the same margins
setFplot_page(margins = "normal")
setFplot_page(margins = "2cm, 2.5cm, 2cm, 2.5cm")
setFplot_page(margins = "2/2.5/2/2.5cm")
setFplot_page(margins = c(2, 2.5) / 2.54) # cm to in
setFplot_page(margins = c(2, 2.5, 2, 2.5) / 2.54)

Description

This data reports the publications of U.S. institutions in the field of economics between 1985 and 1990.

Usage

data(us_pub_econ)

Format

us_pub_econ is a data table with 30,756 observations and 6 variables.

• paper_id: Numeric identifier of the publication.

• year: Year of publication.

• institution: Institution of the authors of the publication.

• journal: Journal/conference name.

• jnl_top_25p: 0/1 variable of whether the journal belongs to the top 25% in terms of average cites.

• jnl_top_5p: 0/1 variable of whether the journal belongs to the top 5% in terms of average cites.

Source

The source is Microsoft Academic Graph (see reference).

References

Arnab Sinha, Zhihong Shen, Yang Song, Hao Ma, Darrin Eide, Bo-June (Paul) Hsu, and Kuansan Wang. 2015. An Overview of Microsoft Academic Service (MAS) and Applications. In Proceedings of the 24th International Conference on World Wide Web (WWW '15 Companion). ACM, New York, NY, USA, 243-246.