plot_graphTable {gseries} | R Documentation |
Generate benchmarking graphics in a PDF file
Description
(version française: https://StatCan.github.io/gensol-gseries/fr/reference/plot_graphTable.html)
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
)
Arguments
graphTable |
(mandatory) Data frame (object of class "data.frame") corresponding to the benchmarking function output |
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 |
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 |
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 |
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
.
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 andinvisible(NA_character_)
otherwise or ifpdf_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).
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)