Plots tables (R.W. Payne).

### Options

`GRAPHICS` = string token |
Type of graph (`highresolution` , `lineprinter` ); default `high` |
---|---|

`METHOD` = string token |
What to plot (`points` , `linesandpoints` , `onlylines` , `data` , `barchart` , `splines` ); default `poin` |

`XFREPRESENTATION` = string token |
How to label the x-axis (`levels` , `labels` ); default `labels` uses the `XFACTOR` labels, if available |

`DFSPLINE` = scalar |
Number of degrees of freedom to use when `METHOD=splines` |

`YTRANSFORM` = string tokens |
Transformed scale for additional axis marks and labels to be plotted on the right-hand side of the y-axis (`identity` , `log` , `log10` , `logit` , `probit` , `cloglog` , `square` , `exp` , `exp10` , `ilogit` , `iprobit` , `icloglog` , `root` ); default `iden` i.e. none |

`PENYTRANSFORM` = scalar |
Pen to use to plot the transformed axis marks and labels; default `*` selects a pen, and defines its properties, automatically |

`KEYMETHOD` = string token |
What to use for the key descriptions when there are `GROUPS` (`labels` , `namesandlabels` ); default `name` |

`PLOTTITLEMETHOD` = string token |
What to use for the titles of the plots when there are `TRELLISGROUPS` (`labels` , `namesandlabels` ); default `name` |

`PAGETITLEMETHOD` = string token |
What to use for the titles of the pages when there are `PAGEGROUPS` (`labels` , `namesandlabels` ); default `name` |

