NAME

Statistics::DEA - Discontiguous Exponential Averaging

SYNOPSIS

    use Statistics::DEA;

    my $dea = Statistics::DEA->new($alpha, $max_gap);

    while (($data, $time) = some_data_source(...)) {
      ...
      $dea->update($data, $time);
      print $dea->average(), "\n";
      print $dea->standard_deviation(), "\n";
      print $dea->completeness($time), "\n";
      ...
   }

DESCRIPTION

The Statistics::DEA module can be used to compute exponentially decaying averages and standard deviations even when the data has gaps. The algorithm also avoids initial value bias and postgap bias.

new

    my $dea = Statistics::DEA->new($alpha, $max_gap);

Creates a new (potentially discontiguous) exponential average object.

The $alpha is the exponential decay of data: from zero (inclusive) to one (exclusive): the lower values cause the effect of data to decay more quickly, the higher values cause the effect of data to decay more slowly . Specifically, weights on older data decay exponentially with a characteristic time of -1/log(alpha) (log being the natural logarithm).

The $max_gap is the maximum time gap after which the data is considered lost. If the time interval between updates is dt, using a $max_gap of N*dt will cause each update to fill in up to N-1 of any preceeding skipped updates with the current data value. Use a $max_gap of dt to prevent such filling.

update

    $dea->update($data, $time);

Update the average with new data at a particular point in time.

The time parameter is how you can indicate gaps in the data; if you don't have gaps in your data, just monotonously increase it, for example $time++.

average

    my $avg = $dea->average();

Return the current average.

Functionally equivalent alias avg() is also available.

standard_deviation

    my $std_dev = $dea->standard_deviation();

Return the current standard deviation.

Functionally equivalent alias std_dev() is also available.

completeness

    my $completeness = $dea->completeness($time);

Return the current completeness: how well based the current average and standard deviation are on actual data. Any time intervals between updates greater than $max_gap reduce this value. A series of updates at time intervals of less than $max_gap will gradually increase this value from its initial, minimum, value of 0 to its maximum value of 1.

The $time should represent the current time. It must be >= the time of the last update.

alpha

    my $alpha = $dea->alpha();

Return the current exponential decay of data.

    $dea->alpha($alpha);

Set the exponential decay of data.

max_gap

    my $alpha = $dea->max_gap();

Return the current maximum time gap.

    $dea->max_gap($max_gap);

Set the maximum time gap.

AUTHOR

Jarkko Hietaniemi <jhi@iki.fi>

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

ACKNOWLEDGEMENT

The idea and the code are from the September 1998 Doctor Dobb's Journal Algorithm Alley article "Discontiguous Exponential Averaging" by John C. Gunther, used with permission. JCG also provided valuable feedback for the documentation -- and even fixed a bug in the code without knowing Perl as such. This is just a Perlification of the pseudocode in the article, all errors in transcription are solely mine.

cpanm Statistics::DEA

perl -MCPAN -e shell
install Statistics::DEA