NAME
PostScript::XYChart - graph lines and points
SYNOPSIS
use PostScript::XYChart;
# Draw a graph from data in the CSV file
# 'results.csv', and saves it as 'results.ps'
my $xy = new PostScript::XYChart();
$xy->line_from_file( "results.csv", "Results" );
$xy->build_chart();
$xy->output("results");
# Or with more direct control
use PostScript::XYChart;
use PostScript::GraphStyle qw(defaults);
$PostScript::GraphStyle::defaults{gray} =
[ [ 1, 1, 0 ], # yellow
[ 0, 1, 0 ], # green
[ 0, 1, 1 ], ]; # cyan
my $xy = new PostScript::XYChart(
file => {
errors => 1,
eps => 0,
landscape => 1,
paper => 'Letter',
},
chart => {
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(gray 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");
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.
$xy = new PostScript::XYChart(
file => {
# for PostScript::File
eps => 1,
},
chart => {
# for PostScript::GraphPaper
title => "My Graph",
},
x_axis => {
# for PostScript::GraphPaper
font => "Courier",
},
y_axis => {
# for PostScript::GraphPaper
rotate => 1,
},
style => {
# for PostScript::GraphStyle
color => 1,
},
key => {
# for PostScript::GraphKey
num_items => 5,
},
);All the settings are optional and the defaults work reasonably well. For convenience, the full tree of over 140 options is given below. See the relevant manpage for full details. The most useful ones are marked with (*).
From PostScript::File
file
debug
errors *
headings
reencode
bottom
clip_command
clipping
dir
eps *
file
font_suffix
height
landscape *
left
paper *
right
top
width
db_active
db_base
db_bufsize
db_color
db_font
db_fontsize
db_xgap
db_xpos
db_xtab
db_ytop
incpage_handler
page
stripFrom PostScript::GraphPaper
chart
background
bottom_edge
color *
dots_per_inch
font
font_color
font_size
heading
heading_font
heading_font_color
heading_font_size
heading_height
heavy_color
heavy_width
key_width
left_edge
light_color
light_width
mid_color
mid_width
right_edge
right_margin
spacing
top_edge
top_margin
x_axis
center
font
font_color
font_size
height
high
label_gap
labels
labels_req
low
mark_min
mark_max
rotate
smallest *
title
width
y_axis
(same as x_axis)From PostScript::GraphStyle
style
auto *
color *
same *
line
color
dashes
inner_color
inner_dashes
inner_width
outer_color
outer_dashes
outer_width
width
point
color
inner_color
inner_width
outer_color
outer_width
shape
size
width
bar
color
inner_color
inner_width
outer_color
outer_width
width
From PostScript::GraphKey
key
file
background
graph_paper
horizontal_spacing
icon_height
icon_width
max_height
num_items
outline_color
outline_width
spacing *
text_color
text_font
text_size
text_width
title
title_color
title_font
title_size
vertical_spacingOBJECT 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::GraphStyle object. If present, the object is created with the options specified.
style-
It is also acceptable to create a PostScript::GraphStyle 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::GraphStyle object. If present, the object is created with the options specified.
style-
It is also acceptable to create a PostScript::GraphStyle object independently and pass that in here.
The comma seperated file should contain data in the form:
x0, y0
x1, y1
x2, y2Optionally, 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.50Where 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()
The main method. It calculates the scales from the data collected, draws the graph paper, puts the lines on it and adds a key.
SUPPORTING METHODS
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.
file
Return the underlying PostScript::File object.
graph_key
Return the underlying PostScript::GraphKey object. Only available after a call to build_chart.
graph_paper
Return the underlying PostScript::GraphPaper object. Only available after a call to build_chart.
newpage( [page] )
Start a new page in the underlying PostScript::File object. See "newpage" in PostScript::File and "set_page_label" in PostScript::File.
output( file [, dir] )
Output the chart as a file. See "output" in PostScript::File.