NAME

Finance::Shares::Lesson3 - Adding colour to charts

DESCRIPTION

The Finance::Shares suite graphs its results. The marks on these are controlled by the PostScript::Graph::Style objects which are the subject of this lesson. This script, called 03color.pl can be found in the tutorial directory of the Finance::Shares package. Most of it should be familiar from Finance::Shares::Lesson2.

    #!/usr/bin/perl
    use strict;
    use warnings;
    use Getopt::Long;
    use Finance::Shares::Sample;
    use Finance::Shares::Chart;

    my $help;
    my $stock = 'MSFT';
    my $start = '2002-01-01';
    my $end   = '2002-01-31';
    my $dates = 'days';
    my $mode  = 'cache';
    my $usage = <<END;
    Usage:
        $0 [ options ]

    where options can be any (or none) of the following
        --stock=<code>          Stock code like 'BA.L'
        --dates=<dmw>           'days', 'weeks' or 'months'
        --start=<YYYY-MM-DD>    First date of sample
          --end=<YYYY-MM-DD>    Last date of sample
         --mode=<mode>          'cache', 'offline' or 'online'
    END

    GetOptions (
        'help'    => \$help,
        'stock=s' => \$stock,
        'dates=s' => \$dates,
        'start=s' => \$start,
        'end=s'   => \$end,
        'mode=s'  => \$mode,
    ) or $help = 1;
    print $usage and exit if $help;

    # Create MySQL object giving access to the data
    my $fss = new Finance::Shares::Sample(
        source => {
            user     => 'test',
            password => 'test',
            database => 'test',
        },

        mode         => $mode,
        symbol       => $stock,
        start_date   => $start,
        end_date     => $end,
    );

    # Create Chart object showing the data
    my $fsc = new Finance::Shares::Chart(
        sample      => $fss,
        background  => 1,
        file    => {
            landscape => 1,
        },
        prices  => {
        },
        volumes => {
        },
    );

    $fsc->output($stock);
    print "$stock quotes from $start to $end saved as $stock.ps\n";

This lesson focuses on the Finance::Shares::Chart constructor options. You were introduced to the file group in lesson 2. Here we have added another two groups, prices and volumes. Most of the exercises involve adding things there.

1. Usually we want to focus on the prices, but those big black volume bars rather dominate the chart. Add a percent key to both the prices and volumes option groups:

       prices {
           percent => 70,
       },

   It would make sense for the volumes percentage to be 30. Run the script and look at the chart. Try setting them both to 70. What happens?

2. Lets add a little colour. One of the top level Chart constructor options is background, currently set to 1. Decimals between 0.0 and 1.0 represent levels of grey with 0 being off and 1 as bright (white) as possible. Any colour can take a single decimal grey value, or an array of three decimals. Change the background entry to read:

       background => [ 1, 1, 0.9 ],

3. The price and volume marks are controlled by a style group. These settings are passed directly to the PostScript::Graph::Style object that controls the appearance of the data. Add this to the volumes group and see what it does.

       volumes => {
           style => {
               color => [ 0.5, 0.8, 0.6 ],
           },
       },

   Note that option names have international (US) English spellings.

4. Notice that the bars have a dark outline around them. All marks controlled by a Style have inner and outer colours. By default the outer edge is a contrasting colour to the background. Try this:

       background => [ 0, 0.3, 0.3 ],

   The outlines should now be pinkish, but probably a bit hard to see. Add a width setting to the volumes style group:

        volumes => {
           style => {
               color => [ 0.5, 0.8, 0.6 ],
               width => 8,

   A bit over the top, but I hope you get the idea.

5. Now let's bring this outline under control. The outer edge is a contrasing colour by default, but it can be removed (or rather set the same as the background) with the bgnd_outline option:

       my $fsc = new Finance::Shares::Chart(
           sample      => $fss,
           background  => [ 1, 1, 0.9 ],
           bgnd_outline=> 1,

   Alternatively, the outer edge can be given it's own colour by setting it explicitly:

        volumes => {
           style => {
               color => [ 0.5, 0.8, 0.6 ],
               width => 8,
               bar   => {
                   outer_color => [ 0.8, 0, 0.4 ],
               },
           },
       },

6. You should now be in a position to improve the appearance of the price marks. Give them some width and colour to begin with.

   I hope you can see the usefulness of the background colour options, now. A Style can control three types of marks. As well as bar, there are also sub-groups for line and point. The prices data is controlled by the point sub-group. See PostScript::Graph::Style for the details, but another way to control the price marks would be:

       prices => {
           style => {
               point => {
                   inner_width => 4,
                   inner_color => [ 0.6, 0.9, 0 ],
                   outer_width => 6,
                   outer_color => [ 0, 0, 0.9 ],
               },
           },
       },

   Comparing the prices and volumes style groups, it is worth noting a few points. color and width are just convenience options. The 'real' settings go on within the bar, line and point sub-groups.

   The 'outer width' is based on the line group which you haven't had a chance to experiment with yet. There, the background is drawn by putting a wider line behind a narrower one. Naturally, for a bar (and some point shapes) the background is an edge line - only have of which is visible. This discrepency is really a bug and might get sorted out sometime.

7. There are a couple of options specific to the points style sub-group.

   size is like width except it makes the whole shape larger or smaller. Price marks are a little different in that their size is controlled by the data, so it makes no sense to try that out here.

   shape is another matter. The shapes available to price style points are stock2, stock, close2 and close. Try them out to see the difference:

       prices => {
           style => {
               point => {
                   shape => 'close2',

   Note that these shapes are ONLY for price points. The shapes for other style points are documented in PostScript::Graph::Style.