/ 
Finance-Shares-0.05
/ fs_model

NAME

fs_model - Run a Finance::Shares::Model

SYNOPSIS

fs_model --help
fs_model [ options ] [ stocks ]

'options' can be any of the following but must include a model specification. See the Finance::Shares::Model manpage for details of the file format.

-m <file> | --model=<file>   Model specification
-c <file> | --stocks=<file>  Source for stock codes
-v <lvl>  | --verbose=<lvl>  Level 0, 1 or 2
-i        | --individual     Output as seperate charts
-n        | --nocharts       Suppress chart output
-f <file> | --file=<file>    Name (single) output file

'stocks' are a list of Yahoo stock symbols such as MSFT BA.L 12126.PA

DESCRIPTION

This provides a simple way to run a Finance::Shares::Model. The specification is placed in a file and run against stocks given on the command line. The following options are recognized.

--model=<filename>

This file is evaluated using the Perl do command. It should return either a list of keys and values or a hash ref containing the same. See the SPECIFICATION section.

--stocks=<filename>

Stock symbols may be declared in any of three ways. They can be embedded in the specification as part of a samples resource, a list of them can be given on the command line, or they can be listed in the file named here.

The format of the file is fairly flexible. Stock symbols may be in upper or lower case, seperated by spaces, commas or on their own lines. Anything after a '#' is ignored, as are blank lines.

--file=<filename>

A script option forcing all charts into the file called <name>.ps.

--individual

This script option forces all charts into their own seperate files. The file names are constructed from the sample's symbol, start and end dates.

--nocharts

Giving this script option prevents any charts being constructed. It can be used to fetch quotes but as it runs the model but discards the results it is less heavy-handed to use fs_fetch instead.

--verbose

Gives some control over the number of messages sent to STDERR during the process.

0	Only fatal messages
1	Minimal
2	Report each process
3+	Debugging

SPECIFICATION

This is fully described in "CONSTRUCTOR" in Finance::Shares::Model. There are eight resources, each key corresponding to an array ref listing them. At least one source and at least one sample must be given.

sources   => [ ... ],
samples   => [ ... ],

groups    => [ ... ],
files     => [ ... ],
charts    => [ ... ],
functions => [ ... ],
tests     => [ ... ],
signals   => [ ... ],

The arrays contain key/value pairs. Each key names a single resource whose value is a hash ref (or an array ref in the case of signals). The hash ref in turn contains a set of options as key/value pairs.

This would be a valid model specification:

    sources => [
	dbase	 => {
	    user     => 'test',
	    password => 'test',
	    database => 'test',
	},
    ],
    
    samples => [
	all => {
	    start_date => '2003-01-01',
	},
    ],

Assuming the above was stored in the file 'simple.mdl' and the database was suitably configured, the model might be run thus:

fs_model -m 'simple.mdl' AMZN

Quotes for Amazon.com would be fetched between January 1st 2003 and today and drawn out on a chart saved as default.ps. Note that it is usually necessary to give at least a start date, and the script will complain if no stock symbols are given.

Suitable defaults have been provided for groups, files and charts. The first entry in each resource list will usually be used if none other is specified, so the 'all' sample is used by AMZN and 'dbase' is the source assumed.

A full model is driven by the samples entries. Each sample should ultimately have a choice from every other resource. Where the key is singular the value should be a resource name, like 'dbase' above. Key names that are plural require an array ref holding a list of names which will be dealt with in order.

Example

    samples => [
	template => {
	    groups     => [],
	    file       => 'my_file',
	    source     => 'dbase',
	    chart      => 'my_chart',
	    functions  => [qw(func1 func2 func3)],
	    tests      => ['my_test'],
	    signals    => ['sig1', 'sig2'],
	    start_date => '2003-04-01',
	    dates_by   => 'quotes',
	},
    ],

Because this is the first sample, it will provide all the settings applied to every stock symbol given to the model from command line and/or file.

Groups

These are named collections of sample keys.

Sources

These keys may be used within a 'database' sub-hash using a Finance::Shares::MySQL object as a source.

hostname	    port
user	    password
database	    exchange
start_date	    end_date
mode	    tries

