guile-charting/doc/guile-charting.texi

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename guile-charting.info
@settitle Guile Charting
@c %**end of header

@copying 
This manual is for Guile Charting (version 0.2.0, updated 19 September
2014)

Copyright 2014 Andy Wingo

@quotation 
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 3 of the License or (at
your option) any later version.  You should have received a copy of the
GNU Lesser General Public License along with this manual; if not, see
http://www.gnu.org/licenses/.

@end quotation

@end copying

@dircategory The Algorithmic Language Scheme
@direntry 
* Guile Charting: (guile-charting.info).  Making graphs and charts with Guile Scheme.
@end direntry

@titlepage 
@title Guile Charting
@subtitle version 0.2.0, updated 19 September 2014
@author Andy Wingo (@email{wingo@@pobox.com})
@page 
@vskip 0pt plus 1filll
@insertcopying 
@end titlepage

@ifnottex 
@node Top
@top Guile Charting
@insertcopying 
@menu 
* charting::             Main charting interface
* charting draw::        Lower-level drawing operators

* Concept Index::        
* Function Index::       
@end menu

@end ifnottex

@iftex 
@shortcontents 
@end iftex

@node charting
@chapter (charting)
@section Overview
@section Usage
@anchor{charting make-bar-chart}@defun make-bar-chart [title] [data] [write-to-png] [bar-width] [group-spacing] [chart-height] [max-y] [chart-params] [legend-params] [ytick-label-formatter] [bar-value-formatter]
Make a bar chart.

The format of @var{data} is defined as follows:

@table @var
@item data
(@var{group}+)

@item group
(@var{group-label} @var{bar}+)

@item group-label
A string, to be written to the X axis.

@item bar
(@var{height} @var{bar-params}?)

@item height
The bar height, as a number.

@item bar-params
A property list suitable to passing to @ref{charting draw draw-bar}.

@end table

