~ Abscissa ~

An embedded domain specific language for plotting 2D data sets in Scheme.

Copyright 2014 Benjamin Silbaugh

See LICENSE for redistribution and modification permissions.

Overview
========

Abscissa is a domain specific language for generating 2D plots. Abscissa is
embedded in Chicken Scheme. Gnuplot is used as the plotting engine. 

Example Usage
~~~~~~~~~~~~~

The following examples should provide a basic sense of how Abscissa is
used. For more examples, see the examples directory in the source tree. 

Example 1: Single data set
--------------------------

Suppose xy is a list of pairs; e.g.

    (define xy '((0 . 0) (1 . 1) (2 . 4) (3 . 9)))

Then the following would create an interactive window containing a line
plot of xy

    ([window]
     ([figure]
      ([cartesian]
       ([line] (<- xy)))))

Note that the indentation used above is not significant: it is only used 
for readability.

Example 2: Multiple data sets
-----------------------------

Suppose xy and pq are lists of pairs; e.g.

    (define xy '((0 . 0.0) (1 . 1.0) (2 . 4.0) (3 . 9.0)))

    (define pq '((0 . 0.1) (1 . 0.9) (2 . 4.1) (3 . 8.9)))

Then the following would create an interactive window with the xy values
represented by lines and pq values represented by symbols

    ([window]
     ([figure]
      ([cartesian]
       ([line] (<- xy))
       ([points] (<- pq)))))

Example 3: Configuring Plot Elements
------------------------------------

Suppose xy is a list of pairs; e.g.

    (define xy '((0 . 0) (1 . 1) (2 . 4) (3 . 9)))

Then the following would create an interactive window with xy values
represented by blue line segments, the x axis limits set to [0,1]

    ([window]
     ([figure]
      ([cartesian x-limits: '(0.0 . 1.0)]
       ([line color: "dark-blue"] (<- xy)))))

Status
======

Abscissa is quite usable at this point for basic plotting tasks. However,
breaking changes may occur, and there may still be critical bugs.

Installation
============

Absicssa is packaged as a Chicken Egg. Thus, installing Abscissa should
simply be a matter of downloading a copy of the source and running
chicken-install in the top level of the source tree. (See
http://wiki.call-cc.org if you're unfamiliar with Chicken Scheme.) The only
prequisites are a working installation of Chicken Scheme and
Gnuplot. Detailed installation instructions are as follows:

0. Ensure that the following prequisite software has been installed on the
   target machine:

       * Chicken Scheme: Abscissa has been tested using version 4.8.0.5.

       * Gnuplot: Abscissa has been tested using version 4.6. Be sure
         that Gnuplot can be executed using the command "gnuplot".

1. Download a copy of the Abscissa source code from Github. The latest release 
   version can be downloaded from Github using,

       wget https://github.com/bsilbaugh/chicken-abscissa/archive/v0.1.0.tar.gz

   or if you prefer the zip format

       wget https://github.com/bsilbaugh/chicken-abscissa/archive/v0.1.0.zip

   The latest development version can be obtained by downloading a snapshop
   from Github,

       wget https://github.com/bsilbaugh/chicken-abscissa/archive/master.zip

   or cloning the repository,

       git clone https://github.com/bsilbaugh/chicken-abscissa.git


2. Unpack the downloaded archive file; e.g.

       tar -xzvf chicken-abscissa-v0.1.0.tar.gz

   or if you downloaded the archive in the zip format

       unzip chicken-abscissa-v0.1.0.zip

3. Change the current working directory to the newly unpacked directory

       cd chicken-abscissa

4. Compile and install using the chicken-install program; e.g.

       chicken-install

  or

      chicken-install -sudo

  if you're egg repository requires super user privileges. Also see the
  Chicken Scheme User Manual and Wiki for additional installation options.