View: HTML | Text | PS | PDF | RTF | Wiki | DocBook | DocBook Inline | changelog | about this header Circle Jeff Boweron  
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML v4.5//EN" "/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd">
<article lang="en">
  <articleinfo>
    <keywordset>
      <keyword>sparkline</keyword>
      <keyword>ubuntu</keyword>
      <keyword>gnuplot</keyword>
      <keyword>docbook</keyword>
    </keywordset>
    <title>Creating Sparklines with Gnuplot Under Ubuntu</title>
    <abstract>
      <para>
Sparklines are small graphs designed to be embedded within a paragraph as though they were words.  This article documents a script that will help you easily create sparklines using Gnuplot.  While written under Ubuntu Maverick there's no real reason it shouldn't be able to be modified for other systems that have access to Gnuplot - possibly including Windows using <ulink url="http://www.cygwin.com">Cygwin</ulink>.
</para>
    </abstract>
  </articleinfo>
  <section id="problem-statement">
    <title>The Problem</title>
    <para>
Sparklines are an interesting concept, while they lack the detail of a full-fledged graph they can provide a very high density of information in the space of a word.  Because of their size they are inherently simplistic, lacking labels and complex annotations.  However, because of Gnuplot's inherent complexity creating the simple can be difficult.  Enter <package>sparkline-gp</package>, a script to create sparkline graphs using Gnuplot with a minimum of effort.  While the script is rapidly increasing in complexity and options, running <command>sparkline-gp f=data.dat</command> is often enough to create a workable sparkline.  Details of these options are documented below.
</para>
    <section id="other-solutions">
      <title>Other Solutions</title>
      <para>
Sparklines are just a concept, there's nothing magic about my script that makes it a sparkline and all other methods inferior.  There is a Ubuntu package <package>libsparkline-php</package> which can also create sparklines, however it has a dependency of <package>apache2</package> which makes it less than a lightweight solution.  Sparklines can be created in the OpenOffice.org (or LibreOffice) spreadsheet programs by simply creating a tiny graph.  Microsoft Excel has <ulink url="http://blogs.office.com/b/microsoft-excel/archive/2009/07/17/sparklines-in-excel.aspx">native support for sparklines</ulink>.  There is a <ulink url="http://omnipotent.net/jquery.sparkline/">jQuery</ulink> implementation with a much more comprehensive set of graphs than my own.  You can also build them as a <ulink url="http://sparklines.bitworking.info/">web service</ulink>.  There's no shortage of ways to create them, but I was looking for a very simple method to create them from a command line.  And being able to add the features <emphasis>I</emphasis> want to incorporate them into my <ulink url="https://www.ebower.com/docs/docbook">DocBook</ulink> documents is just icing on the cake.
</para>
    </section>
  </section>
  <section id="installing-sparkline-gp">
    <title>Installing <package>sparkline-gp</package></title>
    <para>
The easiest way to ensure you've got the latest and greatest is to install the eBower PPA as described in <xref linkend="ebower-ppa-install"/>.  Afterwords run <command>sudo apt-get update &amp;&amp; sudo apt-get install sparkline-gp</command> and the script will install itself in <filename>/usr/bin/sparkline-gp</filename>.
</para>
    <para>
You can also manually install the script if you prefer, but the script is still in the early stages so you'll want to check back often for updates.  Because <package>sparkline-gp</package> is simply a front end to Gnuplot, it has very limited dependencies.  If you decide to manually install the script you'll need to ensure you have <package>gnuplot-nox</package> installed on your system.  The script itself can be found <ulink url="sparkline-gp">here</ulink>, I fear that embedding the script within my document is tedious so I'll leave the click-through to the reader.
</para>
  </section>
  <section id="using-sparkline-gp">
    <title>Using <package>sparkline-gp</package></title>
    <para>
Using <command>sparkline-gp</command> only requires an input file as a parameter.  However there are many options that can be used to tweak and add to your graph.  The format of the parameters is an arbitrarily ordered list of <emphasis>variable=value</emphasis> pairs.
</para>
    <section id="file-processing">
      <title>File Processing Parameters</title>
      <para>
