diff options
Diffstat (limited to 'Master/texmf-dist/doc/metapost/base/source/mpgraph.tex')
-rw-r--r-- | Master/texmf-dist/doc/metapost/base/source/mpgraph.tex | 1109 |
1 files changed, 1109 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/metapost/base/source/mpgraph.tex b/Master/texmf-dist/doc/metapost/base/source/mpgraph.tex new file mode 100644 index 00000000000..104b70bf917 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source/mpgraph.tex @@ -0,0 +1,1109 @@ +\documentclass{article} % article is NOT the original style +\usepackage{makeidx} +\usepackage{fancyvrb} +\usepackage{ctabbing} +\RecustomVerbatimEnvironment{verbatim}{BVerbatim}{baseline=c} +\usepackage{epsf} +\usepackage[textwidth=6in,textheight=8.75in]{geometry} + +\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{rpsyr 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} + + + +\begin{document} + \maketitle + \begin{abstract} \myabstract \end{abstract} + \ifx\keywords\undefined \else + \begin{keywords} \mykeywords \end{keywords} + \fi + + +\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, and Appendix~\ref{nfeats} describes some recent additions to the MetaPost +language that have not been presented elsewhere. + + +\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] +$$ \epsfbox{mpgraph.1} $$ +\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] +$$ \epsfbox{mpgraph.2} $$ +\caption{The 1991 age distribution plotted with bullets} +\label{fig2} +\end{figure} + +% 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] +$$ \epsfbox{mpgraph.3} $$ +\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 +\epsfbox{mpgraph.4} +$$ +\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{\epsfbox{mpgraph.5}} + \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{\epsfbox{mpgraph.6}} +$$ +\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); + gdraw "ttimepop.d"; + 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; + frame.llft; + endgraph; +\end{verbatim} + \atop + \epsfbox{mpgraph.7} +$$ +\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 + \epsfbox{mpgraph.8} +$$ +\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 + \epsfbox{mpgraph.9} +$$ +\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 \epsfbox{mpgraph.10} $$ +and +$$ \hbox{\verb|format("%3g","6.022e23")|} + \quad {\rm yields}\quad \epsfbox{mpgraph.11} +$$ + +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} + + + +\section{New Language Features} +\label{nfeats} + +The {\tt graph.mp} macros and the arithmetic routines in {\tt marith.mp} +and {\tt sarith.mp} use various language features that were introduced +in Version 0.60 of the MetaPost language. We summarize these features here +because they are not covered in existing documentation \cite{ho:mp3,ho:mp4}. +Also new is the built-in macro +$$ \hbox{\tt image($\descr{drawing commands}$)} $$ +that was used in Section~\ref{dfilesec} to find the picture produced by a +sequence of drawing commands. + +\subsection{Reading and Writing Files} + +A new operator +$$ {\tt readfrom}\ \descr{file name} $$ +returns a string giving the next line of input from the named file. The +\tdescr{file name} can be any primary expression of type string. If the file +has ended or cannot be read, the result is a string consisting of a single +null character. The preloaded {\tt plain} macro package introduces the name +{\tt EOF} for this string. After {\tt readfrom} has returned {\tt EOF}, +additional reads from the same file cause the file to be reread from the +start. + +The opposite of {\tt readfrom} is the command +$$ {\tt write}\ \descr{string expression}\ {\tt to} \descr{file name} $$ +This writes a line of text to the specified output file, opening the file +first if necessary. All such files are closed automatically when the +program terminates. They can also be closed explicitly by using {\tt EOF} +as the \tdescr{string expression}. The only way to tell if a {\tt write} +command has succeeded is to close the file and use {\tt readfrom} to look +at it. + +\subsection{Extracting Information from Pictures} + +MetaPost pictures are composed of stroked lines, filled outlines, pieces +of typeset text, clipping paths, and {\tt setbounds} paths. (A {\tt setbounds} +path gives an artificial bounding box as is needed for \TeX\ output.) +A picture can have many components of each type. They can be accessed via +an iteration of the form +$$ {\tt for}\ \descr{symbolic token}\ {\tt within}\ + \descr{picture expression}\hbox{\tt:}\ \descr{loop text}\ {\tt endfor} +$$ +The \tdescr{loop text} can be anything that is balanced with respect to +{\tt for} and {\tt endfor}. The \tdescr{symbolic token} is a loop variable that +scans the components of the picture in the order in which they were drawn. The +component for a clipping or {\tt setbounds} path includes everything the path +applies to. Thus if a single clipping or {\tt setbounds} path applies to +everything in the \tdescr{picture expression}, the whole picture could be +thought of as one big component. In order to make the contents of such a picture +accessible, the {\tt for}\ldots{\tt within} iteration ignores the enclosing +clipping or {\tt setbounds} path in this case. + +Once the {\tt for}\ldots{\tt within} iteration has found a picture component, +there are numerous operators for identifying it and extracting relevant +information. The operator +$$ {\tt stroked}\ \descr{primary expression} $$ +tests whether the expression is a known picture whose first component is a +stroked line. Similarly, the {\tt filled} and {\tt textual} operators +return {\tt true} if the first component is a filled outline or a piece of +typeset text. The {\tt clipped} and {\tt bounded} operators test whether +the argument is a known picture that starts with a clipping path or a +{\tt setbounds} path. This is true if the first component is clipped or +bounded or if the entire picture is enclosed in a clipping or {\tt setbounds} +path. + +There are also numerous part extraction operators that test the first component +of a picture. If {\tt p} is a picture and {\tt stroked p} is true, +{\tt pathpart p} is the path describing the line that got stroked, +{\tt penpart p} is the pen that was used, {\tt dashpart p} is the dash +pattern, and the color is +$$ \hbox{\tt (redpart p, greenpart p, bluepart p)} $$ +If the line is not dashed, {\tt dashpart p} returns an empty picture. + +The same part extraction operators work when {\tt filled p} is true, except +that {\tt dashpart p} is not meaningful in that case. For text components, +{\tt textual p} is true, {\tt textpart p} gives the text that got +typeset, {\tt fontpart p} gives the font that was used, and {\tt xpart~p}, +{\tt ypart~p}, {\tt xxpart~p}, {\tt xypart~p}, {\tt yxpart~p}, {\tt yypart~p} +tell how the text has been shifted, rotated, and scaled. The {\tt redpart}, +{\tt greenpart}, and {\tt bluepart} operators also work for text components. + +When {\tt clipped p} or {\tt bounded p} is true, {\tt pathpart p} gives the +clipping or {\tt setbounds} path and the other part extraction operators are +not meaningful. Such non-meaningful part extractions do not generate +errors---they return null values instead: +the trivial path {\tt (0,0)} for {\tt pathpart}, +{\tt nullpen} for {\tt penpart}, +an empty picture for {\tt dashpart}, +zero for {\tt redpart}, {\tt greenpart}, {\tt bluepart}, +and the null string for {\tt textpart} or {\tt fontpart}. + +One final operator for extracting information from a picture is +$$ {\tt length}\ \descr{picture primary} $$ +This returns the number of components that a {\tt for}\ldots {\tt within} +iteration would find. + +\subsection{Other New Features} + +The {\tt marith.mp} and {\tt sarith.mp} packages use numbers of magnitude +4096 more. Since such numbers can cause overflow problems in MetaPost's +linear equation solving and path fitting algorithms, they are normally +allowed only as intermediate results. This limitation is removed when +the internal variable {\tt warningcheck} is zero. In earlier versions +of MetaPost, the limitation could be removed for variables but explicit +constants were always restricted to be less than 4096. + +For completeness, we also mention one other new feature of MetaPost +Version 0.60. When \TeX\ material is included in a picture via the +{\tt btex}\ldots{\tt etex} feature, the thickness of horizontal and +vertical rules gets rounded to exactly the right number of pixels; i.e., +interpreting MetaPost output according to the PostScript\regmark\ scan +conversion rules~\cite{ad:red} makes the pixel width equal to the ceiling +of the unrounded width. In fact, a similar relationship holds for all line +widths. The generated PostScript sets line widths by first transforming +to device coordinates and rounding appropriately. + + + + + + +\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. |