1. Home
  2. TRELLIS procedure

TRELLIS procedure

Generates a trellis plot (S.J. Welham & S.A. Harding).

Options

GROUPS = factors or variate Factors or variate defining the classification for the plots
GMETHOD = string token Determines the method used to partition the range when GROUPS is set to a variate (equalspacing, quantiles, distinct, limits); default equal
NGROUPS = scalar Determines the number of plots to be formed when GROUPS is set to a variate and GMETHOD is set to quantiles or equalspacing
LIMITS = variate Limits to use to form groups from a GROUPS variate when GMETHOD=limits
OVERLAP = scalar Proportion by which a GROUPS variate should overlap between plots (scalar in range 0 – 0.5); default 0
OMITEMPTY = string token Whether to omit all empty plots from the array (all), or omit levels of a GROUPS factor where all plots are empty (levels), or keep all plots in the array (none); default level
PENGROUP = factors Defines factor combinations to be plotted in different colours, note that the number of colours available may differ between devices
NROWS = scalar Specifies number of rows of plots to appear on one page; default determined automatically from GROUPS
NCOLUMNS = scalar Specifies number of columns of plots to appear on one page; default determined automatically from GROUPS
TITLE = text Supplies a title for the plot
FIRSTPICTURE = string token Whether to put the first picture at bottom or top left of the grid (bottomleft, topleft); default topl
TMETHOD = string token Whether to give plot titles as factor names with labels or just labels (names, labels); default name
YTITLE = text Supplies an overall y-axis title
XTITLE = text Supplies an overall x-axis title
YMARGIN = scalar Relative size of margins for the y-axis labels on individual plots; default 0.04
XMARGIN = scalar Relative size of margins for the x-axis labels on individual plots; default 0.04
TMARGIN = scalar Relative size of margin for titles of individual plots; default 0.04
PENSIZE = scalar Proportionate adjustment to the pen size for individual plot titles and axis labels; default 1
USEPENS = string token Whether to use current pen definitions in the procedure (no, yes); default no
USEAXES = string token Which aspects of the current axis definitions of window 1 to use (none, limits, style, marks, mpositions, nsubticks, transform); default none
NRMAX = scalar Maximum number of rows on page; default 8 for a square frame, 7 for a landscape frame and 10 for a portrait frame
NCMAX = scalar Maximum number of columns on page; default 8 for a square frame, 10 for a landscape frame and 7 for a portrait frame
KEYHEIGHT = scalar Space in y-direction to use for key (0 to suppress key); default * i.e. determined automatically
YPENMETHOD = string token Whether to use the same or different pens for each y-variate (different, same); default diff
FRAMESHAPE = string token Shape of the plotting frame (landscape, portrait, square); default squa

Parameters

Y = variates Y-values of the data to be plotted
X = variates or factors X-values of the data to be plotted
METHOD = string tokens Type of plot (point, line, mean, median, histogram, boxplot, spline, schematic boxplot); default poin
DESCRIPTION = texts Annotation for key

Description

TRELLIS plots one or more y-variates for each level generated by the GROUPS option, and arranges these plots in a grid (or trellis) arrangement on the page.

The data to be plotted are specified using the Y parameter. If more than one variate is specified, these will all be displayed on the same plots. This means that e.g. data points can be plotted with means. The type and method of plotting (points, lines, mean values, medians, histograms, boxplots or splines) is specified using the METHOD parameter. The default is METHOD=point. For methods point, line, mean, median and spline, a graph is produced of y-variates against x-variates, which are specified using the X parameter. When METHOD is set to mean or median, a line is drawn to join the mean or median data values at each value of the x-variate for each level of PENGROUP. In any of these cases, if PENGROUPS is set to one or more factors, a different pen will be used for each of the levels of the combined factors. By default, the pen numbers are incremented so that a different set of pens is used for each y-variate. Alternatively, you can set option YPENMETHOD=same, to use the same set for each one.

When METHOD=histogram, a histogram of the data values is drawn in each plot. In this case, options NGROUPS and LIMITS can be used to specify the number of groups in the histogram or the group limits, respectively. If more than one y-variate is specified, parallel histograms will be drawn for the variates. The PENGROUPS option is ignored when METHOD=histogram.

When METHOD=boxplot, a boxplot of the data values is drawn in each plot. Alternatively, you can set METHOD=schematicboxplot to obtain a schematic boxplot, which displays individual outlying points as well as the box; see the BOXPLOT procedure for more details. If you set the PENGROUP option, parallel box plots (one for each level of PENGROUPS) are drawn within every plot. You can also obtain parallel box plots by supplying several y-variates, which are then plotted in parallel in every plot. However, you cannot simultaneously specify several y-variates and set the PENGROUPS option.

