path: root/graphics/pstricks/contrib/pst-2dplot/pst-2dplot-doc.tex

%%====================================
%% This is help file for pst-2dplot
%% Farshid Delgosha
%% 12/23/2008
%%====================================

\documentclass[10pt]{article}

\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\usepackage[cmex10]{amsmath}
\usepackage[table]{xcolor}
\usepackage{xspace}
\usepackage{array}
\usepackage[bf,labelsep=period]{caption}
\usepackage[margin=1in,dvips,includemp,reversemp,marginparwidth=.85in,marginparsep=0in]{geometry}
\usepackage{pst-2dplot}
\usepackage{pst-node}
\usepackage{showexpl}
\lstset{explpreset={numbers=left,numberstyle=\tiny,numbersep=.5em},width=6cm,%
basicstyle=\ttfamily\footnotesize,rframe=,frame=single,backgroundcolor=\color{orange!30}}

\setlength{\parskip}{.5\baselineskip}

%%=== new macros ====================================================
\def\package{\texttt{pst-2dplot}\xspace}
\def\CMD#1{{\ttfamily\textbackslash #1}}
\def\xyCoor#1{\texttt{($x_{#1}$,$y_{#1}$)}}
\def\margintext#1{\marginpar{\texttt{\small#1}}}
%
\newenvironment{syntax}{%
\begin{tabbing}%
\hspace{2cm}\=\hspace{1cm}\=\hspace{1cm}\=\kill%
}
{\end{tabbing}}
%
\def\xdashline(#1,#2)#3#4{%
\psset{linecolor=#3}%
\psline[linestyle=dashed](0,-#2)(#1,-#2)%
\rput(#1,0){\psline[arrows=|<-](0,0)(0,.5)}%
\rput(#1,-#2){\psline[arrows=|<-](0,0)(0,-.5)}%
\rput[l]{90}(#1,.65){\textcolor{#3}{\texttt{#4}}}%
}
%
\def\ydashline(#1,#2)#3#4{%
\psset{linecolor=#3}%
\psline[linestyle=dashed](-#1,0)(-#1,#2)%
\rput(0,#2){\psline[arrows=|<-](0,0)(.5,0)}%
\rput(-#1,#2){\psline[arrows=|<-](0,0)(-.5,0)}%
\rput[l](.65,#2){\textcolor{#3}{\texttt{#4}}}%
}
%%===================================================================



%%=== data files ====================================================
\begin{filecontents*}{data1.dat}
[0.0]   [0.0]
[0.1]   [0.1]
[0.2]   [0.1]
[0.3]   [0.2]
[0.4]   [0.2]
[0.5]   [0.4]
[0.6]   [0.5]
[0.7]   [0.8]
[0.8]   [0.9]
[0.9]   [1.0]
[1.0]   [0.2]
\end{filecontents*}

\begin{filecontents*}{data2.dat}
[0.0]   [0.8]
[0.1]   [0.9]
[0.2]   [1.0]
[0.3]   [0.8]
[0.4]   [0.7]
[0.5]   [0.5]
[0.6]   [0.3]
[0.7]   [0.2]
[0.8]   [0.1]
[0.9]   [0.2]
[1.0]   [0.3]
\end{filecontents*}

\begin{filecontents*}{data3.dat}
[0.0]   [1.0000000]
[0.1]   [0.6909830]
[0.2]   [0.4122150]
[0.3]   [0.1909830]
[0.4]   [0.0489435]
[0.5]   [0.0000000]
[0.6]   [0.0489435]
[0.7]   [0.1909830]
[0.8]   [0.4122150]
[0.9]   [0.6909830]
[1.0]   [1.0000000]
[1.1]   [1.3090200]
[1.2]   [1.5877900]
[1.3]   [1.8090200]
[1.4]   [1.9510600]
[1.5]   [2.0000000]
[1.6]   [1.9510600]
[1.7]   [1.8090200]
[1.8]   [1.5877900]
[1.9]   [1.3090200]
[2.0]   [1.0000000]
\end{filecontents*}
%%===================================================================




\title{The \package Package \\ {\large (version 1.5)}}
\author{Farshid Delgosha \\ \texttt{fdelgosha@gmail.com}}
\date{26 December, 2008}




\begin{document}

\maketitle




\section{Introduction}

This document introduces the package \package that is an easy-to-use and intuitive tool for drawing two-dimensional plots in \LaTeX{} documents. The main environment introduced by \package is \texttt{pstgraph} that draws grid lines, tag numbers, and labels on both axes. I have to mention that there are more features that I am planning to add. Nevertheless, I felt that the current version is still useful.

To use this package, add the following command to the preamble of your document.
\begin{syntax}
\>\CMD{usepackage\{pst-2dplot\}}
\end{syntax}

The syntax of the \texttt{pstgreaph} \margintext{pstgraph} environment is as follows.
\begin{syntax}
\>\CMD{begin\{pstgraph\}[\textrm{\textit{key}=\textit{value}}]\xyCoor{0}} \\
\>\>$\vdots$ \\
\>\CMD{end\{pstgraph\}}
\end{syntax}
As depicted in Figure~\ref{fig:pstgraph}, the \texttt{pstgraph} environment draws a box of side lengths $x_0$ and $y_0$.
%%===============================================================================
\begin{figure}[ht!]
\centering
\psset{xunit=1.25cm,yunit=8mm}
\begin{pspicture}[showgrid=false](-2,-2)(5.5,6)
%
\multido{\nx=0+1,\rl=0+.25}{5}{%
\rput(\nx,0){\psline[linecolor=gray](0,-.25)(0,4)}%
\rput[t](\nx,-.75){$\rl$}}
%
\multido{\ny=0+1,\rl=0+.25}{5}{%
\rput(0,\ny){\psline[linecolor=gray](-.25,0)(4,0)}%
\rput[r](-.75,\ny){$\rl$}}
%
\psframe(0,0)(4,4)
%
\rput[t](2,-1.65){\textit{x label}}
\rput[b]{90}(-1.75,2){\textit{y label}}
%
\dotnode[linecolor=red](0,0){org}
\dotnode[linecolor=red](4,4){xy0}
\nput{225}{org}{\textcolor{red}{$(0,0)$}}
\nput{45}{xy0}{\textcolor{red}{$(x_0,y_0)$}}
%
\psset{linewidth=.6pt,arrowinset=.25,arrowsize=.125}
\xdashline(4.35,.25){blue}{xticksize}
\xdashline(4.7,.75){orange}{xtagsep}
\xdashline(5.05,1.65){teal}{xlabelsep}
%
\ydashline(.25,4.4){blue}{yticksize}
\ydashline(.75,5){orange}{ytagsep}
\ydashline(1.75,5.6){teal}{ylabelsep}
%
\psset{linecolor=red,linestyle=dashed,arrows=<->}
\psline(0,1.5)(4,1.5)
\rput*(1.5,1.5){\textcolor{red}{$x_0$}}
\psline(2.5,0)(2.5,4)
\rput*(2.5,2.5){\textcolor{red}{$y_0$}}
%
\end{pspicture}
%
\caption{\texttt{pstgraph} environment}
\label{fig:pstgraph}
\end{figure}
%%===============================================================================
The coordinates of the lower left corner and upper right corner of the box are $(0,0)$ and $(x_0,y_0)$, respectively. Keys of the \texttt{pstgraph} environment can be set either directly or through the \CMD{setpstgraph} \margintext{setpstgraph} macro with the following syntax.
\begin{syntax}
\>\CMD{setpstgraph\{\textrm{$key_1$=$value_1,key_2$=$value_2, \dotsc$}\}}
\end{syntax}
This macro must be used outside the \texttt{pstgraph} environment for the keys to take effect. The keys defined by the \texttt{pstgraph} environment are summarized in Table~\ref{tab:keys}.

%%===============================================================================
\rowcolors{1}{}{gray!30}
\begin{table}[b!]
\centering
\caption{\texttt{pstgraph} keys}
\label{tab:keys}
\begin{tabular}{>{\ttfamily}l  >{\itshape}c  c  p{2.6in}}
\hline
\textit{Key}  &  \textit{Value}  &  \textit{Default}  &  \textit{Description} \\
\hline
xmin        &  num     &  $0$                &  Minimum data value on the $x$ axis \\
xmax        &  num     &  $1$                &  Maximum data value on the $x$ axis \\
ymin        &  num     &  $0$                &  Minimum data value on the $y$ axis \\
ymax        &  num     &  $1$                &  Maximum data value on the $y$ axis \\
xgriddiv    &  num     &  $1$                &  Number of vertical grid lines \\
ygriddiv    &  num     &  $1$                &  Number of horizontal grid lines \\
gridstyle   &  style   &  solid              &  Style of grid lines \\
gridcolor   &  color   &  gray               &  Color of grid lines \\
gridwidth   &  dimen   &  0.5pt              &  Width of grid lines \\
xticksize   &  num     &  $0.1$              &  Length of vertical tick lines \\
yticksize   &  num     &  $0.1$              &  Length of horizontal tick lines \\
xtagsep     &  num     &  $0.2$              &  Distance of horizontal tags from the $x$ axis \\
ytagsep     &  num     &  $0.2$              &  Distance of the vertical tags from the $y$ axis \\
xtagformat  &  format  &  \CMD{scriptstyle}  &  Format of horizontal tags \\
ytagformat  &  format  &  \CMD{scriptstyle}  &  Format of vertical tags \\
xlabel      &  text    &  $-$                &  Label of the $x$ axis \\
ylabel      &  text    &  $-$                &  Label of the $y$ axis \\
xlabelsep   &  num     &  $0.55$             &  Distance of the $x$ label from the $x$ axis \\
ylabelsep   &  num     &  $0.75$             &  Distance of the $y$ label from the $y$ axis \\
framewidth  &  dimen   &  1pt                &  Width of the frame \\
framecolor  &  color   &  black              &  Color of the frame \\
\hline
\end{tabular}
\end{table}
\rowcolors{1}{}{}
%%===============================================================================
The labels of the $x$ and $y$ axes can be set either directly or through the \CMD{pstlabel} \margintext{pstlabel} macro, which has the following syntax.
\begin{syntax}
\>\CMD{pstlabel}\{\textit{x-label}\}\{\textit{y-label}\}
\end{syntax}
This macro can be used either inside or outside the \texttt{pstgraph} environment.

The last macro defined by the \package is \CMD{pstfileplot} \margintext{pstfileplot} that is used to draw the data in the file \textit{data-file}. The syntax of this macro is as follows.
\begin{syntax}
\>\CMD{pstfileplot[\textrm{\textit{key}=\textit{value}}]\{{\rmfamily\itshape data-file}\}}
\end{syntax}
Assuming $(x_0,y_0), (x_1,y_1), (x_2,y_2), \dotsc$ are the points on a curve to be plotted, the data file \textit{data-file} must have the following format.
\[
\begin{array}{cc}
{[x_0]}   &  {[y_0]} \\
{[x_1]}   &  {[y_1]} \\
{[x_2]}   &  {[y_2]} \\
\vdots    &  \vdots
\end{array}
\]
The use of brackets around every data value is optional; however, its usage enhances reading the data from the file. The plotted curve is obtained by connecting every point $(x_i, y_i)$ to $(x_{i+1}, y_{i+1})$ by a straight line segment for all $i = 0, 1, 2, \dotsc$. \emph{It is important to notice that all data values in the data file must be nonnegative; otherwise, unexpected results will occur.} Assume $x_{min} \leq x_i \leq x_{max}$ and $y_{min} \leq y_i \leq y_{max}$ for all $i = 0, 1, 2, \dotsc$. If either $x_{min} < 0$ or $y_{min} < 0$, I suggest the following solution. Generate the data file as follows.
\[
\begin{array}{cc}
{[x_0 - x_{min}]}  &  {[y_0 - y_{min}]} \\
{[x_1 - x_{min}]}  &  {[y_1 - y_{min}]} \\
{[x_2 - x_{min}]}  &  {[y_2 - y_{min}]} \\
\vdots  &  \vdots
\end{array}
\]
Then, set \texttt{xmin}=$x_{min}$, \texttt{xmax}=$x_{max}$, \texttt{ymin}=$y_{min}$, and \texttt{ymax}=$y_{max}$. This solution works because the portions of \texttt{pstgraph} and \CMD{pstfileplot} codes responsible for scaling and drawing the curve depend only on the differences $\mathtt{xmax} - \mathtt{xmin}$ and $\mathtt{ymax} - \mathtt{ymin}$. This solution is, in fact, equivalent to moving the origin of the $xy$-plane to the point $(x_{min}, y_{min})$. I am working on automating this process.




\section{Examples}

In this section, we review some examples.

\begin{LTXexample}
\begin{pstgraph}(4,3)
  \psset{linewidth=1.5pt}
  \pstfileplot[linecolor=purple]{data1.dat}
  \pstfileplot[linecolor=teal]{data2.dat}
\end{pstgraph}
\end{LTXexample}


\begin{LTXexample}
\setpstgraph{gridstyle=dashed,%
gridwidth=.2pt,framecolor=orange!60!black}
\begin{pstgraph}[xgriddiv=4,ygriddiv=2](4,3)
  \psset{linewidth=1.5pt}
  \pstfileplot[linecolor=purple]{data1.dat}
  \pstfileplot[linecolor=teal]{data2.dat}
  \pstlabel{$x$ axis}{$y$ axis}
\end{pstgraph}
\end{LTXexample}

Now, assume we would like to plot the curve of $f(x) = \sin(\pi x)$ from $x = -1$ to $x = 1$. First, we generate a data file containing the points of the curve $y = \sin(\pi(x - 1)) + 1$ in which $x$ varies from $0$ to $2$. Notice that the coordinates of all points are nonnegative. Assuming the data file is \texttt{data3.dat}, we plot the curve as follows.
\begin{LTXexample}
\setpstgraph{xmin=-1,xmax=1,ymin=-1,ymax=1,%
xgriddiv=4,ygriddiv=2}
\begin{pstgraph}(4,3)
  \psset{linewidth=1.5pt}
  \pstfileplot[linecolor=purple]{data3.dat}
  \pstlabel{$x$}{$\sin(\pi x)$}
\end{pstgraph}
\end{LTXexample}


\end{document}