/ 
Finance-Shares-0.10
/ Finance::Shares::Momentum

NAME

Finance::Shares::Momentum - functions dealing with rates of change

SYNOPSIS

    use Finance::Shares::Sample;
    use Finance::Shares::Momentum;

    my $s = new Finance::Shares::Sample(...);

    my $id1 = $s->momentum(
	graph  => 'prices',
	line   => 'close',
	period => 10,
	strict => 1,
	scaled => 1,
	shown  => 1,
	style  => {...}, # PostScript::Graph::Style
	key    => 'My Momentum Line',
    );
    my $id2 = $s->ratio(...);
    my $id3 = $s->gradient(...);
    
    my $id4 = $s->rising(
	...
	style    => {...}, # PostScript::Graph::Style
	key      => 'Rising Trends',
	weight   => 50,
	decay    => 0.66,
	ramp     => 0,
	cutoff   => {...}, # PostScript::Graph::Style
	gradient => {...}, # PostScript::Graph::Style
	smallest => 10,
    );
    my $id5 = $s->falling(...);

    my $id6 = $s->oversold(
	...
	gradient => {...}, # PostScript::Graph::Style
	sd => 2.5,
    );
    my $id7 = $s->undersold(...);

DESCRIPTION

This package provides additional methods for Finance::Shares::Sample objects. Some functions analyse how another line changes over time and produce lines on the cycles graph. Others are pseudo-tests producing digital output on the tests graph, although they don't trigger signals (use the test test for that, see "Tests" in Finance::Shares::Models).

Once a line has been constructed it may be referred to by a text identifier returned by the function. The functions may also be referred to by their text names in a model specification (short or full version):

mom	    momentum
roc	    ratio (Rate of Change)
grad    gradient
rise    rising
fall    falling
over    oversold
under   undersold

They all take the following parameters in hash key/value format. All of these keys are optional.

graph

A string indicating the graph for display: one of prices, volumes, cycles or signals. (Default: 'prices')

line

A string indicating the data/function to be analysed - normally the closing prices. (Default: 'close')

period

The number of readings used in the analysis. The actual time spanned depends on how the sample was configured.

strict

Where appropriate, setting this to 0 might produce a better looking line by including some (possibly dubious) guesses. Set as 1 to ensure the line is accurate and reliable.

scaled

Set this to 1 to make comparison easier. It ensures the values all lie within +/- 100. Particularly useful for ratio which normally produces values of +/-1.

shown

A flag controlling whether the function is graphed. 0 to not show it, 1 to add the line to the named graph. (Default: 1)

style

A hash ref holding settings suitable for the PostScript::Graph::Style object used when drawing the line. By default lines and points are plotted, with each line in a slightly different style. (Default: undef)

key

If given this becomes the visual identifier, shown on the Chart key panel.

In addition, the pseudo-tests rising, falling, oversold and undersold also recognize these keys.

smallest

[rising and falling only.] This is the smallest daily change that will be considered. For example,

    $s->falling(
	line     => 'close',
	period   => 10,
	smallest => 5,
    );

This will only produce 'true' if the closing price was 5p or more lower than the day before, according to the 10 day smoothed gradient.

sd

[oversold and undersold only.] Short for standard deviation, this defines the point beyond which stock is deemed oversold or undersold. The following table gives some idea how standard deviation relates to the number of quotes within the normal area or in the under/oversold region.

sd	    within  above or below
3.00    99.74%	 0.13%
2.58    99%		 0.5%
2.33    98%		 1%
2.06    96%		 2%
2.00    95.46%	 2.27%
1.65    90%		 5%
1.29    80%		10%
1.15    75%		12.5%
1.00    68.26%	15.87%
0.85    60%		20%
0.68    50%		25%
weight

How important the test should appear. Most tests implement this as the height of the results line.

decay

If the condition is met over a continuous period, the results line can be made to decay. This factor is multiplied by the previous line value, so 0.95 would produce a slow decay while 0 signals only the first date in the period.

ramp

An alternative method for conditioning the test line. This amount is added to the test value with each period.

gradient

Determine whether, and how, the gradient line will be shown. It can be '0' for hide or '1' for show but the most useful is a PostScript::Graph::Style object or a hash ref holding style settings.

cutoff

Determine whether, and how, the boundary line will be shown. It can be '0' for hide or '1' for show but the most useful is a PostScript::Graph::Style object or a hash ref holding style settings.

momentum

Movement is calculated by subtracting the value period days/weeks/months ago.

ratio

This calculates the rate of change by dividing the current value with a correspnding one period days/weeks/months previously.

strict centers the line around 1, without this it centers around 0. scaled should probably be used.

gradient

This is an attempt to provide a function which performs differentiation, smoothing out abberations as it goes.

A period of 1 just produces the slope of the line to the next point. Larger values, however, take a wider spread of neighbours into account. E.g. a 10 day gradient will calculate each gradient from the weighted average of the differences from the previous 5 and subsiquent 5 days, where they exist.

rising

A pseudo-test producing a true/false output on the tests graph depending on whether the gradient of the specified line is sufficiently positive.

falling

A pseudo-test producing a true/false output on the tests graph depending on whether the gradient of the specified line is sufficiently negative.

BUGS

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

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

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