NAME
Finance::Shares::mark - A line under user program control
SYNOPSIS
Two examples of how to specify a mark line, one showing the minimum required and the other illustrating all the possible fields.
use Finance::Shares::Model;
use Finance::Shares::mark;
my @spec = (
...
lines => [
minimal => {
function => 'mark',
},
full = {
function => 'mark',
use_spec => 1,
graph => 'Stock Prices',
gtype => 'price',
first_only => 1,
key => 'these are special',
style => { ... },
shown => 1,
order => 99,
},
],
tests => [
t1 => q( mark($full, 300) ),
],
samples => [
...
one => {
test => 't1',
...
}
],
);
my $fsm = new Finance::Shares::Model( @spec );
$fsm->build();DESCRIPTION
This module allows model test code to write points or lines on the graphs.
Significant options are line, first_only, style and size.
Call Syntax
This module may be treated like any other line, but it has some additional features.
The Finance::Shares::Model specification lines entry is not required, but may be useful. Normally the entry's tag would be used in a code fragment.
mark( "line_tag", $position );
mark( "line_tag/out_tag", $position );Here line_tag is the lines entry tag and out_tag is an identifier for the output line. This must be inside either single or double quotes. $position should evaluate to a Y axis value. It may be another line tag or an ordinary Perl expression.
Example
lines => [
low10 = {
function => 'lowest',
period => 10,
key => '10 day low',
}
output => {
},
],
code => [
example1 => q(
mark( 'output', 115 );
),
example2 => {
before => 'my $line = $output;'
step => 'mark( "output", $low10 );'
},
example3 => {
before => q(
my $line1 = $output/low;
my $line2 = $output/high;
),
step => q(
mark( "output/low", $close - 10 );
mark( "output/high", $close + 10 );
),
},
# Asking for TROUBLE
example4 => q(
my $line = $output/main;
mark( 'output', $low10 + 5 );
),
],Some Gotchas
Although the default values are useful, mixing defaults and given identifiers can lead to confusion. To be on the safe side, stick to the following usage.
Using the default line
It is not necessary to give the line a name if there is only ever going to be one. That is, all mark calls add points on the same line. And if the line is referenced seperately as in 'example2', it is referring to that line.
Multiple lines
Where the code produces multiple lines, give each line an explicit 'out' tag. Here it is better to always specify the line identifier as in 'example3'.
Mixing the two styles ('example4') is not a good idea. If necessary, the order of lines can be controlled by giving and out field in the lines specification. In that case, the first line is the default.
Seperate code entries
Each code entry (whether a string or before/step/after hash) should have control of the lines it writes to with mark. This means that the lines entries must also be distinct.
It is OK for many different code entries to read from the same line. But only one code entry must write to each line.
OPTIONS
function
If used, it must be mark. However, this is the default so you won't often see it.
first_only
Setting this to 1 ensures that only the first mark of this block is shown, rather than a mark for every date that passes the test. A value of 0 means all appropriate values are marked.
This module is only ever invoked from a code fragment within a model test. See "Marking the Chart" in Finance::Shares::Code. Typically the code fragment will test the data with some condition such as the following.
mark($mymark, $close) if $line1 > $line2;Here the mark module code is only visited for those dates where the value of $line1 is above $line2. Typically these would be entries in the model lines specification, which would include:
lines => [
line1 => {
...
},
line2 => {
...
},
mymark => {
function => 'mark',
...
},
],Imagine a sample with the following data.
date line1 line2 comp
2003-07-08 47 49
2003-07-09 51 50 >
2003-07-10 55 51 >
2003-07-11 53 52 >
2003-07-14 49 52
2003-07-15 48 51
2003-07-16 51 50 >
2003-07-17 56 51 >With first_only set to 0, there would be five marks. But if first_only was 1, there would be only two - on 2003-07-09 and 2003-07-16.
[Undefined values can confuse this feature. To be on the safe side either only use data selected by quotes or be sure to let mark() see the undefined dates:
mark($mymark, $close) if ($line1 > $line2)
or (not defined $line1)
or (not defined $line2);mark() assumes that dates missed are failures, and will normally show a 'first' marker after a gap. But the gap might be just undefined data and not a series of dates that failed. mark() adjusts for any undefined values it sees, but cannot make allowances for undefined values if it is never called for them.]
graph
If present, this should be a tag declared as a charts resource. It identifies a particular graph within a chart page. A gtype is implied. (No default)
gtype
Required, unless graph is given. This specifies the type of graph the function lines should appear on. It should be one of price, volume, analysis or logic. (Default: price)
line
Identifies the line(s) whose data is used by the code writing to this line.
out
If you wish, you may declare the output line names here.
key
Most functions generate suitable (if lengthy) entries. This provides the opportunity to identify the line in the Key panel, next to the style.
order
The entries on the graph are sorted according to this value, which defaults to the order required for calculation. A large integer will bring the line to the front and a negative number will put it behind all the rest.
Examples
- -1
-
The line goes behind the data.
- 0.5
-
In front of the data, but only just.
- 999
-
Probably the top line.
shown
1 for the line to be shown, 0 hides it. (Default: 1)
style
This is normally a hash ref defining the data's appearance. See PostScript::Graph::Style for full details, or "Lines" in Finance::Shares::Model for an example.
There are three special settings, identified by strings circle, up_arrow and down_arrow. They are all affected by the size option. For example,
style => 'up_arrow',
size => 12,is equivalent to:
style => {
bgnd_outline => 0,
point => {
shape => 'up_arrow',
size => 12,
width => 2,
y_offset => -12,
},
},
BUGS
Please 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
LICENCE
Copyright (c) 2002-2003 Christopher P Willmot
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. A copy can be found at http://www.gnu.org/copyleft/gpl.html
SEE ALSO
Finance::Shares::Overview provides an introduction to the suite, and fsmodel is the principal script.
Modules involved in processing the model include Finance::Shares::Model, Finance::Shares::MySQL, Finance::Shares::Chart. Chart and file details may be found in PostScript::File, PostScript::Graph::Paper, PostScript::Graph::Key, PostScript::Graph::Style.
All functions are invoked from their own modules, all with lower-case names such as Finance::Shares::moving_average. The nitty-gritty on how to write each line specification are found there.
The quote data is stored in a Finance::Shares::data object. For information on writing additional line functions see Finance::Shares::Function and Finance::Shares::Line. Also, Finance::Shares::Code covers writing your own tests.
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 364:
Expected text after =item, not a number