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' AMZNQuotes 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 triesSources 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
reencodeCharts
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
headingFunctions
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 keyTests
See "test" in Finance::Shares::Model for details on these keys:
graph1 line1
graph2 line2
test signals
shown style
graph key
decay ramp
weightSignals
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 # TescoThen the command line
fs_model -m model -s retail -iwould 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.psBUGS
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.
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.