SCATTER pairs hfield vfield

# x-series y-series start end symbol (one per pair of series, if not using X and Y options)

 

SCATTER produces high-resolution scatter plots. It has many similarities to the GRAPH instruction, which produces time-series graphs.

Wizard

You can use the Data/Graphics—Scatter (X-Y) Graph Wizard. Note that in order to keep the Wizard from getting too complicated, some of the SCATTER options have been omitted in the wizard. To further customize your graph, you can edit the SCATTER instruction generated by the wizard.

Positioning

If you’re using SPGRAPH to put multiple graphs on a single page, by default, the fields are filled by column, starting at the top left (field 1,1). If you want to fill a particular field instead, use either the combination of COL and ROW options or hfield (for the column) and vfield (for the row) parameters.

Parameters

Supplementary Cards (One for Each Pair of Series if not using X and Y options)

General Options

X=RECTANGULAR matrix of X axis data [not used]

Y=RECTANGULAR matrix of Y axis data [not used]

SYMBOLS=VECTOR of INTEGERS supplying style numbers for X Y matrix pairs [unused]

These provide an alternative to the use of series for inputting data to SCATTER. These are RECTANGULAR arrays (or can be a VECTOR if you have just one set of data) with the data to be graphed in the columns. The number of columns for X and Y either must match or one or the other needs to be 1. If the latter, that's assumed to be repeated with each column from the other axis.

 

When using X and Y, you can also use SYMBOLS to supply a VECTOR of INTEGERS with the style numbers you want to use for the corresponding pairs of columns.

 

STYLE=DOTS/[SYMBOLS]/LINES/BAR/POLYGONALBAR/FILLED/SPIKE/STEP

DOTS draws a filled circle at each point. These become smaller as the number of points plotted grows. It will use different colors to represent different pairs if color is available.

 

SYMBOLS uses a small symbol to represent each data point. If you plot more than one pair on a graph, RATS will use a different color symbol for each pair of series, or, with NOPATTERNS, a different type of symbol for each pair.

 

LINES connects the consecutive pairs of points on the graph with lines.

 

BAR, POLYGON, and FILLED should be used only if the x-axis series is in increasing order. A bar graph draws a filled rectangle centered at each x value to its corresponding y value. POLYGON is similar but connects the (x,y) points with a line and fills in the area between that line and the axis. FILLED is currently identical to POLYGON, but may be differentiated in future releases.

 

SPIKE is similar to BAR, but uses narrow “spikes” instead of wide bars.

 

STEP does a “step” graph, a line graph with constant values across each interval.

 

PATTERNS/[NOPATTERNS]

This chooses the way SCATTER distinguishes among multiple pairs of series. Ordinarily, RATS will use a different color dot or box for each pair. If you print the graph on a black and white printer, RATS uses a different type of symbol for each pair of series. 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.

 

WINDOW="window title" [HEADER or FOOTER option value]

When working in interactive mode, 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 either the HEADER or FOOTER strings; if you have neither of those, nor WINDOW, they are “Graph.01,” “Graph.02,” etc.

 

FOOTER="label" [unused]

Adds a left-justified label in the lower left corner of the graph. To prevent a footer from getting too wide, you can use the characters \\\\ to insert a line break. 

 

FRAME=[FULL]/HALF/NONE/BOTTOM

[BOX]/NOBOX

FRAME controls the box displayed around the outside of the graph. HALF displays the frame only to the left and below the graph, omitting the top and right sides. BOX/NOBOX is an older option for controlling the box (frame) which is superseded by the more flexible FRAME. NOBOX is equivalent to FRAME=NONE.

 

SMPL=Standard SMPL option[unused]

Omits observations where SMPL series or expression is zero from the graph.

 

ROW=row number in SPGRAPH array

COL=column number in SPGRAPH array

When adding a graph to an SPGRAPH array, you can use these options to indicate the row and column in the array in which to place the graph.

 

HEIGHT=height of graph in inches

WIDTH=width of graph in inches

These options specify a fixed size for the graph. You must use both options together to have RATS display the graph at the specified size. The "FIX" toolbar button will be on, freezing the proportions of the graph. RATS maintains the size if you print or save the graph. Resizing the window will resize the graph proportionally. Use the "Unfix" button if you want to change the proportions. To specify sizes in centimeters, use the %CM() function to convert centimeters to inches.

 

LINES=Kx2 RECTANGULAR array with intercept/slope pairs [unused]