The division of the data into separate plots is determined by the setting of the GROUPS option. This can be set to one or more factors, indicating that a separate plot should be drawn for each combinations of the factor levels. The OMITEMPTY option controls what happens if there are no data for some combinations. The default setting levels omits complete levels of any factor for which there are no data points, while the setting all omits all empty plots, i.e. plots where there are no data points. OMITEMPTY=none displays all plots regardless of whether or not they contain any data points.

If the GROUPS option is set to a variate, the plots will show the values of the data for different intervals in the range of the GROUPS variate. The GMETHOD, NGROUPS, LIMITS and OVERLAP options determine how many plots are displayed, and which data points they contain. The default option of GMETHOD is equalspacing. The distinct setting of GMETHOD converts the variate into a factor with a level (and thus a plot) for each distinct value of the variate. With equalspacing, the groups are defined by dividing the range of the GROUPS variate into the required number of intervals of equal length; while with quantiles, the intervals are defined so that each has an equal number of points, according to the ordering of the GROUPS variate. When GMETHOD is set to equalspacing or to quantiles, the number of groups to form can be specified by the NGROUPS option; if NGROUPS is not set, TRELLIS sets the number to the square root of the number of data values, or to the number of distinct values if this is smaller. Finally, when GMETHOD=limits, the LIMITS option specifies boundaries between the intervals; the first group then contains all data points with values of the GROUPS variate less than the first limit, the second group has all values greater than or equal to the first limit but less than the second limit, and so on.

The OVERLAP option allows the intervals of the GROUPS to overlap. The default overlap is 0, so there is no overlap between plots. If OVERLAP is set to 0.1, then 10% of the points (for PARTITION=quantiles) or 10% of the range (for PARTITION=equalspacing) will be in common between neighbouring plots. OVERLAP can be set anywhere in the range 0 (for no overlap) to 0.5.

The FRAMESHAPE option specifies the shape of the graphics frame, with settings:

landscape for a frame of size 1.4 × 1.0 i.e. wider in the x- than the y-direction,
portrait for a frame of size 1.0 × 1.4 i.e. wider in the y- than the x-direction,
square for a frame of size 1.0 × 1.0.

Some graphics devices do not support the use of device coordinates greater than 1.0, so the default is FRAMESHAPE=square. (See FRAME and DEVICE for more information.)

The default layout on the page can be changed by using NROWS and NCOLUMNS to specify the number of rows of plots on the page, and the number of columns of plots across the page, respectively. By default the layout is arranged so that the area of the page used for plotting is maximized, with a maximum of 8 rows and 8 columns of plots for a square frame, 7 rows and 10 columns for a landscape frame, and 10 rows and 7 columns for a portrait frame. Options NRMAX and NCMAX can be used to override these default maximum numbers of rows and columns of plots, so that more can be produced on a page.

An overall title can be put at the head of each page using the TITLE option, and overall titles for the y- and x- axes can be specified using the YTITLE and XTITLE options respectively. By default the plots start at the top left of the page, but you can set option FIRSTPICTURE=bottomleft to start at the bottom left. When GROUPS is set to one or more factors, the plot titles are constructed by default with the factor name and label/level, but this can be restricted to just the label/level by setting option TMETHOD=label.

The margins and pen size are set to give a reasonable picture on the Windows PC implementation, but can be adjusted using options YMARGIN (space for y-axis labels), XMARGIN (space for x-axis labels), TMARGIN (space for plot titles) and PENSIZE (pen size for axis markings and plot titles).

By default the pen and axes attributes are determined automatically within the procedure. Some predefined attributes can be used, as indicated by the USEPENS and USEAXES options. Setting USEPENS to yes, requests all current pen definitions (for pens 1-29) to be used.

You can specify various aspects of the axes, by defining them for window 1, and indicating that they are to be used by setting the USEAXES option. The following settings are available:

    limits y- and x-axis limits (LOWER and UPPER parameters of XAXIS and YAXIS);
    style axis styles (ACTION parameter of XAXIS and YAXIS, together with the GRID option and BOX parameter of FRAME);
    marks location and labelling of the tick marks (MARKS, LABELS, LDIRECTION, LROTATION, DECIMALS, DREPRESENTATION and VREPRESENTATION parameters of XAXIS and YAXIS);
    mpositions positions of the tick marks (MPOSITION parameter of XAXIS and YAXIS); and
    nsubticks number of subticks per interval (NSUBTICKS parameter of XAXIS and YAXIS); and
    transform axis transformations (TRANSFORM parameter of XAXIS and YAXIS).

TRELLIS includes a key on each graphics page for plots other than boxplots if each window of the trellis contains more than plot (i.e. if there is more than one Y variate, or there is a PENGROUPS factor with more than one level). You can use the KEYHEIGHT option to control the size of the key in the y-direction, and setting this to zero will suppress the key. The DESCRIPTION parameter can be used to supply annotation for the key, in the same way as in the DGRAPH directive.

