/ 
Finance-Shares-1.02
/ Finance::Shares::undersold

NAME

Finance::Shares::undersold - Indicate excessive price movement

SYNOPSIS

Two examples of how to specify a undersold line, one showing the minimum required and the other illustrating all the possible fields.

    use Finance::Shares::Model;
    use Finance::Shares::undersold;

    my @spec = (
	...
	lines => [
	    ...
	    minimal => {
		function => 'undersold',
	    },
	    full = {
		function   => 'undersold',
		line       => 'close',
		acceptable => 2.65,
		gradient   => 1,
		period     => 5,
		strict     => 0,
		
		key        => 'accelerated buying',
		style      => { ... },
		shown      => 1,
		order      => -99,
		
		graph      => 'Trading prices',
		gtype      => 'price',
		min        => 230,
		max        => 390,
		decay      => 90,
		ramp       => -10,
	    },
	    ...
	],
	
	samples => [
	    ...
	    one => {
		lines => ['full', 'minimal'],
		...
	    }
	],
    );

    my $fsm = new Finance::Shares::Model( @spec );
    $fsm->build();

DESCRIPTION

This module attempts to identify where the momentum of increasing prices exceeds its normal range. The underlying gradient line can be hidden or visible, and the cutoff point specified as either a number of standard deviations or a percentage of the price range.

To be any use, there must be a Finance::Shares::Model specification lines entry that has a function field declaring the module's name. Then the entry's tag must be used by a sample in some way. This may be either directly in a line field, or by referring to it within a test.

The main options include period, acceptable and gradient.

OPTIONS

function

Required. Must be undersold.

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 level. (Default: level)

line

Identifies the line to be considered. (Default: 'close')

acceptable

There are two forms.

Plain number

The number of standard deviations that are considered normal. The undersold line will go high when the corresponding number of gradients is exceeded. It reflects a proportion of the actual data. The following table indicates how standard deviations relate to percentages of the data in a normal distribution.

sd	    above
3.00     0.13%
2.58     0.5%
2.33     1%
2.06     2%
2.00     2.27%
1.65     5%
1.29    10%
1.15    12.5%
1.00    15.87%
0.85    20%
0.68    25%

E.g. '2.33' would highlight approximately the fastest rising 1% of the quotes.

String ending in '%'

A percentage of the momentum range. When the gradient exceeds this value, the undersold line will go high. Note that this is a fraction of the gradient range rather than a proportion of the data quantity.

E.g. '90%' means that the top 10% of the gradient range is considered unusual and will be highlighted.

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.

min

The Y axis value used for 'false'. (Default: depends on gtype)

max

The Y axis value used for 'true'. (Default: depends on gtype)

decay

A decimal factor applied to the result line for each date while the result is still 'true'. A value of 0.9 makes a shallow decay curve, while 0.1 keeps just 10% of the previous value so falls rapidly. (Default: 1.0)

ramp

A number added to the result line for each date while the result is still 'true'. A value of -10 produces a shallower straight line than a value of -100. (Default: 0)

Depending on other values, ramp and decay can be combined to form various curves.

momentum

This should be the name of a function which computes the rate of change of a line. Suitable values are 'momentum', 'rate_of_change' or 'gradient'. (Default: 'momentum')

period

The number of values to use in smoothing the result. It is passed to Finance::Shares::gradient.

The actual time will depend on the dates by field. (Default: 5)

Normally at least this number of dates will have been read in before the first date shown on the chart. However, a small initial gap may be visible if some of that working data was missing. Set the dates before field to adjust this.

strict

See Finance::Shares::gradient.

gradient

This controls whether or not the internal gradient and cutoff lines appear and what style they use. (Default: 0)

'0'

The line is hidden.

'1'

The line is visible with the default style.

hash ref

The line uses a style created from this specification.

PostScript::Graph::Style object

The line is shown with the style given.

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::Share::Function and Finance::Share::Line. Also, Finance::Share::test covers writing your own tests.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 324:

Expected text after =item, not a number