PostScript::Graph::Stock - draw share price graph from CSV data
Take a CSV file such as that produced by !Yahoo Finance websites (called 'stock_prices.csv' here), draw a graph showing the price and volume data and output as a postscript file for printing ('graph.ps' in this example).
use PostScript::Graph::Stock; my $pgs = new PostScript::Graph::Stock(); $pgs->build_chart( 'stock_prices.csv' ); $pgs->output( 'graph' );
A number of settings are provided to configure the graph's appearance, adding colour for example. The ability to add analysis lines to either chart is planned.
use PostScript::Graph::Stock; my $pgs = new PostScript::Graph::Stock( heading => 'MyCompany Shares', price_title => 'Price in pence', volume_title => 'Transaction volume', price_percent => 75, volume_percent => 25, background => [1, 1, 0.9], show_lines => 1, x_heavy_color => [0, 0, 0.6], x_heavy_width => 0.8, x_mid_color => [0.2, 0.6, 0.8], x_mid_width => 0.8, x_light_color => [0.5, 0.5, 1], x_light_width => 0.25, y_heavy_color => 0.3, y_heavy_width => 0.8, y_mid_color => 0.5, y_mid_width => 0.8, y_light_color => 0.7, y_light_width => 0.25, days => [qw(- Mon Dien Mitt ...)], months => [qw(- Jan Feb Mars ...)], dates => 'weeks', changes_only => 1, show_weekday => 1, show_day => 1, show_month => 1, show_year => 1, color => [1, 0, 0], width => 1.5, shape => 'close2', bgnd_outline => 1, bar_color => [0.8, 0.4, 0.15], bar_width => 0.5, ); $pgs->data_from_file( 'stock_prices.csv' ); #$pgs->line_from_file( 'analysis.csv' ); $pgs->build_chart(); $pgs->output( 'graph' );
Although a number of options are provided for convenience (see "Typical"), many of these are merely a selection of the options which can be given to the underlying objects. See the manpages for the options available in each of the modules mentioned.
use PostScript::Graph::Stock; my $pgs = new PostScript::Graph::Stock( file => { # for PostScript::File }, price => { # options for Price graph layout => { # General proportions, headings # for PostScript::Graph::Paper }, x_axis => { # All settings for X axis # for PostScript::Graph::Paper }, y_axis => { # All settings for Y axis # for PostScript::Graph::Paper }, style => { # Appearance of price points # for PostScript::Graph::Style }, key => { # Settings for Key area if there is one # for PostScript::Graph::Key }, }, volume => { # options for Volume bar chart layout => { # General proportions, headings # for PostScript::Graph::Paper }, x_axis => { # All settings for X axis # for PostScript::Graph::Paper }, y_axis => { # All settings for Y axis # for PostScript::Graph::Paper }, style => { # Appearance of volume bars # for PostScript::Graph::Style }, key => { # Settings for Key area if there is one # for PostScript::Graph::Key }, }, ); $pgs->build_chart( 'stock_prices.csv' ); $pgs->output( 'graph' );
This is a top level module in the PostScript::Graph series. It produces graphs of stock performance given data in either of the following formats. The first extract was obtained by requesting price quotes in CSV file format from http://uk.table.finance.yahoo.com/, the second from a query of a Finance::Shares::MySQL database.
Date,Open,High,Low,Close,Volume 31-Dec-01,448.75,448.75,438.00,439.48,986598 28-Dec-01,445.00,447.25,438.00,444.52,3492096 27-Dec-01,440.00,444.75,435.25,444.06,1053161 Date,Open,High,Low,Close,Volume 2001-06-01,454.50,475.00,448.50,461.00,8535680 2001-06-04,465.00,465.00,458.50,459.00,3254045 2001-06-05,458.25,464.00,455.00,462.00,4615016
Options given to the constructor control the appearance of the chart. The data can be given as a CSV file to data_from_file or as an array passed to data_from_array. It will shortly be possible to superimpose linear graphs on the same charts by calling line_from_file or line_from_array. The chart is comitted to postscript format in build_chart and saved to a postscript file with the output function. This file can be either a printable *.ps file or an Encapsulated PostScript file for inclusion elsewhere.
data_from_file
data_from_array
line_from_file
line_from_array
build_chart
output
The data is displayed as two charts showing price and volume. These only appear if there is suitable data: only a price chart is shown if the file has no volume data. The proportion of space allocated for each is configurable. A Key is shown at the right of the relevant graph when analysis lines are added.
Theoretically, many years' worth of quotes can be accomodated, although the processing time becomes increasingly obvious. The output device tends to impose a practical limit, however. For example, around 1000 vertical lines can be distinguished on an A4 landscape sheet at 300dpi - 3 years of data at a pinch. But it gets difficult to read beyond 6-9 months. To help with this, it is possible to simplify the output.
To show only the closing values for the last day of each week, use these options:
dates => 'weeks', shape => 'close',
The vertical scales largely look after themselves, although you might wish to add a bit of colour as all defaults are monochrome. The horizontal scale showing the dates requires a little more care. The module tries to ensure labels are always legible by missing some out if they become too crowded. This is indicated by minor lines appearing between the labels. If this is likely, the following settings are recommended.
show_lines => 1, changes_only => 0,
When changes_only is on (the default) the month name, for example, is only shown for the first day of a new month. But this could well be one of the dates omitted through over-crowding, in which case the labels may become misleading.
changes_only
Apart from that, the defaults will probably be satisfactory if you have a monochrome printer. However, as there are over 300 configurable options, a couple of examples might be useful.
Vertical lines can be shown and both set to red using top-level options:
show_lines => 1, x_heavy_color => [1, 0, 0],
Or the axis options may be set directly. Note that options unique to this package, such as 'show_lines' are only available at the top level.
show_lines => 1, price => { x_axis => heavy_color => [1, 0, 0], }, }, volume => { x_axis => heavy_color => [1, 0, 0], }, },
Some things cannot be done directly using the top-level shortcuts. Here the X axis marks are made more prominent and the labels are printed in dark green 8pt Courier.
price => { x_axis => { mark_min => 5, mark_max => 20, font => 'Courier', font_size => 8, font_color => [0, 0.4, 0], }, },
Most commonly the defaults are adequate, but using the deeper options gives more control. The following will give an orange price mark outlined in black.
shape => 'stock2', color => [0.5, 0.5, 0], width => 1,
This does essentially the same thing except the orange is now a narrow strip inside a dark blue border.
price => { style => { point => { shape => 'stock2', inner_color => [0.5, 0.5, 0], outer_color => [0, 0, 0.6], inner_width => 0.5, outer_width => 2.5, }, }, },
options can either be a list of hash keys and values or a hash reference. In either case, the hash is expected to have the same structure. Some of the primary keys are simple values but a few point to sub-hashes which hold options or groups themselves.
options
All color options can take either monochrome or colour format values. If a single number from 0 to 1.0 inclusive, this is interpreted as a shade of grey, with 0 being black and 1 being white. Alternatively an array ref holding three such values is read as holding red, green and blue values - again 1 is the brightest possible value.
Value Interpretation ===== ============== 0 black 0.5 grey 1 white [1, 0, 0] red [0, 1, 0] green [0, 0, 1] blue [1, 1, 0.9] light cream [0, 0.8, 0.6] turquoise
Other numbers are floating point values in PostScript native units (72 per inch).
Fill colour for price and volume chart backgrounds. (Default: 1)
Shortcut for price =>{ layout =>{ background => ... }} and/or volume =>{ layout =>{ background => ... }}.
Sets the colour of the volume bars. (Defaults to color)
color
Shortcut for volume =>{ style =>{ point =>{ color => ... }}}.
Sets the width of the volume bar outline. (Defaults to width)
width
Shortcut for volume =>{ style =>{ bar =>{ width => ... }}}.
By default shapes 'stock2' and 'close2' (see shape) are outlined with the complementary colour to the background, making them stand out. Setting this to 1 makes the outline default to the background colour itself. (Default: 0)
The date labels are made up of weekday, day, month and year. Which sections are shown by default depends on the dates setting. If this is 1, each part is only shown if it has changed from the previous label. If 0, all the selected parts are shown. (Default: 1)
Sets the colour of the price marks and/or volume bars. (Default: 0)
Shortcut for price =>{ style =>{ point =>{ color => ... }}} and/or volume =>{ style =>{ bar =>{ color => ... }}}.
This string determines how the dates are distributed across the X axis.
The dates are those present in the CSV file, but in chronological order.
Every day between the first and last day in the CSV file is listed, whether there is data for that day or not.
Every day except Saturdays and Sundays. Occasional holidays are ignored, just showing as days with no data.
Only the data for last trading day of each week is presented. No attempt is made to take the rest of the week into account - those days are just hidden. If any trading is recorded for that week, the latest day is given; if not the last working day is shown, with no data.
As weeks, but showing the last trading day of each month.
This allows the weekday abbreviations to be presented in a different language. It should be an array ref containing strings. Monday = 1, so there should probably be a dummy string for 0. (Defaults to English).
This may be either a PostScript::File object or a hash ref holding options for it. See PostScript::File for details. Options within this group include the paper size, orientation, debugging features and whether it is an EPS or a normal PostScript file.
Creating the PostScript::File object first has the advantage of allowing more than one chart to be printed from the same document.
Example
use PostScript::Graph::Stock; use PostScript::File; my $pgf = new PostScript::File(); my $gs1 = new PostScript::Graph::Stock( file => pgf, ); $gs1->build_chart( 'stock1.csv' ); $pgf->newpage(); my $gs1 = new PostScript::Graph::Stock( file => pgf, ); $gs1->build_chart( 'stock2.csv' ); $pgf->output( 'graph' );
A string which appears centrally above the price chart (or the volume chart if there are no prices). (Default: '')
Shortcut for price =>{ layout =>{ heading => ... }} or volume =>{ layout =>{ heading => ... }}.
This allows the month abbreviations to be presented in a different language. It should be an array ref containing strings. January = 1, so there should probably be a dummy string for 0. (Defaults to English).
This holds all the options pertaining to the price chart. It is similar in structure to PostScript::Graph::XY options with the following exceptions.
file
The 'file' section is not used here but is a seperate top-level option.
style
This section only controls the price points, so the 'line' and 'bar' subsections are not used. There is only one PostScript::Graph::Style object used to show the price points, so 'sequence' and 'auto' are irrelevent too.
chart
There is no 'chart' group. Settings specific to the stock graph are given to the constructor directly, at the top level.
See the manpage indicated for the details on what is relevant for each subsection.
price => { layout => { # General proportions, headings # See PostScript::Graph::Paper }, x_axis => { # All settings for X axis # See PostScript::Graph::Paper }, y_axis => { # All settings for Y axis # See PostScript::Graph::Paper }, style => { # Appearance of price points # See PostScript::Graph::Style }, key => { # Settings for Key area if there is one # See PostScript::Graph::Key }, },
The percentage of paper allocated to the price as opposed to the volume chart. This is more of a 'rough ratio' rather than a percentage, but it does give some control over the relative sizes. The price_percent value includes the date labels area whereas the volume_percent value does not.
A string labelling the Y axis on the price chart. (Default: '')
Shortcut for price =>{ y_axis =>{ title => ... }}.
Show the date of day within the month. (Default: depends on dates)
dates
Sets the shape of the price marks. Suitable values are 'stock', 'stock2', 'close' and 'close2'. (Default: 'stock2')
The stock2 and close2 variants are drawn with inner and outer colours where the others are drawn just once using the inner colour.
Shortcut for price =>{ style =>{ point =>{ shape => ... }}}. Do NOT use the values normally available for point shapes. The postscript routines for 'dot', 'diamond' etc. require 2 parameters instead of the 5 used here. Using them would cause the code to fail unpredictably. See "POSTSCRIPT CODE" for further details.
If 1, vertical lines are drawn on the charts. 0 means only horizontal graph lines are visible. (Default: 0)
Show the month. (Default: depends on dates)
Show the day of the week. (Default: depends on dates)
This holds all the options pertaining to the volume chart. It is similar in structure to PostScript::Graph::Bar. See price for the structure and most of the exceptions. Of course in the style section, it is 'bar' that is relevant with 'point' and 'line' ignored.
The percentage of paper allocated to the volume as opposed to the price chart. This is more of a 'rough ratio' rather than a percentage, but it does give some control over the relative sizes. The price_percent value includes the date labels area whereas the volume_percent value does not.
A string labelling the Y axis on the volume chart. (Default: '')
Shortcut for volume =>{ y_axis =>{ title => ... }}.
Sets the width of lines in the price marks. (Default: 1.0)
Shortcut for price =>{ style =>{ point =>{ width => ... }}}.
The colour of the main vertical lines, if show_lines is set. (Default: 0.4)
Shortcut for price =>{ x_axis =>{ heavy_color => ... }} and/or volume =>{ x_axis =>{ heavy_color => ... }}.
The width of the main vertical lines, if show_lines is set. (Default: 0.75)
Shortcut for price =>{ x_axis =>{ heavy_width => ... }} and/or volume =>{ x_axis =>{ heavy_width => ... }}.
If show_lines is set and some date labels have been supressed, the unlabelled marks have lines of this colour. (Default: 0.5)
Shortcut for price =>{ x_axis =>{ mid_color => ... }} and/or volume =>{ x_axis =>{ mid_color => ... }}.
The width of mid lines. See x_mid_color. (Default: 0.5)
Shortcut for price =>{ x_axis =>{ mid_width => ... }} and/or volume =>{ x_axis =>{ mid_width => ... }}.
Colour of major (labelled) lines on the Y axis. (Default: 0.4)
Shortcut for price =>{ y_axis =>{ heavy_color => ... }} and/or volume =>{ y_axis =>{ heavy_color => ... }}.
Width of major (labelled) lines on the Y axis. (Default: 0.75)
Shortcut for price =>{ y_axis =>{ heavy_width => ... }} and/or volume =>{ y_axis =>{ heavy_width => ... }}.
Colour of intermediate (unlabelled) lines on the Y axis. (Default: 0.5)
Shortcut for price =>{ y_axis =>{ mid_color => ... }} and/or volume =>{ y_axis =>{ mid_color => ... }}.
Width of intermediate (unlabelled) lines on the Y axis. (Default: 0.5)
Shortcut for price =>{ y_axis =>{ mid_width => ... }} and/or volume =>{ y_axis =>{ mid_width => ... }}.
Colour of lightest intermediate (unlabelled) lines on the Y axis. (Default: 0.6)
Shortcut for price =>{ y_axis =>{ light_color => ... }} and/or volume =>{ y_axis =>{ light_color => ... }}.
Width of lightest intermediate (unlabelled) lines on the Y axis. (Default: 0.25)
Shortcut for price =>{ y_axis =>{ light_width => ... }} and/or volume =>{ y_axis =>{ light_width => ... }}.
An optional fully qualified path-and-file or a simple file name. If omitted, the special file File::Spec->devnull() is returned.
dir
An optional directory dir. If present (and file is not already an absolute path), it is prepended to file.
A CSV file is read and converted to price and/or volume data, as appropriate. The comma seperated values are interpreted by Text::CSV_XS and so are currently unable to tolerate white space. See data_from_array for how the field contents are handled.
Any leading '~' is expanded to the users home directory. If no absolute directory is given either as part of file, it is placed within the current directory. File::Spec|File::Spec is used throughout so file access should be portable.
The array should be a list of array-refs, with each sub-array holding data for one day. Three formats are recognized:
Date, Open, High, Low, Close, Volume Date, Open, High, Low, Close Date, Volume
Examples
$pgs->data_from_array( [ [2001-04-26, 345, 400, 300, 321, 12345678], [Apr-1-01, 234.56, 240.00, 230.00, 239.99], [13/4/01, 987654], ] );
The first field must be a date. Attempts are made to recognize the format in turn:
The Finance::Shares::MySQL format is tried first, YYYY-MM-DD.
European format dates are tried next using Date::Pcalc's Decode_Date_EU().
Finally US dates are tried, picking up the !Yahoo format, Mar-01-99.
The four price values are typically decimals and the volume is usually an integer in the millions. These are used to automatically calculate the vertical axes.
This is the heart of the class which constructs the charts and produces the postscript code to draw them. If an array_ref is passed as the argument, this is given to data_from_array. Any other arguments are passed to data_from_file. These are just for convenience. build_chart itself requires that the necessary options have been given to new and that it has some stock data to work on.
Return the underlying PostScript::File object.
A convenience function to output the chart as a file. See "output" in PostScript::File.
A few functions are defined in the gstockdict dictionary. These provide the code for the shapes drawn as price marks. Of the 20 dictionary entries, 12 are defined, so there is room for a few more marks to be added externally.
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
2 POD Errors
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head3'
=back without =over
To install PostScript::Graph::Stock, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PostScript::Graph::Stock
CPAN shell
perl -MCPAN -e shell install PostScript::Graph::Stock
For more information on module installation, please visit the detailed CPAN module installation guide.