summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/metapost/base/source/mpgraph.tex
blob: 77c5d71c5a59ba64488f62804c1f27c6a188d77c (plain)
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
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
% $Id: mpgraph.tex,v 1.3 2005/03/22 00:16:53 karl Exp $
% MetaPost graph doc, by John Hobby.  License at end.
\ifnum\pdftexversion<140
\else
\pdfminorversion=5
\pdfobjcompresslevel=1% Use compressed object streams.
\fi
\RequirePackage[resetfonts]{cmap}
\documentclass{article} % article is NOT the original style
\usepackage{makeidx}
\usepackage{fancyvrb}
\usepackage{ctabbing}
\RecustomVerbatimEnvironment{verbatim}{BVerbatim}{baseline=c}
\usepackage{graphics}
\usepackage[textwidth=6in,textheight=8.65in]{geometry}
\usepackage{multicol}

\newcommand\descr[1]{{\langle\hbox{\rm#1}\rangle}}
\newcommand\invisgap{\nobreak\hskip0pt\relax}
\newcommand\tdescr[1]{$\langle$\invisgap{\rm#1}\invisgap$\rangle$}
\newcommand\Ignore[1]{} % For fooling delatex so spell will work

\newfont\psyvii{psyr at 7pt}
\newcommand\regmark{$^{\hbox{\psyvii\char'322}}$}   % Registered trademark
\newcommand\logofn{\global\font\logofn=logo8 \logofn}
\newcommand\logo{\global\font\logo=logo10 \logo}
\newcommand\logosl{\global\font\logosl=logosl10 \logosl}
\newcommand\MF{{\ifdim \fontdimen6\font <9pt \def\logo{\logofn}\fi
        \ifdim \fontdimen1\font >0pt \def\logo{\logosl}\fi
        {\logo META}\-{\logo FONT}}}

\newcommand\mathcenter[1]{\vcenter{\hbox{#1}}}

\author{John D. Hobby}
\title{Drawing Graphs with {MetaPost}}
\date{}


\newcommand\myabstract{%
This paper describes a graph-drawing package that has been implemented
as an extension to the MetaPost graphics language.  MetaPost has
a powerful macro facility for implementing such extensions.  There are
also some new language features that support the graph macros.
Existing features for generating and manipulating pictures
allow the user to do things that would be difficult to achieve
in a stand-alone graph package.}

\newcommand\mykeywords{%
    typesetting; graphs; MetaPost}

\usepackage[rgb,x11names]{xcolor}% Optimize for screen reading.
\usepackage{hyperxmp}
\usepackage{hyperref}
\hypersetup{
  pdftitle={Drawing Graphs with MetaPost},
  pdfauthor={John D. Hobby and the MetaPost development team},
  pdfkeywords={typesetting, graphs, MetaPost, TeX}
}
\hypersetup{
  pdfstartview={XYZ null null null},% Zoom factor is determined by viewer.
  colorlinks,
  linkcolor=RoyalBlue3,
  urlcolor=Chocolate4,
  citecolor=SpringGreen3
}
\usepackage[all]{hypcap}


\begin{document}
  \maketitle
  \begin{abstract} \myabstract \end{abstract}
  \ifx\keywords\undefined \else
    \begin{keywords} \mykeywords \end{keywords}
  \fi

\setlength{\columnsep}{2.5em}
\begin{multicols}{2}
\tableofcontents
\end{multicols}

\section{Introduction}
\label{intro}

MetaPost is a batch-oriented graphics language based on Knuth's \MF\footnote{\MF\
is a trademark of Addison Wesley Publishing Company.}, but with
PostScript\footnote{PostScript is a registered trademark of Adobe Systems Inc.}
output and numerous features for integrating text and graphics.
The author has tried to make this paper as independent as possible of the
user's manual~\cite{ho:mp3}, but fully appreciating all the material requires
some knowledge of the MetaPost language.

We concentrate on the mechanics of producing particular kinds of graphs
because the question of what type of graph is best in a given situation
is covered elsewhere; e.g., Cleveland~\cite{Cleve85,Cleve93,Cleve93a} and
Tufte~\cite{Tufte83}.
The goal is to provide at least the power of UNIX\footnote{UNIX is a registered
trademark of UNIX System Laboratories, Inc.} {\it
grap\/}~\cite{BenKer90}, but within the MetaPost language.
Hence the package is implemented using MetaPost's powerful macro facility.

The graph macros provide the following functionality:
\begin{enumerate}
\item Automatic scaling
\item Automatic generation and labeling of tick marks or grid lines
\item Multiple coordinate systems
\item Linear and logarithmic scales
\item Separate data files
\item Ability to handle numbers outside the usual range
\item Arbitrary plotting symbols
\item Drawing, filling, and labeling commands for graphs
\end{enumerate}
In addition to these items, the user also has access to all the features
described in the MetaPost user's manual~\cite{ho:mp3}.
These include access to almost all the features of PostScript\regmark,
ability to use and manipulate typeset text,
ability to solve linear equations,
and data types for points, curves, pictures, and coordinate transformations.

Section~\ref{grmac} describes the graph macros from a user's perspective
and presents several examples.  Sections \ref{nummac} and~\ref{formsec} discuss
auxiliary packages for manipulating and typesetting numbers and Section~\ref{concl}
gives some concluding remarks.  Appendix~\ref{summsec} summarizes the graph-drawing
macros.


\section{Using the Graph Macros}
\label{grmac}

A MetaPost input file that uses the graph macros should begin with
$$ \hbox{\tt input graph} $$
This reads a macro file {\tt graph.mp} and defines the graph-drawing commands
explained below.  The rest of the file should be one or more instances of
$$ \vbox{\hbox{\tt beginfig($\descr{figure number}$);}
        \hbox{\tt $\descr{graphics commands}$ endfig;}}
$$
followed by {\tt end}.

The following \tdescr{graphics commands} suffice to generate the graph in
Figure~\ref{fig1} from the data file {\tt agepop91.d}:
$$\begin{verbatim}
draw begingraph(3in,2in);
  gdraw "agepop91.d";
  endgraph;
\end{verbatim}
$$
(Each line of {\tt agepop91.d} gives an age followed the estimated number of
Americans of that age in 1991 \cite{Census92}.)

\begin{figure}[htp]
$$ \includegraphics{mpgraph-1.mps} $$
\caption{A graph of the 1991 age distribution in the United States}
\label{fig1}
\end{figure}

\subsection{Basic Graph-Drawing Commands}

% begingraph, endgraph, gdraw

All graphs should begin with
$$ \hbox{\tt begingraph($\descr{width}$,$\descr{height}$);} $$
and end with {\tt endgraph}.  This is syntactically a \tdescr{picture expression},
so it should be preceded by {\tt draw} and followed by a semicolon as in the
example.\footnote{See the User's Manual~\cite{ho:mp3} for explanations of {\tt draw}
commands and syntactic elements like \tdescr{picture expression}.}
The \tdescr{width} and \tdescr{height} give the dimensions of the
graph itself without the axis labels.

The command
$$ {\tt gdraw}\ \descr{expression}\ \descr{option list} $$
draws a graph line.  If the \tdescr{expression} is of type string, it names a data
file; otherwise it is a path that gives the function to draw.  The
\tdescr{option list} is zero or more drawing options
$$ {\tt withpen} \descr{pen expression}
   \mid {\tt withcolor} \descr{color expression}
   \mid {\tt dashed} \descr{picture expression}
$$
that give the line width, color, or dash pattern as explained in the User's
Manual~\cite{ho:mp3}.

% plot <picture>

In addition to the standard drawing options, the \tdescr{option list} in a
{\tt gdraw} statement can contain
$$ {\tt plot}\ \descr{picture expression} $$
The \tdescr{picture expression} gives a plotting symbol to be drawn at each
path knot.  The {\tt plot} option suppresses line drawing so that%
\footnote{Troff users should replace {\tt btex \$\string\bullet\$ etex} with
{\tt btex \string\(bu etex}.}
\Ignore{\)}% Help delatex so spell will work
$$ \hbox{\verb|gdraw "agepop91.d" plot btex $\bullet$ etex|} $$
generates only bullets as shown in Figure~\ref{fig2}.
(Following the {\tt plot} option with a {\tt withpen} option would
cause the line to reappear superimposed on the plotting symbols.)

\begin{figure}[htp]
$$ \includegraphics{mpgraph-2.mps} $$
\caption{The 1991 age distribution plotted with bullets}
\label{fig2}
\end{figure}

Watch out for the following: the \tdescr{picture expression} is placed
with the lower-left corner at the path knot, not its center. If you
want it to be dead-center, you have to correct the placement
yourself. For the example above, you need something like this instead:

\medskip
\begin{verbatim}
def MPbullet = 
   btex \lower\fontdimen22\cmsy \hbox to 0pt{\hss\cmsy\char15\hss} etex 
enddef;
\end{verbatim}

\medskip\noindent
followed by:
$$ \hbox{\verb|gdraw "agepop91.d" plot MPbullet|} $$


% glabel, gdotlabel, OUT

The {\tt glabel} and {\tt gdotlabel} commands add labels to a graph.  The
syntax for {\tt glabel} is
$$ {\tt glabel.}\ \descr{label suffix}
    \hbox{\tt ($\descr{string or picture expression}$, $\descr{location}$)}
    \ \descr{option list}
$$
where \tdescr{location} identifies the location being labeled and
\tdescr{label suffix} tells how the label is offset relative to that location.
The {\tt gdotlabel} command is identical, except it marks the location with a
dot.  A \tdescr{label suffix} is as in plain MetaPost:
\tdescr{empty} centers the label on the location;
{\tt lft}, {\tt rt}, {\tt top}, {\tt bot} offset the label horizontally or
vertically; and {\tt ulft}, {\tt urt}, {\tt llft}, {\tt lrt} give diagonal
offsets.  The \tdescr{location} can be a pair of graph coordinates, a knot
number on the last {\tt gdraw} path, or the special location {\tt OUT}.
Thus
$$ \hbox{\verb|gdotlabel.top(btex $(50,0)$ etex, 50,0)|} $$
would put a dot at graph coordinates {\tt(50,0)} and place the typeset text
``$(50,0)$'' above it.  Alternatively,
$$ \hbox{\verb|glabel.ulft("Knot3", 3)|} $$
typesets the string {\tt "Knot3"} and places it above and to the left of
Knot~3 of the last {\tt gdraw} path.  (The knot number 3 the path's ``time''
parameter~\cite[Section 8.2]{ho:mp3}.)

The \tdescr{location} {\tt OUT} places a label relative to the whole graph.
For example, replacing ``{\tt gdraw "agepop91.d"}'' with
$$\begin{verbatim}
glabel.lft(btex \vbox{\hbox{Population} \hbox{in millions}} etex, OUT);
glabel.bot(btex Age in years etex, OUT);
gdraw "agepopm.d";
\end{verbatim}
$$
in the input for Figure~\ref{fig1} generates Figure~\ref{fig3}.
This improves the graph by adding axis labels and using a new data file
{\tt agepopm.d} where the populations have been divided by one million to avoid
large numbers.  We shall see later that simple transformations such as this can
be achieved without generating new data files.

\begin{figure}[htp]
$$ \includegraphics{mpgraph-3.mps} $$
\caption{An improved version of the 1991 age distribution graph}
\label{fig3}
\end{figure}

All flavors of \TeX\ can handle multi-line labels via the \verb|\hbox| within
\verb|\vbox| arrangement used above, but \LaTeX\ users will find it more natural
to use the {\tt tabular} environment~\cite{LaTeXman}.
Troff user's can use nofill mode:
$$\begin{verbatim}
btex .nf
Population
in millions etex
\end{verbatim}
$$


\subsection{Coordinate Systems}
\label{coords}

The graph macros automatically shift and rescale coordinates from data files,
{\tt gdraw} paths, and {\tt glabel} locations to fit the graph.  Whether the
range of $y$~coordinates is 0.64 to 4.6 or 640,000 to 4,600,000, they
get scaled to fill about 88\% of the height specified in the {\tt begingraph}
statement.  Of course line widths, labels, and plotting symbols are not
rescaled.

% setrange

The {\tt setrange} command controls the shifting and rescaling process by
specifying the minimum and maximum graph coordinates:
$$ \hbox{\tt setrange($\descr{coordinates}$,\,$\descr{coordinates}$)} $$
where
\begin{ctabbing}
$\tt \descr{coordinates} \rightarrow \descr{pair expression}$\\
$\tt \qquad \;|\; \descr{numeric or string expression}\hbox{\tt ,}
        \descr{numeric or string expression}$
\end{ctabbing}
The first \tdescr{coordinates} give $(x_{\rm min},y_{\rm min})$ and the second give
$(x_{\rm max},y_{\rm max})$.  The lines $x=x_{\rm min}$, $x=x_{\rm max}$,
$y=y_{\rm min}$, and $y=y_{\rm max}$ define the rectangular frame around the graph
in Figures \ref{fig1}--\ref{fig3}.  For example, an adding a statement
$$ \hbox{\tt setrange(origin, whatever,\,whatever)} $$
to the input for Figure~\ref{fig3} yields Figure~\ref{fig4}.
The first \tdescr{coordinates} are given by the predefined pair constant
{\tt origin}, and the other coordinates are left unspecified.  Any unknown
value would work as well, but {\tt whatever} is the standard MetaPost
representation for an anonymous unknown value.

\begin{figure}[htp]
$$ \begin{verbatim}
draw begingraph(3in,2in);
 glabel.lft(btex \vbox{\hbox{Population} \hbox{in millions}} etex, OUT);
 glabel.bot(btex Age in years etex, OUT);
 setrange(origin, whatever,whatever);
 gdraw "agepopm.d";
 endgraph;
\end{verbatim}
\atop
\includegraphics{mpgraph-4.mps}
$$
\caption{The 1991 age distribution graph and the input that creates it.}
\label{fig4}
\end{figure}

% strings for big coordinates

Notice that the syntax for {\tt setrange} allows coordinate values to be given
as strings.  Many commands in the graph package allow this option.  It is
provided because the MetaPost language uses fixed point numbers that must be
less than 32768.  This limitation is not as serious as it sounds because good
graph design dictates that coordinate values should be ``of reasonable
magnitude''~\cite{Cleve85,Tufte83}.  If you really want $x$ and $y$
to range from 0 to 1,000,000,
$$ \hbox{\tt setrange(origin, "1e6",\,"1e6")} $$
does the job.  Any fixed or floating point representation is acceptable
as long as the exponent is introduced by the letter ``{\tt e}''.

% setcoords

Coordinate systems need not be linear.  The {\tt setcoords} command allows
either or both axes to have logarithmic spacing:
\begin{ctabbing}
$\tt \descr{coordinate setting} \rightarrow setcoords\hbox{\tt (}
        \descr{coordinate type}\hbox{\tt ,}\,\descr{coordinate type}\hbox{\tt )}$\\
$\tt \descr{coordinate type} \rightarrow
        log \;|\; linear \;|\; \hbox{\tt -}log \;|\; \hbox{\tt -}linear$
\end{ctabbing}
A negative \tdescr{coordinate type} makes $x$ (or $y$) run backwards so it is
largest on the left side (or bottom) of the graph.

Figure~\ref{fig5} graphs execution times for two matrix multiplication algorithms
using
$$ \hbox{\tt setcoords(log,log)} $$
to specify logarithmic spacing on both axes.  The data file {\tt matmul.d} gives
timings for both algorithms:
$$ \hbox to\hsize{\footnotesize\hfil$
\begin{verbatim}
20      .007861  standard MM: size, seconds
30      .022051
40      .050391
60      .15922
80      .4031
120     1.53
160     3.915
240     18.55
320     78.28
480     279.24

20      .006611  Strassen: size, seconds
30      .020820
40      .049219
60      .163281
80      .3975
120     1.3125
160     3.04
240     9.95
320     22.17
480     72.60
\end{verbatim}
\hfil$}
$$
A blank line in a data file ends a data set.  Subsequent {\tt gdraw} commands
access additional data sets by just naming the same data file again.
Since each line gives one $x$~coordinate and one $y$~coordinate, commentary
material after the second data field on a line is ignored.

\begin{figure}[htp]
$$ \mathcenter{\includegraphics{mpgraph-5.mps}}
 \quad
\begin{BVerbatim}[baseline=c]
draw begingraph(2.3in,2in);
 setcoords(log,log);
 glabel.lft(btex Seconds etex,OUT);
 glabel.bot(btex Matrix size etex,
   OUT);
 gdraw "matmul.d" dashed evenly;
 glabel.ulft(btex Standard etex,8);
 gdraw "matmul.d";
 glabel.lrt(btex Strassen etex,7);
 endgraph;
\end{BVerbatim}
$$
\caption{Timings for two matrix multiplication algorithms with the corresponding
        MetaPost input.}
\label{fig5}
\end{figure}

Placing a {\tt setcoords} command between two {\tt gdraw} commands graphs two
functions in different coordinate systems as shown in Figure~\ref{fig6}.
Whenever you give a {\tt setcoords} command, the interpreter examines what has
been drawn, selects appropriate $x$ and $y$ ranges, and scales everything to
fit.  Everything drawn afterward is in  a new coordinate system that need not
have anything in common with the old coordinates unless {\tt setrange} commands
enforce similar coordinate ranges.  For instance, the two {\tt setrange}
commands force both coordinate systems to have $x$ ranging from 80 to~90 and
$y$~starting at 0.

\begin{figure}[htp]
$$ \begin{verbatim}
draw begingraph(6.5cm,4.5cm);
 setrange(80,0, 90,whatever);
 glabel.bot(btex Year etex, OUT);
 glabel.lft(btex \vbox{\hbox{Emissions in} \hbox{thousands of}
   \hbox{metric tons} \hbox{(heavy line)}}etex, OUT);
 gdraw "lead.d" withpen pencircle scaled 1.5pt;
 autogrid(,otick.lft);
 setcoords(linear,linear);
 setrange(80,0, 90,whatever);
 glabel.rt(btex \vbox{\hbox{Micrograms} \hbox{per cubic}
   \hbox{meter of air} \hbox{(thin line)}}etex, OUT);
 gdraw "lead.d";
 autogrid(otick.bot,otick.rt);
 endgraph;
\end{verbatim}
  \atop
\mathcenter{\includegraphics{mpgraph-6.mps}}
$$
\caption{Annual lead emissions and average level at atmospheric monitoring
        stations in the United States.  The MetaPost input is shown above
        the graph.}
\label{fig6}
\end{figure}

% autogrid

When you use multiple coordinate systems, you have to specify where the axis
labels go.  The default is to put tick marks on the bottom and the left side of
the frame using the coordinate system in effect when the {\tt endgraph} command
is interpreted.  Figure~\ref{fig6} uses the
$$ \hbox{\tt autogrid(,otick.lft)} $$
to label the left side of the graph with the $y$~coordinates in effect before
the {\tt setcoords} command.  This suppresses the default axis labels, so another
{\tt autogrid} command is needed to label the bottom and right sides of the
graph using the new coordinate system.  The general syntax is
$$ \hbox{$\tt autogrid\hbox{\tt (}\descr{axis label command}\hbox{\tt ,}\,
        \descr{axis label command}\hbox{\tt )}\ \descr{option list}$}
$$
where
\begin{ctabbing}
$\tt \descr{axis label command} \rightarrow \descr{empty}
        \;|\; \descr{grid or tick}\, \descr{label suffix}$\\
$\tt \descr{grid or tick} \rightarrow grid \;|\; itick \;|\; otick$
\end{ctabbing}
The \tdescr{label suffix} should be {\tt lft}, {\tt rt}, {\tt top},
or {\tt bot}.

The first argument to {\tt autogrid} tells how to label the $x$~axis and the
second argument does the same for~$y$.  An \tdescr{empty} argument suppresses
labeling for that axis.  Otherwise, the \tdescr{label suffix} tells which side
of the graph gets the numeric label.  Be careful to use {\tt bot} or {\tt top}
for the $x$~axis and {\tt lft} or {\tt rt} for the $y$~axis.  Use {\tt otick}
for outward tick marks, {\tt itick} for inward tick marks, and {\tt grid} for
grid lines.  The \tdescr{option list} tells how to draw the tick marks or grid
lines.  Grid lines tend to be a little overpowering, so it is a good idea to
give a {\tt withcolor} option to make them light gray so they do not make the
graph too busy.


\subsection{Explicit Grids and Framing}

% otick, itick, grid, (format)

In case {\tt autogrid} is not flexible enough, axis label commands generate
grid lines or tick marks one at a time.  The syntax is
$$ \descr{grid or tick}\hbox{\tt .}\descr{label suffix}
        \hbox{\tt ($\descr{label format}$,\,$\descr{numeric or string expression}$)}
        \ \descr{option list}
$$
where \tdescr{grid or tick} and \tdescr{label suffix} are as in {\tt autogrid},
and \tdescr{label format} is either a format string like \verb|"%g"| or a
picture containing the typeset numeric label.

The axis label commands use a macro
$$ \hbox{\tt format($
        \descr{format string}$,\,$\descr{numeric or string expression}$)}
$$
to typeset numeric labels.  Full details appear in Section~\ref{formsec},
but when the \tdescr{format string} is \verb|"%g"|, it uses decimal notation
unless the number is large enough or small enough to require scientific notation.

The example in Figure~\ref{fig7} invokes
$$ \hbox{\verb|format("%g",y)|} $$
explicitly so that grid lines can be placed at transformed coordinates.
It defines the transformation ${\tt newy}(y)=y/75+\ln y$ and shows that
this function increases almost linearly.\footnote{The manual~\cite{ho:mp3}
explains how {\tt vardef} defines functions and {\tt mlog} computes logarithms.}
This is a little like using logarithmic $y$-coordinates, except that $y$ is
mapped to $y/75+\ln y$ instead of just $\ln y$.

\begin{figure}[htp]
$$ \begin{verbatim}
vardef newy(expr y) = (256/75)*y + mlog y enddef;
draw begingraph(3in,2in);
 glabel.lft(btex \vbox{\hbox{Population} \hbox{in millions}} etex, OUT);
 path p;
 gdata("timepop.d", $, augment.p($1, newy(Scvnum $2)); );
 gdraw p withpen nullpen;
 for y=5,10,20,50,100,150,200,250:
   grid.lft(format("%g",y), newy(y)) withcolor .85white;
 endfor
 autogrid(grid.bot,) withcolor .85white;
 gdraw p;
 frame.llft;
 endgraph;
\end{verbatim}
   \atop
   \includegraphics{mpgraph-7.mps}
$$
\caption{Population of the United States in millions versus time with the
        population re-expressed as $p/75+\ln p$.  The MetaPost input shown
        above the graph assumes a data file {\tt ttimepop.d} that gives
        (year, $p/75+\ln p$) pairs.}
\label{fig7}
\end{figure}

% frame

Figure~\ref{fig7} uses the command
$$ \hbox{\tt frame.} \descr{label suffix}\ \descr{option list} $$
to draw a special frame around the graph.  In this case the \tdescr{label suffix}
is {\tt llft} to draw just the bottom and left sides of the frame.  Suffixes
{\tt lrt}, {\tt ulft}, and {\tt urt} draw other combinations of two sides;
suffixes {\tt lft}, {\tt rt}, {\tt top}, {\tt bot} draw one side, and \tdescr{empty}
draws the whole frame.  For example
$$ \hbox{\verb|frame dashed evenly|} $$
draws all four sides with dashed lines.  The default four-sided frame is drawn
only when there is no explicit {\tt frame} command.

% auto, (sarith.mp)

To label an axis as {\tt autogrid} does but with the labels transformed
somehow, use
$$ \hbox{{\tt auto.x}\quad or\quad {\tt auto.y}} $$
for positioning tick marks or grid lines.  These macros produce comma-separated
lists for use in {\tt for} loops.  Any $x$ or $y$ values in these lists that
cannot be represented accurately within MetaPost's fixed-point number system
are given as strings.  A standard macro package that is loaded via
$$ \hbox{\tt input sarith}  $$
defines arithmetic operators that work on numbers or strings.  Binary operators
{\tt Sadd}, {\tt Ssub}, {\tt Smul}, and {\tt Sdiv} do addition, subtraction
multiplication, and division.

One possible application is rescaling data.
Figure~\ref{fig4} used a special data file {\tt agepopm.d} that had $y$~values
divided by one million.  This could be avoided by replacing
``{\tt gdraw "agepopm.d"}'' by
$$\begin{verbatim}
gdraw "agepop91.d";
for u=auto.y: otick.lft(format("%g",u Sdiv "1e6"), u); endfor
autogrid(otick.bot,)
\end{verbatim}
$$


\subsection{Processing Data Files}
\label{dfilesec}

% gdata

The most general tool for processing data files is the {\tt gdata} command:
$$ \hbox{\tt gdata(} \descr{string expression} \hbox{\tt,}\, \descr{variable}
        \hbox{\tt,}\, \descr{commands} \hbox{\tt )}
$$
It takes a file name, a variable~$v$, and a list of commands to be executed for
each line of the data file.  The commands are executed with {\tt i} set to the
input line number and strings $v${\tt 1}, $v${\tt 2}, $v${\tt 3}, \ldots\ set
to the input fields on the current line.  A null string marks the end of the
$v$ array.

Using a {\tt glabel} command inside of {\tt gdata} generates a scatter plot
as shown in Figure~\ref{fig8}.  The data file {\tt countries.d} begins
$$\begin{verbatim}
20.910 75.7 US
 1.831 66.7 Alg
\end{verbatim}
$$
where the last field in each line gives the label to be plotted.  Setting
{\tt defaultfont} in the first line of input selects a small font for these
labels.  Without these labels, no {\tt gdata} command would be needed.
Replacing the {\tt gdata} command with
$$ \hbox{\verb|gdraw "countries.d" plot btex$\circ$etex|} $$
would change the abbreviated country names to open circles.

\begin{figure}[htp]
$$\begin{verbatim}
defaultfont:="cmr7";
draw begingraph(3in,2in);
  glabel.lft(btex \vbox{\hbox{Life}\hbox{expectancy}} etex, OUT);
  glabel.bot(btex Per capita G.N.P. (thousands of dollars) etex, OUT);
  setcoords(log,linear);
  gdata("countries.d", s,
    glabel(s3, s1, s2);
  )
  endgraph;
\end{verbatim}
 \atop
 \includegraphics{mpgraph-8.mps}
$$
\caption{A scatter plot and the commands that generated it}
\label{fig8}
\end{figure}

Both {\tt gdraw} and {\tt gdata} ignore an optional initial `\%' on each input
line, parse data fields separated by white space, and stop if they encounter an
input line with no data fields.  Leading percent signs make graph data
look like MetaPost comments so that numeric data can be placed at the beginning
of a MetaPost input file.

% augment

It is often useful to construct one or more paths when reading a data file
with {\tt gdata}.  The {\tt augment} command is designed for this:
$$ \hbox{\tt augment.} \descr{path variable} \hbox{\tt(}\descr{coordinates}\hbox{\tt)}
$$
If the path variable does not have a known value, it becomes a path of length
zero at the given coordinates; otherwise a line segment to the given coordinates
is appended to the path.  The \tdescr{coordinates} may be a pair expression or
any combination of strings and numerics as explained at the beginning of
Section~\ref{coords}.

If a file {\tt timepop.d} gives $t$,~$p$ pairs, {\tt augment} can be used like
this to graph {\tt newy(}$p${\tt)} versus~$t$:
$$\begin{verbatim}
path p;
gdata("timepop.d", s, augment.p(s1, newy(scantokens s2)); );
gdraw p;
\end{verbatim}
$$
(MetaPost's {\tt scantokens} primitive interprets a string as if it were the
contents of an input file.  This finds the numeric value of data field
{\tt s2}.)

% gfill (energy.d)

Figure~\ref{fig9} shows how to use {\tt augment} to read multiple column data
and make multiple paths.  Paths {\tt p2}, {\tt p3}, {\tt p4}, {\tt p5} give
cumulative totals for columns 2 through 5 and pictures {\tt lab2} through
{\tt lab5} give corresponding labels.  The expression
$$ \hbox{\verb|image(unfill bbox lab[j]; draw lab[j])|} $$
executes the given drawing commands and returns the resulting picture:
``{\tt unfill bbox lab[j]}'' puts down a white background and ``{\tt draw
lab[j]}'' puts the label on the background.
The {\tt gfill} command is just like {\tt gdraw}, except it takes a cyclic
path and fills the interior with a solid color.  The color is black unless
a {\tt withcolor} clause specifies another color.
See the manual~\cite{ho:mp3} for
explanations of {\tt for} loops, arrays, colors, and path construction
operators like \verb|--|, {\tt cycle}, and {\tt reverse}.

\begin{figure}[htp]
$$\begin{verbatim}
draw begingraph(3in,2in);
  glabel.lft(btex \vbox{\hbox{Quadrillions}\hbox{of BTU}} etex, OUT);
  path p[];
  numeric t;
  gdata("energy.d", $,
    t:=0; augment.p1($1,0);
    for j=2 upto 5:
       t:=t+scantokens $[j]; augment.p[j]($1,t);
    endfor)
  picture lab[];
  lab2=btex coal etex; lab3=btex crude oil etex;
  lab4=btex natural gas etex; lab5=btex hydroelectric etex;
  for j=5 downto 2:
    gfill p[j]--reverse p[j-1]--cycle withcolor .16j*white;
    glabel.lft(image(unfill bbox lab[j]; draw lab[j]), .7+length p[j]);
  endfor
  endgraph;
\end{verbatim}
 \atop
 \includegraphics{mpgraph-9.mps}
$$
\caption{A graph of U.S. annual energy production
        and the commands that generated it}
\label{fig9}
\end{figure}


\section{Manipulating Big Numbers}
\label{nummac}

MetaPost inherits a fixed-point number system from Knuth's \MF~\cite{kn:d}.
Numbers are expressed in multiples of $2^{-16}$ and they must have absolute
value less than 32768.  Knuth chose this system because it is perfectly adequate
for font design, and it guaranteed to give identical results on all types of
computers.  Fixed-point numbers are seldom a problem in MetaPost because all
computations are based on coordinates that are limited by the size the paper on
which the output is to be printed.  This does not hold for the input data in a
graph-drawing application.  Although graphs look best when coordinate axes are
labeled with numbers of reasonable magnitude, the strict limits of fixed-point
arithmetic would be inconvenient.

% Sadd, Ssub, Smul, Sdiv

A simple way to handle large numbers is to include the line
$$ \hbox{\tt input sarith} $$
and then use binary operators {\tt Sadd}, {\tt Ssub}, {\tt Smul}, and {\tt Sdiv}
in place of \verb|+|, \verb|-|, \verb|*|, and \verb|/|.  These operators are
inefficient but very flexible.  They accept numbers or strings and return
strings in exponential notation with the exponent marked by ``{\tt e}'';
e.g., \verb|"6.7e-11"| means $6.7\times10^{-11}$.

% Sabs, Sleq, Sneq

The unary operator\footnote{The argument to a unary operator need not be
parenthesized unless it is an expression involving binary operators.}
$$ {\tt Sabs}\ \descr{string} $$
finds a string the represents the absolute value.  Binary operators {\tt Sleq}
and {\tt Sneq} perform numeric comparisons on strings and return boolean
results.

% Scvnum

The operation
$$ {\tt Scvnum}\ \descr{string} $$
finds the numeric value for a string if this can be done without overflowing
MetaPost's fixed-point number system.  If the string does not contain
``{\tt e}'', it is much more efficient to use the primitive operation
$$ {\tt scantokens}\ \descr{string} $$

% Mten

The above operators are based on a low-level package that manipulates numbers
in ``{\tt Mlog} form.''  A number $x$ in {\tt Mlog} form represents
$$ \mu^{2^{16}x}, \quad {\rm where\ } \mu=-e^{2^{-24}}. $$
Any value between $1.61\times10^{-28}$ and $3.88\times10^{55}$ can be
represented this way.  (There is a constant {\tt Mten} such that $k*{\tt Mten}$
represents $10^k$ for any integer~$k$ in the interval $[-29,55]$.)

% Mreadpath, Gpaths

The main reason for mentioning {\tt Mlog} form is that it allows graph data
to be manipulated as a MetaPost path.  The function
$$ \hbox{\tt Mreadpath($\descr{file name}$)} $$
reads a data file and returns a path where all the coordinates are in
{\tt Mlog} form.  An internal variable {\tt Gpaths} determines whether
{\tt gdraw} and {\tt gfill} expect paths to be given in {\tt Mlog} form.
For example, this graphs the data in {\tt agepop91.d} with $y$ coordinates
divided by one million:
$$\begin{verbatim}
interim Gpaths:=log;
gdraw Mreadpath("agepop91.d") shifted (0,-6*Mten);
\end{verbatim}
$$


\section{Typesetting Numbers}
\label{formsec}

% format

The graph package needs to compute axis labels and then typeset them.
The macro
$$ \hbox{\tt format($\descr{string expression}$,\,%
        $\descr{numeric or string expression}$)} $$
does this.  You must first {\tt input graph} or {\tt input format} to load the
macro file.  The macro takes a format string and a number to typeset and returns
a picture containing the typeset result.  Thus
$$ \hbox{\verb|format("%g",2+2)|}\quad {\rm yields}\quad \includegraphics{mpgraph-10.mps} $$
and
$$ \hbox{\verb|format("%3g","6.022e23")|}
        \quad {\rm yields}\quad \includegraphics{mpgraph-11.mps}
$$

A format string consists of
\begin{itemize}
\item an optional initial string not containing a percent sign,
\item a percent sign,
\item an optional numeric precision $p$,
\item one of the conversion letters {\tt e}, {\tt f}, {\tt g}, {\tt G},
\item an optional final string $\beta$.
\end{itemize}
The initial and final strings are typeset in the default font (usually
{\tt cmr10}), and the typeset number is placed between them.  For the {\tt e}
and {\tt g} formats, the precision~$p$ is the number of significant digits
allowed after rounding; for {\tt f} and {\tt G}, the number is rounded to the
nearest multiple of $10^{-p}$.  If the precision is not specified, the default
is $p=3$.  The {\tt e} format always uses scientific
notation and the {\tt f} format uses ordinary decimal notation but reverts to
scientific notation if the number is at least 10000.  The {\tt g} and {\tt G}
formats also revert to scientific notation for non-zero numbers of magnitude
less than 0.001.

% init_numbers

The {\tt format} macro needs a set of templates to determine what font to use,
how to position the exponent, etc.  The templates are normally initialized
automatically, but it is possible to set them explicitly by passing five picture
expressions to {\tt init\_numbers}.  For instance, the default definition for
\TeX\ users is
$$\begin{verbatim}
init_numbers(btex$-$etex, btex$1$etex, btex${\times}10$etex,
    btex${}^-$etex, btex${}^2$etex)
\end{verbatim}
$$
The first argument tells how to typeset a leading minus sign;
the second argument is an example of a 1-digit mantissa;
third comes whatever to put after the mantissa in scientific notation;
next come a leading minus sign for the exponent and a sample 1-digit exponent.

% Fe_plus, Fe_base

Picture variable \verb|Fe_plus| gives a leading plus sign for positive numbers,
and \verb|Fe_base| gives whatever should precede the exponent when typesetting
a power of ten.  Calling \verb|init_numbers| initializes \verb|Fe_plus| to an
empty picture and constructs \verb|Fe_base| from its second and third arguments.



\section{Conclusion}
\label{concl}

The graph package makes it convenient to generate graphs from within the MetaPost
language.  The primary benefits are the power of the MetaPost language and its
ability to interact with \TeX\ or troff for typesetting labels.  Typeset labels
can be stored in picture variables and manipulated in various ways such measuring
the bounding box and providing a white background.

We have seen how to generate shaded regions and control line width, color, and
styles of dashed lines.  Numerous other variations are possible.
The full MetaPost language~\cite{ho:mp3} provides many other potentially useful
features.  It also has enough computing power to be useful for generating and
processing data.



\appendix
\section{Summary of the Graph Package}
\label{summsec}

% Not described elsewhere: gdrawarrow, gdrawdblarrow, Gmarks, Gminlog, Autoform

In the following descriptions, italic letters such as $w$ and $h$ denote
expression parameters and words in angle brackets denote other syntactic
elements.  Unless specified otherwise, expression parameters can be either
numerics or strings.  An \tdescr{option list} is a list of drawing options such
as {\tt withcolor .5white} or {\tt dashed evenly};
a \tdescr{label suffix} is one of {\tt lft}, {\tt rt}, {\tt top}, {\tt bot},
{\tt ulft}, {\tt urt}, {\tt llft}, {\tt lrt}.

\subsection{Graph Administration}

\begin{description}
\item[{\tt begingraph($w$,$h$)}]
        Begin a new graph with the frame width and height given by numeric
        parameters $w$ and $h$.
\item[{\tt endgraph}]
        End a graph and return the resulting picture.
\item[{\tt setcoords($t_x$,\,$t_y$)}]
        Set up a new coordinate system as specified by numeric flags $t_x$,
        $t_y$.  Flag values are $\pm{\tt linear}$ and $\pm{\tt log}$.
\item[{\tt setrange($\descr{coordinates}$,\,$\descr{coordinates}$)}]
        Set the lower and upper limits for the current coordinate system.
        Each \tdescr{coordinates} can be a single pair expression or two
        numeric or string expressions.
\end{description}

\subsection{Drawing and Labeling}

All of the drawing and labeling commands can be followed by an
\tdescr{option list}.  In addition to the usual MetaPost drawing options, the
list can contain a {\tt plot} \tdescr{picture} clause to plot a specified
picture at each data point.

The drawing and labeling commands are closely related to a set of similarly
named commands in plain MetaPost.  The {\tt gdrawarrow} and {\tt gdrawdblarrow}
commands are included to maintain this relationship.

\begin{description}
\item[{\tt gdotlabel.$\descr{label suffix}$($p$,\,$\descr{location}$)}]
        This is like {\tt glabel} except it also puts a dot at the location
        being labeled.
\item[{\tt gdraw $p$}]
        Draw path $p$, or if $p$ is a string, read coordinate pairs from
        file~$p$ and draw a polygonal line through them.
\item[{\tt gdrawarrow $p$}]
        This is like {\tt dgraw} $p$ except it adds an arrowhead at the end of
        the path.
\item[{\tt gdrawdblarrow $p$}]
        This is like {\tt dgraw} $p$ except it adds an arrowheads at each end of
        the path.
\item[{\tt gfill $p$}]
        Fill cyclic path~$p$ or read coordinates from the file named by
        string~$p$ and fill the resulting polygonal outline.
\item[{\tt glabel.$\descr{label suffix}$($p$,\,$\descr{location}$)}]
        If $p$ is not a picture, it should be a string.  Typeset it using
        {\tt defaultfont}, then place it near the given location and offset as
        specified by the \tdescr{label suffix}.  The \tdescr{location} can be
        $x$~and $y$ coordinates, a pair giving $x$~and $y$, a numerc value giving
        a time on the last path drawn, or {\tt OUT} to label the outside of the
        graph.
\end{description}

\subsection{Grids, Tick Marks, and Framing}

\begin{description}
\item[{\tt auto.}$\descr{{\tt x} or {\tt y}}$]
        Generate default $x$ or $y$ coordinates for tick marks.
\item[{\tt autogrid($\descr{axis label command}$,\,$\descr{axis label command}$)}]
        Draw default axis labels using the specified commands for the $x$ and
        $y$ axes.  An \tdescr{axis label command} may be \tdescr{empty} or it
        may be {\tt itick}, {\tt otick}, or {\tt grid} followed by a
        \tdescr{label suffix}.
\item[{\tt frame.}$\descr{label suffix}$\ $\descr{option list}$]
        Draw a frame around the graph, or draw the part of the frame specified
        by the \tdescr{label suffix}.
\item[{\tt grid.}$\descr{label suffix}$($f$,$z$)]
        Draw a grid line across the graph from the side specified by the
        \tdescr{label suffix}, and label it there using format string~$f$ and
        coordinate value~$z$.  If $f$ is a picture, it gives the label.
\item[{\tt itick.}$\descr{label suffix}$($f$,$z$)]
        This is like {\tt grid} except it draws an inward tick mark.
\item[{\tt otick.}$\descr{label suffix}$($f$,$z$)]
        This is like {\tt grid} except it draws an outward tick mark.
\end{description}

\subsection{Miscellaneous Commands}

\begin{description}
\item[{\tt augment.$\descr{variable}$($\descr{coordinates}$)}]
        Append \tdescr{coordinates} to the path stored in \tdescr{variable}.
\item[{\tt format($f$,\,$x$)}]
        Typeset $x$ according to format string~$f$ and return the resulting
        picture.
\item[{\tt gdata($f$,\,$\descr{variable}$,\,$\descr{commands}$)}]
        Read the file named by string~$f$ and execute \tdescr{commands} for each
        input line using the \tdescr{variable} as an array to store data fields.
\item[{\tt init\_numbers($s$,\,$m$,\,$x$,\,$t$,\,$e$)}]
        Provide five pictures as templates for future {\tt format} operations:
        $s$ is a leading minus; $m$ is a sample mantissa; $x$ follows the
        mantissa; $t$ is a leading minus for the exponent~$e$.
\item[{\tt Mreadpath($f$)}]
        Read a path for the data file named by string~$f$ and return it in
        ``{\tt Mlog} form''.
\end{description}

\subsection{Arithmetic on Numeric Strings}

It is necessary to {\tt input sarith} before using the following macros:
\begin{description}
\item[{\tt Sabs $x$}]
        Compute $|x|$ and return a numeric string.
\item[{\tt $x$ Sadd $y$}]
        Compute $x+y$ and return a numeric string.
\item[{\tt Scvnum $x$}]
        Return the numeric value for string $x$.
\item[{\tt $x$ Sdiv $y$}]
        Compute $x/y$ and return a numeric string.
\item[{\tt $x$ Sleq $y$}]
        Return the boolean result of the comparison $x\leq y$.
\item[{\tt $x$ Smul $y$}]
        Compute $x*y$ and return a numeric string.
\item[{\tt $x$ Sneq $y$}]
        Return the boolean result of the comparison $x\neq y$.
\item[{\tt $x$ Ssub $y$}]
        Compute $x-y$ and return a numeric string.
\end{description}

\subsection{Internal Variables and Constants}

\begin{description}
\item[{\tt Autoform}]
        Format string used by {\tt autogrid}.  Default: \verb|"%g"|.
\item[{\tt Fe\_base}]
        What precedes the exponent when typesetting a power of ten.
\item[{\tt Fe\_plus}]
        Picture of the leading plus sign for positive exponents.
\item[{\tt Gmarks}]
        Minimum number of tick marks per axis for {\tt auto} and {\tt autogrid}.
        Default: 4.
\item[{\tt Gminlog}]
        Minimum largest/smallest ratio for logarithmic spacing with {\tt auto}
        and {\tt autogrid}.  Default: 3.0.
\item[{\tt Gpaths}]
        Code for coordinates used in {\tt gdraw} and {\tt gfill} paths:
        {\tt linear} for standard form, {log} for ``{\tt Mlog} form''.
\item[{\tt Mten}]
        The ``{\tt Mlog} form'' for 10.0
\end{description}


\bibliographystyle{plain}
\bibliography{mpgraph}

\end{document}



% Copyright 1990 - 1995 by AT&T Bell Laboratories.

% Permission to use, copy, modify, and distribute this software
% and its documentation for any purpose and without fee is hereby
% granted, provided that the above copyright notice appear in all
% copies and that both that the copyright notice and this
% permission notice and warranty disclaimer appear in supporting
% documentation, and that the names of AT&T Bell Laboratories or
% any of its entities not be used in advertising or publicity
% pertaining to distribution of the software without specific,
% written prior permission.

% AT&T disclaims all warranties with regard to this software,
% including all implied warranties of merchantability and fitness.
% In no event shall AT&T be liable for any special, indirect or
% consequential damages or any damages whatsoever resulting from
% loss of use, data or profits, whether in an action of contract,
% negligence or other tortious action, arising out of or in
% connection with the use or performance of this software.

% In addition, John Hobby, the original author of MetaPost and this
% manual, makes the following requests:
% - I request that it remain clear that I am the author of
%   "A User's Manual for MetaPost" and "Drawing Graphs with MetaPost".
% - I request to be consulted before significant changes are made.