The only required variable is the input file, everything else is optional.  File processing parameters are fairly-self explanatory - they define the input and output files of the script.
</para>
      <variablelist>
        <varlistentry>
          <term>f</term>
          <listitem>
            <para>
This parameter represents the Gnuplot formatted input file.  Additional details of this format can be found in <xref linkend="input-format"/>.
</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>o</term>
          <listitem>
            <para>
This parameter defines the output PNG file.  By default it will be of the format <filename>inputfile.png</filename> - simply tagging a <filename>.png</filename> extension to the input file.  Note that the output file format will always be PNG, if you need another format you'll need to use an external program to perform the conversion.  The <package>imagemagick</package> package includes a utility called <command>convert</command> that can be used for this.
</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <section id="input-format">
        <title>Input File Format</title>
        <para>
The format is just a standard Gnuplot file.  Lines starting with # will be ignored as comments.  Each row represents a space separated <varname>x</varname> <varname>y</varname> value.  Additional columns will be ignored.  A simple example file that outputs <inlinemediaobject><imageobject><imagedata fileref="sparkline.png"/></imageobject><imageobject><imagedata fileref="sparkline.eps"/></imageobject></inlinemediaobject> is below.
</para>
        <example>
          <title>Sample Input File</title>
          <programlisting><inlinemediaobject><imageobject><imagedata fileref="sparkdata.txt" format="linespecific"/></imageobject></inlinemediaobject></programlisting>
        </example>
      </section>
    </section>
    <section id="image-scale">
      <title>Image Scaling</title>
      <para>
The Y axis may be manually scaled as needed.
</para>
      <variablelist>
        <varlistentry>
          <term>min</term>
          <listitem>
            <para>
This variable will force the graph to a use a defined minimum value.  By default this value will be automatically calculated based on the data, however it may be useful to force a lower bound to change the shape of the graph or to normalize multiple graphs displayed simultaneously.
</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>max</term>
          <listitem>
            <para>
This variable will force the graph to a use a defined maximum value.  By default this value will be automatically calculated based on the data, however it may be useful to force an upper bound to change the shape of the graph or to normalize multiple graphs displayed simultaneously.
</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section id="marks-annotations">
      <title>Marks and Annotations</title>
      <para>
Sparklines can include marks and annotations to call out certain properties.  Colors are represented by text (red, blue, green, orange, etc.) or by an RGB specification of the format #RRGGBB.
</para>
      <variablelist>
        <varlistentry>
          <term>c</term>
          <listitem>
            <para>
This parameter will modify the color of the line which, by default, will be red.
</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>marklast</term>
          <listitem>
            <para>
This will create a dot of the specified color to highlight the last point on the graph.  By default there will be no dot.
</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>markmin</term>
          <listitem>
            <para>
This will create a dot of the specified color to highlight the first instance of the lowest point on the graph.  By default there will be no dot.
</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>markmax</term>
          <listitem>
            <para>
This will create a dot of the specified color to highlight the last instance of the highest point on the graph.  By default there will be no dot.
</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section id="ranges">
      <title>Creating a Range</title>
      <para>
Sometimes it's useful to highlight a range on the graph, for example to show the normal range of values and highlight deviations from this.  If the range specified exceeds the automatically calculated minimum and maximum Y values the range will supersede the values.  To override this you may manually specify the <varname>min</varname> and/or <varname>max</varname> values.
</para>
      <variablelist>
        <varlistentry>
          <term>rangestart</term>
          <listitem>
            <para>
This is the lower value of the range, by default there is no range defined.  When defined without a <varname>rangestop</varname> value the script will exit with an error code.
</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>rangestop</term>
          <listitem>
            <para>
This is the higher value of the range, by default there is no range defined.  When defined without a <varname>rangestart</varname> value the script will exit with an error code.
</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>rangecolor</term>
          <listitem>
            <para>
This allows you to change the color of the range rectangle, by default it will be a muted grey.  The format of this variable is described in <xref linkend="marks-annotations"/>.
</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section id="image-size">
      <title>Image Size and Positioning Parameters</title>
      <para>
The default parameters are designed to work well with common font settings.  In some cases (for example, with different font sizes) these parameters can be tweaked to improve the overall effect.
</para>
      <variablelist>
        <varlistentry>
          <term>h</term>
          <listitem>
            <para>
