TRELLIS procedure

Does a trellis plot (S.J. Welham).


Options

GROUPS = factors or variate
Factors or variate defining the classification for the plots

GMETHOD = string
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
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
Whether to put the first picture at bottom or top left of the grid (bottomleft, topleft); default topl

TMETHOD = string
Whether to give plot titles as factor names with labels or just labels (names, labels); default names

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

XMARGIN = scalar
Relative size of margins for the x-axis labels on individual plots; default 0.03

TMARGIN = scalar
Relative size of margin for titles of individual plots; default 0.03

PENSIZE = scalar
Proportionate adjustment to the pensize for individual plot titles and axis labels; default 0.6

USEPENS = string
Whether to use current pen definitions in the procedure (no, yes); default no

USEAXES = string
Which aspects of the current axes definition of window 1 to use (none, limits, style, marks, mpositions); default none

NRMAX = scalar
Maximum number of rows on page; default 8

NCMAX = scalar
Maximum number of columns on page; default 8


Parameters

Y = variates
Y-values of the data to be plotted

X = variates or factors
X-values of the data to be plotted

METHOD = strings
Type of plot (point, line, mean, median, histogram, boxplot, spline); default poin


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.

   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 box-plot of the data values is drawn in each plot. If the PENGROUP option is set, parallel box plots will be drawn for each level of PENGROUPS within each plot. If multiple y-variates are set, parallel box plots will be drawn for each y-variate within each plot. Note that you cannot specify parallel box plots by simultaneously using multiple y-variates and the PENGROUPS option.

   Other options control various aspects of the plot layout. 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 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 up to 64 plots per page. Options NRMAX and NCMAX can be used to override the default maximum numbers of rows and columns of plots, so that more can be produced on a page; the default value of both options is 8.

   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 pensize 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. The graphs are all plotted in Window 1, and various aspects of the current axes definitions of window 1 can be retained, as specified by the settings of the USEAXES option: limits allows y- and x- axis limits to be imposed for all plots (by the YLOWER, YUPPER, XLOWER and XUPPER parameters of AXES); style means that the current axes style is used (STYLE parameter of AXES); marks means that the location and labelling of tick marks on both axes can be defined for the procedure (YMARKS, XMARKS, YLABELS and XLABELS parameters of AXES); mpositions means that the positions of tick marks on the axes can be defined (YMPOSITION and XMPOSITION parameters of AXES).

 

Options: GROUPS, GMETHOD, NGROUPS, LIMITS, OVERLAP, OMITEMPTY, PENGROUP, NROWS, NCOLUMNS, TITLE, FIRSTPICTURE, TMETHOD, XMARGIN, YMARGIN, TMARGIN, PENSIZE, USEPENS, USEAXES, NRMAX, NCMAX.

Parameters: Y, X, METHOD.


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.