\documentclass{article}
\usepackage{listings}
\usepackage{color}
\usepackage{epsfig}

\definecolor{orange}{rgb}{1,0.5,0}
\definecolor{bluegreen}{rgb}{0,.6,.6}
\definecolor{purple}{rgb}{1,0,1}

%\DeclareGraphicsRule{*}{mps}{*}{}
\begin{document}
\title{The Matlab MetaPost Package \\
--- {\tt matlab} style data plotting with {\tt mpgraph}}
\author{Yang Yang\\
{\tt yangyang@juggler.ucsd.edu}}

\section{Introduction}
{\tt matlab.mp} is a MetaPost package for  plotting out 2-D data. This
is a common task for any scientists or engineers. The most frequently
used tool for doing such tasks are probably {\sf Gnuplot} and {\sf
Matlab}. But I have not been very satisfied with the plotting quality
of either. {\sf Gnuplot} is fast, versatile, and you can choose
between several line styles/widths, but the available line styles are largely
hard-coded into {\sf Gnuplot}, and not very beautiful. {\sf Matlab}
generates better plots, but one particular problem with {\sf Matlab}
made me decided to create something that suits me needs: if you need
to plot a thick dotted line in {\sf Matlab}, the seperation distance
between dots along the line stays {\em constant}, so the line 
looks like a ``railroad track'', instead of a dotted line.  

Another choice for plotting data is the {\tt mpgraph} MetaPost
package. The ``weakness'' of this package  is that its default style
does not look like {\sf Matlab} (because I am accustomed to {\sf
Matlab} style). Plus, the usage of {\tt mpgraph} is not as easy as
{\sf Matlab}. Then I decided to integrate the rich plotting ability
of {\tt mpgraph} with the ease of use of {\sf Matlab}.



\section{Quick Usage}
The process of plotting a data plot consists of roughly 3 steps:
(1) read in the data from a data source file. (2) plotting out the
data, possibly specifying desired line styles. (3) plotting
``decorations'', i.e. legends, axis labels, grids, etc.  Since we use
{\tt mpgraph} package, steps (2) and (3) should appear within the {\tt
begingraph}/{\tt endgraph} construct.

Here is a sample file {\tt simple.mp} that uses of {\tt matlab.mp}:
%
%
%
\input lstmp
\begin{lstlisting}[frame=single]
input matlab.mp
prologues:=0;
beginfig(1)
%begin a matlab data plot
begingrf(5in,4in);
% read in column 1 of data file "sample_data"
% and store it as the 0th "data vector" in our repository
rdata("sample_data", 1);
% read in column 2 of data file "sample_data"
% and store it as the 1st "data vector" in our repository
rdata("sample_data", 2);
% plot out data, using vector 0 as X values, and vector 1 as Y values
% well, we have to make sure that the two vectors have the same
% lengths
mtplot("0 1");
ylabel("sample Y label $\alpha$");
xlabel("sample X label {\bf Bold} and {\it italic} ");
% do the post-processing
finishgrf;
legend(3, 3, "\bf column 1 and 2 of sample\_file");
endfig;
end
\end{lstlisting}
%
%
{\tt sample\_data} is a text file containing columns of numbers.
Both files can be found in the {\tt examples} directory of the
package. That directory also contains a Makefile to generate the
resulting {\tt simple.1} eps file.

\begin{figure}[b]
\centering
\epsfig{file=simple.1,width=.6\columnwidth}
\caption{simple graph}
\end{figure}



\section{More Details}
Now we show in more detail how to draw a data plot. First we call
{\tt draw begingrf(width,height)}, just as when using {\tt mpgrah}. 
In fact, {\tt begingrf} just calls {\tt begingraph}, and set a few
default style parameters. Then we read in data from external data
files by {\tt rdata("file name", column\_index)}. So each call of
rdata only reads in one column of data, which is stored into an
internal vector, indexed from 0 upwards.

Then we actually plot out the data by calling {\tt mtplot("X Y
.....")}. The parameters to this macro are all put into the same
string, so the implementation can be easier. Parameters are seperated
by space in the string. There are two required parameters: the column
index of the data vector to be used as X coordinates, and that for Y.
The remaining parameters are used to specify line styles. We have {\bf
4 categories of line styles}: widths, color, marker shape, and line
pattern (dotted, dashed, etc). Widths are specified by "{\tt
linewidth}{\bf n}", where {\bf n} is a number giving the linewidth in
{\tt pt}. Color specification is "{\tt c}{\bf x}", where x is "{\tt
k|r|g|b|y|o|p}" for black, red, green, blue, yellow, orange, and
purple, respectively. Marker shape is "{\tt m}{\bf x}", where x is
{\tt o|x|*|d|s} for circle, cross, star, diamond, and square. Line
patterns are  "{\tt solid, dash, dot, dashdot,
dddash}" (for dot dot dash) and "{\tt dddot}" (for dash dash dot).
If you do not specify line styles, each newly plotted line is
automatically assigned a new style.



Finally we can plot out the legends, by calling {\tt legend}.
  The first parameter gives X position, 1,2,3 corresponds to left,
  center, and right. Similarly, 1,2,3 for the second parameter
  corresponds to bottom, middle, and top. Axis labels are printed
  out by {\tt xlabel(s), ylabel(x)}, where {\tt s} is just a
  string. Since we use the {\tt latexmp} package for strings,
  you can use any valid latex constructs for the legends and labels.



\begin{figure}
\centering
\epsfig{file=example.1,width=.6\columnwidth}
\caption{Full feature  graph}
\end{figure}



\end{document}