`USEAXES` = string token |
Which aspects of the current axis definitions of window 1 to use (`none` , `limits` , `marks` , `mpositions` , `mlower%` , `mupper%` , `nsubticks,)` ; default `none` |

### Parameters

`TABLE` = tables |
Tables to plot |
---|---|

`DATA` = variates |
Data values to plot with each table when `METHOD=data` |

`XFACTOR` = factors |
Factor providing the x-values for the plot of each table |

`GROUPS` = factors or pointers |
Factor or factors identifying the different lines from a multi-way table |

`TRELLISGROUPS` = factors or pointers |
Factor or factors specifying the different plots of a trellis plot of a multi-way table |

`PAGEGROUPS` = factors or pointers |
Factor or factors specifying plots to be displayed on different pages |

`BAR` = scalars, tables or pointers |
Scalar defining the length of error bar to be plotted to indicate the overall (or average) variability of the values in each table, or table defining the variability of each individual table value, or pointer containing either two scalars or two tables defining the upper and lower positions of the error bar(s) |

`NEWXLEVELS` = variates |
Values to be used for `XFACTOR` instead of its existing levels |

`TITLE` = texts |
Title for the graph; default uses the identifier of the `TABLE` |

`YTITLE` = texts |
Title for the y-axis; default `' '` |

`XTITLE` = texts |
Title for the x-axis; default is to use the identifier of the `XFACTOR` |

`BARDESCRIPTION` = texts |
Descriptions for the bars |

`PENS` = variates |
Defines the pen to use to plot the points and/or line for each group defined by the `GROUPS` factors |

### Description

`DTABLE`

plots the tables specified by the `TABLE`

parameter (each table displayed in a separate set of plots). The `GRAPHICS`

option controls whether a high-resolution or a line-printer graph is plotted; by default, `GRAPHICS=high`

.

The `METHOD`

option controls how each table is plotted in high-resolution graphics, with settings:

`points` |
to plot points at the table values; |
---|---|

`linesandpoints` |
to plot points and join them by lines; |

`onlylines` |
to draw lines between the table values; |

`data` |
to draw lines between the table values, and then also plot the data values supplied (in a variate) by the `DATA` parameter; |

`barchart` |
to plot the table values as a barchart; |

`splines` |
to plot the points together with a smooth spline to show the trend over each group of points; the `DFSPLINE` specifies the degrees of freedom for the splines; if this is not set, 2 d.f. are used when there are up to 10 points, 3 if there are 11 to 20, and 4 for 21 or more. |

By default `METHOD=points`

(and this is the only display available in line-printer graphics).

The `XFACTOR`

parameter defines the factor against whose levels the values of the table are plotted. With a multi-way table, there will be a plot of the table values against the `XFACTOR`

levels for every combination of levels of the other factors classifying the table. The `GROUPS`

parameter specifies factors whose levels are to be included in a single window of the graph. So, for example, if you specify

`DTABLE [METHOD=line] Table; XFACTOR=A; GROUPS=B`

`DTABLE`

will plot the values of `Table`

in a single window with factor `A`

on the x-axis, and a line for each level of the factor `B`

. You can set `GROUPS`

to a pointer to specify several factors to define groups. For example

`POINTER [VALUES=B,C] Groupfactors`

`DTABLE [METHOD=line] Table; XFACTOR=A; GROUPS=Groupfactors`

to plot a line for every combination of the levels of factors `B`

and `C`

. Similarly, the `TRELLISGROUPS`

option can specify one or more factors to define a trellis plot. For example,

`DTABLE [METHOD=line] Table; XFACTOR=A; GROUPS=B;\`

`TRELLISGROUPS=C`

will produce a plot for each level of `C`

, in a trellis arrangement; each plot will again have factor `A`

on the x-axis, and a line for each level of the factor `B`

. Likewise, the `PAGEGROUPS`

parameter can specify factors whose combinations of levels are to be plotted on different pages. So

`DTABLE [METHOD=line] Table; XFACTOR=A; GROUPS=B; PAGEGROUPS=C`

will again produce a plot for each level of `C`

, but now on separate pages.

If `XFACTOR`

is unset, `DTABLE`

will select the `XFACTOR`

according to the following criteria (in decreasing order of importance): that the factor has no labels, that it has levels that are not the default integers 1 upwards, or that it has more levels than the other factors. If `GROUPS`

is unset, it will be set to all the factors except the `XFACTOR`

. (So, if you want to use either `TRELLISGROUPS`

or `PAGEGROUPS`

, you must also specify `XFACTOR`

and `GROUPS`

.)

The `BAR`

parameter can be set to a scalar to specify an overall (or average) error bar, such as a standard error for differences between any pair of table values. Alternatively, it can be set to a table to specify a different error value, such as an effective standard error, for every table value; `DTABLE`

then plots a bar of the defined size above and below each table value. Finally, it can be set to a pointer containing either two scalars or two tables, specifying the upper and lower positions of the error bar(s). Note, however, that the table setting may be unsuitable for plots other than barcharts when there are `GROUPS`

, as the error bars may overlap each other.

The `NEWXLEVELS`

parameter enables different levels to be supplied for `XFACTOR`

if the existing levels are unsuitable. If `XFACTOR`

has labels, these are used to label the x-axis unless you set option `XFREPRESENTATION=levels`

.

The `TITLE`

, `YTITLE`

and `XTITLE`

parameters can supply titles for the graph, the y-axis and the x-axis, respectively. The symbols, colours and line styles that are used in a high-resolution plot are usually set up by `DTABLE`

automatically. If you want to control these yourself, you should use the `PEN`

directive to define a pen with your preferred symbol, colour and line style, for each of the groups defined by combinations of the `GROUPS`

factors. The pen numbers should then be supplied to `DTABLE`

, in a variate with a value for each group, using the `PENS`

parameter.

The `YTRANSFORM`

option allows you to include additional axis markings, transformed onto another scale, on the right-hand side of the y-axis. Suppose, for example, the table contains means from an analysis of a variate of percentages that had been transformed to logits. You might then set `YTRANSFORM=ilogit`

(the inverse-logit transformation) to include markings in percentages alongside the logits. The settings are the same as those of the `TRANSFORM`

parameter of `AXIS`

(which is used to add the markings). You can control the colours of the transformed marks and labels, by defining a pen with the required properties, and specifying it with the `PENYTRANSFORM`

option. Otherwise, the default is to plot them in blue.

When there are `GROUPS`

, the `KEYMETHOD`

controls whether to use the factor names with their labels (or levels for factors with no labels) or just the labels (or levels) in the key descriptions. The default is to use the names and the labels (or levels). Similarly, the `PLOTTITLEMETHOD`

specifies what to use for the titles of the plots when there are `TRELLISGROUPS`

, and the `PAGETITLEMETHOD`

specifies what to use for the titles of the plots when there are `PAGEGROUPS`

. You can set `KEYMETHOD=*`

to have no key at all.

The `USEAXES`

option allows you to control various aspects of the axes. First you need to use the `XAXIS`

and `YAXIS`

directives to define them for window 1. Then specify which of the aspects of the axes in window 1 are to be used by `DTABLE`

, by specifying `USEAXES`

with the following settings:

`limits` |
y- and x-axis limits (`LOWER` and `UPPER` parameters); |

`marks` |
location and labelling of the tick marks (`MARKS` , `LABELS` , `LDIRECTION` , `LROTATION` , `DECIMALS` , `DREPRESENTATION` , and `VREPRESENTATION` parameters); |

`mpositions` |
positions of the tick marks (`MPOSITION` parameter); |

`mlower%` |
how large a margin to set between the lowest x and y values and the lower values of their axes, expressed as a percentage of the range of their values, if not set explicitly by the axis limits (`MLOWER%` parameter); |

`mupper%` |
how large a margin to set between the highest x and y values and the upper values of their axes, expressed as a percentage of the range of their values, if not set explicitly by the axis limits (`MUPPER%` parameter); and |

`nsubticks` |
number of subticks per interval (`NSUBTICKS` parameter). |

By default none are used.

Options: `GRAPHICS`

, `METHOD`

, `XFREPRESENTATION`

, `DFSPLINE`

, `YTRANSFORM`

, `PENYTRANSFORM`

, `KEYMETHOD`

, `PLOTTITLEMETHOD`

, `PAGETITLEMETHOD`

, `USEAXES`

.

Parameters: `TABLE`

, `DATA`

, `XFACTOR`

, `GROUPS`

, `TRELLISGROUPS`

, `PAGEGROUPS`

, `BAR`

, `NEWXLEVELS`

, `TITLE`

, `YTITLE`

, `XTITLE`

, `BARDESCRIPTION`

, `PENS`

.

### See also

Directives: `TABLE`

, `TABULATE`

, `PREDICT`

, `VPREDICT`

.

Procedures: `AGRAPH`

, `AUGRAPH`

, `DMOSAIC`

, `MTABULATE`

. `SVTABULATE`

, `VGRAPH`

.

Commands for: Graphics.

### Example

CAPTION 'DTABLE example',\ 'Data from Guide to Genstat Part 1, Section 4.11.';\ STYLE=meta,plain VARIATE [NVALUES=15] Quantity FACTOR [NVALUES=15; LABELS=!T(A,B)] Type & [LABELS=!T(London,Manchester,Birmingham,Bristol)] Town READ [PRINT=errors] Town,Quantity,Type; FREPRESENTATION=labels London 10 A Manchester 5 B Birmingham 10 B Bristol 25 A Manchester 10 * Birmingham 100 B London 200 B Manchester 25 A Bristol 50 A Birmingham 25 A Bristol 25 B London 25 A London 50 B Manchester 25 B London 50 A : TABLE [CLASSIFICATION=Town,Type] Totdisp; UNKNOWN=Udisp TABULATE Quantity; TOTALS=Totdisp PRINT Totdisp; DECIMALS=0 DTABLE Totdisp; XFACTOR=Town; GROUPS=Type