gseries (version 3.0.2)

plot_graphTable: Generate benchmarking graphics in a PDF file

Description

Create a PDF file (US Letter paper size format in landscape view) containing benchmarking graphics for the set of series contained in the specified benchmarking function (benchmarking() or stock_benchmarking()) output graphTable data frame. Four types of benchmarking graphics can be generated for each series:

• Original Scale Plot (argument ori_plot_flag) - overlay graph of:

  • Indicator series

  • Average indicator series

  • Bias corrected indicator series (when \(\rho < 1\))

  • Benchmarked series

  • Average benchmark

• Adjustment Scale Plot (argument adj_plot_flag) - overlay graph of:

  • Benchmarking adjustments

  • Average benchmarking adjustments

  • Bias line (when \(\rho < 1\))

• Growth Rates Plot (argument GR_plot_flag) - bar chart of the indicator and benchmarked series growth rates.

• Growth Rates Table (argument GR_table_flag) - table of the indicator and benchmarked series growth rates.

These graphics can be useful to assess the quality of the benchmarking results. Any of the four types of benchmarking graphics can be enabled or disabled with the corresponding flag. The first three types of graphics (the plots) are generated by default while the fourth (growth rates table) is not.

Usage

plot_graphTable(
  graphTable,
  pdf_file,
  ori_plot_flag = TRUE,
  adj_plot_flag = TRUE,
  GR_plot_flag = TRUE,
  GR_table_flag = FALSE,
  add_bookmarks = TRUE
)

Value

In addition to creating a PDF file containing the benchmarking graphics (except when pdf_file = NULL), this function also invisibly returns a list with the following elements:

• graphTable: Character string (character vector of length one) that contains the complete name and path of the PDF file if it was successfully created and invisible(NA_character_) otherwise or if pdf_file = NULL was specified.

• graph_list: List of the generated benchmarking graphics (one per series) with the following elements:

  • name: Character string describing the series (matches the bookmark name in the PDF file).

  • page: Integer representing the sequence number of the first graphic for the series in the entire sequence of graphics for all series (matches the page number in the PDF file).

  • ggplot_list: List of ggplot objects (one per graphic or page in the PDF file) corresponding to the generated benchmarking graphics for the series. See section Value in bench_graphs for details.

Note that the returned ggplot objects can be displayed manually with print(), in which case some updates to the ggplot2 theme defaults are recommended in order to produce graphics with a similar look and feel as those generated in the PDF file (see section Value in bench_graphs for details). Also keep in mind that these graphics are optimized for the US Letter paper size format in landscape view (as displayed in the PDF file), i.e., 11in wide (27.9cm, 1056px with 96 DPI) and 8.5in tall (21.6cm, 816px with 96 DPI).

Arguments

graphTable

(mandatory)

Data frame (object of class "data.frame") corresponding to the benchmarking function outputgraphTable data frame.

pdf_file

(mandatory)

Name (and path) of the PDF file that will contain the benchmarking graphics. The name should include the ".pdf" file extension. The PDF file is created in the R session working directory (as returned by getwd()) if a path is not specified. Specifying NULL would cancel the creation of a PDF file.

ori_plot_flag, adj_plot_flag, GR_plot_flag, GR_table_flag

(optional)

Logical arguments indicating whether or not the corresponding type of benchmarking graphic should be generated. All three plots are generated by default but not the growth rates tables.

Default values are ori_plot_flag = TRUE, adj_plot_flag = TRUE, GR_plot_flag = TRUE and GR_table_flag = FALSE.

add_bookmarks

Logical argument indicating whether or not bookmarks should be added to the PDF file. See Bookmarks in section Details for more information.

Default value is add_bookmarks = TRUE.

Details

List of the graphTable data frame variables corresponding to each element of the four types of benchmarking graphics:

• Original Scale Plot (argument ori_plot_flag)

  • subAnnual for the Indicator Series line

  • avgSubAnnual for the Avg. Indicator Series segments

  • subAnnualCorrected for the Bias Corr. Indicator Series line (when \(\rho < 1\))

  • benchmarked for the Benchmarked Series line

  • avgBenchmark for the Average Benchmark segments

• Adjustment Scale Plot (argument adj_plot_flag)

  • benchmarkedSubAnnualRatio for the BI Ratios (Benchmarked Series / Indicator Series) line \(^{(*)}\)

  • avgBenchmarkSubAnnualRatio for the Average BI Ratios segments \(^{(*)}\)

  • bias for the Bias line (when \(\rho < 1\))

• Growth Rates Plot (argument GR_plot_flag)

  • growthRateSubAnnual for the Growth R. in Indicator Series bars \(^{(*)}\)

  • growthRateBenchmarked for the Growth R. in Benchmarked Series bars \(^{(*)}\)

• Growth Rates Table (argument GR_table_flag)

  • year for the Year column

  • period for the Period column

  • subAnnual for the Indicator Series column

  • benchmarked for the Benchmarked Series column

  • growthRateSubAnnual for the Growth Rate in Indicator Series column \(^{(*)}\)

  • growthRateBenchmarked for the Growth Rate in Benchmarked Series column \(^{(*)}\)

