SPGRAPH

 one or more graphics instructions

SPGRAPH(DONE)

SPGRAPH (SPecial Graph) allows you to create special graphs and graphics presentations. In particular, you can use SPGRAPH to put several complete graphs on a single page, or add one or more strings of text to a graph using GRTEXT. You can also supply a header, footer, and other labels for the special graph.

Description

SPGRAPH tells RATS the overall structure of the graphics content. As shown above, you follow this with the instructions which create the graphs themselves, then SPGRAPH(DONE) when you are finished. You can also “nest” SPGRAPH blocks inside other SPGRAPH blocks to create more complex graph presentations.

 

You must use SPGRAPH(DONE) at the end even if you only need a single graphing instruction.

Positioning

If the SPGRAPH is inside of another SPGRAPH, the fields in the outer SPGRAPH are, by default, filled by column, starting at the top left (field 1,1). If you want to fill a particular field instead, use the combination of ROW and COL options.

Options

HFIELDS=number of horizontal fields [1]

VFIELDS=number of vertical fields [1]

FILLBY=[COLUMNS]/ROW

You can use these options, alone or together, to put several graphs on a single page. They tell RATS to divide the specified axis into multiple fields. If you use these options, you can use the COL and ROW options (or the hfield parameter for the column and vfield for the row) on GRAPH, GBOX, GCONTOUR, or SCATTER (or inner SPGRAPHs) to control the positioning of each graph. By default, the graph instructions fill the fields by columns, beginning with the top left, working down. Use FILLBY=ROWS to fill across in rows by default instead. Either can be overridden by ROW and COLUMN options on the graphing instructions.

 

DONE/[NODONE]

Use this to signal the end of the special graph

 

SAMESIZE/[NOSAMESIZE]

Use SAMESIZE if you want all the graphs in the SPGRAPH to be the same size.

 

HEADER="header string for graph page" [none]

SUBHEADER="subheader string for graph page" [none]

FOOTER="footer string for graph page" [unused]

These are nearly identical to the options of the same name on GRAPH, SCATTER, GCONTOUR and GBOX, but they add labels for the entire SPGRAPH page, rather than the individual graphs. You can use a STRING variable or an explicit string in quotes for these. See the example below. Use the analogous options on GRAPH, SCATTER, GCONTOUR or GBOX instructions to label the individual graphs.

 

WINDOW="title for graph window" [HEADER or FOOTER if used]

The WINDOW option allows you to set a title for the graph window that will be associated with the graph. By default, graph windows are titled using the HEADER or FOOTER options or, if those aren't used, as “Graph.01,” “Graph.02,” etc.

 

HLABEL="horizontal content label" [unused]

VLABEL="vertical content label" [none]

XLABELS=VECTOR[STRINGS] supplying labels for the horizontal fields

XPOS=[UPPER]/LOWER/BOTH/NONE

YLABELS=VECTOR[STRINGS] supplying labels for the vertical fields

YPOS=[LEFT]/RIGHT/BOTH/NONE

YROTATE/[NOYROTATE]

These options control the labelling on outside of the content (but between the headers and footer). HLABEL is a general horizontal label, centered below the content. VLABEL is a general vertical label, written vertically on the left side. XLABELS and YLABELS are used to label the individual rows (YLABELS) and columns (XLABELS) in the fields. You can supply these as a variable of type VECTOR of STRINGS, or using in-line matrix notation (such as YLABELS=||"label1","label2"||). XPOS and YPOS determine the positioning of the XLABELS and YLABELS respectively. YROTATE determines the orientation of the YLABELS. See the examples.

 

HEIGHT=height of graph in inches

WIDTH=width of graph in inches

Use these options to specify a fixed size for the SPGRAPH. You must use both options together. RATS will display the SPGRAPH. at the specified size, with the “Fix” toolbar button turned on to freeze the proportions of the graph. It will maintain that size if you print or save the graph. Resizing the graph window will resize the graph proportionally.  Click on the “Unfix” toolbar button if you want to change the proportions. To specify sizes in centimeters, use the %CM() function to convert centimeters to inches.

 

ROW=row number in SPGRAPH array

COL=column number in SPGRAPH array

When nesting an SPGRAPH inside an existing SPGRAPH array, you can use these options to indicate the row and column in the array in which to place the special graph being defined.

 

RGF="name of RATS Graph File to insert" [unused]

This inserts a saved graph file into an SPGRAPH matrix of graphs. This is the one use of SPGRAPH that does not require a closing SPGRAPH(DONE). Use ROW and COL, if needed, to override the standard order in which fields are filled.

Options for Adding a Key

If you would like to add a key to the outside of the SPGRAPH array (if the individual graphs use the same basic set of representations), you have to input all the information to define the key yourself since, at the time the key is being created, none of the content has been added.

 

PATTERNS/[NOPATTERNS]

