<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[]>

<!-- Manual page for ygraph -->

<refentry>
  <refmeta>
    <refentrytitle>ygraph</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>ygraph</refname>
    <refpurpose>plot and animate 1D data</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>ygraph</command>
      <arg choice="opt">-cspgrv?</arg>
      <arg choice="opt">-C <replaceable>columns</replaceable></arg>
      <arg choice="opt">-d <replaceable>delay</replaceable></arg>
      <arg choice="opt">-k <replaceable>step</replaceable></arg>
      <arg choice="opt">-x <replaceable>xmin,xmax</replaceable></arg>
      <arg choice="opt">-y <replaceable>ymin,ymax</replaceable></arg>
      <arg choice="opt">-S <replaceable>file1</replaceable> 
        <replaceable>file2</replaceable></arg>
      <arg choice="opt">-I <replaceable>file</replaceable></arg>
      <arg choice="opt">--frame-integrate <replaceable>file</replaceable></arg>
      <arg choice="opt">--time-integrate <replaceable>file</replaceable></arg>
      <arg choice="opt" rep="repeat">file</arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>Description</title>
    <para>
      <command>ygraph</command> is a simple program to produce
      an xy-plot of 1D data. It features animation, zooming, and
      the ability to load multiple data sets into a single plot.
    </para>
      
    <para>
      <command>ygraph</command> is intended to be a quick first-glance
      data reader, so simple, instinctive use was the major design
      goal. Most features are directly available from the control
      panel and plot window menus. Some data manipulation functions
      are present, but fancy plot formatting has been largely ignored,
      as there already exist more sophisticated tools for producing
      publication quality plots.
    </para>

    <para>
      The input file format read by <command>ygraph</command> is a
      slight generalisation of the historical
      <command>xgraph</command> format which, for instance, is
      generated by the standard I/O methods of the <ulink
      url="http://www.cactuscode.org/"> Cactus Computational
      Toolkit</ulink>. A more detailed description of the input file
      format is given below.
    </para>
    
    <para>
      The special filename <filename>-</filename> can be used to read
      data from the standard input:
    </para>
    <para>
      <userinput>cat data1.xl | ygraph -</userinput>
    </para>
    <para>
      Filenames starting with '<' are interpreted and opened as pipe:
    </para>
    <para>
      <userinput>ygraph "&lt;cat data1.xl"</userinput>
    </para>
     
    <para>
      Command-line options are as follows:
    </para>

    <para>
      <variablelist>
        <varlistentry>
          <term>
            <parameter class="option">-c</parameter>,
            <parameter class="option">--no-control-panel</parameter>
          </term>
          <listitem>
            <para>Start without the control panel.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <parameter class="option">-s</parameter>,
            <parameter class="option">--separate-windows</parameter>
          </term>
          <listitem>
            <para>Start with each requested plot in a separate
            window.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <parameter class="option">-p</parameter>,
            <parameter class="option">--no-points</parameter>
          </term>
          <listitem>
            <para>Turn off points drawn at each data point</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <parameter class="option">-g</parameter>,
            <parameter class="option">--no-grid</parameter>
          </term>
          <listitem>
            <para>Don't draw a grid on the plot background.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <parameter class="option">-r</parameter>,
            <parameter class="option">--no-range</parameter>
          </term>
          <listitem>
            <para>Don't draw axis range values on the plot background.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <parameter class="option">-C</parameter>,
            <parameter class="option">--columns</parameter>
            <replaceable>column list</replaceable>
          </term>
          <listitem>
            <para>Set (globally) the columns to be read from the input
              in the format <replaceable>x:y</replaceable>. Default is
              1:2.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <parameter class="option">-d</parameter>,
            <parameter class="option">--delay</parameter>
            <replaceable>time</replaceable>
          </term>
          <listitem>
            <para>Delay between successive animation frames. The
              specified value <replaceable>time</replaceable> should
              be an integer representing the number of milliseconds to
              delay between frames.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <parameter class="option">-k</parameter>,
            <parameter class="option">--skip</parameter>
            <replaceable>n</replaceable>
          </term>
          <listitem>
            <para>Read in only every <replaceable>n</replaceable>th frame
              of data.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <parameter class="option">-l</parameter>,
            <parameter class="option">--legend</parameter>
            <replaceable>pos</replaceable>
          </term>
          <listitem>
            <para>
              Set the position of the plot legend in the plot
              window. Valid <replaceable>pos</replaceable> values are:
              <simplelist>
                <member>a -- the legend is placed above the plot</>
                <member>r -- the legend is placed to the right of the plot</>
                <member>o -- the legend is placed over the plot data</>
                <member>0 -- the legend is turned off (not displayed).</>
              </simplelist>
            </para>
            <para>
              By default, the legend is placed over the plot data,
              `o'.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <parameter class="option">-S</parameter>,
            <parameter class="option">--subtract</parameter>
            <replaceable>file1</replaceable>
            <replaceable>file2</replaceable>
          </term>
          <listitem>
            <para>Subtract the second listed file from the first. If
            x-values of the two plots don't match, then values of
            the second are interpolated linearly to points of the
            first.</para>
          </listitem>
        </varlistentry>
  
        <varlistentry>
          <term>
            <parameter class="option">-I</parameter>,
            <parameter class="option">--integrate</parameter>
            <replaceable>file</replaceable>
          </term>
          <listitem>
            <para>Integrate file assuming f(left boundary)=0</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <parameter class="option">--frame-integrate</parameter>
            <replaceable>file</replaceable>
          </term>
          <listitem>
            <para>Integrate frames of file</para>
          </listitem>
        </varlistentry>
  
        <varlistentry>
          <term>
            <parameter class="option">--time-integrate</parameter>
            <replaceable>file</replaceable>
          </term>
          <listitem>
            <para>Integrate frames of file and multiplying with time
            given by comments in the file</para>
          </listitem>
        </varlistentry>
  
        <varlistentry>
          <term>
            <parameter class="option">-?</parameter>,
            <parameter class="option">--help</parameter>
          </term>
          <listitem>
            <para>List the command line options and exit.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <parameter class="option">-v</parameter>,
            <parameter class="option">--version</parameter>
          </term>
          <listitem>
            <para>Print a version message and exit.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </para>

    <para>
      If a single `-' is specified in place of an input file, then
      data will be read from STDIN.
    </para>

  </refsect1>
  <refsect1>
    <title>Usage</title>
    <para>
      Once the plot window is displayed, most of the available actions
      should be obvious from the menu bar and control panel
      buttons.
    </para>
    <refsect2>
      <title>Zoom</title>
      <para>
        To zoom in to a region of the plot, click the mouse left button
        at the upper left corner, drag to the lower right corner, and
        release the button. A menu option exists to unzoom back to the
        plot's original dimensions.
      </para>
    </refsect2>
    <refsect2>
      <title>Logarithmic plots</title>
      <para>
      Logarithmic axes can be set up using the `Setting/Range...'
      dialog. Alternatively, the `shift-L' keybinding can be used
      to toggle between the following four axis configurations in
      order:
      (x,y) = (linear,linear), (linear,log), (log,log), (log,linear).
      </para>
    </refsect2>
    <refsect2>
      <title>Derivatives</title>
      <para>
        The derivative of any displayed plot can be calculated by
        using the <guimenuitem>`/Plot/Derivative'</guimenuitem> menu
        option from the plot window.
      </para>
    </refsect2>
    <refsect2>
      <title>Difference between data sets</title>
      <para>
      The difference between a pair of data sets can be plotted using
      the -S command line option (the next two listed files will be
      subtracted pointwise) or the
      <guimenuitem>`Plot/Subtract A-B...'</guimenuitem> menu option.
      Linear interpolation of the subtracted data set is used if
      the data locations do not line up exactly.
      </para>
    </refsect2>
    <refsect2>
      <title>Re-scaled data sets</title>
      <para>
      The y-values of individual data sets can be rescaled using the
      <guimenuitem>`Plot/Scale...'</guimenuitem> dialog.
      </para>
    </refsect2>
    <refsect2>
      <title>Pointer location</title>
      <para>
      Right-clicking at any point in the plot window will print the
      pointer location on the plot background. The labels remain until
      the window is refreshed. The `c' keybinding can be used to force
      a refresh and clean off the labels.
      </para>
    </refsect2>
    <refsect2>
      <title>Export of images and animations</title>
      <para>
        It is possible to export a single frame of a plot using the
        <guimenuitem>`File/Export image...'</guimenuitem> menu option. The
        extension of the chosen file name will determine the type of data
        which is output (eg. jpeg, png, tiff, ps, etc.).
      </para>
      <para>
        Currently, support for animations exists only in the form
        of allowing the export of multiple frames of a plot, which
        must then be recombined afterwards using external software.
        Multiple frames of an animation can be saved to a directory
        using the <guimenuitem>`File/Export animation...'</guimenuitem>
        menu option. On selecting this option, the user is asked to
        give a directory name in which a sequence of images
        corresponding to the currently loaded frames of the plot
        will be saved. By default, the frames are saved in png
        format under the names <filename>frame_000001.png</filename>,
        <filename>frame_000002.png</filename>, etc. The resulting
        files can be combined to produce an animation using an
        external tool, such as the <command>convert</command>
        utility distributed with ImageMagick. For example, if the
        animation frames were saved to the directory 
        <filename>anim_data</filename>, then the command
      </para>
      <para>
        <userinput>convert -delay 20 anim_data/frame*.png 
          test_anim.gif</userinput>
      </para>
      <para>
        could be used to create an animated gif 
        (<filename>test_anim.gif</filename>) whose frames consist
        of the images in <filename>anim_data</filename> with a delay
        of 20/100 seconds between successive frames.
      </para>
    </refsect2>

    <refsect2>
      <title>Hints</title>
      <itemizedlist>
        <listitem>
          <para> If at any time you lose track of the control panel
            (eg. by covering it with other windows), you can raise it
            by pressing `p' in a plot window.
          </para>
        </listitem>        
        <listitem>
          <para> If you find the control panel annoying, don't forget
            the '-c' command line option, which suppresses the control
            panel on startup. You can use keybindings to control the
            animation, and call up the control panel at any time using
            the 'p' key.
          </para>
        </listitem>
        <listitem>
          <para> If you would like to test convergence of a set of
            data sets at different resolutions, you can load
            them into <command>ygraph</command> and rescale individual
            plots using the <guimenuitem>`Plot/Scale...'</guimenuitem>
            dialog.
          </para>
        </listitem>
      </itemizedlist>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>Keybindings</title>
    <para> The following keybindings are available from the plot window:
      <simplelist>
        <member>
        h     -- go to the first frame
        </member>
        <member>
        j     -- step back one frame
        </member>
        <member>
        k     -- step forward one frame
        </member>
        <member>
        l     -- go to the last frame
        </member>
        <member>
        space --  play/pause
        </member>
        <member>
        s     -- show all frames
        </member>
        <member>
        L     -- toggle log/linear axes (lin-lin, lin-log, log-log, log-lin)
        </member>
        <member>
        c     -- clean the window
        </member>
        <member>
        p     -- raise the control panel, if it's hidden behind the plot window
        </member>
        <member>
        C-n   -- open a new plot window
        </member>
        <member>
        C-o   -- open a new file in the current window
        </member>
        <member>
        C-p   -- open a new file in a new window
        </member>
        <member>
        C-e   -- export individual frames as images
        </member>
        <member>
        C-m   -- export multiple frames as images
        </member>
        <member>
        C-w   -- close the plot window
        </member>
        <member>
        C-d   -- take a spatial derivative of the current plot
        </member>
        <member>
        C-s   -- subtract one data set from another
        </member>
        <member>
        C-m   -- rescale data sets
        </member>
        <member>
        C-u   -- unzoom
        </member>
        <member>
        C-x   -- open the plot range dialog
        </member>
        <member>
        C-p   -- toggle the display of dots at each data point
        </member>
        <member>
        C-g   -- toggle display of grid lines
        </member>
        <member>
        C-r   -- toggle display of ranges on the plot window
        </member>
        <member>
        C-k   -- open a window listing the keybindings
        </member>
        <member>
        C-q   -- quit <command>ygraph</command>
        </member>
        <member>
        Left-mouse   -- zoom
        </member>
        <member>
        Right-mouse  -- print the mouse position on the plot
        </member>
      </simplelist>
    </para>
  </refsect1>

  <refsect1>
    <title>Input file format</title>
    <para>
      <command>ygraph</command> reads the standard 1D
      <command>xgraph</command> data format output by Cactus.  The
      data can be in the form of an ASCII text file, gzipped or bzipped, in
      which case the file will be automatically decompressed as it is
      read. XY-data are listed in columns of the form
      <screen>
        &lt;x-val1&gt; &lt;y-val1&gt;
        &lt;x-val2&gt; &lt;y-val2&gt;
        &lt;x-val3&gt; &lt;y-val3&gt;
        etc.
      </screen>
      where <replaceable>x-val</replaceable> and
      <replaceable>y-val</replaceable> are floating point coordinates
      of (x,y) points to be plotted and are seperated by at least one
      whitespace character. Multiple plots are seperated by a blank
      line. Comment lines are delimited by beginning the line with a "
      (double-quote) character, or by a hash `#' symbol. An optional
      time value can be assigned to each data frame by adding a line of
      the form
      <screen>
        "Time = &lt;time-val&gt
      </screen>
      to the head of a set of (x,y) values, where
      <replaceable>time-val</replaceable> is a floating point value
      which will label the particular data set during animation. The
      plot can also be assigned a name by a line of the form
      <screen>
        "Label = &lt;name&gt
      </screen>
      The assigned name will be used in the legend of the plot.
    </para>
    <refsect2>
      <title>Input data example:</title>
      <screen>
        "This is just a comment
        "Label = Random numbers
        "Time = 0.0
        0.1   1.343
        0.2   1.939
        0.3   2.439
        0.4   3.949
        0.5   5.495
        
        "Time = 0.2
        0.1   1.442
        0.2   2.303
        0.3   3.349
        0.4   4.192
        0.5   6.029
      </screen>
    </refsect2>
  </refsect1>


  <refsect1>
    <title>Examples</title>

    <para>
      To plot the files <filename>data1.xl</filename> and
      <filename>data2.xl</filename> in the same window, use:
    </para>
    <para>
      <userinput>ygraph data1.xl data2.xl</userinput>
    </para>

    <para>
      To plot the same pair of files but starting with each in a
      separate window, use:
    </para>
    <para>
      <userinput>ygraph -s data1.xl data2.xl</userinput>
    </para>

    <para>
      To control the delay between successive frames of the animation
      of a data set, use the -d flag. For example, to set
      the delay to 100ms, use:
    </para>
    <para>
      <userinput>ygraph -d 100 data1.xl</userinput>
    </para>

    <para>
      To plot a file with the x-range set to (-1,3) and the y-range to
      (-2,4), use:
    </para>
    <para>
      <userinput>ygraph -x -1,3 -y -2,4 data1.xl data2.xl</userinput>
    </para>

    <para>
      To plot <filename>data1.xl</filename> minus
      <filename>data2.xl</filename>, use:
    </para>
    <para>
      <userinput>ygraph -S data1.xl data2.xl</userinput>
    </para>

  </refsect1>

  <refsect1>
    <title>Author</title>

    <para>
      The development of <command>ygraph</command> has been
      driven by the needs of the <ulink
      url="http://numrel.aei.mpg.de/">Numerical Relativity
      Group</ulink> at the Max-Planck-Institute fuer
      Gravitationsphysik, Golm, Germany.
    </para>

    <para>
      <command>ygraph</command> was originally written by
      Denis Pollney 
      <ulink url="http://numrel.aei.mpg.de/Misc/email.html">
      <email>firstname.lastname@aei.mpg.de</email>
      </ulink>. Code has
      been contributed by a number of authors, listed in the AUTHORS
      file of the source code distribution.
    </para>

  </refsect1>

  <refsect1>
    <title>Distribution</title>
    <para>
      <command>ygraph</command> is distributed under the GNU General
      Public License.
    </para>

    <para>
      More information, recent binaries, and source code can be found
      at the author's <ulink
      url="http://www.aei.mpg.de/~pollney/ygraph/">homepage</ulink>.
    </para>

  </refsect1>

  <refsect1>
    <title>Reporting bugs</title>
    <para>
      Please report problems to DP at the address above, or to 
      the majordomo mailing list <email>ygraph-users@aei.mpg.de</email>.
    </para>
  </refsect1>

  <refsect1>
    <title>See also</title>
    <para>
      <citerefentry>
        <refentrytitle>xgraph</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>
      <citerefentry>
        <refentrytitle>convert</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>
    </para>
  </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->