\(^{(*)}\) BI ratios and growth rates actually correspond to differences when \(\lambda = 0\) (additive benchmarking).

The function uses the extra columns of the graphTable data frame (columns not listed in the Value section of benchmarking() and stock_benchmarking()), if any, to build BY-groups. See section Benchmarking Multiple Series of benchmarking() for more details.

Performance

The two types of growth rates graphics, i.e., the bar chart (GR_plot_flag) and table (GR_table_flag), often requires the generation of several pages in the PDF file, especially for long monthly series with several years of data. This creation of extra pages slows down the execution of plot_graphTable(). This is why only the bar chart is generated by default (GR_plot_flag = TRUE and GR_table_flag = FALSE). Deactivating both types of growth rates graphics (GR_plot_flag = FALSE and GR_table_flag = FALSE) or reducing the size of the input graphTable data frame for very long series (e.g., keeping only recent years) could therefore improve execution time. Also note that the impact of benchmarking on the growth rates can be deduced from the adjustment scale plot (adj_plot_flag) by examining the extent of vertical movement (downward or upward) of the benchmarking adjustments between adjacent periods: the greater the vertical movement, the greater the impact on corresponding growth rate. Execution time of plot_graphTable() could therefore be reduced, if needed, by only generating the first two types of graphics while focusing on the adjustment scale plot to assess period-to-period movement preservation, i.e., the impact of benchmarking on the initial growth rates.

ggplot2 themes

The plots are generated with the ggplot2 package which comes with a convenient set of complete themes for the general look and feel of the plots (with theme_grey() as the default theme). Use function theme_set() to change the theme applied to the plots generated by plot_graphTable() (see the Examples).

Bookmarks

Bookmarks are added to the PDF file with xmpdf::set_bookmarks() when argument add_bookmarks = TRUE (default), which requires a command-line tool such as Ghostscript or PDFtk. See section Installation in vignette("xmpdf", package = "xmpdf") for details.

Important: bookmarks will be successfully added to the PDF file if and only if xmpdf::supports_set_bookmarks() returns TRUE and the execution of xmpdf::set_bookmarks() is successful. If Ghostscript is installed on your machine but xmpdf::supports_set_bookmarks() still returns FALSE, try specifying the path of the Ghostscript executable in environment variable R_GSCMD (e.g., Sys.setenv(R_GSCMD = "C:/Program Files/.../bin/gswin64c.exe") on Windows). On the other hand, if xmpdf::supports_set_bookmarks()} returns TRUE but you are experiencing (irresolvable) issues with xmpdf::set_bookmarks() (e.g., error related to the Ghostscript executable), bookmarks creation can be disabled by specifying add_bookmarks = FALSE.

See Also

bench_graphs plot_benchAdj() benchmarking() stock_benchmarking()

Examples

# Set the working directory (for the PDF files)
iniwd <- getwd() 
setwd(tempdir())

# Quarterly car and van sales (indicator series)
qtr_ind <- ts_to_tsDF(
  ts(matrix(c(# Car sales
              1851, 2436, 3115, 2205, 1987, 2635, 3435, 2361, 2183, 2822,
              3664, 2550, 2342, 3001, 3779, 2538, 2363, 3090, 3807, 2631,
              2601, 3063, 3961, 2774, 2476, 3083, 3864, 2773, 2489, 3082,
              # Van sales
              1900, 2200, 3000, 2000, 1900, 2500, 3800, 2500, 2100, 3100,
              3650, 2950, 3300, 4000, 3290, 2600, 2010, 3600, 3500, 2100,
              2050, 3500, 4290, 2800, 2770, 3080, 3100, 2800, 3100, 2860),
            ncol = 2),
     start = c(2011, 1),
     frequency = 4,
     names = c("car_sales", "van_sales")))

# Annual car and van sales (benchmarks)
ann_bmk <- ts_to_bmkDF(
  ts(matrix(c(# Car sales
              10324, 10200, 10582, 11097, 11582, 11092,
              # Van sales
              12000, 10400, 11550, 11400, 14500, 16000),
            ncol = 2),
     start = 2011,
     frequency = 1,
     names = c("car_sales", "van_sales")), 
  ind_frequency = 4)

# Proportional benchmarking without bias correction
out_bench <- benchmarking(qtr_ind, ann_bmk, 
                          rho = 0.729, lambda = 1, biasOption = 1,
                          allCols = TRUE,
                          quiet = TRUE)


# Default set of graphics (the first 3 types of plots)
plot_graphTable(out_bench$graphTable, "bench_graphs.pdf")

# Temporarily use ggplot2 `theme_bw()` for the plots
library(ggplot2)
ini_theme <- theme_get()
theme_set(theme_bw())
plot_graphTable(out_bench$graphTable, "bench_graphs_bw.pdf")
theme_set(ini_theme)

# Generate all 4 types of graphics (including the growth rates table)
plot_graphTable(out_bench$graphTable, "bench_graphs_with_GRTable.pdf",
                GR_table_flag = TRUE)

# Reduce execution time by disabling both types of growth rates graphics
plot_graphTable(out_bench$graphTable, "bench_graphs_no_GR.pdf",
                GR_plot_flag = FALSE)


# Reset the working directory to its initial location
setwd(iniwd)