Finance::Shares::Chart - Draw stock quotes on a PostScript graph
use Finance::Shares::Chart; use Finance::Shares::Chart 'deep_copy'; # ensure quotes data exists my $fss = new Finance::Shares::Sample(...); # add data lines with e.g. $fss->add_line('prices', $id, $data, $key, $style); # optional support objects my $psf = new PostScript::File(...); my $seq = new PostScript::Graph::Sequence; $seq->setup(...); $seq->auto(...); # create the Chart object my $fsc = new Finance::Shares::Chart( file => $psf, sample => $fss, dots_per_inch => 72, background => [1, 1, 0.9], bgnd_outline => 1, reverse => 1, heading => 'Results chart', heading_font => { font => 'Times-Bold', size => 12, color => [0, 0, 0.7], }, normal_font => { # as heading_font }, key => { # see PostScript::Graph::Key }, x_axis => { show_lines => 1, show_weekday=> 1, show_day => 1, show_month => 1, show_year => 1, changes_only=> 0, # see PostScript::Graph::Paper }, prices => { sequence => $seq, show_dates => 1, percent => 25, layout => { # see PostScript::Graph::Paper }, y_axis => { smallest => 4, # see PostScript::Graph::Paper }, points => { # style settings }, }, volumes => { # as prices, but with 'bars' # instead of 'points' }, cycles => { # as prices, but without 'points' }, tests => { # as prices, but without 'points' }, ); # draw the chart and output it $fsc->build_chart(); $fsc->output($filename);
The chart produced by this module is about A4 size by default and has up to four graphs stacked vertically, with key panels to the right of each one.
This panel must always be present. It shows the share prices, usually showing opening and closing prices on a high-low range. Lines drawn on this are usually functions acting on the price data.
If volume data exists, it is placed on this chart. Lines drawn here are usually functions acting on the volume data.
This axis has a negative as well as a positive range, designed for graphing functions describing how the prices change.
Tests applied to functions from the other graphs would typically place their results here. By default, the axis ranges from 0 to 100 to indicate a confidence percentage.
Specifications are given to the constructor, the most important being the Finance::Shares::Sample holding the data and function and test lines. Lines can be added to the sample until build_chart is invoked, typically by calling the output method.
As can be seen from the "SYNOPSIS" there are a number of top-level parameters which apply to all visible graphs, followed by a sub-group controlling each graph independently. Of particular interest are the graph parameters percent and show_dates which control how the vertical space is allocated. Horizontal space is allocated automatically, with the key panels taking up as much space as needed to describe the superimposed lines.
Each graph also has its own sequence. This tries to make sure that the lines on that graph all have different characteristics in terms of colour, point shape, dash pattern and so on.
If no PostScript::File is given to the constructor, one is generated. However, passing an existing PostScript::File object means that several charts can be placed on the one file. See "build_chart".
options can be a hash ref or a list of hash keys and values. The top level keys are as follows.
options
The background colour for all the graphs. This can be a shade of grey (0.0 for black, 1.0 for brightest) or an array ref holding similar decimals for red, green and blue, e.g. [ 0.6, 0.4, 0 ] for a red-orange. (Default: 1.0)
By default the price and volume marks are drawn with a contrasting outline. Setting this to 1 makes this outline the same colour as the background. (Default: 0)
The dates can be shown with every part (day, month etc) shown on every label, or with these parts only shown when they change. (Default: 1)
A hash ref controlling the appearance of the cycles graph. See "'Individual graphs'" for details.
One of the advantages of PostScript output is that it can make the best use of each medium. Setting this to 72 produces output suitable for most computer monitors. Use a higher figure for hard copy, depending on you printer's capabilities. (Default: 300)
This can be either a PostScript::File object or a hash ref holding parameters suitable for creating one. The default is to set up a landscape A4 page with half inch margins.
Generating PostScript is a one-way process. It is not possible to find out how much space will be taken up by a string using a proportional spaced font, so guesses are made. This allows that guess to be fine tuned. (Default: 0.5)
A hash ref holding font settings for the main heading. See normal_font for details.
If true, the order in which lines are drawn is reversed.
A hash ref controlling the appearance of the key panels. The following keys are recognized. See PostScript::Graph::Key for details.
background outline_color outline_width title title_font text_font spacing horz_spacing vert_spacing text_width icon_height icon_width glyph_ratio
A hash ref holding font settings for the text used for axis labels etc. It may contain these keys:
The font family name which should be one of the following. (Default: 'Helvetica')
Courier Courier-Bold Courier-BoldOblique Courier-Oblique Helvetica Helvetica-Bold Helvetica-BoldOblique Helvetica-Oblique Times-Roman Times-Bold Times-BoldItalic Times-Italic Symbol
Point size to use. (Default: 10)
The normal colour format: either a grey value or an array ref holding [<red>,<green>,<blue>]. (Default: 1.0)
An optional string used as the PostScript page 'number'. Although this may be anything many programs expect this to be short like a page number, with no spaces.
A hash ref controlling the appearance of the prices graph. See "'Individual graphs'" for details.
The Finance::Shares::Sample object holding the data to be displayed. Required - no default.
The underlying PostScript::Graph::Paper module will sometimes generate more subdivisions and axis lines than needed, especially at high resolutions. smallest provides some control over this for the Y axes. It specifies the size of the smallest gap between lines; giving a larger number means fewer lines. The default produces 3 dots at the resolution given to dots_per_inch.
smallest
Note that the only way to control the line density on the X axis is to plot fewer dates. One way of doing this is to set the Finance::Shares::Sample contructor option dates_by to 'weeks' or 'months'.
dates_by
A hash ref controlling the appearance of the volumes graph. See "'Individual graphs'" for details.
A hash ref controlling the appearance of the dates axis and the vertical grid lines. These keys are defined in this module:
True means that vertical lines are to be shown on all the graphs. This can get a little crowded if a lot of dates are shown. (Default: 1)
True means the day of the week is to be shown on the date axis. (Default: 0)
True means the day of the month is to be shown on the date axis. The default depends on the timescale of the sample.
True means the month abbreviation is to be shown on the date axis. The default depends on the timescale of the sample.
True means the year is to be shown on the date axis. The default depends on the timescale of the sample.
The date labels can either show all parts (day, month etc.) on every date or only show them as they change. (Default: 1)
These keys are also recognized within x_axis. See PostScript::Graph::Paper for details.
title color heavy_color mid_color heavy_width mid_width mark_min mark_max
'heavy' vertical lines are those marked with a date lablel. Date positions whose labels have been omitted are marked with 'mid' lines. Although there is no way to stop these from being drawn, the chart can be made visually simpler by setting mid_width to 0 and/or mid_color to the background color.
mid_width
mid_color
prices, volumes, cycles and tests all use extensive hash refs. More or less, these are passed on to PostScript::Graph::Paper and friends. To make them more manageable, they are broken down into sub-hashes. Here are the top level keys within each graph.
A hash ref controlling how the volume data is to be displayed. Only relevant for the volume graph. These are the recognized keys; see PostScript::Graph::Style for details.
color inner_color outer_color width inner_width outer_width
A hash ref controlling some general aspects of the graph. The following keys are recognized. See PostScript::Graph::Paper for details.
spacing top_margin right_margin
This is the proportion of space allocated to the graph. Specifying 0 hides it. It is not a strict percentage in that they don't all have to add up to 100, but it does give an idea of the sort of numbers to put here. There may be problems if the value is less than 10, or so small the graph cannot physically be drawn in the space.
Some graphs will become visible automatically (provided their percent is not 0) if data or lines should be shown there. They take a default value of 20.
A hash ref controlling how the price data is to be displayed. Only relevant for the price graph. These are the recognized keys; see PostScript::Graph::Style for details.
size shape* color width inner_color outer_color inner_width outer_width
*The allowed values for shape are 'stock', 'stock2', 'close' and 'close2' and NOT as listed under "shape" in PostScript::Graph::Style.
Lines added to a graph are shown by default with slightly differing styles controlled by a PostScript::Graph::Sequence object. Each graph has a default sequence which can be accessed by the sequence() method. Alternatively, you can set up your own sequence and declare it here. See PostScript::Graph::Style for details.
True if the dates axis is to be shown under this chart. By default the dates are placed under the first graph that hasn't specified show_dates => 0.
These keys are recognized within y_axis. See PostScript::Graph::Paper for details.
color heavy_color mid_color light_color smallest heavy_width mid_width light_width title mark_min mark_max label_gap si_shift
This provides access to the PostScript::Graph::Sequence object which by default controls the styles of lines placed on each of the graphs. graph is one of 'prices', 'volumes', 'cycles', 'tests'.
graph
Example
Here, a number of lines (moving averages) are drawn on a chart. Each line will be given a different colour even though they are all have the same style options.
my $fss = Finance::Shares::Sample( ... ); my $fsc = Finance::Shares::Chart( sample => $fss, ... ); my $pseq = $fsc->sequence( 'prices' ); $pseq->auto( qw(color dashes shape) ); my $style = { sequence => $pseq, width => 2, }; $fss->simple_average( period => 5, style => $style, ); $fss->simple_average( period => 15, style => $style, ); $fss->simple_average( period => 30, style => $style, );
See PostScript::Graph::Style for details concerning sequences and styles.
The graphs are constructed and written out to a PostScript file. A suitable suffix (.ps, .epsi or .epsf) will be appended to the file name.
If no filename is given, the PostScript text is returned. This makes handling CGI requests easier.
If given, file should be a PostScript::File object or a hash ref suitable for creating one.
file
This writes the appropriate PostScript to either the file given or one created internally. This is normally called by output() and should only need calling directly if several charts are to be placed on the same file.
# Create the file my $pf = new PostScript::File(...); # Create the necessary samples my $s1 = new Finance::Shares::Sample(...); my $s2 = new Finance::Shares::Sample(...); my $s3 = new Finance::Shares::Sample(...); # add lines as required $s1->add_line(...); $s2->add_line(...); ... # Create a chart object for each sample my $ch1 = new Finance::Shares::Chart( file => $pf, sample => $s1, ... ); my $ch2 = new Finance::Shares::Chart( file => $pf, sample => $s2, ... ); my $ch3 = new Finance::Shares::Chart( file => $pf, sample => $s3, ... ); # add more lines if required $s3->add_line(...); # Build the charts on seperate pages $ch1->build_chart(); $pf->newpage(); $ch2->build_chart(); $pf->newpage(); $ch3->build_chart(); $pf->newpage(); # Output the file $pf->output($filename);
Returns true if the graph or line is visible. graph must be one of the graph names. If entry is given it should be a ref to the line's data structure, as stored in Sample.
entry
Return the Finance::Shares::Sample holding the data for this chart.
Return the heading printed at the top of the chart.
Return the page identifier, if any.
If id is given this replaces the returned value.
id
The PostScript code is a class method so that it may be available to other classes that don't need a Stock object.
The useful functions in the 'gstockdict' dictionary draw a stock chart mark and a close mark in either one or two colours.
make_stock make_stock2 make_close make_close2
The all consume 5 numbers from the stack (even if they aren't all used):
x yopen ylow yhigh yclose
A few functions are defined in the gstockdict dictionary. These provide the code for the shapes drawn as price marks. These dictionary entries are defined:
make_stock Draw single price mark make_stock2 Draw double price mark make_close Draw single closing price mark make_close2 Draw double closing price mark yclose parameter ylow parameter yhigh parameter yopen parameter x parameter dx working value
A postscript function suitable for passing to the shape option to new must have 'make_' preprended to the name. It should take 5 parameters similar to the code for shape = 'stock'> which is called as follows.
shape
shape =
x yopen ylow yhigh yclose make_stock
var is returned unless it is, or contains, a hash ref or an array ref. These are copied recursively and the copy is returned.
var
The complexity of this software has seriously outstripped the testing, so there will be unfortunate interactions. Please do let me know when you suspect something isn't right. A short script working from a CSV file demonstrating the problem would be very helpful.
Chris Willmot, chris@willmot.org.uk
Finance::Shares::Sample, PostScript::Graph::Style and Finance::Shares::Model.
There is also an introduction, Finance::Shares::Overview and a tutorial beginning with Finance::Shares::Lesson1.
To install TestFuncs, copy and paste the appropriate command in to your terminal.
cpanm
cpanm TestFuncs
CPAN shell
perl -MCPAN -e shell install TestFuncs
For more information on module installation, please visit the detailed CPAN module installation guide.