This allows you to draw lines on the graph by supplying pairs of intercept and slope values for each line. The array should have one row for each line you wish to draw. For each row, put the intercept value in the first column and the slope value in the second column.

Graph Header Options

HEADER="header string" [unused]

The header is centered above the graph. Although RATS will accept a string of up to 256 characters, it may not be possible to fit such a long string on the page. To get a very long header to fit, you may have to change the header font size (which is drawn in 24 point boldface by default) using GRPARM. You can also insert line breaks in the string, by including the characters \\\\ at the point where you want the line break.

 

SUBHEADER="subheader string" [unused]

The subheader is centered above the graph and below the header. By default, it is presented in 18 point italics. As with the HEADER option, you can use the characters \\\\ to insert a line break.

Labelling Options

HLABEL=horizontal scale label [unused]

VLABEL=vertical scale label [none]

These provide labels for the horizontal and vertical scales. The placement of the labels depends upon your choices for HSCALE and VSCALE. The HLABEL will be centered at the bottom just below the horizontal tick marks for HSCALE=LOWER or BOTH, or centered at the top above the tick marks if you use HSCALE=UPPER. The VLABEL is centered at the left for VSCALE=LEFT or NONE, and centered at the right for VSCALE=RIGHT. It appears on both sides with VSCALE=BOTH.

 

XLABELS=VECTOR of STRINGS for x-axis labels

Use this option to supply an arbitrary set of labels for the x-axis (by default, SCATTER uses values taken from the x-axis series). You can supply any size VECTOR of STRINGS. SCATTER will evenly space the supplied strings across the x-axis.

Axis and Scale Options

AXIS=NONE/VERTICAL/HORIZONTAL/[BOTH]

This option controls the plotting of vertical (x=0) and horizontal (y=0) axes on the graph. Regardless of your choice of AXIS, you will only get a particular axis if the 0 value lies within the graph range.

 

HSCALE=[LOWER]/UPPER/BOTH/NONE

VSCALE=[LEFT]/RIGHT/BOTH/NONE

These control the placement of the horizontal and vertical scales on the graph. The horizontal scale indicates the values of the x-series. You can place it on the bottom of the graph (the default), on the top of the graph, on both the top and bottom, or you can omit it entirely. The vertical scale indicates the values of the y-series. You can place it on the left of the graph (the default), the right, both left and right or omit it.
 

HMAX=value for right-side boundary [largest value of x series]

HMIN=value for left boundary [smallest value of x]

VMAX=value for upper boundary [largest value of y]

VMIN=value for lower boundary [smallest value of y]

These set the boundary values for the plot range. For instance, HMIN=0.0,VMIN=0.0 puts the origin at the lower left corner of the graph. Pairs that don’t fit within the specified ranges are omitted from the graph.

 

HLOG=base for a log scale for the horizontal axis [not used]

VLOG=base for a log scale for the vertical axis [not used]

Use one or both of these to graph data on a semi-log or log-log scale. The base chosen really affects only the levels that get labeled, which will always be powers of the base. The values of 10, 2, 4 and 5 are most likely to work best.

 

HTICKS=maximum number of horizontal tick marks [7]

VTICKS=maximum number of vertical ticks [9]

These set the maximum number of labeled tick marks on the horizontal scale and vertical scales, respectively. With either, you can provide a VECTOR to override the automatic assignment.

 

HPICTURE="picture code for formatting x-axis"

VPICTURE="picture code for formatting y-axis"

You can use these options to set the representation for the numeric labels on the two axes. For instance, VPICTURE="*.##" will show the numbers on the vertical axis with two digits right of the decimal. By default, SCATTER chooses the shortest representation that can show all values accurately

 

EXTEND=[NONE]/VERTICAL/HORIZONTAL/BOTH

Normally, RATS marks the vertical and horizontal axis with small tick marks outside the graph. You can use the EXTEND option to have RATS draw dotted grid lines from each tick mark all the way across or down the graph. HORIZONTAL draws horizontal grid lines, VERTICAL draws vertical grid lines, and BOTH draws horizontal and vertical grid lines.

 

HGRID=VECTOR of grid line values for the horizontal axis

VGRID=VECTOR of grid line values for the vertical axis

HSHADE=RECTANGULAR with shading zones for the horizontal axis

VSHADE=RECTANGULAR with shading zones for the vertical axis

These options provide you with the ability to highlight single values (with grids) or ranges of values (with shading). The “grid” options give a VECTOR with the x (y for VGRID) values at which a vertical (horizontal) line will be placed. The “shade” options take a RECTANGULAR array with two columns, where each row of the array gives start and end values for a zone which will be shaded from top to bottom (for HSHADE) or side to side (for VSHADE)
 

