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.`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`

.`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).`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:

*N*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')