diff options
Diffstat (limited to 'systems/doc/metapost/source-manual/mpgraph.tex')
-rw-r--r-- | systems/doc/metapost/source-manual/mpgraph.tex | 1044 |
1 files changed, 1044 insertions, 0 deletions
diff --git a/systems/doc/metapost/source-manual/mpgraph.tex b/systems/doc/metapost/source-manual/mpgraph.tex new file mode 100644 index 0000000000..759c6e8506 --- /dev/null +++ b/systems/doc/metapost/source-manual/mpgraph.tex @@ -0,0 +1,1044 @@ +% $Id: mpgraph.tex 870 2009-03-06 11:04:56Z stephanhennig $ +% MetaPost graph doc, by John Hobby. License at end. +\listfiles +\RequirePackage{ifpdf} +\ifpdf +\ifnum\pdftexversion<140 +\else +\pdfminorversion=5 +\pdfobjcompresslevel=1% Use compressed object streams. +\fi +\RequirePackage{cmap} +\fi +\documentclass{article} % article is NOT the original style +\usepackage[T1]{fontenc} +\usepackage{lmodern} +\usepackage{textcomp} +\usepackage{mflogo} +\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 + +\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} +\ifpdf +\pdfmapfile{=cm2lm.map}% replace CM by LM in figures +\else +\DeclareGraphicsExtensions{.mps} +\DeclareGraphicsRule{mps}{eps}{*}{} +\usepackage{breakurl} +\fi + + +\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, +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. + +%%% Local Variables: +%%% mode: latex +%%% TeX-PDF-mode: t +%%% TeX-master: t +%%% End: |