aboutsummaryrefslogtreecommitdiffstats
path: root/doc/user/gra_data
blob: f39c7510eb1af4aea60acc0a6c70229b44d99992 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
@Section
   @Title { Changing the appearance of the data }
   @Tag { data }
@Begin
@PP
The @Code "@Data" symbol has options for controlling the
graphs. @RawIndex { graphs (statistical) }
graphs.data @SubIndex { @Code "@Data" symbol }
data.graph @Index { @Code "@Data" symbol (graphs) }
appearance of its data.  We have already seen the
@Code "points" option, which controls what is printed at each data
graphs. @RawIndex { graphs (statistical) }
graphs.points @SubIndex { @Code points option }
points.graph @Index { @Code "points" option (graphs) }
point:
@CD @Tab
   vmargin { 0.5vx }
   @Fmta { @Col @Code A ! @Col B ! @Col ! @Col @Code C ! @Col D }
{
@Rowa
    A { cross }
    B { @GraphCross }
    C { plus }
    D { @GraphPlus }
@Rowa
    A { square }
    B { @GraphSquare }
    C { filledsquare }
    D { @GraphFilledSquare }
@Rowa
    A { diamond }
    B { @GraphDiamond }
    C { filleddiamond }
    D { @GraphFilledDiamond }
@Rowa
    A { circle }
    B { @GraphCircle }
    C { filledcircle }
    D { @GraphFilledCircle }
@Rowa
    A { triangle }
    B { @GraphTriangle }
    C { filledtriangle }
    D { @GraphFilledTriangle }
}
Filled and open squares have exactly the same size, filled and open
diamonds have exactly the same size, and so on.  If the @Code "points"
option is omitted or empty, nothing is printed.  The symbols are
centred over the data point.  There is a @Code "symbolsize"
graphs. @RawIndex { graphs (statistical) }
graphs.symbolsize @SubIndex { @Code symbolsize option }
symbolsize.graph @Index { @Code "symbolsize" option (graphs) }
option which controls the size (radius) of all these symbols,
and a @Code "symbollinewidth" option
@FootNote {
The @Code "symbollinewidth" option was introduced in Version 3.37,
as part of a bug fix which also caused the printed size of some
symbols to change slightly.
}
which controls their line width:
@ID @OneRow @Code {
"@Data"
"    symbolsize { 0.15f }"
"    symbollinewidth { 0.5p }"
}
shows their default values, 0.15 times the current font size and half
a point.  More precisely, these default values are taken from options
to the @Code "@Graph" symbol with the same names.  By setting those
options you can therefore control all data points in the graph at
once.  The @Code "symbollinewidth" option does not affect the
appearance of @Code { filledsquare }, @Code { filleddiamond },
@Code { filledcircle }, or @Code { filledtriangle }.
@PP
The @Code "@Data" symbol also has a @Code "pairs" option which
graphs. @RawIndex { graphs (statistical) }
graphs.pairs @SubIndex { @Code pairs option }
pairs.graph @Index { @Code "pairs" option (graphs) }
determines how each pair of points is connected.  The choices are
@Code none (not connected, the default), @Code solid (a solid line),
@Code dashed (a dashed line), @Code dotted (a dotted line), or
@Code { dotdashed }, @Code { dotdotdashed }, and @Code { dotdotdotdashed }
for mixing dots and dashes.  For example,
@ID @OneRow @Code @Verbatim {
@Graph
    abovecaption { Estimated population of Boston, New York, and Philadelphia }
{
    @Data  points { plus }  pairs { solid }
    { 1720 12000  1730 13000  1740 15601  1760 15631  1770 15877 }

    @Data  points { plus }  pairs { dashed }
    { 1720 7000  1730 8622  1740 10451  1750 14255  1760 18000  1770 22667 }

    @Data  points { plus }  pairs { dotdashed }
    { 1720 10000  1730 11500  1740 12654  1750 18202  1760 23750  1770 34583 }
}
}
produces
@CD @Graph
    abovecaption { Estimated population of Boston, New York, and Philadelphia
}
{
    @Data  points { plus }  pairs { solid }
    { 1720 12000  1730 13000  1740 15601  1760 15631  1770 15877 }

    @Data  points { plus }  pairs { dashed }
    { 1720 7000  1730 8622  1740 10451  1750 14255  1760 18000  1770 22667 }

    @Data  points { plus }  pairs { dotdashed }
    { 1720 10000  1730 11500  1740 12654  1750 18202  1760 23750  1770 34583 }

}
(R. C. Simmons, @I { The American Colonies }, W. W. Norton, New York,
1981.)  We will see in Section {@NumberOf key} how to add an explanatory key to
this graph.  If the points have symbols, these connecting lines will stop 1.5
symbolsizes away from the data points, so as not to overstrike them.  If
the points have no symbols and @Code "pairs" is {@Code "dashed"}, the
first and last dash in each segment will have half the length of the
others.
@PP
A @Code "dashlength" option controls the length of dashes and also the
graphs. @RawIndex { graphs (statistical) }
graphs.dashlength @SubIndex { @Code dashlength option }
dashlength.graph @Index { @Code "dashlength" option (graphs) }
separation between dots, and a @Code "linewidth" option controls the
graphs. @RawIndex { graphs (statistical) }
graphs.linewidth @SubIndex { @Code linewidth option }
linewidth.graph @Index { @Code "linewidth" option (graphs) }
width (thickness) of the lines and dots:
@ID @OneRow @Code @Verbatim {
@Data
    dashlength { 0.2f }
    linewidth { 0.5p }
{
    ...
}
}
This shows the default values, {@Code "0.2f"} for @Code "dashlength"
and {@Code "0.5p"} (half a point) for {@Code "linewidth"}.  Actually
the default value for @Code "linewidth" is whatever happens to be
already in use, but Lout sets line widths to half a point initially.
This option also controls the separation between bars in histograms.
@PP
The @Code "pairs" option is also used for producing histograms, like
graphs. @RawIndex { graphs (statistical) }
graphs.histograms @SubIndex { histograms }
histograms. @Index { histograms }
graphs. @RawIndex { graphs (statistical) }
graphs.yhisto @SubIndex { @Code yhisto option }
yhisto.graph @Index { @Code "yhisto" option (graphs) }
this:
@ID @OneRow @Code @Verbatim {
@Graph
    hidecaptions { yes }
    abovecaption { Computer Science 3 Results (1993) }
    leftcaption { Number of
students }
    belowcaption { Final mark (%) }
    yextra { 0c }
    ymax { 80 }
{
    @Data pairs { yhisto }
    { 0 1 10 3 20 2 30 4 40 15 50 60 60 58 70 28 80 15 90 7 100 0 }
}
}
which has result
@CD @Graph
    hidecaptions { yes }
    abovecaption { Computer Science 3 Results (1993) }
    leftcaption { Number of
students }
    belowcaption { Final mark (%) }
    yextra { 0c }
    ymax { 80 }
{
    @Data
        pairs { yhisto }
    { 0 1 10 3 20 2 30 4 40 15 50 60 60 58 70 28 80 15 90 7 100 0 }
}
Note carefully that one y histogram rectangle occupies the space from
one x value to the next, with height equal to the y value lying between
these two x values.  This means that the very last y value has no effect
on the result (however, there must be a last y value anyway).
@PP
There is an alternative to @Code "yhisto" called {@Code "surfaceyhisto"}:
graphs. @RawIndex { graphs (statistical) }
graphs.surfaceyhisto @SubIndex { @Code surfaceyhisto option }
surfaceyhisto.graph @Index { @Code "surfaceyhisto" option (graphs) }
@CD @Graph
    hidecaptions { yes }
    abovecaption { Computer Science 3 Results (1993) }
    leftcaption { Number of
students }
    belowcaption { Final mark (%) }
    yextra { 0c }
    ymax { 80 }
{
    @Data
        pairs { surfaceyhisto }
    { 0 1 10 3 20 2 30 4 40 15 50 60 60 58 70 28 80 15 90 7 100 0 }
}
As you can see, @Code "surfaceyhisto" draws just the surface of the
histogram, not the descending lines.
@PP
There are @Code "xhisto" and @Code "surfacexhisto" values of
graphs. @RawIndex { graphs (statistical) }
graphs.xhisto @SubIndex { @Code xhisto option }
xhisto.graph @Index { @Code "xhisto" option (graphs) }
graphs. @RawIndex { graphs (statistical) }
graphs.surfacexhisto @SubIndex { @Code surfacexhisto option }
surfacexhisto.graph @Index { @Code "surfacexhisto" option (graphs) }
@Code "pairs" which produce a histogram whose bars are parallel to
the x axis.  There are also {@Code "filledyhisto" } and
{@Code "filledxhisto" } values which produce filled rectangles rather
graphs. @RawIndex { graphs (statistical) }
graphs.filledxhisto @SubIndex { @Code filledxhisto option }
filledxhisto.graph @Index { @Code "filledxhisto" option (graphs) }
graphs. @RawIndex { graphs (statistical) }
graphs.filledyhisto @SubIndex { @Code filledyhisto option }
filledyhisto.graph @Index { @Code "filledyhisto" option (graphs) }
than outlined ones:
@ID @OneRow @Code @Verbatim {
@Graph
    abovecaption { Fertility rates in some developing countries }
    xextra { 0c }
    yextra { 0c }
    xmax { 8 }
    yticks {
        1.5 (Turkey) 2.5 (Thailand)
        3.5 (Indonesia) 4.5 (Costa Rica)
        5.5 (Colombia) 6.5 (Cameroon)
        7.5 (Botswana) 8.5 (Bangladesh)
    }
    yticklength { 0c }
{
    @Data
        pairs { filledxhisto }
    { 0 1 3.2 2 2.2 3 3.0 4 3.5 5 2.8 6 5.9 7 4.8 8 5.3 9 }
}
}
produces
@CD @Graph
    abovecaption { Fertility rates in some developing countries }
    xextra { 0c }
    yextra { 0c }
    xmax { 8 }
    yticks { 1.5 (Turkey) 2.5 (Thailand) 3.5 (Indonesia) 4.5 (Costa Rica)
             5.5 (Colombia) 6.5 (Cameroon) 7.5 (Botswana) 8.5 (Bangladesh) }
    yticklength { 0c }
{
    @Data
        pairs { filledxhisto }
    { 0 1 3.2 2 2.2 3 3.0 4 3.5 5 2.8 6 5.9 7 4.8 8 5.3 9 }
}
(Bryant Robey, Shea O. Rutstein, and Leo Morros:  The fertility decline in
developing countries, @I { Scientific American }, December 1993.)  Once
again each bar goes from one y value to the next, with its x value
equal to the x value lying between the two y values; this time the very
first x value has no effect on the result.
@PP
The colour of one set of data can be changed with a @Code "colour"
graphs. @RawIndex { graphs (statistical) }
graphs.colour @SubIndex { @Code colour option }
colour.graph @Index { @Code "colour" option (graphs) }
option:
@ID @OneRow @Code @Verbatim {
@Data
    colour { blue }
}
For the complete list of acceptable colours, see Section
{@NumberOf colour}.  The @Code "colour" option's name may also be
spelt @Code {"color"}.
@PP
It is also possible to paint the area between the data points and
the x axis (or frame if @Code "style" is not {@Code "axes"}), using
graphs. @RawIndex { graphs (statistical) }
graphs.paint @SubIndex { @Code paint option }
paint. @RawIndex { @Code "paint" option }
paint.in.graphs @SubIndex { in graphs }
@ID @OneRow @Code {
"@Data"
"    paint { yes }"
}
The paint colour is determined by the @Code "colour" option just
introduced; it will be @Code "black" if no colour is specified.  Paint
(including white paint) hides paint, points, and lines drawn by previous
data sets.  However the points and lines of each data set are drawn after
painting that set, so they cannot be hidden under their own paint; and
axes and frames are drawn last so that they too are never hidden.
@PP
Wherever there is a @Code paint option in Lout's standard packages,
there is a neighbouring @Code texture option.  For historical reasons
the @Code paint option of @Code "@Graph" is not quite the same as other
@Code "paint" options, but the @Code "texture" option is available
graphs. @RawIndex { graphs (statistical) }
graphs.texture @SubIndex { @Code texture option }
texture.option. @RawIndex { @Code "texture" option }
texture.option.in.graph @SubIndex { in graphs }
as usual:
@ID @OneRow @Code @Verbatim {
@Graph
    yextra { 0c }
{
    @Data
        paint { yes }
        texture { chessboard angle { 45d } }
    { 0 0.00 1 1.00 2 1.50 3 1.83 4 2.08 5 2.28 6 2.45 }
}
}
produces
@FootNote {
If you can't see any textures here, the fault is probably with your
PostScript viewer.  See Section {@NumberOf textures}.
}
@CD @Graph
    yextra { 0c }
{
    @Data
        paint { yes }
        texture { striped angle { 90d } }
    { 0 0.00 1 1.00 2 1.50 3 1.83 4 2.08 5 2.28 6 2.45 }
}
Any value acceptable to the @Code "texture" option of @Code "@Box"
(Section {@NumberOf boxes}) is acceptable here.  The @Code "texture"
option will also give a texture to the filled areas of a
{@Code filledxhisto} or {@Code filledyhisto}:
@ID @OneRow @Code @Verbatim {
@Graph
    yextra { 0c }
{
    @Data
        pairs { filledyhisto }
        texture { striped angle { 45d } }
    { 0 0.00 1 1.00 2 1.50 3 1.83 4 2.08 5 2.28 6 2.45 7 0 }
}
}
produces
@CD @Graph
    yextra { 0c }
{
    @Data
        pairs { filledyhisto }
        texture { striped angle { 45d } }
    { 0 0.00 1 1.00 2 1.50 3 1.83 4 2.08 5 2.28 6 2.45 7 0 }
}
If you want the bars to vary in colour or texture, you have to give
multiple @Code "@Data" sets, one for each combination of colour and
texture.
@PP
A @Code "dataformat" option is provided for changing the interpretation
graphs. @RawIndex { graphs (statistical) }
graphs.dataformat @SubIndex { @Code dataformat option }
dataformat.graph @Index { @Code "dataformat" option (graphs) }
of the data.  Ordinarily, as we know, the numbers are taken to be pairs of
x and y coordinates, like this:
@ID @OneRow @Code {
"@Data"
"{"
"    x y  x y  ...  x y"
"}"
}
However, by setting @Code "dataformat" to {@Code "yonly"}, the
interpretation is changed to a sequence of y coordinates only:
@ID @OneRow @Code {
"@Data"
"    dataformat { yonly }"
"{"
"    y y  ...  y"
"}"
}
and x values 1, 2, and so on are inserted automatically, as though
the original input was
@ID @OneRow @Code {
"@Data"
"{"
"    1 y  2 y  ..."
"}"
}
Similarly, {@Code "xonly"} inserts y values 1, 2, and so on.  The
default value, {@Code "xandy"}, gives the usual interpretation, and
{@Code "swapxandy"} exchanges adjacent pairs of numbers:  the data
is interpreted as @M { (y, x) } pairs rather than @M { (x, y) }
pairs.  The layout of data on lines has no effect on the interpretation.
@End @Section