rplotengine {rplotengine}

R as a plotting engine

Description

Generate a set of graphs as defined in the file specified.

Usage

   rplotengine (args_file = "mygraph.arg")

Arguments

args_file

A character string giving the name of the text file containing the parameters for the graph to be plotted. The format of such input file is described in detail below.

Details

The input file name passed to rplotengine is a plain text file with a list of pairs parameter=value, one-per-line. The meaning of each parameter is explained below:

title

Main title that can be shown in the graph. It is required to specify show_titles=1; otherwise the value will be ignored.

subtitle

Subtitle that can be shown in the graph. It is required to specify show_titles=1; otherwise the value will be ignored.

x_axis_title

Title for the X-axis.

y_axis_title

Title for the Y-axis.

col_x_values

Column number of the values for the X-axis within the input data file (1-based). DEPRECATED: since 1.0-6 the first column (1) is always the values for the X-axis (this argument will be ignored).

col_y_values

List with the columns number within the input data file corresponding to the series to be plotted. In case of using confidence intervals, each column within the input data file should be followed by another column containing its corresponding confidence interval values, but that column is not specified here, and this is why a typical value for this argument is something like: 2,4,6,8 (being 3,5,7,9 the corresponding columns for the confidence intervals). DEPRECATED: since 1.0-6 all columns in the data file will be used (this argument will be ignored).

series_names

Name for the series to be plotted as should be shown in the legend. The number of names specified should match with the number of columns specified in the argument col_y_values. In case of showing an overall serie (total_serie greater than 0), an additional name for it should be specified too.

x_factor

Value which the X-axis values will be multiplied by (usually 1).

y_factor

Value which the Y-axis values will be multiplied by (usually 1).

total_serie

Value ranged from 0 to 4, to indicate if an additional summary serie should be shown. The values mean: 0-none; 1-sum of all the series; 2-average of all the series; 3-constant value (specified by total_value); 4-proportional to the x value (proportion specified by total_value). In case of a total serie be shown (argument total_serie greater than 0), an additional name need to be specified in the list of names (argumento series_names).

total_value

Value used for the argument total_serie in certain cases (3 and 4); otherwise, it is ignored.

x_min

Minimum value for the X-axis (usually 0). Specify 'automatic' (without the quotes) in order to consider the minimum value from the data.

x_max

Maximum value for the X-axis. It is recommended to adjust automatically the graph depending on the data by assigning the value 'automatic' (without the quotes).

y_min

Minimum value for the Y-axis (usually 0). Specify 'automatic' (without the quotes) in order to consider the minimum value from the data. When using logarithmic scale in the y-axis (y_log=1), this value cannot be 0.0; the script try to fix this automatically.

y_max

Maximum value for the Y-axis (usually -1). It is recommended to adjust automatically the graph depending on the data by assigning the value 'automatic' (without the quotes).

y_log

Value 0/1 to indicate if the Y-axis should be shown in logarithm scale (usually 0).

smooth_data

Smooth data; 0.0 (data as is) to 1.0 (maximum).

show_titles

Value 0/1 to indicate if title and subtitle are shown.

show_grid

Value 0/1 to indicate if a grid are shown in the background.

show_confint

Value 0/1 to indicate if confidence interval are shown.

confint_as_percentage

Value 0/1 to indicate if the values for the confidence interval within the input data file are expressed as absolute values (0) or as a % value (1, the margin need to be calculated).

text_size_title

Font size for the title. The value specified will be a proportion to the normal text (1.0): for a greater font size specify values > 1.0; for smaller font size specify values < 1.0.

text_size_subtitle

Font size for the subtitle. The value specified will be a proportion to the normal text (1.0), as explained before.

text_size_axis_ticks

Font size for the X-axis and Y-axis numbers. The value specified will be a proportion to the normal text (1.0), as explained before.

text_size_axis_titles

Font size for the X-axis and Y-axis titles. The value specified will be a proportion to the normal text (1.0), as explained before.

text_size_legend

Font size for the series names in the legend. The value specified will be a proportion to the normal text (1.0), as explained before.

pos_legend

Place for the legend in the graph, within a 3x3 grid with cells numbered from 1 to 9: 1-top left corner, 2-top middle; 3-top right corner; ... ; 9-bottom right corner. Specify a 0 value if a legend is not required.