This chooses the way the SPGRAPH key distinguishes among series. Ordinarily, RATS will use a different color line or box. If you print the graph on a black and white printer, RATS uses a different type of symbol for each. If you want to see on the screen (approximately) how the hard copy will appear, use the PATTERNS option—RATS will use different symbols rather than different colors on the graph.

 

KEY=[NONE]/ABOVE/BELOW/LEFT/RIGHT

KEY controls the placement of the key. The choices are:

 

 

STYLE=[LINE]/POLYGON/BAR/STACKEDBAR/OVERLAPBAR/VERTICAL/STEP/SYMBOL/MIDPOLYGON/FAN/DOTS/SPIKE

Choose the style that will be used for displaying the information in the graph. There are actually only three ways that a key sample is shown: a line, a filled rectangle or a symbol so you just have to pick a style in the correct "family".
 

KLABEL=VECTOR of STRINGS for KEY labels [required]

This is required so SPGRAPH will know how to describe the series. You can create the VECTOR[STRINGS] ahead of time, or enter it using the ||..|| matrix notation.

 

SYMBOLS=VECTOR of INTEGERS supplying style numbers for SERIES [1,2,3,...]

Use SYMBOLS to supply a VECTOR of INTEGERS with the style numbers you want to use for the corresponding series if you don't want the standard behavior of using styles 1, 2, 3, ... in order.

 

[KBOX]/NOKBOX

This controls whether or not a box (border) is drawn around the key.

 

KHEIGHT=height of key box (between 0 and 1)

KWIDTH=width of key box (between 0 and 1)

By default, RATS tries to find the most efficient arrangement for the key, given the number of series in the key, its position, the setting of the GRPARMKEYLABELING parameter, and so on. KHEIGHT and KWIDTH allow you to control the size and proportion of the box by specifying the height and width of the box as a fraction of the graph’s overall height and width. You must specify both options.

Notes

HFIELDS and VFIELDS offer an alternative to creating full size graphs and then pasting and resizing them into another application (or photoreducing them) in order to put several on a page. RATS will automatically scale all elements of the graphs, including labels, to fit the page. Together, they create a “matrix” of graphs. See, for instance, the example below. Once you get beyond two or three graphs on a page, you will probably want to eliminate the tick marks and axis labeling. The graphs will get too cluttered for the labeling to be useful.

 

You can use the SAMESIZE option to force the graph boxes to be the same size.

Examples

spgraph(vfields=2,footer="FIGURE 2.5 Time Path of Interest Rate Spread")

 graph(header="Panel (a): The interest rate spread")

 # spread

 graph(header="Panel (b): First difference of the spread")

 # dspread

spgraph(done)

 

This does a two-pane graph with the two stacked one over the other.

 

spgraph(vfields=3,hfields=2,$

  hlabel="Impulse Responses; Fry-Pagan Minimizers")

do i=1,nvar

   set resp 1 nstep = ik=%xt(impulses,t)*a,ik(i)

   graph(ticks,number=0,picture="##.##",header="Impulse Responses for "+vl(i)) 3

   # resp     1 nstep

   # lower(i) 1 nstep 2

   # upper(i) 1 nstep 2

end do i

*

spgraph(done)

 

This creates a 3 x 2 page of graphs. Here NVAR is equal to six, but a graph with six stacked vertically would not be very attractive, so it lays it out with 3 rows and 2 columns. The first three will in the left column of graphs and the second three will be in the right column.

 

spgraph

 graph(vgrid=||4.53,3.66||,header="Figure 14.5 F-Statistics Testing for a Break in the Phillips Curve")

 # fstat t1 t2

 grtext(entry=1990:1,y=4.53,valign=center) "1% Critical Value"

 grtext(entry=1990:1,y=3.66,valign=center) "5% Critical Value"

spgraph(done)

 

This uses SPGRAPH to wrap around just a single graph, but it allows text to be added using GRTEXT.

Sample Graph

This shows the positioning of various labels. Note that the XLABELS from the SPGRAPH and the HEADERS from the inner GRAPH instructions are right on top of each other. If you want to use XLABELS and also want to do something extra to label the inner graphics, we would suggest using HLABELS on the inner graphs.

 

all 100

set x1 = %ran(1.0)

set x2 = %ran(1.0)

set x3 = %ran(1.0)

set x4 = %ran(1.0)

spgraph(header="SPGRAPH Header",subheader="SPGRAPH Subheader",$

  footer="SPGRAPH Footer",vlabel="SPGRAPH VLabel",$

  xlabels=||"XLABEL(1)","XLABEL(2)"||,ylabels=||"YLABEL(1)","YLABEL(2)"||,$

  vfields=2,hfields=2)

  graph(header="Graph header (1)")

  # x1

  graph(header="Graph header (2)")

  # x2

  graph(header="Graph header (3)")

  # x3

  graph(header="Graph header (4)")

  # x4

spgraph(done)

 

 

Copyright © 2026 Thomas A. Doan