Overview
============================================================

As a developer, the need to display data charts and graphs on your web
site/service presents two major generation options: server-side, or
client/browser-side.

- The primary benefits of server-side chart generation are: completely
  consistent display across browsers (even IE can handle showing
  images), and re-use of the chart image outside the browser, e.g. in
  generating PDF documents.

- The primary benefit of client/browser-side chart generation is:
  interactivity (if needed), or generally more dynamic behavior,
  e.g. immediately updated charts with a user's new input.

webplotlib could be for you if you want Python server-side chart
generation, providing a convenient and modular package/API.  It is GPL
licensed.


Installation
------------

NOTE: Even though I wrote this package for a Django context, it can
easily be used without/outside Django.  See below for more details.

webplotlib has these direct dependencies:

1. Numpy, which Matplotlib also depends on.  You can install this
   globally (e.g. sudo pip install numpy) or just for the relevant
   virtualenv.  For its full functionality you'll want to install
   system dependencies (like Fortran), e.g. on Ubuntu, the packages
   libatlas-base-dev, gfortran, gcc, g++.
2. Matplotlib - you can get this via your OS packaging system (likely
   too old), from PyPI, or from source.  The latest version, 1.0.1, is
   ostensibly on PyPI, but pip pulls down the wrong version currently
   (as of May 2011; not pip's fault, see this `SO discussion`_),
   unless you do the following:
   pip install -f http://downloads.sourceforge.net/project/matplotlib/matplotlib/matplotlib-1.0.1/matplotlib-1.0.1.tar.gz matplotlib
   You can also install this globally or locally to one virtualenv.
   Note that Matplotlib has numerous system dependencies depending on
   usage: e.g. for server usage on Ubuntu, install packages: python,
   python-dev, libpng12-dev, libfreetype6-dev.
3. py.test, if you want to run the unit tests.


.. _SO discussion: http://stackoverflow.com/questions/3555551/why-does-pip-install-matplotlib-version-0-91-1-when-pypi-shows-version-1-0-0


With dependencies installed (and within the relevant virtualenv),
install webplotlib from PyPI with:

::

    pip install webplotlib


Or you can install from source via github.


Usage
-----

While I wrote webplotlib to work with a Django project, currently
there are no direct dependencies on Django, so you can treat
webplotlib like any other Python package and call it directly. For
example:

::

    from webplotlib.chart_builders import create_chart_as_png_str
    
    
    # When you have at least one sequence (list, tuple, iterable) 
    # of data, you can plot it:
    chart_png_str = create_chart_as_png_str(
        'timeseries',
        {'data': [[your_data_sequence]], 'names': 'MyDataLine'},
        labels_dct={'title': 'TheBigBoard', 'x': 'Data', 'y': 'Value'})
    # Save chart_png_str, etc.
        

More examples of usage can be found in the test_chart_builders.py
module.

Django integration: I found confusing and inconsistent examples of
integrating Matplotlib with Django on the web, so experimented a bit
on my own.  You can see some examples in webplotlib's views.py file
which shows how to serve/return server-side generated PNG charts
directly as a string - which can be handy for rapid feedback when you
want to style a chart.

So to use webplotlib in Django, update your Django project's
settings.py INSTALLED_APPS to include 'webplotlib' and also update
your project's urls.py file (there's nothing in models.py yet) to have
something like,

::

    urlpatterns = patterns('',
        ...
        (r'^wpl/', include('webplotlib.urls')),
        ...
        )


Also, consider using webplotlib with my app django-metaimage_, which
readily handles creating new images and saving them to a useful Django
ORM model instance/representation.


.. _django-metaimage: https://github.com/limist/django-metaimage


Testing
-------

Basic unit tests can be run using Tox_ or py.test.  


.. _Tox: http://codespeak.net/tox/


History + Design
----------------

webplotlib relies on Matplotlib_ - the most powerful and popular
Python charting package available - for the actual chart generation.
But what I found (as of Spring 2011) was a lack of well-abstracted
examples of Matplotlib usage in web environments, as well as a lack of
examples using its non-interactive, object-oriented, programmer's
interface (by contrast, there are tons of examples_ for interactive
user-driven chart creation, emulating MATLAB).  Thus the need to write
a new app that could quickly be used to generate server-side charts.

I wanted a way to generate a Matplotlib chart (time-series and bar
charts initially) with a single function call that would create and
return the raw chart data/image as a string - from there it's easy to
save it, or process it further (e.g. add watermark), or return it via
HTTP, etc.  After studying lots of online examples and documentation,
experimenting, and refactoring, enter webplotlib.  Initially it
supports time-series and bar charts, taking sequences and returning
non-ugly charts as PNG-image strings you can readily use.  There will
be more abstractions (e.g. defining chart templates separately) and
improvements to come, but this version is usable now.

Alternatives: Why not use a Flash library? Not OSS, same limitations
as Javascript library.  And why not use a Javascript library?  After
looking at a bunch of client-side libraries (Grafico, Highcharts,
flot, Google Chart Tools, dygraphs, Raphaël), I thought Protovis_ was
it - the one tool to rule them all.  But after making sense of their
docs and examples, I found displays were inconsistent: simple charts
would look fine in Firefox 3/4 but show up in Chrome without tick
marks and labels, which was unacceptable.  And I didn't even bother
looking at IE rendering, where more pain was likely.  Furthermore, my
requirements changed; I needed to use the charts in reporting, so it
was essential to have the charts as images, consistent across several
mediums.  So server-side generation was the way to go, and with
Python, one finds out very quickly there's no serious competition to
Matplotlib.


.. _examples: http://matplotlib.sourceforge.net/gallery.html
.. _Matplotlib: http://matplotlib.sourceforge.net/index.html
.. _Protovis: http://vis.stanford.edu/protovis/