/ 
PostScript-Graph-1.02
River stage zero No dependents
/ PostScript::Graph::XY

NAME

PostScript::Graph::XY - graph lines and points

SYNOPSIS

Simplest

Draw a graph from data in the CSV file 'results.csv', and saves it as 'results.ps':

use PostScript::Graph::XY;

my $xy = new PostScript::Graph::XY();
$xy->build_chart("results.csv");
$xy->output("results");

Typical

With more direct control:

    use PostScript::Graph::XY;
    use PostScript::Graph::Style;

    my $seq = PostScript::Graph::Sequence;
    $seq->setup('color',
	[ [ 1, 1, 0 ],	    # yellow
	  [ 0, 1, 0 ],	    # green
	  [ 0, 1, 1 ], ],   # cyan
      );
	
    my $xy = new PostScript::Graph::XY(
	    file  => {
		errors    => 1,
		eps       => 0,
		landscape => 1,
		paper     => 'Letter',
	    },
	    
	    layout => {
		dots_per_inch => 72,
		heading       => "Example",
		background    => [ 0.9, 0.9, 1 ],
		heavy_color   => [ 0, 0.2, 0.8 ],
		mid_color     => [ 0, 0.5, 1 ],
		light_color   => [ 0.7, 0.8, 1 ],
	    },
	    
	    x_axis => {
		smallest => 4,
		title    => "Control variable",
		font     => "Courier",
	    },
	    y_axis => {
		smallest => 3,
		title    => "Dependent variable",
		font     => "Courier",
	    },
	    
	    style  => {
		auto  => [qw(color dashes)],
		color => 0,
		line  => {
		    inner_width  => 2,
		    outer_width  => 2.5,
		    outer_dashes => [],
		},
		point => {
		    shape => "circle",
		    size  => 8,
		    color => [ 1, 0, 0 ],
		},
	    },
	    
	    key    => {
		    background => 0.9,
	    },
	);

    $xy->line_from_array(
	[ [ qw(Control First Second Third Fourth),
	    qw(Fifth Sixth Seventh Eighth Nineth)],
	  [ 1, 0, 1, 2, 3, 4, 5, 6, 7, 8 ],
	  [ 2, 1, 2, 3, 4, 5, 6, 7, 8, 9 ],
	  [ 3, 2, 3, 4, 5, 6, 7, 8, 9,10 ],
	  [ 4, 3, 4, 5, 6, 7, 8, 9,10,11 ], ]
	);
    $xy->build_chart();
    $xy->output("controlled");

All options

    $xy = new PostScript::Graph::XY(
	file    => {
	    # see PostScript::File
	},
	layout  => {
	    # see PostScript::Graph::Paper
	},
	x_axis  => {
	    # see PostScript::Graph::Paper
	},
	y_axis  => {
	    # see PostScript::Graph::Paper
	},
	style   => {
	    # see PostScript::Graph::Style
	},
	key     => {
	    # see PostScript::Graph::Key
	},
	chart   => {
	    # see 'new' below 
	},
    );

DESCRIPTION

A graph is drawn on a PostScript file from one or more sets of numeric data. Scales are automatically adjusted for each data set and the style of lines and points varies between them. A title, axis labels and a key are also provided.

CONSTRUCTOR

new( [options] )

options may be either a list of hash keys and values or a hash reference. Either way, the hash should have the same structure - made up of keys to several sub-hashes. Only one (chart) holds options for this module. The other sections are passed on to the appropriate module as it is created.

Hash Key	Module
========	======
file	PostScript::File
layout	PostScript::Graph::Paper
x_axis	PostScript::Graph::Paper
y_axis	PostScript::Graph::Paper
style	PostScript::Graph::Style
key		PostScript::Graph::Key
chart	this one, see below

data

This may be either an array or the name of a CSV file. See line_from_array or line_from_file for details. If data is given here, the chart is built automatically. There is no opportunity to add extra lines (they should be included in this data) but there is no need to call build_chart explicitly as the chart is ready for output.

show_key

Set to 0 if key panel is not required. (Default: 1)

show_lines

Set to 0 to hide lines and make a scatter graph. (Default: 1)

show_points

Set to 0 to hide points. (Default: 1)

All the settings are optional and the defaults work reasonably well. See the other PostScript manpages for details of their options.

OBJECT METHODS

line_from_array( data [, label | opts | style ]... )

