1. Home
  2. DELLIPSE procedure

DELLIPSE procedure

Draws a 2-dimensional scatter plot with confidence, prediction and/or equal-frequency ellipses superimposed (V.M. Cave).

Options

PLOT = string tokens What type of ellipse to plot (confidence, prediction, equalfrequency); default conf
PROBABILITY = scalar or variate Probability level(s) for the ellipse(s); default 0.95
NPOINTS = scalar Number of points used to draw the ellipses; default 1000
DISPLAY = string token Whether to include the data points on the graph (show, hide); default show
PAXES = string token Whether to plot the principal axes on the graph (no, yes); default no
TFILL = scalar Transparency used to fill the area inside the ellipses, on a scale of 0 (opaque) to 255 (completely transparent); default 255
USEPENS = string token Whether to use the current pen definitions for drawing the ellipses, drawing the principal axes and plotting the data (no, yes); default no
CMATCH = string token When USEPENS=yes and groups are to be plotted, indicates whether the colours for the ellipses and principal axes are matched to the corresponding group, or to the colours defined by the pens for the different ellipse types and principal axes (group, pen); default group
WINDOW = scalar Window to use for the graph(s); default 1
KEYWINDOW = scalar Window to use for the key; by default the key is drawn on the right, in window 255
KEYDESCRIPTION = text Overall title for the key; default * i.e. none
SCREEN = string token Whether to clear the screen before plotting or to continue plotting on the old screen (clear, keep); default clear

Parameters

Y = variates or pointers Vertical coordinates (i.e. variable to plot on the y-axis)
X = variates or pointers Horizontal coordinates (i.e. variable to plot on the x-axis)
GROUPS = factors Defines groupings of the data points
DESCRIPTION = texts Labels for the groups; default generates the labels automatically
TITLE = text Title for the plot; default * i.e. none
YTITLE = text Title for the y-axis; by default a title is generated automatically
XTITLE = text Title for the x-axis; by default a title is generated automatically

Description

The DELLIPSE procedure produces a 2-dimensional scatter plot with confidence, prediction and/or equal-frequency ellipses superimposed, using high-resolution graphics.

The parameters Y and X supply variates or pointers containing the y- and x-coordinates to be plotted in the scatter plot, respectively. The DISPLAY option allows you to control whether the data points are shown or hidden in the initial graph displayed by the Graphics Viewer. By default, they are displayed (i.e. DISPLAY=show).

The PROBABILITY option specifies the probability level for the ellipse, or ellipses, that are superimposed onto the scatter plot; default 0.95. You can supply either a single probability in a scalar, or several in a variate. When a variate is supplied, an ellipse is drawn at each value.

The PLOT option specifies the types of ellipses to be plotted. These are:

confidence confidence ellipse (the default),
prediction prediction ellipse,
equalfrequency equal-frequency.
 
Assuming a bivariate normal distribution, for PROBABILITY level p it is expected that (100×p)% of confidence ellipses will contain the true bivariate mean, (100×p)% of prediction ellipses will contain a future bivariate observation, and (100×p)% of the observed data will be enclosed within the equal-frequency ellipse. When PROBABILITY specifies several probability levels, a separate graph is drawn for each selected ellipse type, unless over-written by setting the option SCREEN=keep.
 
When both X and Y supply variates, the GROUPS option can be used to specify a factor to partition the data into different groups, so that separate ellipses are superimposed for each group. Alternatively, groups of data can be plotted by supplying pointers for X and/or Y. Here, the elements of the pointer(s) define separate groups. For example, if both X and Y are pointers of length 2, then separate ellipses are drawn for the groups of data (X[1],Y[1]) and (X[2],Y[2]). Similarly, if X supplies a pointer of length 2 but Y supplies a variate, then separate ellipses are drawn for (X[1],Y) and (X[2],Y). The number of groups must not exceed 25. By default, different colours will be used for plotting the units belonging to the different groups and their ellipses. Options USEPENS and CMATCH can be used to change the colours (see below).
 
Principal axes (also known as major and minor axes) can be added to the plot by setting the option PAXES to yes. By default, they are not plotted (PAXES=no). For the principal axes to be drawn at right-angles, the x- and y-axes must be identically scaled. This can be controlled through the FRAME directive, by setting the SCALING parameter to xyequal for the WINDOW in which the graph is to be plotted.

By default, the pen attributes are defined automatically within the procedure. However, you can set option USEPENS=yes to request that the current pen definitions are used. The following pens are used to draw the different elements in the plot:

pen=253 confidence ellipse,
pen=254 prediction ellipse,
pen=255 equal-frequency ellipse,
pen=256 principal axes,
pen=1…data (where N is the number of groups to be plotted).
 

When USEPENS=yes and groups are to be plotted (i.e. GROUPS is supplied or X and/or Y supplies a pointer), the CMATCH option is used to control the colour of the ellipses and principal axes drawn for each group. The default setting, CMATCH=group matches the colours of the ellipses and principal axes to those used for plotting the data from each group (i.e. the colours used to draw the ellipses and principal axes are controlled by pens 1…N, where N is the number of groups). Alternatively, CMATCH=pen draws the ellipses for all groups using the colour defined by the pen of the corresponding ellipse type (i.e. pen 253, 254 or 255), and the principal axes using the colour defined by pen 256. When USEPENS=yes, but there are no separate groups to be plotted, the colours used for drawing the different ellipse types and the principal axes are taken from pens 253, 254, 255 and 256, and the setting of CMATCH is ignored.

