/ 
Finance-Shares-1.02
/ Finance::Shares::data

NAME

Finance::Shares::data - Store quote prices and volumes for a particular stock

SYNOPSIS

$data->write_csv($filename, $directory);

$source = $data->source();
$hash   = $data->dates_by();
$date   = $data->start();
$date   = $data->end();
$date   = $data->first();
$date   = $data->last();
$array  = $data->dates();
$hash   = $data->dates_hash();
$date   = $data->idx_to_date($i);
$i      = $data->date_to_idx($date);
$i2     = $data->x_coord($i);
$number = $data->nprices();
$number = $data->nvolumes();

Inherited from Finance::Shares::Function. See that module for details.

$name   = $data->id();
$name   = $data->name();
$fsc    = $data->chart();
@names  = $data->line_ids();
$fsl    = $data->line($name);
@fsls   = $data->lines($regexp);
$string = $data->show_lines();

DESCRIPTION

This module is used by Finance::Shares::Model and fsmodel and is not intended for stand-alone use. However, those features that may be useful to module writers are documented here.

Data Structure

A Finance::Shares::data object is a Finance::Shares::Function like all other lower-case-named Finance::Share modules. It holds five lines named:

data/open
data/high
data/low
data/close
data/volume

Finance::Shares::Model provides aliases for these using the names resource, so the 'data' suffix may usually be omitted.

$closing_prices = $data->line('close');

The data lines are Finance::Shares::Line objects, holding the raw data in array format indexed to match the dates held here. So this would print the price range for each date:

    my $dates  = $data->dates();
    my $high   = $data->line('high');
    my $low    = $data->line('low');
    my $hidata = $high->data();
    my $lodata = $low->data();

    for (my $i = 0; $i <= $#$dates; $i++) {
	my $date    = $dates->[$i];
	my $highest = $hidata->[$i];
	my $lowest  = $lodata->[$i];
	print "$date : from $lowest to $highest\n";
    }

As well as array access, individual dates can also be checked directly using a hash. For example, to obtain the closing price for a given date:

 my $i = $data->date_to_idx('2003-06-14');
 my $close = $data->line('close');
 my $array = $close->data();
 my $closing_price = $array->[$i];

METHODS

write_csv( filename [, directory ] )

Output all the data to the named file in CSV format. No headings are output and each line has these fields, comma seperated with no spaces:

date, open, high, low, close, volume

This data file is in the correct format for using as a source file in a Model specification.

nearest( date [, after, [data]] )

Returns the date closest to date.

after indicates whether the next later or earlier date is prefered if an exact match is not found. (Default: 0, earlier)

If given, data should be a hash ref indexed by dates. Only dates belonging to this set are considered.

This works by scanning through all the dates, so it should be called once and the result stored if it is to be needed again.

source( )

Return the source of the data as passed from Finance::Shares::Model. This can be an array ref, a CSV file name or a Finance::Shares::MySQL object - giving database access.

dates_by( )

Return how the dates are counted. One of quotes, weekdays, days, weeks, months.

start( )

The first date from the user's point of view. This is the date requested (or close to it) and will normally be the first date displayed on the chart.

end( )

The last date from the user's point of view. This is the date requested (or close to it) and will normally be the final date displayed on the chart.

first( )

The first date stored in the line data. This is derived from start but includes the maximum lead time required by functions working on the data.

last( )

The date of the last data item stored. end may be after this if the user has requested an extrapolation area.

dates( )

An array ref holding all known dates.

$d = $data->dates();

$d->[0]    == $data->first();
$d->[$#$d] == $data->last();

date_hash( )

The index linking each date with its array offset.

$d = $data->dates();
$h = $data->date_hash();

$date = $d->[$i];
$h->{$date} == $i;

x_coord( idx )

This converts the data array index into the equivalent display index, taking any hidden leading data into account.

For example, if 21 quotes were needed to establish valid calculations, the first date displayed (display index 0) would be data array element 20.

date_to_idx( date )

Return the data array index for a given date or undef if the date is not known.

idx_to_date( index )

Return the date corresponding to the date array index given.

nprices( )

Return the number of prices stored in the lines 'open', 'high', 'low' and 'close'.

nvolumes( )

Return the number of volumes stored in the line 'volume'. This is normally the same as nprices, but may be zero if no volume data was available.

chart( )

Return the Finance::Shares::Chart displaying this data set.

model( )

Return the controlling Finance::Shares::Model.

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.