Bayesian Econometrics Software

B.16 Plotting

BayES can produce ﬁve types of plots:

histograms
scatter plots (y versus x)
correlograms (acf plots)
line plots (y versus x or the values of y versus their row index)
kernel density estimates

There are ﬁve basic plotting functions in BayES, each one of which corresponds to a plot type: hist(), scatter(), acf(), plot(), and kden(). These functions are documented in the following table and, in their simple use, they draw their respective plots on a new ﬁgure window that they initiate. For example, execution of a statement of the form:

plot( y, x );

will create a new ﬁgure window and plot the values contained in vector y versus the values contained in vector x. All ﬁve basic plot functions return the title of the ﬁgure window on which they are plotting. If, for example, the following statement is executed, while no ﬁgure windows are currently open:

figureTitle = plot( y, x );

apart from creating a new ﬁgure window and displaying the plot, BayES will create a new string item in the current workspace, with id value figureTitle and content "Figure 1".

The ﬁve basic plotting functions diﬀer in the number of numerical arguments they take, but all of them have the following optional arguments:

"title"
"xlabel"
"ylabel"
"grid"
"colors"

These arguments, if provided, must be given after the numerical arguments of the plotting function, separated by commas and in any order. For example, the statement:

scatter(y, x, "title"="my title", "xlabel"="my x

-

axis label", "grid"="on");

produces a scatter plot of the values contained in vector y versus the values in vector x and sets the plot’s title and x-axis label. Finally, it requests a grid to be drawn on the ﬁgure. The statement is equivalent to:

scatter(y, x, "xlabel"="my x

-

axis label", "grid"="on", "title"="my title");

"title", "xlabel" and "ylabel" must be followed by the assignment operator, ‘=’, and a string that speciﬁes the corresponding option. "grid" must be followed by the assignment operator and either the string "on" or the string "oﬀ".

The "colors" option speciﬁes the colors to be used in the graph. Its value must be a matrix with three columns and all elements between zeros and one. Each row of this matrix speciﬁes a color in RGB (red-green-blue) format, with the ﬁrst row specifying the background color, the second the color of the axes and the text labels and the remaining rows specifying the colors used for plotting the data. For example, the statement:

scatter(y, x, "colors"=[0,0,0; 1,0,0; 0.5,0,0.5]);

plots a scatter plot of the values in y versus the values in x and sets the graph’s background color to black (0, 0, 0), the color of the axes and labels to red (1, 0, 0) and the color of the markers used to represent the data to magenta (0.5, 0, 0.5).

For the remainder of this section the ﬁve optional arguments described above will be represented by <plot options>.

Multiple plots per ﬁgure window can be drawn by combining the ﬁve plotting functions with the multiplot() and subplot() functions. For example, the statement:

figureTitle = multiplot( 2, 3 );

will initialize and display a ﬁgure window that can plot 6 plots, across 2 rows. At this stage, this window will be empty and need to be populated by actual plots. Submitting the statement:

plot( subplot(figureTitle, 2, 1), y, x ) ;

after a call to multiplot() will plot the values in y versus the values in x in row 2, column 1 of the ﬁgure window whose title bar displays the same string as the value of figureTitle. Similar calls to other plotting functions can be used to populate the remaining spaces of the multiple-plot ﬁgure window. Notice that the subplot() function must be provided as the ﬁrst argument of a plotting function. If the call to plot() in the previous statement did not include a call to subplot(), the plot would be created in a new ﬁgure window, even after an empty multiple-plot window has been initialized. Thus, the call to subplot() is optional and, for the remainder of this section, any possible complete call to this function will be denoted by <subplot options>. Note that subplots within graphs must have the same background color. The overall background color in graphs that contain multiple subplots is the background color speciﬁed for the subplot located at the upper left corner of the graph.

The close() function can be used to close a ﬁgure window programmatically. For example the statement:

close("Figure 1");

will close the ﬁgure window with “Figure 1" displayed in its title bar, while the statement:

close(all);

will close all currently open ﬁgure windows. The contents of ﬁgure windows can be exported using the export() function, which is documented in section B.4.

BayES limits the maximum number of ﬁgure windows that can be open at any given time. If a new ﬁgure window is requested when this maximum number has been reached then BayES produces an error. The function maxﬁgures() can be used to change the maximum number of ﬁgure windows using a statement like:

maxfigures( <positive integer> );

Finally, plotdraws() is a utility function that can be used to create a multiple-plot ﬁgure window and plot four types of plots of the draws from the posterior distribution of a parameter from a model in the current workspace. Because this function works on the results of models only, it is documented in section B.14.


Syntax	Arguments and performed function

$[$ W = $]$ acf( $[$ <subplot options>, $]$ y $[$ , lags, <plot options> $]$ );	Plots a correlogram for the values in vector y. lags sets the maximum lags for which the correlation coeﬃcients are calculated and plotted. If lags is not provided then its value is set equal to 30. If a left-hand-side id value, W, is provided then the title of the ﬁgure window on which the function is plotting is stored in W. y must be a column vector lags must be a positive integer the use of <plot options> is described at the beginning of this section the use of <subplot options> is described at the beginning of this section if acf() is called without a call to subplot(), a new ﬁgure window is created; otherwise, the plot is drawn on an existing multiple-plot ﬁgure and at the location speciﬁed by <subplot options>

$[$ W = $]$ hist( $[$ <subplot options>, $]$ y $[$ , bins, <plot options> $]$ );	Plots a histogram of the values in vector y. bins is the number of bins to be used for the histogram. If bins is not provided then its optimal value is calculated internally. If a left-hand-side id value, W, is provided then the title of the ﬁgure window on which the function is plotting is stored in W. y must be a column vector bins must be a positive integer the use of <plot options> is described at the beginning of this section the use of <subplot options> is described at the beginning of this section if hist() is called without a call to subplot(), a new ﬁgure window is created; otherwise, the plot is drawn on an existing multiple-plot ﬁgure and at the location speciﬁed by <subplot options>

$[$ W = $]$ kden( $[$ <subplot options>, $]$ y $[$ , <plot options> $]$ );	Plots the kernel density of the values in y. If y contains more than one column then each column is treated as a separate variable; the kernel density is estimated separately and plotted using a diﬀerent line color on the same plot. If a left-hand-side id value, W, is provided then the title of the ﬁgure window on which the function is plotting is stored in W. y must be a column vector or matrix the use of <plot options> is described at the beginning of this section the use of <subplot options> is described at the beginning of this section if kden() is called without a call to subplot(), a new ﬁgure window is created; otherwise, the plot is drawn on an existing multiple-plot ﬁgure and at the location speciﬁed by <subplot options>

$[$ W = $]$ plot( $[$ <subplot options>, $]$ y $[$ , x, <plot options> $]$ );	Plots a line plot of the values in y versus either the values in x (if provided) or the row index of each value. If y contains more than one column then each column is plotted as a diﬀerent variable versus x or the row index and using a diﬀerent line color for each variable. If a left-hand-side id value, W, is provided then the title of the ﬁgure window on which the function is plotting is stored in W. y must be a column vector or matrix x must be a column vector with rows equal to the rows of y the use of <plot options> is described at the beginning of this section the use of <subplot options> is described at the beginning of this section if plot() is called without a call to subplot(), a new ﬁgure window is created; otherwise, the plot is drawn on an existing multiple-plot ﬁgure and at the location speciﬁed by <subplot options>

$[$ W = $]$ scatter( $[$ <subplot options>, $]$ y, x $[$ , <plot options> $]$ );	Plots a scatter plot of the values in y versus the values in x. If y contains more than one column then each column is plotted as a diﬀerent variable versus the values in x and using a diﬀerent color and mark symbol for each variable. If a left-hand-side id value, W, is provided then the title of the ﬁgure window on which the function is plotting is stored in W. y must be a column vector or matrix x must be a column vector with rows equal to the rows of y the use of <plot options> is described at the beginning of this section the use of <subplot options> is described at the beginning of this section if scatter() is called without a call to subplot(), a new ﬁgure window is created; otherwise, the plot is drawn on an existing multiple-plot ﬁgure and at the location speciﬁed by <subplot options>

$[$ W = $]$ multiplot(i, j)	Initializes a ﬁgure window on which multiple plots can be drawn and sets its dimensions: i is the number of plots that can be drawn per column and j is the number of plots that can be drawn per row. That is, the window can be thought of as an area consisting of i rows and j columns, with each cell being able to accommodate a individual plot. If a left-hand-side id value, W, is provided then the title of the ﬁgure window which is initialized by the function is stored in W. i must be a positive integer j must be a positive integer see also subplot

subplot(s, i, j)	This function does not form a complete statement on its one and it can only be used as the ﬁrst argument to the ﬁve basic plotting functions: hist(), scatter(), acf(), plot(), and kden(). When these plotting functions contain a call to subplot(), instead of plotting the respective plot on a new ﬁgure window, they plot it on the window whose title bar displays the string in s. i speciﬁes the row of the ﬁgure window on which the plot is displayed and j the column of this window. s must be a string with contents equal to the string displayed on the title bar of an open ﬁgure window i must be a positive integer, not greater than the number of rows of the ﬁgure window j must be a positive integer, not greater than the number of columns of the ﬁgure window see also multiplot

[next] [prev] [prev-tail] [front] [up]