When the pen attributes are defined by the procedure (i.e. when USEPENS=no), the TFILL option can be used to fill the area inside the ellipses with transparent colours. It supplies a scalar, ranging from 0 (opaque) to 255 (completely transparent). By default, the ellipses are not filled, i.e. TFILL=255. (Note, when filled ellipses are wanted, TFILL=200 usually provides a good level of transparency.) When using your own pen definitions (i.e. when USEPENS=yes), you can fill the ellipses by setting the METHOD parameter of the PEN directive to fill for the appropriate pen number. You can also control the transparency of the fill by using the TAREA parameter.

The number of points used to draw the ellipses is specified by the NPOINTS option (default 1000). Increasing NPOINTS will improve the accuracy (and visual smoothness) of the resulting ellipses, but it also increases the computational burden. However, it may be necessary sometimes to capture the curvature accurately around the vertices, especially when FILL=yes.

The TITLE, YTITLE and XTITLE parameters can supply an overall title, a y-axis title and a x-axis title for the plot, respectively. If no y- or x-axis titles are supplied, titles are generated automatically. To omit the axis title, a blank string can be supplied, i.e. YTITLE=' '. By default, no overall title is displayed.

The WINDOW option defines the window to plot the graph (default 1). Similarly the KEYWINDOW option defines the window to use for the key. By default, the key is drawn in window 255, which is defined to be on the right of the scatter plot. Setting KEYWINDOW=0 suppresses the key. Default labels are constructed automatically for the different groups of data (i.e., when GROUPS is supplied, or X and/or Y supplies a pointer). However, you can use the DESCRIPTION parameter to supply as a text structure containing N labels of your own for the key. The KEYDESCRIPTION option can supply an overall description for the key. By default, no title is displayed for the key.

Options: PLOT, PROBABILITY, NPOINTS, DISPLAY, PAXES, TFILL, USEPENS, CMATCH, WINDOW, KEYWINDOW, KEYDESCRIPTION, SCREEN
Parameters: Y, X, GROUPS, DESCRIPTION, TITLE, YTITLE, XTITLE

Method

DELLIPSE uses the methods described in Sokal & Rohlf (1995).

Action with RESTRICT

When X and Y supply both variates, DELLIPSE takes account of restrictions on Y, X and GROUPS. However, if more than one are restricted, they must be restricted in the same way. Furthermore, their unrestricted lengths must be the same.

When X and/or Y supplies a pointer, any restrictions are ignored.

Reference

Sokal, R.R., & Rohlf, J.F. (1995). Chapter 15: Correlation. In Biometry: The Principles and Practice of Statistics in Biological Research, Third edition, 555-608. New York: W.H. Freeman & Company.

See also

Directives: DGRAPH, CORRELATE, PEN, FRAME, PCP.
Procedures: DCORRELATION, FCORRELATION.
Functions: CORRELATION.
Commands for: Graphics.

Example

CAPTION 'DELLIPSE examples'; STYLE=meta
SPLOAD  '%Data%/Iris.gsh'
"Plot 95% confidence and prediction ellipses"
DELLIPSE [PLOT=confidence,prediction] Y=Petal_Length; X=Petal_Width
"Plot with principal axes (plotted at right-angles)"
FRAME    WINDOW=1; SCALING=xyequal
DELLIPSE [PLOT=confidence,prediction; PAXES=yes] Y=Petal_Length; \
         X=Petal_Width
FRAME    [RESET=yes] WINDOW=1
"Plot for each group (i.e. species)"
DELLIPSE [PLOT=confidence,prediction] Y=Petal_Length; X=Petal_Width; \
         GROUPS=Species
"Plot filled prediction ellipses over a range of probability levels"         
DELLIPSE [PLOT=prediction; PROBABILITY=!(0.90,0.95,0.99); TFILL=200] \
         Y=Petal_Length; X=Petal_Width; GROUPS=Species
"Define your own pen attributes to plot the prediction ellipses and data,
 add appropriate titles"
PEN      [RESET=yes] NUMBER=254; LINESTYLE='dot'; COLOUR='gray'
PEN      [RESET=yes] NUMBER=1...3; COLOUR='black','red','blue'; \
         SYMBOL='cross','circle','plus'
DELLIPSE [PLOT=prediction; PROBABILITY=!(0.90,0.95,0.99); USEPENS=yes] \
         Y=Petal_Length; X=Petal_Width; GROUPS=Species; XTITLE='Petal Width'; \
         YTITLE='Petal Length'; TITLE='Fisher''s iris data'
PEN      [RESET=yes] NUMBER=254,1...3 
"Use pointers to plot ellipses of petal vrs sepal measurement"
POINTER  [VALUES=Petal_Length,Petal_Width] Petal
POINTER  [VALUES=Sepal_Length,Sepal_Width] Sepal
DELLIPSE [PLOT=conf,pred,equal] Y=Petal; X=Sepal; \
         DESCRIPTION=!T('Length','Width')
Updated on February 17, 2022

Was this article helpful?