This variable is the height of the image in pixels.  By default this will be 15 pixels.
</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>w</term>
          <listitem>
            <para>
This variable is the width of the image in pixels.  By default this will be 100 pixels.
</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>tbuff</term>
          <listitem>
            <para>
This variable allows you to add a buffer to the top of the image.  This can be useful if the top of a marker is cut off or missing.  The default value is 0.
</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>bbuff</term>
          <listitem>
            <para>
This variable allows you to add a buffer to the bottom of the image.  This can be useful if the bottom of a marker is cut off or missing.  The default value is 0.
</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>rbuff</term>
          <listitem>
            <para>
This variable allows you to add a buffer to the right of the image.  This can be useful if the right of a marker is cut off or missing.  The default value is 0.
</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>lbuff</term>
          <listitem>
            <para>
This variable allows you to add a buffer to the right of the image.  This can be useful if the left of a marker is cut off or missing.  The default value is 0.
</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
  </section>
  <!-- INCLUDE ../ebower-ppa.docbook -->
  <appendix id="ebower-ppa-install">
    <title>Installing the eBower PPA</title>
    <para>
I've created a Personal Packages Archive (PPA) on Launchpad.net.  You can add this using the command <command>sudo add-apt-repository ppa:ubuntu-ebower/ebower</command> and then <command>sudo apt-get update</command> to load the list of packages.  Alternatively you can add the following lines to your <filename>/etc/apt/sources.lst</filename> (this is useful if you're running server and don't want to add the <command>add-apt-repository</command> command):
</para>
    <programlisting>
deb http://ppa.launchpad.net/ubuntu-ebower/ebower/ubuntu precise main 
deb-src http://ppa.launchpad.net/ubuntu-ebower/ebower/ubuntu precise main 
</programlisting>
    <para>
Make sure you replace <emphasis>precise</emphasis> above with your distro (lucid, oneiric, etc.).  If your distro is not available please contact me with the version and package name and I'll try to update things posthaste.  After this is done, run the command <command>sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys C27A63B3</command> to import the keys.
</para>
    <para>
By installing my scripts from the PPA you'll be sure to have the most up-to-date versions in case I need to make changes.  However, note that I'm not a developer and I only play one on the Internet.  If you use my scripts as a baseline and make changes yourself please let me know how you're changing things and I'll try to accommodate your efforts to ensure that I don't stomp on your customizations.
</para>
  </appendix>
  <!-- INCLUDE_END ../ebower-ppa.docbook -->
<!-- INCLUDE ../about-me.docbook -->
  <appendix id="about-me">
    <title>About Me</title>
    <para>
My name is Jeff Bower, I'm a <ulink url="http://www.linkedin.com/in/jdbower">technology professional</ulink> with more years of experience in the telecommunications industry than I'd care to admit.  I tend to post with the username jdbower on various forums, including <ulink url="http://komodokamado.com/forum/">Komodo Kamado</ulink>, <ulink url="http://forum.androidcentral.com/">Android Central</ulink>, <ulink url="http://forums.virtualbox.org/">VirtualBox</ulink>, and <ulink url="http://www.makemkv.com/forum2/">MakeMKV</ulink>.  Writing these documents is a hobby of mine, I hope you find them useful and feel free to browse more at <ulink url="https://www.ebower.com/docs">https://www.ebower.com/docs</ulink>.  
</para>
    <para>
I also enjoy cooking, especially outdoors with my <ulink url="http://www.komodokamado.com">Komodo Kamado</ulink> and using my <ulink url="https://www.rocksbarbque.com">Stoker</ulink>.  Take a look at my recipes stored at <ulink url="https://www.ebower.com/recipes">https://www.ebower.com/recipes</ulink>.
</para>
    <para>
If you've got any questions or feedback please feel free to email me at <ulink url="mailto:docs@ebower.com">docs@ebower.com</ulink> or follow me on <ulink url="https://profiles.google.com/100268310848930740059">Google+</ulink> or <ulink url="http://twitter.com/jdbower">Twitter</ulink>.
</para>
  </appendix>

<!-- INCLUDE_END ../about-me.docbook -->
</article>