This function returns the cairo surface.  By default, make-chart will
create an image surface, but you may override this by passing a
@code{#:make-surface} function in the @var{chart-params}.  In this way
you can render charts to any surface supported by Cairo, e.g.  PS, PDF,
SVG, GDK, etc.

The #:write-to-png option will write the chart out to the PNG file that
you name.

An example invocation might look like:

@example 
 (make-bar-chart "Average Height at Iihenda JSS"
                 '(("Grade 9" (150 "Boys") (140 "Girls"))
                   ("Grade 10" (150 "Boys")
                               (140 "Girls" (#:y+-bracket 5 #:y--bracket 4.5))))
                 #:write-to-png "/tmp/graph.png")
@end example

@end defun

@anchor{charting make-chart}@defun make-chart [title] [chart-height] [chart-width] [font-family] [line-width] [title-text-height] [axis-text-height] [x-axis-label] [y-axis-label] [tick-size] [y-axis-ticks] [x-axis-ticks] [y-axis-tick-labels] [x-axis-tick-labels] [x-axis-tick-mode] [y-axis-tick-mode] [chart-margin] [margin] [padding-left] [padding-right] [padding-top] [padding-bottom] [make-surface]
Make a chart.

@var{tick-lables} is an alist of label-value pairs, where the value is
given in chart height coordinates.  The label can be #f.

This function makes the basic chart, setting up the basics like the
title, axes, etc.  You probably don't want to call this unless you are
making a custom chart type.

This function returns a cairo context whose coordinate system has been
flipped so that the origin of the chart is (0, 0), with positive in the
northeast quadrant.

@end defun

@anchor{charting make-page-map}@defun make-page-map [title] [data] [write-to-png] [margin] [page-size] [page-width] [page-height] [page-spacing] [title-text-height] [text-height] [label-bar-spacing] [font-family]
@verbatim 
Make a page map.

A page map shows the components of a one-dimensional space.  Each
component has a label, a start, and a size.  The result is a graphical
representation of the space, divided in @@var@{page-size@} strips, along
with a summary list of the different components.

The format of @@var@{data@} is as follows:

@@example
 ((@@var@{label@} . (@@var@{start@} . @@var@{size@})) ...)@}
@@end example

@@var@{label@} should be a string.  @@var@{start@} and @@var@{size@} should be
numbers.

The #:write-to-png option will write the chart out to the PNG file
that you name.

An example invocation might look like:

@@example
 (make-page-map
  "foo.so"
  '((".text" 1024 65535)
    (".data" 65536 20)
    (".rodata" 65556 200))
  #:write-to-png "foo.png")
@@end example
@end verbatim

@end defun

@anchor{charting make-performance-chart}@defun make-performance-chart [title] [data] [write-to-png] [box-width] [box-spacing] [test-spacing] [chart-height] [max-y] [min-y] [chart-params] [legend-params] [ytick-label-formatter] [box-value-formatter]
Make a performance chart.

A performance chart compares runtimes for some set of tests across some
set of scenarios.

The format of @var{data} is defined as follows:

@example 
 ((@var{scenario} (@var{test} @var{data-point} ...) ...) ...)
@end example

@var{scenario} and @var{test} should be strings.  @var{data-point}
should be numbers.

The resulting plot will have time on the Y axis, and one X axis entry
for each test.  Each test/scenario data set will be represented as a box
plot.  In the future we should add more options (for example, a small
vertical histogram on the plot).

This function returns the cairo surface.  By default, make-chart will
create an image surface, but you may override this by passing a
@code{#:make-surface} function in the @var{chart-params}.  In this way
you can render charts to any surface supported by Cairo, e.g.  PS, PDF,
SVG, GDK, etc.

The #:write-to-png option will write the chart out to the PNG file that
you name.

An example invocation might look like:

@example 
 (make-performance-chart
  "Gabriel Benchmarks"
  '(("guile-1.8"
     ("tak" 0.12 0.13 0.17)
     ("fib" 1.13 1.24 1.05))
    ("guile-2.0"
     ("tak" 0.05 0.051 0.047)
     ("fib" 0.64 0.59 0.71)))
  #:write-to-png "/tmp/graph.png")
@end example

@end defun

@anchor{charting make-performance-series}@defun make-performance-series [title] [data] [write-to-png] [box-width] [box-spacing] [test-spacing] [chart-height] [max-y] [min-y] [chart-params] [annotations] [ytick-label-formatter] [box-value-formatter]
Make a performance chart.

A performance chart compares runtimes for some set of tests across some
set of scenarios.

The format of @var{data} is defined as follows:

@example 
 ((@var{x} @var{data-point} ...) ...)
@end example

@var{x} and @var{data-point} should be numbers.

The resulting plot will have time on the Y axis, and one X axis entry
for each test.  Each data set will be represented as a box plot.  In the
future we should add more options (for example, a small vertical
histogram on the plot).

This function returns the cairo surface.  By default, make-chart will
create an image surface, but you may override this by passing a
@code{#:make-surface} function in the @var{chart-params}.  In this way
you can render charts to any surface supported by Cairo, e.g.  PS, PDF,
SVG, GDK, etc.

The #:write-to-png option will write the chart out to the PNG file that
you name.

An example invocation might look like:

@example 
 (make-performance-chart
  "Gabriel Benchmarks"
  '(("guile-1.8"
     ("tak" 0.12 0.13 0.17)
     ("fib" 1.13 1.24 1.05))
    ("guile-2.0"
     ("tak" 0.05 0.051 0.047)
     ("fib" 0.64 0.59 0.71)))
  #:write-to-png "/tmp/graph.png")
@end example

@end defun

@anchor{charting make-scatter-plot}@defun make-scatter-plot [title] [data] [write-to-png] [test-spacing] [chart-height] [min-x] [max-x] [min-y] [max-y] [log-x-base] [log-y-base] [chart-params] [legend-params] [x-axis-label] [y-axis-label] [tick-label-formatter]
Make a scatter plot.

A scatter plot shows a number of series as individual points.

The format of @var{data} is defined as follows:

@example 
 ((@var{series} (@var{x} . @var{y}) ...) ...)
@end example

@var{series} should be a string.  @var{x} and @var{y} should be numbers.

This function returns the cairo surface.  By default, make-chart will
create an image surface, but you may override this by passing a
@code{#:make-surface} function in the @var{chart-params}.  In this way
you can render charts to any surface supported by Cairo, e.g.  PS, PDF,
SVG, GDK, etc.

The #:write-to-png option will write the chart out to the PNG file that
you name.

An example invocation might look like:

@example 
 (make-scatter-plot
  "MPG for cars"
  '(("ford" (1 . 2) (2 . 3))
    ("opel" (1.2 . 3.5) (4.5 . 1)))
  #:write-to-png "/tmp/graph.png")
@end example

@end defun

@node charting draw
@chapter (charting draw)
@section Overview
@verbatim 
 
@end verbatim

@section Usage
@anchor{charting draw draw-annotations}@defun draw-annotations [cr] [annotations] [xticks] [width] [height]
@end defun

@anchor{charting draw draw-axis-label}@defun draw-axis-label [cr] [text] [text-height] [axis-length] [vertical?]
Draw an axis label.

The label will be drawn such that the current position of @var{cr} is
the closest corner of the label's bounding box.

@end defun

@anchor{charting draw draw-background}@defun draw-background [cr]
Draw the background.

@end defun

@anchor{charting draw draw-bar}@defun draw-bar [cr] [height] [scale] [bar-width] [bar-value-formatter] [series] [decorator]
Draw a single bar.

@var{cr} is expected to have been placed at the lower left corner of
where the bar should be.  @var{decorator} is a property list that can be
passed to @ref{charting draw draw-decorator}.

@end defun

@anchor{charting draw draw-bar-group}@defun draw-bar-group [cr] [data] [bar-width] [scale] [bar-value-formatter]
Draw a group of bars.

@var{data} is a property list suitable for passing to @ref{charting draw
draw-bar}.  @var{cr} is expected to have been positioned along the x
axis in the center of where the bar group should be displayed.

@end defun

@anchor{charting draw draw-bar-legend}@defun draw-bar-legend [cr] [data] [width] [text-height] [font-family] [horizontal-spacing] [vertical-spacing]
Draw a "bar legend".

A bar legend is meant to show what categories exist, as well as
indicating their contribution to a graph.  Use a bar legend if it would
be confusing to label some other chart in which the pixel count of a
category is proportional to its magnitude, but you want to make sure to
label all categories, even those with small magnitudes.

@var{data} is as in @ref{charting draw draw-page-map}.  The legend will
be written below the current position of @var{cr}.

@end defun

@anchor{charting draw draw-chart-area}@defun draw-chart-area [cr] [width] [height]
Draw the actual box for the chart background.

@var{cr} is expected to have been positioned at the origin.

@end defun

@anchor{charting draw draw-decorator}@defun draw-decorator [cr] [scale] [label] [y+-bracket] [y--bracket] [y-bracket]
Draw a decorator.

A decorator is something drawn around a point, such as error bars.  This
function currently supports drawing error bars in the Y direction, which
are specified individually as @var{y+-bracket} and @var{y--bracket}.

@end defun

@anchor{charting draw draw-grid}@defun draw-grid [cr] [ticks] [width] [vertical?]
Draw grid lines.

@var{ticks} is a list of positions in the current cairo coordinate
system.  @var{width} is the that the grid lines should be: the chart
width of @var{vertical?}, and the height otherwise.

@end defun

@anchor{charting draw draw-legend}@defun draw-legend [cr] [expand-right?] [expand-down?] [measure-only?] [text-height] [draw-outlines?] [draw-background?] [text-measurer] [series-list]
Draw a legend.

@var{series-list} is expected to be a list of series names.  The
@var{cr} is expected to be positioned at one of the corners of the
legend; @var{expand-right?} and @var{expand-down?} control which way the
legend will be rendered.

@end defun

@anchor{charting draw draw-page-map}@defun draw-page-map [cr] [data] [chart-width] [chart-height] [page-size] [page-height] [page-spacing]
Draw a page map for the given data set.

@var{data} := @code{(@var{label} .  (@var{start} .  @var{size})) ...)}

@var{label} is a string, and @var{start} and @var{size} are numbers.
@var{cr} is expected to have been positioned at the lower-left corner of
the chart area.

@end defun

@anchor{charting draw draw-perf-series}@defun draw-perf-series [cr] [data] [xticks] [box-width] [box-spacing] [min-y] [y-scale] [box-value-formatter]
Draw a group of boxes corresponding to runs of one benchmark in
different scenarios.

@var{data} := @code{(@var{x} @var{point} ...) ...)}

, where the series is a string, and the points are numbers.  @var{cr} is
expected to have been positioned along the x axis in the center of where
the data for the test should be displayed.

@end defun

@anchor{charting draw draw-perf-test}@defun draw-perf-test [cr] [data] [box-width] [box-spacing] [min-y] [y-scale] [box-value-formatter]
Draw a group of boxes corresponding to runs of one benchmark in
different scenarios.

Each scenario corresponds to a series.  The format of @var{data} is
@code{((@var{series} @var{point} ...) ...)}, where the series is a
string, and the points are numbers.  @var{cr} is expected to have been
positioned along the x axis in the center of where the data for the test
should be displayed.

@end defun

@anchor{charting draw draw-point}@defun draw-point [cr] [x] [y] [label]
Draw a point at the current position.

@end defun

@anchor{charting draw draw-tick-labels}@defun draw-tick-labels [cr] [tick-labels] [tick-size] [vertical?] [text-height]
Draw tick labels on an axis.

@var{tick-labels} is an alist of label-position pairs, where position is
in the current cairo coordinate system, along one axis.

@end defun

@anchor{charting draw draw-ticks}@defun draw-ticks [cr] [ticks] [tick-size] [vertical?]
Draw ticks on an axis.

@var{ticks} is a list of positions in the current cairo coordinate
system.

@end defun

@anchor{charting draw draw-title}@defun draw-title [cr] [text] [font-size]
Draw a title.

@var{cr} is expected to have been positioned at the lower boundary of
where the title should be written, in the center.

@end defun

@anchor{charting draw reset-colors!}@defun reset-colors! 
@end defun

@node Concept Index
@unnumbered Concept Index
@printindex cp
@node Function Index
@unnumbered Function Index
@printindex fn
@bye