Sources may also be the name of a CSV file.

Files

These sub-hashes control the PostScript output file. They accept these keys documented in PostScript::File.

paper	    eps
height	    width
bottom	    top
left	    right
clip_command    clipping
dir		    file
landscape	    headings
reencode

Charts

There are hundreds of options controlling the appearance of Finance::Shares::Chart objects. These are the top level keys:

prices	    volumes
cycles	    signals
x_axis	    key
dots_per_inch   reverse
bgnd_outline    background
heading_font    normal_font
heading

Functions

There is always a 'function' key indicating the name of the method producing the line. Apart from that the keys vary, but these are common:

graph	    line
period	    percent
strict	    shown
style	    key

Tests

See "test" in Finance::Shares::Model for details on these keys:

graph1	    line1
graph2	    line2
test	    signals
shown	    style
graph	    key
decay	    ramp
weight

Signals

The format of these entries is different. Each name refers to an array holding parameters for "add_signal" in Finance::Shares::Model. The signals are all different, but this example marks the price data with an arrow.

    signals => [
	buy => [ 'mark_buy', undef, {
		  graph => 'prices',
		  line  => 'low',
		  key   => 'Buy suggestion',
	}],
    ],

Example

This example assumes you have a mysql database set up as outlined in Finance::Shares::Overview.

The following is the file 'model'.

    my $bgnd = [0.95,0.95,0.9];
    my $data = [0.7, 0.7, 0.3];

    sources => [
	default => {
	    user     => 'test',
	    password => 'test',
	    database => 'test',
	    mode     => 'offline',
	},
    ],

    samples => [
	default => {
	    start_date => '1998-01-01',
	    end_date   => '2003-06-01',
	    dates_by   => 'months',
	    functions  => [qw(fast)],
	},
    ],

    files => [
	default => {
	    landscape => 1,
	},
    ],

    charts => [
	default => {
	    dots_per_inch => 75,
	    background => $bgnd,
	    x_axis => {
		mid_width => 0,
		mid_color => $bgnd,
	    },
	    key => {
		background => $bgnd,
	    },
	    prices => {
		percent => 60,
		points => {
		    color => $data,
		    width => 1.5,
		},
	    },
	    volumes => {
		percent => 20,
		bars => {
		    color => $data,
		},
	    },
	},
    ],

    functions => [
	fast => {
	    function => 'simple_average',
	    period => 3,
	    style => {
		auto => 'none',
		same => 1,
		width => 1,
		color => [1,0.4,0],
	    },
	},
    ],

The file 'retail' holds:

BOOT.L	    # Boots Group
DXNS.L	    # Dixons Group
KGF.L	    # Kingfisher
MKS.L	    # Marks & Spencer
MRW.L	    # Morrison Supermarket
NXT.L	    # Next
SFW.L	    # Safeway
SBRY.L	    # Sainsbury
TSCO.L	    # Tesco

Then the command line

fs_model -m model -s retail -i

would produce charts as the following files, each showing a 3 month moving average of closing prices.

BOOT.L_months_1998-02-27_to_2003-05-14.ps
DXNS.L_months_1998-02-27_to_2003-05-14.ps
KGF.L_months_1998-02-27_to_2003-05-14.ps
MKS.L_months_1998-02-27_to_2003-05-14.ps
MRW.L_months_1998-02-27_to_2003-05-14.ps
NXT.L_months_1998-02-27_to_2003-05-14.ps
SBRY.L_months_1998-02-27_to_2003-05-14.ps
SFW.L_months_1998-02-27_to_2003-05-14.ps
TSCO.L_months_1998-02-27_to_2003-05-14.ps

BUGS

Yes, there will be many. Please report those you find to the author.

AUTHOR

Chris Willmot, chris@willmot.org.uk

SEE ALSO

Finance::Shares::Model, Finance::Shares::MySQL, Finance::Shares::Sample and Finance::Shares::Chart.

Most models use functions from one or more of Finance::Shares::Averages, Finance::Shares::Bands and Finance::Shares::Momentum as well.

There is also an introduction, Finance::Shares::Overview and a tutorial beginning with Finance::Shares::Lesson1.