Produces contour maps of two-way arrays of numbers using character (i.e. line-printer) graphics.
Options
CHANNEL = scalar |
Channel number of output file; default is current output file |
|---|---|
INTERVAL = scalar |
Contour interval for scaling; default * i.e. determined automatically |
TITLE = text |
General title; default * |
YTITLE = text |
Title for y-axis; default * |
XTITLE = text |
Title for x-axis; default * |
YLOWER = scalar |
Lower bound for y-axis; default 0 |
YUPPER = scalar |
Upper bound for y-axis; default 1 |
XLOWER = scalar |
Lower bound for x-axis; default 0 |
XUPPER = scalar |
Upper bound for x-axis; default 1 |
YINTEGER = string token |
Whether y-labels integral (yes, no); default no |
XINTEGER = string token |
Whether x-labels integral (yes, no); default no |
LOWERCUTOFF = scalar |
Lower cut-off for array values; default * |
UPPERCUTOFF = scalar |
Upper cut-off for array values; default * |
Parameters
GRID = identifiers |
Pointers (of variates representing the columns of a data matrix), matrices or two-way tables specifying values on a regular grid |
|---|---|
DESCRIPTION = texts |
Annotation for key |
Description
A contour plot provides a way of displaying three-dimensional data in a two-dimensional plot. LPCONTOUR produces these in “line-printer” format, that is, using the characters of ordinary output rather than a high-resolution graphics display. It was added in Release 10 as a synonym of the earlier CONTOUR directive, which may be modified to use high-resolution graphics in a future release.
The data values are supplied as a rectangular array of numbers that represent the values of the variable in the third dimension, often referred to as height or the z-axis. The first two dimensions (x and y) are the rows and columns indexing the array; the complete three-dimensional data set is referred to as a surface or grid. Contours are lines that are used to join points of equal height, and usually some form of interpolation is used to estimate where these points lie. The resulting contour plot is not necessarily very “realistic” when compared to perspective plots produced by DSURFACE, but it has the advantage that the entire surface can easily be examined, without the danger of some parts being obscured by high points or regions.
You might use contour plots for example when you have data sampled at points on a regular grid, such as the concentrations of a trace element or nutrient in the soil. Contours are also very useful when fitting nonlinear models, when they can be used to study two-dimensional slices of the likelihood surface, to help find good initial estimates of the parameters.
LPCONTOUR produces output by using cubic interpolation between the grid points to estimate a z-value for each character position in the plot. Each value is reduced to a single digit in the range 0 … 9, according to the rules described below. To produce the contour plot only the even digits are printed: you can then see the contours as the boundaries between the blank areas and the printed digits.
The GRID parameter can be set to a matrix, a two-way table (with the first factor defining the rows), or a pointer to a set of variates each containing a column of data. We explain the conventions in terms of a matrix as input, but similar rules apply to the other structures. When reading or printing a matrix the origin of the rows and columns (row 1, column 1) appears at the top left-hand corner. However, in forming the contour plot the rows are reversed in order so that the first row of the matrix is placed at the bottom of the contour; thus the origin of the contour is located, according to the usual conventions, at the bottom left-hand corner of the plot. The DCONTOUR directive, which plots contours using high-resolution graphics, also reverses the rows of the grid in the same way.
LPCONTOUR scales the grid values by dividing by the contour interval. The scaled grid values are then converted to single digits by taking the remainder modulo 10 and truncating the fractional part. The INTERVAL option allows you to set the contour interval. For example, if the grid values range from 17 to 72 and the interval is set to 10, contour lines (the boundaries between blank space and printed digits) will occur at grid values of 20, 30, 40, 50, 60 and 70. By default, the interval is determined from the range of the data in order to obtain 10 contours.
The UPPERCUTOFF and LOWERCUTOFF options can be used to define a window for the grid values that will form the contours. All values above or below these are printed as X. Setting either UPPERCUTOFF or LOWERCUTOFF will change the default contour interval, as the range of data values is effectively curtailed.
You can use the TITLE, YTITLE and XTITLE option to annotate the contour plot. If you specify several grids, these will be plotted in separate frames and the text of the TITLE option will appear at the top of each one. You should thus use TITLE only to give a general description of what the contours represent. The DESCRIPTION parameter can be used to add specific descriptions to be printed at the bottom of each individual plot.
The YUPPER and YLOWER options allow you to set upper and lower bounds for the y-axis; thus generating axis labels that reflect the range of values over which the grid was observed or evaluated. Setting YINTEGER=yes will ensure the labels are printed as integers, if possible. The default axis bounds are 0.0 and 1.0. The options XLOWER, XUPPER and XINTEGER similarly control labelling of the x-axis.
Options: CHANNEL, INTERVAL, TITLE, YTITLE, XTITLE, YLOWER, YUPPER, XLOWER, XUPPER, YINTEGER, XINTEGER, LOWERCUTOFF, UPPERCUTOFF.
Parameters: GRID, DESCRIPTION.
Action with RESTRICT
LPCONTOUR takes account of restrictions on any of the variates in a GRID pointer.
See also
Directives: DCONTOUR, LPGRAPH, LPHISTOGRAM.
Commands for: Graphics.
Example
" Example 1:6.10.3a-b "
MATRIX [ROWS=5; COLUMNS=7] X,Y; VALUES=!((1...7)5),!(7(1...5))
CALCULATE Zvalues = (X-2.5)*(X-6)*X - 10*(Y-3)*(Y-3)
LPCONTOUR [TITLE='Z(x,y) = x*(x-2.5)*(x-6) - 10*(y-3)**2';\
YTITLE='Y values'; XTITLE='X values'] Zvalues
" Core samples were taken from a wetland rice experiment to examine
the leaching of ammonium nitrate. Three three cores were taken at
intervals of 5cm, and the concentration of ammonium nitrate was
measured at depths of 4, 8, ... 20 cm. "
VARIATE [NVALUES=5] Core[1...5]
READ Core[]
7 6 129 10 9
8 82 2315 53 7
5 195 1064 77 7
10 35 1034 30 9
11 20 161 10 15:
TEXT [VALUES=' Samples taken 40 days after placement ',\
' of 2 grams supergranule urea. '] Coredesc
CALCULATE Core[] = LOG10(REVERSE(Core[]))
LPCONTOUR [YTITLE='Soil depth in cm';\
XTITLE='Distance from central core';\
YINTEGER=yes; XINTEGER=yes;
YUPPER=4; YLOWER=20; XUPPER=10; XLOWER=-10]\
Core; DESCRIPTION=Coredesc