graph_type

Type of graph to generate (0:lines; 1:stacked bars).

lines_width

Width of lines for series (default: 1.0); total series will be shown x3.

hotspots_size

Size of the hotspots (default: 1.0).

width_factor

Graph width. The value specified will be a proportion to the normal size (1.0): for a greater font size specify values > 1.0; for smaller font size specify values < 1.0.

height_factor

Graph height. The value specified will be a proportion to the normal size (1.0): for a greater font size specify values > 1.0; for smaller font size specify values < 1.0.

dpi

Dots per inch; by default, dpi=72. This parameter affects to the width and height of the chart.

latex_digits

Decimal digits for tables exported to latex (requires the 'xtable' R package).

verbose

Value 0/1 to indicate if debug messages are printed on the screen.

data_filename

Path and name for the input data file. Path may be absolute or relative to the current directory.

graph_filename

Path and name for the graphs to be generated (without suffix). Path may be absolute or relative to the current directory.

graph_fileext_seq

List of suffixes for each output format to generate. For example: png,eps,pdf. The latter suffix 'pdf' will generate a PDF file with embedded fonts; the other formats not embed the fonts used. The final graph file names generated will be the specified with graph_filename joined to each of these suffixes.

The following is an example of input file called ‘mygraph.arg’.

# -------------------------------------------------------
# File: mygraph.arg
# -------------------------------------------------------
title=QoE - PSNR (AI mode; all tiles; varying BGT)
subtitle=Varying Background Traffic
x_axis_title=Background packets per second
y_axis_title=PSNR (dB)
col_x_values=1
col_y_values=2,4,6,8
series_names=Serie 1, Serie 2, Serie 3, Serie 4, Maximum, Acceptable
x_factor=1.0
y_factor=1.0
total_serie=3, 3
total_value=36.14, 27.0
x_min=automatic
x_max=automatic
y_min=14.5
y_max=36.5
y_log=0
smooth_data=0
show_titles=0
show_grid=1
show_confint=0
confint_as_percentage=0
text_size_title=1.0
text_size_subtitle=1.2
text_size_axis_ticks=1.6
text_size_axis_titles=1.8
text_size_legend=1.6
pos_legend=7
graph_type=2
lines_width=2
hotspots_size=3
width_factor=1.0
height_factor=1.0
dpi=72
latex_digits=3
verbose=1
data_filename=mydata.txt
graph_filename=mygraph
graph_fileext_seq=png,eps,pdf

In the previous file, a data file called ‘mydata.txt’ is specified with the data_filename parameter. The following is an example of input data file (slighly modified for clarity), which includes columns for the 95% confidence intervals for each statistic:

0	36.141	36.142	36.139	36.139
25	29.271	30.083	31.751	31.839
50	22.076	23.907	26.977	27.684
75	15.383	19.44	22.346	23.899

As we can see, column #1 is the X-axis values, as set with the col_x_values parameter. On the other hand, four series are going to be shown, corresponding to the columns specified by col_y_values parameter: 2,4,6,8. The rest of columns (3,5,7,9) are the confidence intervals computed for each serie, respectively.

As a result of executing the command rplotengine("mygraph.arg") within the R console, the following graphs files will be generated: ‘mygraph.png’, ‘mygraph.eps’ and ‘mygraph.pdf’. In addition, a LaTeX file ‘mygraph.tex’ will be written with the same values as in the input data file but formatted as a table ready for be imported from a LaTeX document. NOTE: the package 'xtable' should be installed and loaded before: install.packages('xtable');library('xtable').

The same can be achieved from the system console with the command:

Rscript -e "library('xtable');source('rplotengine.R');rplotengine('mygraph.arg')".

The following graph ‘mygraph.png’ is the result of the previous command with the parameter file ‘mygraph.arg’ and data file ‘mydata.txt’ shown:

Value

This function return a logical value indicating if the operation ended successfully (TRUE) or not (FALSE).

Author(s)

Pedro-Pablo Garrido Abenza ([e-mail])
Miguel Hernandez University (Elche, Spain)

Examples

## Generate the graphs as defined in the 'mygraph.arg' file.
rplotengine ()
## Generate the graphs as defined in the 'mygraph.arg' file.
rplotengine ("mygraph.arg")