fs_model - Run a Finance::Shares::Model
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
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.
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.
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.
A script option forcing all charts into the file called <name>.ps.
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.
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.
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
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.
These are named collections of sample keys.
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.
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
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
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
See "test" in Finance::Shares::Model for details on these keys:
graph1 line1 graph2 line2 test signals shown style graph key decay ramp weight
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', }], ],
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
Yes, there will be many. 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::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.
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.