Editing Tutorial (section)

==Plotting==

VPLOT provides a method for making plots that are small in size, aesthetically pleasing, and easily compatible with Latex for rapid creation of productio-quality images in Madagascar.
===VPLOT===
The VPLOT file format (.vpl suffix) is a self-contained binary data
format that describes in vector format how to draw a plot on the
screen or a page using an interpreter. Since VPLOT is not a standard
imaging format, VPLOT files must be viewed with 
interpreter programs which, for historical reasons, are called pens. Each pen interfaces VPLOT with a
third-party graphing library such as X11, plplot, opengl, and
others. This flexibility makes VPLOT files almost as portable as
standard image formats such as: EPS, GIF, JPEG, PDF, PNG, SVG, and TIFF. Unlike rasterized
formats, VPLOT files can be scaled to any size without losing image
quality.
===Creating plots===
To generate VPLOT files, we need to pass our computed RSF files through VPLOT filters, that convert RSF data files to VPLOT files. The VPLOT filters are named by the type of plot that they produce. The following table lists all of the available VPLOT filters.
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="2" style="background:#ffdead;" | List of available plotting programs in Madagascar.
|- 
| '''sfbox''' || make box-line plots 
|-
| '''sfcontour''' || make contour plots 
|-
| '''sfcontour3''' || make contour plots of 3D surfaces 
|-
| '''sfdots'''  || plot signal with lollipops 
|-
| '''sfgraph''' || create line plots, or scatter plots 
|-
| '''sfgraph3''' || generate 3-D cube plots for surfaces. 
|-
| '''sfgrey''' || create raster plots or 2D image plots 
|-
| '''sfgrey3''' || create 3D image plots of panels (or slices) of a 3D cube 
|-
| '''sfgrey4''' || generate movies of 3-D cube plots 
|-
| '''sfplotrays''' || make plots of rays 
|-
| '''sfthplot''' || make hidden-line surface plots 
|-
| '''sfwiggle''' || plot data with wiggly traces 
|}

To actually create a plot, we can use the plotting programs on the command line in the same fashion that we would use a Madagascar program:
<pre>
sfspike n1=100 | sfnoise > file.rsf
sfgraph < file.rsf title="noise" > file.vpl
</pre>
===Visualizing plots===
In this example, we create a single trace full of noise and then send
it to sfgraph to produce a single VPLOT file, <tt>file.vpl</tt>.  As
you may have noticed, this only creates the file which is useful for
saving the plot, does not allow us to visualize the data.  To visualize
the data we need to use a '''pen''' , which tells your machine how
to actually draw the plot.  A typical Madagascar installation will
have multiple pens available for you to use.  By default, you should
use '''sfpen'''  which will pick the best pen available for you.
You can use '''sfpen'''  to visualize your plots in the following
manner:
<pre>
sfpen < file.vpl
</pre>
This will pop up a screen on your window with the plot shown.  Depending on which pen you are using you may be able to interact with the pen interface to control various parameters of the plot as shown by the buttons at the top of the screen.  Depending on the pen that you are using, there may be keyboard shortcuts to many of the buttons.  NOTE: '''oglpen'''  uses a mouse interface that can be accessed by right-clicking on the plot.

===Converting VPLOT to other formats===
If you want to build reports or documents using other programs, or want to send your images to someone who does not have Madagascar you will need to convert your VPLOT files to other image formats for transfer.    To convert a VPLOT plot to another format use the tool '''vpconvert''' .  
'''vpconvert'''  allows you to convert VPLOT files to any of the following formats, provided that you have the appropriate third-party libraries installed: 
  
*avi,  
*eps, 
*gif,  
*jpeg/jpg, 
*mpeg/mpg (movie format), 
*pdf, 
*png, 
*ppm, 
*ps, 
*svg, 
*and tif. 
Here's an example of how to use '''vpconvert''' :
<pre>
vpconvert file.vpl format=jpeg
</pre>
NOTE: details on how to install these third-party libraries are not
included with the Madagascar library, and we provide no support on
installing them.  Most users will be able to install them using either
package management software (on Linux, Windows, and Mac) or
pre-compiled binaries. The PS and EPS support is provided by default.