data

An array reference pointing to a list of positions.

label

A string to represent this line in the Key.

opts

This should be a hash reference containing keys and values suitable for a PostScript::Graph::Style object. If present, the object is created with the options specified.

style

It is also acceptable to create a PostScript::Graph::Style object independently and pass that in here.

One or more lines of data is added to the chart. This may be called many times before the chart is finalized with build_chart.

Each position is the data array contains an x value and one or more y values. For example, the following points will be plotted on an x axis from 2 to 4 a y axis including from 49 to 57.

[ [ 2, 49.7 ],
  [ 3, 53.4 ],
  [ 4. 56.1 ], ]

This will plot three lines with 6 points each.

[ ["X", "Y", "Yb", "Yc"],
  [x0, y0, yb0, yc0],
  [x1, y1, yb1, yc1],
  [x2, y2, yb2, yc2],
  [x3, y3, yb3, yc3],
  [x4, y4, yb4, yc4],
  [x5, y5, yb5, yc5], ]

The first line is made up of (x0,y0), (x1,y1)... and these must be there. The second line comes from (x0,yb0), (x1,yp1)... and so on. Optionally, the first row of data in the array may be labels for the X and Y axis, and then for each line.

Where multiple lines are given, it is best to specify label as an option. Otherwise it will default to the name of the first line - rarely what you want. Of course this is ignored if the new option 'y_axis => title' was given.

line_from_file( file [, label|opts|style ]... )

file

The name of a CSV file.

label

A string to represent this line in the Key.

opts

This should be a hash reference containing keys and values suitable for a PostScript::Graph::Style object. If present, the object is created with the options specified.

style

It is also acceptable to create a PostScript::Graph::Style object independently and pass that in here.

The comma seperated file should contain data in the form:

x0, y0
x1, y1
x2, y2

Optionally, the first line may hold labels. Any additional columns are interpreted as y-values for additional lines. For example:

Volts, R1k2, R1k8, R2k2
4.0,   3.33, 2.22, 1.81
4.5,   3.75, 2.50, 2.04
5.0,   4.16, 2.78, 2.27
5.5,   4.58, 3.05, 2.50

Where multiple lines are given, it is best to specify label as an option. Otherwise it will default to the name of the first line - rarely what you want. Of course the new option 'y_axis => title' takes precedence over both.

Note that the headings have to begin with a non-digit in order to be recognized as such.

build_chart([ file | data [, label | opts | style ]... ])

data

An array reference pointing to a list of positions. See "line_from_array".

file

The name of a CSV file. See "line_from_file".

label

A string to represent this line in the Key.

opts

This should be a hash reference containing keys and values suitable for a PostScript::Graph::Style object. If present, the object is created with the options specified.

style

It is also acceptable to create a PostScript::Graph::Style object independently and pass that in here.

If the first parameter is an array they are all passed to line_from_array, otherwise if there are any parameters they are passed to line_from_file. With no parameters, either of these two functions must have already been called.

This method then calculates the scales from the data collected, draws the graph paper, puts the lines on it and adds a key.

SUPPORTING METHODS

file

Return the underlying PostScript::File object.

graph_key

Return the underlying PostScript::Graph::Key object. Only available after a call to build_chart.

graph_paper

Return the underlying PostScript::Graph::Paper object. Only available after a call to build_chart.

sequence()

Return the style sequence being used. This is only required when you wish to alter the ranges used by the auto style feature.

output( file [, dir] )

Output the chart as a file. See "output" in PostScript::File.

newpage( [page] )

Start a new page in the underlying PostScript::File object. See "newpage" in PostScript::File and "set_page_label" in PostScript::File.

add_function( name, code )

Add functions to the underlying PostScript::File object. See "add_function" in PostScript::File for details.

add_to_page( [page], code )

Add postscript code to the underlying PostScript::File object. See "add_to_page" in PostScript::File for details.

CLASS METHODS

The PostScript functions are provided as a class method so they are available to modules not needing an XY object.

BUGS

This is still alpha software. It has only been tested in limited, predictable conditions and the interface is subject to change.

AUTHOR

Chris Willmot, chris@willmot.org.uk

SEE ALSO

PostScript::File, PostScript::Graph::Style, PostScript::Graph::Key, PostScript::Graph::Paper, PostScript::Graph::Bar, Finance::Shares::Chart.