Options: GROUPS, GMETHOD, NGROUPS, LIMITS, OVERLAP, OMITEMPTY, PENGROUP, NROWS, NCOLUMNS, TITLE, FIRSTPICTURE, TMETHOD, XMARGIN, YMARGIN, TMARGIN, PENSIZE, USEPENS, USEAXES, NRMAX, NCMAX, KEYHEIGHT, YPENMETHOD, FRAMESHAPE.
Parameters: Y, X, METHOD, DESCRIPTION.

Action with RESTRICT

TRELLIS takes account of any restriction on Y, X or GROUPS.

Method

TRELLIS uses the standard Genstat facilities for data manipulation and plotting.

See also

Procedures: DTABLE, DMSCATTER, DSCATTER, D2GROUPS.
Commands for: Graphics.

Example

CAPTION  'TRELLIS example','Sulphur polution data'; STYLE=meta,plain
FACTOR   [LABELS=!t(N,NE,E,SE,S,SW,W,NW)] Winddir
&        [LABELS=!t(no,yes)] Rain
READ     Sulphur,Windsp,Winddir,Rain; FREPRESENTATION=labels
  0  14.8   W  no   13  14.3   N  no   12   5.5   W  no   22   5.0  NW  no
 12   4.5   W  no    6   4.8  NE  no    2   4.3   E  no   24   4.0  SE  no
 36   9.3   S  no    6   6.3  NE  no   10   5.8  SW yes    4   8.3   W yes
  3  16.0  SW yes    7  15.8   W  no    2  16.0  SW yes    3  16.7   W yes
  5   9.5   W  no    6   9.8   W yes   13  12.0   W yes   49   4.8   N  no
 26   2.7   W  no    6   6.5  SW  no    3  13.5  SW yes    6   6.0   S yes
  8  10.5   W yes    4   5.3   S  no    6  18.0   S yes    5   8.5   W yes
  3  15.0  SW yes    3  22.7  SW  no   10    *    * yes    7   8.5  NW  no
  3   8.3  SW  no    1  14.3  SW  no    4  15.0  SW  no    5  10.5   S  no
  3  13.8   S  no    3   8.5   S  no    3   6.0  SE  no    5  16.5   S yes
  3   7.3  SE  no    1   9.8  NE yes    6   7.3  NE yes    5   5.5  NE yes
  5   6.0   E  no    6  11.3   E  no   11   8.8   E  no    2   8.5  SE  no
  3   8.3  SE  no    3  14.5  SE yes    2   9.0   S yes    3  11.5   S yes
  7  10.0  SW  no    3  11.3  SW  no    3  18.5  SW yes    5  16.0   W  no
 29   8.3   W  no   14  13.0  NW yes   15  13.5  NW  no    9  10.0  NW  no
 17   9.0  NE  no    4   7.3   N  no    7   5.8   E  no   14   8.5  SE  no
  4   6.0  SE yes    5   8.0  SW  no    3   7.5   S yes    3  10.5  SW yes
  4  11.0  SW yes    4  16.0   W  no    2  13.5  SW yes    5  20.2  SW  no
  3  11.5   W yes    4  15.0   W  no    5  10.3  SW yes   33   7.8   W yes
 28   6.3   N yes   13   6.8  SW  no    5  10.0  SE yes   26   5.5  SE  no
  4  17.0   N yes    8  19.2   N yes    9  10.0  NE yes   36   6.0  NE  no
  7   8.8  NW  no   29   9.3  NE yes   11   6.5   W  no   12   6.8  SW  no
 26   8.8   W  no   21   8.3  NW  no   13   5.3   E  no    9  10.3  SW  no
 24  13.3   S yes   19   7.0   E yes   14  20.5  NE yes   28  17.5  NE  no
 20  14.8  NW yes   43  18.5  NW  no   20   8.3   N  no   25   0.5   N  no
  1   7.8  NW yes   16   3.5   E  no   31   4.5  NW  no   38   3.7  SE yes
 11   8.0   W  no    5  11.5  SW yes    5   5.8   S yes    4  14.8  SW  no
 14  13.3   S yes    3  10.8   S yes    3  15.0  SW yes    7  17.2  SW yes
  2  12.0  SW  no    2  18.0  SW yes :
TRELLIS  [GROUPS=Winddir; TITLE='Sulphur versus wind speed'] Sulphur; Windsp
TRELLIS  [GROUPS=Winddir; TITLE='Sulphur versus wind speed'; NROW=4;\ 
         YTITLE='Sulphur measurements'; XTITLE='Wind speed (km/h)';\
         PENGROUPS=Rain] Sulphur; Windsp
Updated on February 7, 2023

Was this article helpful?