Two-Scale Graph Options

OVERLAY=DOTS/SYMBOLS/LINE/BAR/POLY/FILLED/SPIKE/STEP

This gives the style for an “overlay” graph, where one or more of the pairs is graphed using a different style or on a different scale.

 

OVSAMESCALE/[NOOVSAMESCALE]

You can use OVSAMESCALE to force both the regular and the overlay series to share a common scale. They will just be shown in different styles.

 

OVCOUNT=Number of series for right-side scale [1]

The last Number series listed on the supplementary cards are graphed using the right-side scale. The other series are graphed using the left-side scale.

 

OMAX=Maximum value for right-side scale [largest value]

OMIN=Minimum value for right-side scale [smallest value]

OVLABEL=label for right-side scale

OMAX and OMIN allow you to set the maximum and minimum values, respectively, for the right-side scale. These function like the MAX and MIN options (which control the left-side scale when doing a two-scale graph). OVLABEL allows you to supply a label for the right-side scale.

 

[OVKEY]/NOOVKEY

You can use NOOVKEY to eliminate the key for the overlay series, if the meaning is either obvious, or provided using the labels.

Key Options

KEY=[NONE]/UPLEFT/UPRIGHT/LOLEFT/LORIGHT/ATTACHED/ABOVE/BELOW/LEFT/RIGHT

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

 

 

KLABEL=VECTOR of STRINGS for KEY labels

By default, RATS labels the KEY with the names of the series. Use KLABEL to supply your own labels. You can create the VECTOR[STRINGS] ahead of time, or enter it using the ||..|| matrix notation.

The order of labels in the VECTOR should match the order of the supplementary cards. You can use \\\\ in a string to put a line break in the string.
 

[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 GRPARM KEYLABELING 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.

 

[KSAMPLE]/NOKSAMPLE

NOKSAMPLE eliminates the sample line styles, colors, or fill patterns from the key, leaving only the labels.

Missing Values

RATS leaves out any entry for which either of the two series in the pair is missing.

Examples

This graphs inflation vs unemployment with one set of symbols (squares) for the period 1954 to 1968 and another (diamonds) for 1969 to 1983.

 

scatter(style=symbol,header="Inflation vs. Unemployment", $

        patterns,hlabel="Unemployment",vlabel="Inflation") 2

# unemp inflation 1954:1 1968:1 1

# unemp inflation 1969:1 1983:1 2

 

This computes a histogram for the series AGES, presented as a bar graph. The title on the graph is “Histogram of Ages” and it goes into a window labeled “Histogram”.

 

density(type=histogram) ages / grid density

scatter(style=bar,window="Histogram",header="Histogram of Ages")

# grid density

 

 

This draws a set of data from a gamma distribution, estimates the sample density, then graphs the estimate with the true density. The actual density is done using the (filled) polygon style, while the estimated density overlays that with a line. The colors are adjusted so the line comes in as solid black. OVSAME is used to force both to use a single scale. The graph is shown below.

 

all 1000

set test = %rangamma(4.0)

density(bandwidth=1.00) test / x fx

set actual = exp(log(x)*3.0-x-%lngamma(4.0))

scatter(style=polygon,overlay=line,ovsame) 2

# x actual / 4

# x fx / 1
 

This does a scatter graph of testlambdas (on the X axis) vs testmse (on the Y axis) using a log 10 scale on the horizontal axis.

scatter(x=testlambdas,y=testmse,hlog=10,style=lines,footer="MSE for L2 Penalty")

 

 

This rather complex example is taken from the cumulated periodogram procedure (on the file CUMPGDM.SRC).

 

ctor 1 half

# 1 2

# actual white_noise

label actual white_noise

# "Actual" "White Noise"

 

set freqs 1 half = t-1

grparm(font="Symbol") axislabels *

spgraph

 

scatter(style=line,key=upleft, $

  header="Cumulated Periodogram Test", $

  xlabels=||"0","p/4","p/2","3p/4","p"||) 2

# freqs white_noise 1 half

# freqs actual      1 half

display(store=gaplabel) "gap = " #.#### %maximum

 

if actual(%maxent)<white_noise(%maxent)

   grtext(align=left,x=%maxent-1,y=actual(%maxent)-.01) gaplabel

else

   grtext(align=right,x=%maxent-1,y=actual(%maxent)+.01) gaplabel

spgraph(done)

 

Copyright © 2025 Thomas A. Doan